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: если в API функции смешаны аргументы Optional и Parameter, то после того, как строковый необязательный аргумент не пройдёт проверку, он будет считаться концом аргументов Optional. Оставшиеся аргументы будут сопоставляться с любыми аргументами Parameter или Switch.

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