# HG changeset patch # User Rik # Date 1408639585 25200 # Node ID d900f863335c0a7903aa45ee11565bfcaa12f356 # Parent 0073c0ffbfec7e404ebd833484cd0a7f24455af9 inputParser.m: Format docstring to Octave guidelines. * inputParser.m: Format docstring to Octave guidelines. diff -r 0073c0ffbfec -r d900f863335c scripts/general/inputParser.m --- a/scripts/general/inputParser.m Wed Aug 20 01:25:50 2014 +0100 +++ b/scripts/general/inputParser.m Thu Aug 21 09:46:25 2014 -0700 @@ -17,111 +17,118 @@ ## . ## -*- texinfo -*- -## @deftypefn {Function File} {} inputParser () -## Create object @var{parser} of the inputParser class. +## @deftypefn {Function File} {@var{p} =} inputParser () +## Create object @var{p} of the inputParser class. ## -## This class is designed to allow easy parsing of function arguments. This +## This class is designed to allow easy parsing of function arguments. The ## class supports four types of arguments: ## ## @enumerate ## @item mandatory (see @command{addRequired}); +## ## @item optional (see @command{addOptional}); +## ## @item named (see @command{addParamValue}); +## ## @item switch (see @command{addSwitch}). ## @end enumerate ## -## After defining the function API with this methods, the supplied arguments +## After defining the function API with these methods, the supplied arguments ## can be parsed with the @command{parse} method and the parsing results ## accessed with the @command{Results} accessor. ## -## @deftypefnx {Accessor method} parser.Parameters -## Return list of parameters name already defined. +## @deftypefnx {Accessor method} {} parser.Parameters +## Return list of parameter names already defined. ## -## @deftypefnx {Accessor method} parser.Results +## @deftypefnx {Accessor method} {} parser.Results ## Return structure with argument names as fieldnames and corresponding values. ## -## @deftypefnx {Accessor method} parser.Unmatched -## Return structure similar to @command{Results} for unmatched parameters. See -## the @command{KeepUnmatched} property. +## @deftypefnx {Accessor method} {} parser.Unmatched +## Return structure similar to @command{Results}, but for unmatched parameters. +## See the @command{KeepUnmatched} property. ## -## @deftypefnx {Accessor method} parser.UsingDefaults +## @deftypefnx {Accessor method} {} parser.UsingDefaults ## Return cell array with the names of arguments that are using default values. ## -## @deftypefnx {Class property} parser.CaseSensitive = @var{boolean} -## Set whether matching of argument names should be case sensitive. Defaults to false. +## @deftypefnx {Class property} {} parser.CaseSensitive = @var{boolean} +## Set whether matching of argument names should be case sensitive. Defaults +## to false. ## -## @deftypefnx {Class property} parser.FunctionName = @var{name} -## Set function name to be used on error messages. Defauls to empty string. +## @deftypefnx {Class property} {} parser.FunctionName = @var{name} +## Set function name to be used in error messages; Defaults to empty string. ## -## @deftypefnx {Class property} parser.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 @command{Switch} -## and @command{ParamValue} 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 -## @command{ParamValue} type and it is expected to be followed by a value. +## @deftypefnx {Class property} {} parser.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 +## @command{Switch} and @command{ParamValue} 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 @command{ParamValue} type and it is expected to +## be followed by a value. ## -## @deftypefnx {Class property} parser.StructExpand = @var{boolean} -## Set whether a structure can be passed to the function instead of parameter -## value pairs. Defaults to true. Not implemented yet. +## @deftypefnx {Class property} {} parser.StructExpand = @var{boolean} +## Set whether a structure can be passed to the function instead of +## parameter/value pairs. Defaults to true. Not implemented yet. ## ## The following example shows how to use this class: ## ## @example ## @group ## function check (varargin) -## p = inputParser (); # create object -## p.FunctionName = "check"; # set function name -## p.addRequired ("pack", @@ischar); # create mandatory argument +## @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 ## -## p.addOptional ("path", pwd(), @@ischar); # create optional argument -## -## ## one can 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 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 ParamValue type of arguments -## val_type = @@(x) any (strcmp (x, @{"linear", "quadratic"@})); -## p.addParamValue ("type", "linear", val_type); -## val_verb = @@(x) any (strcmp (x, @{"low", "medium", "high"@})); -## p.addParamValue ("tolerance", "low", val_verb); +## ## create two arguments of type "ParamValue" +## val_type = @@(x) any (strcmp (x, @{"linear", "quadratic"@})); +## p.addParamValue ("type", "linear", val_type); +## val_verb = @@(x) any (strcmp (x, @{"low", "medium", "high"@})); +## p.addParamValue ("tolerance", "low", val_verb); ## -## ## create a switch type of argument -## p.addSwitch ("verbose"); +## ## create a switch type of argument +## p.addSwitch ("verbose"); ## -## p.parse (varargin@{:@}); +## p.parse (varargin@{:@}); # Run created parser on inputs ## -## ## the rest of the function can access the input by accessing p.Results -## ## for example, to access the value of tolerance, use p.Results.tolerance +## ## the rest of the function can access inputs by using p.Results. +## ## for example, get the tolerance input with p.Results.tolerance ## endfunction +## @end group ## -## check ("mech"); # valid, will use defaults for other arguments -## check (); # error since at least one argument is mandatory -## check (1); # error since !ischar -## check ("mech", "~/dev"); # valid, will use defaults for other arguments +## 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 ## -## ## the following is also valid. Note how the Switch type of argument can be -## ## mixed into or before the ParamValue (but still after Optional) +## ## following is also valid. Note how the Switch argument type can +## ## be mixed into or before the ParamValue argument type (but it +## ## must still appear after any Optional argument). ## check ("mech", "~/dev", [0 1 0 0], "verbose", "tolerance", "high"); ## -## ## the following returns an error since not all optional arguments, `path' and -## ## `mat', were given before the named argument `type'. +## ## 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. @command{Required} arguments must be the very -## first which can be followed by @command{Optional} arguments. Only the -## @command{ParamValue} and @command{Switch} arguments can be mixed together but -## must be at the end. +## @emph{Note 1}: A function can have any mixture of the four API types but +## they must appear in a specific order. @command{Required} arguments must be +## first and can be followed by any @command{Optional} arguments. Only +## the @command{ParamValue} and @command{Switch} arguments may be mixed +## together and they must appear at the end. ## -## @emph{Note 2}: if both @command{Optional} and @command{ParamValue} arguments -## are mixed in a function API, once a string Optional argument fails to validate -## against, it will be considered the end of @command{Optional} arguments and the -## first key for a @command{ParamValue} and @command{Switch} arguments. +## @emph{Note 2}: If both @command{Optional} and @command{ParamValue} arguments +## are mixed in a function API then once a string Optional argument fails to +## validate it will be considered the end of the @command{Optional} +## arguments. The remaining arguments will be compared against any +## @command{ParamValue} or @command{Switch} arguments. ## ## @seealso{nargin, validateattributes, validatestring, varargin} ## @end deftypefn @@ -132,20 +139,20 @@ ## 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 +## @var{argname} must be a string with the name of the new argument. The order ## in which new arguments are added with @command{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. +## @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 @command{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 +## 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). @@ -155,15 +162,15 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {} addParamValue (@var{argname}, @var{default}) ## @deftypefnx {Function File} {} 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. +## 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 +## for the parameter with name @var{argname}. Alternatively, a function name ## can be used. ## ## See @command{help inputParser} for examples. @@ -178,12 +185,12 @@ ## 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 +## @var{argname} must be a string with the name of the new argument. The order ## in which new arguments are added with @command{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 +## for the argument with name @var{argname}. Alternatively, a function name ## can be used. ## ## See @command{help inputParser} for examples. @@ -195,16 +202,18 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {} addSwitch (@var{argname}) -## Add new switch type of argument to the object @var{parser} of inputParser class. +## 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{ParamValue}. 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. +## @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{ParamValue}. 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 @command{help inputParser} for examples. ## @@ -212,11 +221,11 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {} parse (@var{varargin}) -## Parses and validates list of arguments according to object @var{parser} of the -## class inputParser. +## Parses and validates list of arguments according to object @var{parser} of +## the class inputParser. ## ## After parsing, the results can be accessed with the @command{Results} -## accessor. See @command{help inputParser} for a more complete description. +## accessor. See @command{help inputParser} for a more complete description. ## ## @end deftypefn