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.FunctionName = name ¶

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

: inputParser.CaseSensitive = boolean ¶

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

: inputParser.KeepUnmatched = boolean ¶

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

: inputParser.PartialMatching = boolean ¶

Установить, могут ли имена аргументов для параметров Parameter и Switch быть заданы в сокращенной форме, если имя однозначно определяет опцию; По умолчанию true. Например, аргумент 'opt' будет соответствовать параметру 'opt_color', но потерпит неудачу, если также существует параметр 'opt_case'.

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

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

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

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