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

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

: p = inputParser () ¶

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

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

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

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

: inputParser.Parameters ¶

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

: inputParser.Results ¶

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

: inputParser.Unmatched ¶

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

: inputParser.UsingDefaults ¶

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

: inputParser.CaseSensitive = boolean ¶

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

: inputParser.FunctionName = name ¶

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

: inputParser.KeepUnmatched = boolean ¶

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

: inputParser.StructExpand = boolean ¶

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

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

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.