Mercurial > octave
changeset 28513:59c6625e0180 stable
move classdef docstring comments inside classdef definitions
* +containers/Map.m, inputParser.m, weboptions.m: Move docstring
comments inside classdef block and individual method definitions
instead of grouping them all at the top of the file.
| author | John W. Eaton <jwe@octave.org> |
|---|---|
| date | Fri, 29 May 2020 10:56:22 -0400 |
| parents | 88f11d96d64c |
| children | fab862fedf85 |
| files | scripts/+containers/Map.m scripts/miscellaneous/inputParser.m scripts/web/weboptions.m |
| diffstat | 3 files changed, 476 insertions(+), 450 deletions(-) [+] |
line wrap: on
line diff
--- a/scripts/+containers/Map.m Fri May 29 08:50:29 2020 -0400 +++ b/scripts/+containers/Map.m Fri May 29 10:56:22 2020 -0400 @@ -23,115 +23,79 @@ ## ######################################################################## -## -*- texinfo -*- -## @deftypefn {} {@var{m} =} containers.Map () -## @deftypefnx {} {@var{m} =} containers.Map (@var{keys}, @var{vals}) -## @deftypefnx {} {@var{m} =} containers.Map (@var{keys}, @var{vals}, @qcode{"UniformValues"}, @var{is_uniform}) -## @deftypefnx {} {@var{m} =} containers.Map (@qcode{"KeyType"}, @var{kt}, @qcode{"ValueType"}, @var{vt}) -## -## Create an object of the containers.Map class that stores a list of key/value -## pairs. -## -## @var{keys} is an array of @emph{unique} keys for the map. The keys can be -## numeric scalars or strings. The type for numeric keys may be one of -## @qcode{"double"}, @qcode{"single"}, @qcode{"int32"}, @qcode{"uint32"}, -## @qcode{"int64"}, or @qcode{"uint64"}. Other numeric or logical keys will -## be converted to @qcode{"double"}. A single string key may be entered as is. -## Multiple string keys are entered as a cell array of strings. -## -## @var{vals} is an array of values for the map with the @emph{same} number -## of elements as @var{keys}. -## -## When called with no input arguments a default map is created with strings -## as the key type and @qcode{"any"} as the value type. -## -## The @qcode{"UniformValues"} option specifies whether the values of -## the map must be strictly of the same type. If @var{is_uniform} is true, any -## values which would be added to the map are first validated to ensure they -## are of the correct type. -## -## When called with @qcode{"KeyType"} and @qcode{"ValueType"} arguments, create -## an empty map with the specified types. The inputs @var{kt} and @var{vt} are -## the types for the keys and values of the map respectively. Allowed values -## for @var{kt} are @qcode{"char"}, @qcode{"double"}, @qcode{"single"}, -## @qcode{"int32"}, @qcode{"uint32"}, @qcode{"int64"}, @qcode{"uint64"}. -## Allowed values for @var{vt} are @qcode{"any"}, @qcode{"char"}, -## @qcode{"double"}, @qcode{"single"}, @qcode{"int32"}, @qcode{"uint32"}, -## @qcode{"int64"}, @qcode{"uint64"}, @qcode{"logical"}. -## -## The return value @var{m} is an object of the containers.Map class. -## @seealso{struct} -## @end deftypefn - -## -*- texinfo -*- -## @deftypefn {} {@var{n} =} Map.Count () -## Return the number of key/value pairs in the map, as a uint64. -## @end deftypefn -## -## @deftypefn {} {@var{type} =} Map.KeyType () -## Return the key type. -## -## Possible values are listed above when describing input variable @var{kt}. -## @end deftypefn -## -## @deftypefn {} {@var{type} =} Map.ValueType () -## Return the value type. -## -## Possible values are listed above when describing input variable @var{vt}. -## @end deftypefn - -## -*- texinfo -*- -## @deftypefn {} {@var{mask} =} Map.isKey (@var{keySet}) -## Return a logical array which is true where the elements of @var{keySet} are -## keys of the map and false otherwise. -## -## @var{keySet} is a cell array of keys. If a single key is being checked, it -## can be entered directly as a scalar value or a char vector. -## @end deftypefn -## -## @deftypefn {} {@var{keys} =} Map.keys () -## Return the sorted list of all keys of the map as a cell vector. -## @end deftypefn -## -## @deftypefn {} {@var{n} =} Map.length () -## Return the number of key/value pairs in the map. -## @end deftypefn -## -## @deftypefn {} {} Map.remove (@var{keySet}) -## Remove the list of key/value pairs specified by a cell array of keys -## @var{keySet} from the map. -## -## @var{keySet}) can also be a scalar value or a string when specifying a -## single key. -## @end deftypefn -## -## @deftypefn {} {@var{l} =} Map.size (@var{n}) -## @deftypefnx {} {@var{sz} =} Map.size () -## @deftypefnx {} {@var{dim_1}, @dots{}, @var{dim_n} =} Map.size () -## If @var{n} is 1, return the number of key/value pairs in the map, otherwise -## return 1. -## Without input arguments, return vector @code{[@var{l}, 1]} where @var{l} is -## the number of key/value pairs in the map. -## With multiple outputs, return @code{[@var{l}, @dots{}, 1]}. -## @end deftypefn -## -## @deftypefn {} {@var{val} =} Map.values () -## @deftypefnx {} {@var{val} =} Map.values (@var{keySet}) -## Return the list of all the values stored in the map as a cell vector. -## -## If @var{keySet}, a cell array of keys is provided, the corresponding -## values will be returned. -## @end deftypefn - classdef Map < handle + ## -*- texinfo -*- + ## @deftypefn {} {@var{m} =} containers.Map () + ## @deftypefnx {} {@var{m} =} containers.Map (@var{keys}, @var{vals}) + ## @deftypefnx {} {@var{m} =} containers.Map (@var{keys}, @var{vals}, @qcode{"UniformValues"}, @var{is_uniform}) + ## @deftypefnx {} {@var{m} =} containers.Map (@qcode{"KeyType"}, @var{kt}, @qcode{"ValueType"}, @var{vt}) + ## + ## Create an object of the containers.Map class that stores a list of key/value + ## pairs. + ## + ## @var{keys} is an array of @emph{unique} keys for the map. The keys can be + ## numeric scalars or strings. The type for numeric keys may be one of + ## @qcode{"double"}, @qcode{"single"}, @qcode{"int32"}, @qcode{"uint32"}, + ## @qcode{"int64"}, or @qcode{"uint64"}. Other numeric or logical keys will + ## be converted to @qcode{"double"}. A single string key may be entered as is. + ## Multiple string keys are entered as a cell array of strings. + ## + ## @var{vals} is an array of values for the map with the @emph{same} number + ## of elements as @var{keys}. + ## + ## When called with no input arguments a default map is created with strings + ## as the key type and @qcode{"any"} as the value type. + ## + ## The @qcode{"UniformValues"} option specifies whether the values of + ## the map must be strictly of the same type. If @var{is_uniform} is true, any + ## values which would be added to the map are first validated to ensure they + ## are of the correct type. + ## + ## When called with @qcode{"KeyType"} and @qcode{"ValueType"} arguments, create + ## an empty map with the specified types. The inputs @var{kt} and @var{vt} are + ## the types for the keys and values of the map respectively. Allowed values + ## for @var{kt} are @qcode{"char"}, @qcode{"double"}, @qcode{"single"}, + ## @qcode{"int32"}, @qcode{"uint32"}, @qcode{"int64"}, @qcode{"uint64"}. + ## Allowed values for @var{vt} are @qcode{"any"}, @qcode{"char"}, + ## @qcode{"double"}, @qcode{"single"}, @qcode{"int32"}, @qcode{"uint32"}, + ## @qcode{"int64"}, @qcode{"uint64"}, @qcode{"logical"}. + ## + ## The return value @var{m} is an object of the containers.Map class. + ## @seealso{struct} + ## @end deftypefn + properties (GetAccess = public, SetAccess = private) + + ## -*- texinfo -*- + ## @deftypefn {} {@var{type} =} Map.KeyType () + ## Return the key type. + ## + ## Possible values are listed above when describing input variable @var{kt}. + ## @end deftypefn + KeyType = "char"; + + ## -*- texinfo -*- + ## @deftypefn {} {@var{type} =} Map.ValueType () + ## Return the value type. + ## + ## Possible values are listed above when describing input variable @var{vt}. + ## @end deftypefn + ValueType = "any"; + endproperties properties (Dependent, SetAccess = protected) + + ## -*- texinfo -*- + ## @deftypefn {} {@var{n} =} Map.Count () + ## Return the number of key/value pairs in the map, as a uint64. + ## @end deftypefn + Count = 0; + endproperties properties (private) @@ -266,11 +230,27 @@ endfunction function keySet = keys (this) + + ## -*- texinfo -*- + ## @deftypefn {} {@var{keys} =} Map.keys () + ## Return the sorted list of all keys of the map as a cell vector. + ## @end deftypefn + keySet = fieldnames (this.map).'; # compatibility requires row vector keySet = decode_keys (this, keySet); endfunction function valueSet = values (this, keySet) + + ## -*- texinfo -*- + ## @deftypefn {} {@var{val} =} Map.values () + ## @deftypefnx {} {@var{val} =} Map.values (@var{keySet}) + ## Return the list of all the values stored in the map as a cell vector. + ## + ## If @var{keySet}, a cell array of keys is provided, the corresponding + ## values will be returned. + ## @end deftypefn + if (nargin == 1) valueSet = struct2cell (this.map).'; else @@ -291,6 +271,16 @@ endfunction function tf = isKey (this, keySet) + + ## -*- texinfo -*- + ## @deftypefn {} {@var{mask} =} Map.isKey (@var{keySet}) + ## Return a logical array which is true where the elements of @var{keySet} are + ## keys of the map and false otherwise. + ## + ## @var{keySet} is a cell array of keys. If a single key is being checked, it + ## can be entered directly as a scalar value or a char vector. + ## @end deftypefn + if (! iscell (keySet)) if (isnumeric (keySet) || islogical (keySet)) keySet = num2cell (keySet); @@ -308,6 +298,16 @@ endfunction function this = remove (this, keySet) + + ## -*- texinfo -*- + ## @deftypefn {} {} Map.remove (@var{keySet}) + ## Remove the list of key/value pairs specified by a cell array of keys + ## @var{keySet} from the map. + ## + ## @var{keySet}) can also be a scalar value or a string when specifying a + ## single key. + ## @end deftypefn + if (! iscell (keySet)) if (isnumeric (keySet) || islogical (keySet)) keySet = num2cell (keySet); @@ -325,6 +325,18 @@ endfunction function varargout = size (this, n) + + ## -*- texinfo -*- + ## @deftypefn {} {@var{l} =} Map.size (@var{n}) + ## @deftypefnx {} {@var{sz} =} Map.size () + ## @deftypefnx {} {@var{dim_1}, @dots{}, @var{dim_n} =} Map.size () + ## If @var{n} is 1, return the number of key/value pairs in the map, otherwise + ## return 1. + ## Without input arguments, return vector @code{[@var{l}, 1]} where @var{l} is + ## the number of key/value pairs in the map. + ## With multiple outputs, return @code{[@var{l}, @dots{}, 1]}. + ## @end deftypefn + c = length (this); if (nargin == 1) if (nargout <= 1) @@ -343,6 +355,12 @@ endfunction function len = length (this) + + ## -*- texinfo -*- + ## @deftypefn {} {@var{n} =} Map.length () + ## Return the number of key/value pairs in the map. + ## @end deftypefn + len = double (this.Count); endfunction
--- a/scripts/miscellaneous/inputParser.m Fri May 29 08:50:29 2020 -0400 +++ b/scripts/miscellaneous/inputParser.m Fri May 29 10:56:22 2020 -0400 @@ -23,241 +23,135 @@ ## ######################################################################## -## -*- texinfo -*- -## @deftypefn {} {@var{p} =} inputParser () -## Create object @var{p} of the inputParser class. -## -## This class is designed to allow easy parsing of function arguments. The -## class supports four types of arguments: -## -## @enumerate -## @item mandatory (see @code{addRequired}); -## -## @item optional (see @code{addOptional}); -## -## @item named (see @code{addParameter}); -## -## @item switch (see @code{addSwitch}). -## @end enumerate -## -## After defining the function API with these methods, the supplied arguments -## can be parsed with the @code{parse} method and the parsing results -## accessed with the @code{Results} accessor. -## -## @end deftypefn -## @deftypefn {} {} inputParser.Parameters -## Return list of parameter names already defined. -## -## @end deftypefn -## @deftypefn {} {} inputParser.Results -## Return structure with argument names as fieldnames and corresponding values. -## -## @end deftypefn -## @deftypefn {} {} inputParser.Unmatched -## Return structure similar to @code{Results}, but for unmatched parameters. -## See the @code{KeepUnmatched} property. -## -## @end deftypefn -## @deftypefn {} {} inputParser.UsingDefaults -## Return cell array with the names of arguments that are using default values. -## -## @end deftypefn -## @deftypefn {} {} inputParser.CaseSensitive = @var{boolean} -## Set whether matching of argument names should be case sensitive. Defaults -## to false. -## -## @end deftypefn -## @deftypefn {} {} inputParser.FunctionName = @var{name} -## Set function name to be used in error messages; Defaults to empty string. -## -## @end deftypefn -## @deftypefn {} {} inputParser.KeepUnmatched = @var{boolean} -## Set whether an error should be given for non-defined arguments. Defaults to -## false. If set to true, the extra arguments can be accessed through -## @code{Unmatched} after the @code{parse} method. Note that since -## @code{Switch} and @code{Parameter} arguments can be mixed, it is -## not possible to know the unmatched type. If argument is found unmatched -## it is assumed to be of the @code{Parameter} type and it is expected to -## be followed by a value. -## -## @end deftypefn -## @deftypefn {} {} inputParser.StructExpand = @var{boolean} -## Set whether a structure can be passed to the function instead of -## parameter/value pairs. Defaults to true. -## -## The following example shows how to use this class: -## -## @example -## function check (varargin) -## @c The next two comments need to be indented by one for alignment -## p = inputParser (); # create object -## p.FunctionName = "check"; # set function name -## p.addRequired ("pack", @@ischar); # mandatory argument -## p.addOptional ("path", pwd(), @@ischar); # optional argument -## -## ## create a function handle to anonymous functions for validators -## val_mat = @@(x) isvector (x) && all (x <= 1) && all (x >= 0); -## p.addOptional ("mat", [0 0], val_mat); -## -## ## create two arguments of type "Parameter" -## val_type = @@(x) any (strcmp (x, @{"linear", "quadratic"@})); -## p.addParameter ("type", "linear", val_type); -## val_verb = @@(x) any (strcmp (x, @{"low", "medium", "high"@})); -## p.addParameter ("tolerance", "low", val_verb); -## -## ## create a switch type of argument -## p.addSwitch ("verbose"); -## -## p.parse (varargin@{:@}); # Run created parser on inputs -## -## ## the rest of the function can access inputs by using p.Results. -## ## for example, get the tolerance input with p.Results.tolerance -## endfunction -## @end example -## -## @example -## @group -## check ("mech"); # valid, use defaults for other arguments -## check (); # error, one argument is mandatory -## check (1); # error, since ! ischar -## check ("mech", "~/dev"); # valid, use defaults for other arguments -## -## check ("mech", "~/dev", [0 1 0 0], "type", "linear"); # valid -## -## ## following is also valid. Note how the Switch argument type can -## ## be mixed into or before the Parameter argument type (but it -## ## must still appear after any Optional argument). -## check ("mech", "~/dev", [0 1 0 0], "verbose", "tolerance", "high"); -## -## ## following returns an error since not all optional arguments, -## ## 'path' and 'mat', were given before the named argument 'type'. -## check ("mech", "~/dev", "type", "linear"); -## @end group -## @end example -## -## @emph{Note 1}: A function can have any mixture of the four API types but -## they must appear in a specific order. @code{Required} arguments must be -## first and can be followed by any @code{Optional} arguments. Only -## the @code{Parameter} and @code{Switch} arguments may be mixed -## together and they must appear at the end. -## -## @emph{Note 2}: If both @code{Optional} and @code{Parameter} arguments -## are mixed in a function API then once a string Optional argument fails to -## validate it will be considered the end of the @code{Optional} -## arguments. The remaining arguments will be compared against any -## @code{Parameter} or @code{Switch} arguments. -## -## @seealso{nargin, validateattributes, validatestring, varargin} -## @end deftypefn +classdef inputParser < handle -## -*- texinfo -*- -## @deftypefn {} {} addOptional (@var{argname}, @var{default}) -## @deftypefnx {} {} addOptional (@var{argname}, @var{default}, @var{validator}) -## Add new optional argument to the object @var{parser} of the class -## inputParser to implement an ordered arguments type of API -## -## @var{argname} must be a string with the name of the new argument. The order -## in which new arguments are added with @code{addOptional}, represents the -## expected order of arguments. -## -## @var{default} will be the value used when the argument is not specified. -## -## @var{validator} is an optional anonymous function to validate the given -## values for the argument with name @var{argname}. Alternatively, a -## function name can be used. -## -## See @code{help inputParser} for examples. -## -## @emph{Note}: if a string argument does not validate, it will be considered a -## ParamValue key. If an optional argument is not given a validator, anything -## will be valid, and so any string will be considered will be the value of the -## optional argument (in @sc{matlab}, if no validator is given and argument is -## a string it will also be considered a ParamValue key). -## -## @end deftypefn - -## -*- texinfo -*- -## @deftypefn {} {} addParameter (@var{argname}, @var{default}) -## @deftypefnx {} {} addParameter (@var{argname}, @var{default}, @var{validator}) -## Add new parameter to the object @var{parser} of the class inputParser to -## implement a name/value pair type of API. -## -## @var{argname} must be a string with the name of the new parameter. -## -## @var{default} will be the value used when the parameter is not specified. -## -## @var{validator} is an optional function handle to validate the given values -## for the parameter with name @var{argname}. Alternatively, a function name -## can be used. -## -## See @code{help inputParser} for examples. -## -## @end deftypefn + ## -*- texinfo -*- + ## @deftypefn {} {@var{p} =} inputParser () + ## Create object @var{p} of the inputParser class. + ## + ## This class is designed to allow easy parsing of function arguments. The + ## class supports four types of arguments: + ## + ## @enumerate + ## @item mandatory (see @code{addRequired}); + ## + ## @item optional (see @code{addOptional}); + ## + ## @item named (see @code{addParameter}); + ## + ## @item switch (see @code{addSwitch}). + ## @end enumerate + ## + ## After defining the function API with these methods, the supplied arguments + ## can be parsed with the @code{parse} method and the parsing results + ## accessed with the @code{Results} accessor. + ## + ## @end deftypefn + ## @deftypefn {} {} inputParser.Parameters + ## Return list of parameter names already defined. + ## + ## @end deftypefn + ## @deftypefn {} {} inputParser.Results + ## Return structure with argument names as fieldnames and corresponding values. + ## + ## @end deftypefn + ## @deftypefn {} {} inputParser.Unmatched + ## Return structure similar to @code{Results}, but for unmatched parameters. + ## See the @code{KeepUnmatched} property. + ## + ## @end deftypefn + ## @deftypefn {} {} inputParser.UsingDefaults + ## Return cell array with the names of arguments that are using default values. + ## + ## @end deftypefn + ## @deftypefn {} {} inputParser.CaseSensitive = @var{boolean} + ## Set whether matching of argument names should be case sensitive. Defaults + ## to false. + ## + ## @end deftypefn + ## @deftypefn {} {} inputParser.FunctionName = @var{name} + ## Set function name to be used in error messages; Defaults to empty string. + ## + ## @end deftypefn + ## @deftypefn {} {} inputParser.KeepUnmatched = @var{boolean} + ## Set whether an error should be given for non-defined arguments. Defaults to + ## false. If set to true, the extra arguments can be accessed through + ## @code{Unmatched} after the @code{parse} method. Note that since + ## @code{Switch} and @code{Parameter} arguments can be mixed, it is + ## not possible to know the unmatched type. If argument is found unmatched + ## it is assumed to be of the @code{Parameter} type and it is expected to + ## be followed by a value. + ## + ## @end deftypefn + ## @deftypefn {} {} inputParser.StructExpand = @var{boolean} + ## Set whether a structure can be passed to the function instead of + ## parameter/value pairs. Defaults to true. + ## + ## The following example shows how to use this class: + ## + ## @example + ## function check (varargin) + ## @c The next two comments need to be indented by one for alignment + ## p = inputParser (); # create object + ## p.FunctionName = "check"; # set function name + ## p.addRequired ("pack", @@ischar); # mandatory argument + ## p.addOptional ("path", pwd(), @@ischar); # optional argument + ## + ## ## create a function handle to anonymous functions for validators + ## val_mat = @@(x) isvector (x) && all (x <= 1) && all (x >= 0); + ## p.addOptional ("mat", [0 0], val_mat); + ## + ## ## create two arguments of type "Parameter" + ## val_type = @@(x) any (strcmp (x, @{"linear", "quadratic"@})); + ## p.addParameter ("type", "linear", val_type); + ## val_verb = @@(x) any (strcmp (x, @{"low", "medium", "high"@})); + ## p.addParameter ("tolerance", "low", val_verb); + ## + ## ## create a switch type of argument + ## p.addSwitch ("verbose"); + ## + ## p.parse (varargin@{:@}); # Run created parser on inputs + ## + ## ## the rest of the function can access inputs by using p.Results. + ## ## for example, get the tolerance input with p.Results.tolerance + ## endfunction + ## @end example + ## + ## @example + ## @group + ## check ("mech"); # valid, use defaults for other arguments + ## check (); # error, one argument is mandatory + ## check (1); # error, since ! ischar + ## check ("mech", "~/dev"); # valid, use defaults for other arguments + ## + ## check ("mech", "~/dev", [0 1 0 0], "type", "linear"); # valid + ## + ## ## following is also valid. Note how the Switch argument type can + ## ## be mixed into or before the Parameter argument type (but it + ## ## must still appear after any Optional argument). + ## check ("mech", "~/dev", [0 1 0 0], "verbose", "tolerance", "high"); + ## + ## ## following returns an error since not all optional arguments, + ## ## 'path' and 'mat', were given before the named argument 'type'. + ## check ("mech", "~/dev", "type", "linear"); + ## @end group + ## @end example + ## + ## @emph{Note 1}: A function can have any mixture of the four API types but + ## they must appear in a specific order. @code{Required} arguments must be + ## first and can be followed by any @code{Optional} arguments. Only + ## the @code{Parameter} and @code{Switch} arguments may be mixed + ## together and they must appear at the end. + ## + ## @emph{Note 2}: If both @code{Optional} and @code{Parameter} arguments + ## are mixed in a function API then once a string Optional argument fails to + ## validate it will be considered the end of the @code{Optional} + ## arguments. The remaining arguments will be compared against any + ## @code{Parameter} or @code{Switch} arguments. + ## + ## @seealso{nargin, validateattributes, validatestring, varargin} + ## @end deftypefn -## -*- texinfo -*- -## @deftypefn {} {} addParamValue (@var{argname}, @var{default}) -## @deftypefnx {} {} addParamValue (@var{argname}, @var{default}, @var{validator}) -## Add new parameter to the object @var{parser} of the class inputParser to -## implement a name/value pair type of API. -## -## This is an alias for @code{addParameter} method without the -## @qcode{"PartialMatchPriority"} option. See it for the help text. -## -## @end deftypefn - -## -*- texinfo -*- -## @deftypefn {} {} addRequired (@var{argname}) -## @deftypefnx {} {} addRequired (@var{argname}, @var{validator}) -## Add new mandatory argument to the object @var{parser} of inputParser class. -## -## This method belongs to the inputParser class and implements an ordered -## arguments type of API. -## -## @var{argname} must be a string with the name of the new argument. The order -## in which new arguments are added with @code{addrequired}, represents the -## expected order of arguments. -## -## @var{validator} is an optional function handle to validate the given values -## for the argument with name @var{argname}. Alternatively, a function name -## can be used. -## -## See @code{help inputParser} for examples. -## -## @emph{Note}: this can be used together with the other type of arguments but -## it must be the first (see @code{@@inputParser}). -## -## @end deftypefn - -## -*- texinfo -*- -## @deftypefn {} {} addSwitch (@var{argname}) -## Add new switch type of argument to the object @var{parser} of inputParser -## class. -## -## This method belongs to the inputParser class and implements a switch -## arguments type of API. -## -## @var{argname} must be a string with the name of the new argument. Arguments -## of this type can be specified at the end, after @code{Required} and -## @code{Optional}, and mixed between the @code{Parameter}. They default to -## false. If one of the arguments supplied is a string like @var{argname}, -## then after parsing the value of @var{parse}.Results.@var{argname} will be -## true. -## -## See @code{help inputParser} for examples. -## -## @end deftypefn - -## -*- texinfo -*- -## @deftypefn {} {} parse (@var{varargin}) -## Parses and validates list of arguments according to object @var{parser} of -## the class inputParser. -## -## After parsing, the results can be accessed with the @code{Results} -## accessor. See @code{help inputParser} for a more complete description. -## -## @end deftypefn - -classdef inputParser < handle properties ## FIXME: set input checking for these properties CaseSensitive = false; @@ -307,6 +201,30 @@ endfunction function addRequired (this, name, val = inputParser.def_val) + + ## -*- texinfo -*- + ## @deftypefn {} {} addRequired (@var{argname}) + ## @deftypefnx {} {} addRequired (@var{argname}, @var{validator}) + ## Add new mandatory argument to the object @var{parser} of inputParser class. + ## + ## This method belongs to the inputParser class and implements an ordered + ## arguments type of API. + ## + ## @var{argname} must be a string with the name of the new argument. The order + ## in which new arguments are added with @code{addrequired}, represents the + ## expected order of arguments. + ## + ## @var{validator} is an optional function handle to validate the given values + ## for the argument with name @var{argname}. Alternatively, a function name + ## can be used. + ## + ## See @code{help inputParser} for examples. + ## + ## @emph{Note}: this can be used together with the other type of arguments but + ## it must be the first (see @code{@@inputParser}). + ## + ## @end deftypefn + if (nargin < 2 || nargin > 3) print_usage (); elseif (numel (this.Optional) || numfields (this.Parameter) @@ -319,6 +237,33 @@ endfunction function addOptional (this, name, def, val = inputParser.def_val) + + ## -*- texinfo -*- + ## @deftypefn {} {} addOptional (@var{argname}, @var{default}) + ## @deftypefnx {} {} addOptional (@var{argname}, @var{default}, @var{validator}) + ## Add new optional argument to the object @var{parser} of the class + ## inputParser to implement an ordered arguments type of API + ## + ## @var{argname} must be a string with the name of the new argument. The order + ## in which new arguments are added with @code{addOptional}, represents the + ## expected order of arguments. + ## + ## @var{default} will be the value used when the argument is not specified. + ## + ## @var{validator} is an optional anonymous function to validate the given + ## values for the argument with name @var{argname}. Alternatively, a + ## function name can be used. + ## + ## See @code{help inputParser} for examples. + ## + ## @emph{Note}: if a string argument does not validate, it will be considered a + ## ParamValue key. If an optional argument is not given a validator, anything + ## will be valid, and so any string will be considered will be the value of the + ## optional argument (in @sc{matlab}, if no validator is given and argument is + ## a string it will also be considered a ParamValue key). + ## + ## @end deftypefn + if (nargin < 3 || nargin > 4) print_usage (); elseif (numfields (this.Parameter) || numfields (this.Switch)) @@ -330,6 +275,18 @@ endfunction function addParamValue (this, name, def, val = inputParser.def_val) + + ## -*- texinfo -*- + ## @deftypefn {} {} addParamValue (@var{argname}, @var{default}) + ## @deftypefnx {} {} addParamValue (@var{argname}, @var{default}, @var{validator}) + ## Add new parameter to the object @var{parser} of the class inputParser to + ## implement a name/value pair type of API. + ## + ## This is an alias for @code{addParameter} method without the + ## @qcode{"PartialMatchPriority"} option. See it for the help text. + ## + ## @end deftypefn + if (nargin < 3 || nargin > 4) print_usage (); endif @@ -337,6 +294,25 @@ endfunction function addParameter (this, name, def, varargin) + + ## -*- texinfo -*- + ## @deftypefn {} {} addParameter (@var{argname}, @var{default}) + ## @deftypefnx {} {} addParameter (@var{argname}, @var{default}, @var{validator}) + ## Add new parameter to the object @var{parser} of the class inputParser to + ## implement a name/value pair type of API. + ## + ## @var{argname} must be a string with the name of the new parameter. + ## + ## @var{default} will be the value used when the parameter is not specified. + ## + ## @var{validator} is an optional function handle to validate the given values + ## for the parameter with name @var{argname}. Alternatively, a function name + ## can be used. + ## + ## See @code{help inputParser} for examples. + ## + ## @end deftypefn + if (nargin < 3 || nargin > 6) print_usage (); endif @@ -367,6 +343,26 @@ endfunction function addSwitch (this, name) + + ## -*- texinfo -*- + ## @deftypefn {} {} addSwitch (@var{argname}) + ## Add new switch type of argument to the object @var{parser} of inputParser + ## class. + ## + ## This method belongs to the inputParser class and implements a switch + ## arguments type of API. + ## + ## @var{argname} must be a string with the name of the new argument. Arguments + ## of this type can be specified at the end, after @code{Required} and + ## @code{Optional}, and mixed between the @code{Parameter}. They default to + ## false. If one of the arguments supplied is a string like @var{argname}, + ## then after parsing the value of @var{parse}.Results.@var{argname} will be + ## true. + ## + ## See @code{help inputParser} for examples. + ## + ## @end deftypefn + if (nargin != 2) print_usage (); endif @@ -375,6 +371,17 @@ endfunction function parse (this, varargin) + + ## -*- texinfo -*- + ## @deftypefn {} {} parse (@var{varargin}) + ## Parses and validates list of arguments according to object @var{parser} of + ## the class inputParser. + ## + ## After parsing, the results can be accessed with the @code{Results} + ## accessor. See @code{help inputParser} for a more complete description. + ## + ## @end deftypefn + this.Results = struct (); this.Unmatched = struct (); this.UsingDefaults = cell ();
--- a/scripts/web/weboptions.m Fri May 29 08:50:29 2020 -0400 +++ b/scripts/web/weboptions.m Fri May 29 10:56:22 2020 -0400 @@ -23,124 +23,125 @@ ## ######################################################################## -## -*- texinfo -*- -## @deftypefn {} {@var{output} =} weboptions () -## @deftypefnx {} {@var{output} =} weboptions (@var{name1}, @var{value1}, @dots{}) -## -## Specify parameters for RESTful web services. -## -## @code{weboptions} with no inputs returns a default @code{weboptions} object -## to specify parameters for a request to a web service. A @code{weboptions} -## object can be an optional input argument to the @code{webread} and -## @code{webwrite} functions. -## -## Multiple name and value pair arguments may be specified in any order as -## @var{name1}, @var{value1}, @var{name2}, @var{value2}, etc. -## -## The option names must match @strong{exactly} one of those specified in the -## table below. -## -## The following options are available: -## -## @itemize @bullet -## @item -## @samp{CharacterEncoding} --- Specify the character encoding of the data: -## -## @samp{auto} (default), @samp{UTF-8}, @samp{US-ASCII} -## @samp{auto} chooses an encoding based on the content-type of the data. -## -## @item -## @samp{UserAgent} --- Specify the User Agent for the connection. -## -## Default value is @samp{GNU Octave/version}, where @samp{version} is the -## current version of Octave as returned by @code{version}. -## -## @item -## @samp{Timeout} --- Specify the timeout value for the connection in seconds. -## -## Default is 10 seconds. @samp{Inf} is not currently supported. -## -## @item -## @samp{Username} --- User identifier for a basic HTTP connection. -## -## Default is NULL@. It must be a string. -## -## @item -## @samp{Password} --- User authentication password for HTTP connection. -## -## Default is NULL@. It must be a string or character vector. -## Programming Note: If you display a @code{weboption} object with the Password -## property set, the value is displayed as a string containing -## @qcode{'*'}. However, the object stores the value of the Password -## property as plain text. -## -## @item -## @samp{KeyName} --- Specify the name of an additional key to be added to -## the HTTP request header. It should be coupled with @samp{KeyValue}. It -## must be a string or character vector. -## -## @item -## @samp{KeyValue} --- Specify the value of the key @samp{KeyName}. -## -## @samp{KeyName} must be present in order to assign to this field. -## -## @item -## @samp{@nospell{HeaderFields}} --- Specify the header fields for the -## connection. -## -## Names and values of header fields, specified as an m-by-2 array of strings -## or cell array of character vectors to add to the HTTP request header. -## @nospell{HeaderFields}@{i,1@} is the name of a field and -## @nospell{HeaderFields}@{i,2@} is its value. -## -## @example -## @group -## weboptions ("HeaderFields", @{"Content-Length" "78";"Content-Type" "application/json"@}) -## Creates a weboptions object that contains two header fields: Content-Length -## with value 78 and Content-Type with value application/json. -## @end group -## @end example -## -## @item -## @samp{ContentType} --- Specify the content type of the data. -## -## The following values are available: -## @samp{auto}, @samp{text}, @samp{json} -## -## Default is @samp{auto}. It automatically determines the content type. -## All other formats like @samp{audio}, @samp{binary}, etc.@: available in -## @sc{matlab} are not currently supported. -## -## @item -## @samp{ContentReader} --- Not yet implemented. Only for @sc{matlab} -## compatibility. -## -## @item -## @samp{MediaType} --- Not yet implemented. Only for @sc{matlab} -## compatibility. -## -## @item -## @samp{RequestMethod} --- Specifies the type of request to be made. -## -## The following methods are available: -## @samp{get}, @samp{put}, @samp{post}, @samp{delete}, @samp{patch} -## -## @code{webread} uses the HTTP GET method. @code{webwrite} uses the HTTP POST -## method as default. -## -## @item -## @samp{ArrayFormat} -- Not yet implemented. Only for @sc{matlab} -## compatibility. -## -## @item -## @samp{CertificateFilename} --- Not yet implemented. Only for @sc{matlab} -## compatibility. -## @end itemize -## -## @seealso{webread, webwrite} -## @end deftypefn +classdef weboptions < handle -classdef weboptions < handle + ## -*- texinfo -*- + ## @deftypefn {} {@var{output} =} weboptions () + ## @deftypefnx {} {@var{output} =} weboptions (@var{name1}, @var{value1}, @dots{}) + ## + ## Specify parameters for RESTful web services. + ## + ## @code{weboptions} with no inputs returns a default @code{weboptions} object + ## to specify parameters for a request to a web service. A @code{weboptions} + ## object can be an optional input argument to the @code{webread} and + ## @code{webwrite} functions. + ## + ## Multiple name and value pair arguments may be specified in any order as + ## @var{name1}, @var{value1}, @var{name2}, @var{value2}, etc. + ## + ## The option names must match @strong{exactly} one of those specified in the + ## table below. + ## + ## The following options are available: + ## + ## @itemize @bullet + ## @item + ## @samp{CharacterEncoding} --- Specify the character encoding of the data: + ## + ## @samp{auto} (default), @samp{UTF-8}, @samp{US-ASCII} + ## @samp{auto} chooses an encoding based on the content-type of the data. + ## + ## @item + ## @samp{UserAgent} --- Specify the User Agent for the connection. + ## + ## Default value is @samp{GNU Octave/version}, where @samp{version} is the + ## current version of Octave as returned by @code{version}. + ## + ## @item + ## @samp{Timeout} --- Specify the timeout value for the connection in seconds. + ## + ## Default is 10 seconds. @samp{Inf} is not currently supported. + ## + ## @item + ## @samp{Username} --- User identifier for a basic HTTP connection. + ## + ## Default is NULL@. It must be a string. + ## + ## @item + ## @samp{Password} --- User authentication password for HTTP connection. + ## + ## Default is NULL@. It must be a string or character vector. + ## Programming Note: If you display a @code{weboption} object with the Password + ## property set, the value is displayed as a string containing + ## @qcode{'*'}. However, the object stores the value of the Password + ## property as plain text. + ## + ## @item + ## @samp{KeyName} --- Specify the name of an additional key to be added to + ## the HTTP request header. It should be coupled with @samp{KeyValue}. It + ## must be a string or character vector. + ## + ## @item + ## @samp{KeyValue} --- Specify the value of the key @samp{KeyName}. + ## + ## @samp{KeyName} must be present in order to assign to this field. + ## + ## @item + ## @samp{@nospell{HeaderFields}} --- Specify the header fields for the + ## connection. + ## + ## Names and values of header fields, specified as an m-by-2 array of strings + ## or cell array of character vectors to add to the HTTP request header. + ## @nospell{HeaderFields}@{i,1@} is the name of a field and + ## @nospell{HeaderFields}@{i,2@} is its value. + ## + ## @example + ## @group + ## weboptions ("HeaderFields", @{"Content-Length" "78";"Content-Type" "application/json"@}) + ## Creates a weboptions object that contains two header fields: Content-Length + ## with value 78 and Content-Type with value application/json. + ## @end group + ## @end example + ## + ## @item + ## @samp{ContentType} --- Specify the content type of the data. + ## + ## The following values are available: + ## @samp{auto}, @samp{text}, @samp{json} + ## + ## Default is @samp{auto}. It automatically determines the content type. + ## All other formats like @samp{audio}, @samp{binary}, etc.@: available in + ## @sc{matlab} are not currently supported. + ## + ## @item + ## @samp{ContentReader} --- Not yet implemented. Only for @sc{matlab} + ## compatibility. + ## + ## @item + ## @samp{MediaType} --- Not yet implemented. Only for @sc{matlab} + ## compatibility. + ## + ## @item + ## @samp{RequestMethod} --- Specifies the type of request to be made. + ## + ## The following methods are available: + ## @samp{get}, @samp{put}, @samp{post}, @samp{delete}, @samp{patch} + ## + ## @code{webread} uses the HTTP GET method. @code{webwrite} uses the HTTP POST + ## method as default. + ## + ## @item + ## @samp{ArrayFormat} -- Not yet implemented. Only for @sc{matlab} + ## compatibility. + ## + ## @item + ## @samp{CertificateFilename} --- Not yet implemented. Only for @sc{matlab} + ## compatibility. + ## @end itemize + ## + ## @seealso{webread, webwrite} + ## @end deftypefn + properties CharacterEncoding = "auto"; UserAgent = ["GNU Octave/", version()];