Parsing Arguments (GNU Octave (version 9.3.0))

#### 11.9.3 Parsing Arguments ¶

If none of the preceding validation functions is sufficient there is also the class `inputParser` which can perform extremely complex input checking for functions.

: `p =` inputParser `()` ¶

  Create object p of the inputParser class.

  This class is designed to allow easy parsing of function arguments. The class supports four types of arguments:

  1. mandatory (see `addRequired`);
  2. optional (see `addOptional`);
  3. named (see `addParameter`);
  4. switch (see `addSwitch`).

  After defining the function API with these methods, the supplied arguments can be parsed with the `parse` method and the results accessed with the `Results` accessor.

: inputParser.Parameters ¶

  Return the list of parameter names already defined. (read-only)

: inputParser.Results ¶

  Return a structure with argument names as fieldnames and corresponding values. (read-only)

: inputParser.Unmatched ¶

  Return a structure similar to `Results`, but for unmatched parameters. (read-only) See the `KeepUnmatched` property.

: inputParser.UsingDefaults ¶

  Return cell array with the names of arguments that are using default values. (read-only)

: inputParser.FunctionName `= name` ¶

  Set function name to be used in error messages; Defaults to empty string.

: inputParser.CaseSensitive `= boolean` ¶

  Set whether matching of argument names should be case sensitive; Defaults to false.

: inputParser.KeepUnmatched `= boolean` ¶

  Set whether string arguments which do not match any Parameter are parsed and stored in the `Unmatched` property; Defaults to false. If false, an error will be emitted at the first unrecognized argument and parsing will stop. Note that since `Switch` and `Parameter` arguments can be mixed, it is not possible to know the type of the unmatched argument. Octave assumes that all unmatched arguments are of the `Parameter` type and therefore must be followed by a value.

: inputParser.PartialMatching `= boolean` ¶

  Set whether argument names for `Parameter` and `Switch` options may be given in shortened form as long as the name uniquely identifies an option; Defaults to true. For example, the argument `'opt'` will match a parameter `'opt_color'`, but will fail if there is also a parameter `'opt_case'`.

: inputParser.StructExpand `= boolean` ¶

  Set whether a structure passed to the function is expanded into parameter/value pairs (parameter = fieldname); Defaults to true.

  The following example shows how to use this class:

      function check (varargin)
        p = inputParser ();                      # create object
        p.FunctionName = "check";                # set function name
        p.addRequired ("pack", @ischar);         # mandatory argument
        p.addOptional ("path", pwd(), @ischar);  # optional argument

        ## Create anonymous function handle for validators
        valid_vec = @(x) isvector (x) && all (x >= 0) && all (x <= 1);
        p.addOptional ("vec", [0 0], valid_vec);

        ## Create two arguments of type "Parameter"
        vld_type = @(x) any (strcmp (x, {"linear", "quadratic"}));
        p.addParameter ("type", "linear", vld_type);
        vld_tol = @(x) any (strcmp (x, {"low", "medium", "high"}));
        p.addParameter ("tolerance", "low", vld_tol);

        ## 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

      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 in with or before the Parameter argument type (but it
      ## must still appear after any Optional arguments).
      check ("mech", "~/dev", [0 1 0 0], "verbose", "tolerance", "high");

      ## following returns an error since an Optional argument, 'path',
      ## was given after the Parameter argument 'type'.
      check ("mech", "type", "linear", "~/dev");

  Note 1: A function can have any mixture of the four API types but they must appear in a specific order. `Required` arguments must be first and can be followed by any `Optional` arguments. Only the `Parameter` and `Switch` arguments may be mixed together and they must appear following the first two types.

  Note 2: If both `Optional` and `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 `Optional` arguments. The remaining arguments will be compared against any `Parameter` or `Switch` arguments.

  See also: nargin, validateattributes, validatestring, varargin.