11.9.3 Разбор аргументов

Если ни одна из предыдущих функций валидации не подходит, есть также класс inputParser, который может выполнять чрезвычайно сложную проверку входных данных для функций.

p = inputParser ()

Создать объект p класса inputParser.

Этот класс предназначен для лёгкого разбора аргументов функций. Класс поддерживает четыре типа аргументов:

1. обязательные (см. addRequired);
2. необязательные (см. addOptional);
3. именованные (см. addParameter);
4. переключатели (см. addSwitch).

После определения API функции с помощью этих методов, предоставленные аргументы можно разобрать с помощью метода parse и результаты разбора получить с помощью accessor Results.

inputParser.Parameters

Возвращает список имен параметров, уже определённых.

inputParser.Results

Возвращает структуру с именами аргументов в качестве имён полей и соответствующими значениями.

inputParser.Unmatched

Возвращает структуру, аналогичную Results, но для несопоставленных параметров. Смотрите свойство KeepUnmatched.

inputParser.UsingDefaults

Возвращает массив ячеек с именами аргументов, использующих значения по умолчанию.

inputParser.CaseSensitive = boolean

Устанавливает, должен ли соответствие имён аргументов быть чувствительным к регистру. По умолчанию значение false.

inputParser.FunctionName = name

Устанавливает имя функции, которое будет использоваться в сообщениях об ошибках. По умолчанию пустая строка.

inputParser.KeepUnmatched = boolean

Устанавливает, следует ли выдавать ошибку для неопределённых аргументов. По умолчанию значение false. Если установлено значение true, дополнительные аргументы можно получить через Unmatched после метода parse. Обратите внимание, что поскольку аргументы Switch и Parameter могут быть смешаны, невозможно узнать тип несопоставленных аргументов. Если аргумент не найден, предполагается, что он имеет тип Parameter и ожидается, что за ним последует значение.

inputParser.StructExpand = boolean

Устанавливает, может ли структура передаваться в функцию вместо пар "параметр/значение". По умолчанию значение true.

Следующий пример показывает, как использовать этот класс:

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

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");

Примечание 1: Функция может содержать любую смесь четырёх типов API, но они должны появляться в определённом порядке. Аргументы Required должны быть первыми и могут следовать за любыми аргументами Optional. Только аргументы Parameter и Switch могут быть смешаны и должны появиться в конце.

Примечание 2: Если в API функции смешаны как аргументы Optional, так и Parameter, то как только строковый аргумент Optional не пройдёт валидацию, он будет считаться концом аргументов Optional. Остальные аргументы будут сравниваться с любыми аргументами Parameter или Switch.

См. также: nargin, validateattributes, validatestring, varargin.