inputParser

Введите синтаксический анализатор для функций

расширьте все на странице

Описание

Объект inputParser позволяет вам управлять входными параметрами к функции путем создания входной схемы синтаксического анализатора. Чтобы проверять вход, можно задать функции валидации для обязательных аргументов, дополнительных аргументов и аргументов пары "имя-значение". Опционально, можно установить свойства настроить поведение парсинга, такое как обработка чувствительности к регистру, входных параметров массива структур и входных параметров, которые не находятся во входной схеме синтаксического анализатора.

После определения вашей входной схемы синтаксического анализатора вызовите функцию parse. inputParser хранит информацию о входных параметрах.

Введите имена и значенияГде сохранено
Соответствие с входной схемой синтаксического анализатораСвойство Results
Не переданный функции и, поэтому, присвоенные значения по умолчаниюСвойство UsingDefaults
Никакое соответствие не ввело схему синтаксического анализатораСвойство Unmatched

Создание

Синтаксис

p = inputParser

Описание

пример

p = inputParser создает входной объект синтаксического анализатора со значениями свойств по умолчанию.

Свойства

развернуть все

Индикатор, чтобы совпадать со случаем при проверке имен аргумента, заданных как false или true (или 0 или 1). По умолчанию соответствия имени аргумента не являются чувствительными к регистру. Например, 'a' совпадает с 'A'. Для чувствительных к регистру соответствий, набор CaseSensitive к true (или 1).

Это значение свойства хранится как логическое значение.

Имя функции, чтобы отобразиться в сообщениях об ошибке, заданных как вектор символов или представить скаляр в виде строки. По умолчанию FunctionName является пустым символьным вектором (''). Как правило, вы устанавливаете FunctionName на имя функции, которое вы подтверждаете. Затем если функция parse сталкивается с недопустимыми входными параметрами, она сообщает об ошибке имя функции.

Это значение свойства хранится как вектор символов.

Типы данных: char | string

Индикатор Matching, чтобы выдать ошибку, когда вход не найден во входной схеме синтаксического анализатора, задал как false или true (или 0 или 1). По умолчанию функция parse выдает ошибку, если имя входного параметра не совпадает с тем, заданным во входной схеме синтаксического анализатора. Чтобы подавить ошибку и сохранить имя входного параметра и значение, установите KeepUnmatched на true (или 1). inputParser хранит несопоставленные имена входного параметра и значения в свойстве Unmatched.

Это значение свойства хранится как логическое значение.

Частичный индикатор соответствия для принятия частично совпадающего входа называет как допустимый, заданный как true или false (или 1 или 0). По умолчанию введите названия параметра, которые ведут подстроки названий параметра во входной схеме синтаксического анализатора, допустимы, и входное значение является соответствующим к тому параметру. Если существует несколько возможных соответствий к входному параметру, MATLAB® выдает ошибку. Чтобы потребовать, чтобы входные названия параметра совпадали с именем во входной схеме синтаксического анализатора точно, уважая свойство CaseSensitive, устанавливают PartialMatching на false (или 0).

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

  • Если значением свойства StructExpand является true (или 1), то inputParser не поддерживает частичное соответствие для имен полей структуры, которые соответствуют входным названиям параметра.

  • Если PartialMatching и KeepUnmatched является оба true (или 1), то MATLAB не выдает ошибку. Вместо этого это хранит неоднозначное название параметра в свойстве Unmatched.

Это значение свойства хранится как логическое значение.

Индикатор Structure, который интерпретирует структуру как один вход или как набор пар "имя-значение" параметра, заданных как true или false (или 1 или 0). По умолчанию inputParser расширяет структуры в отдельные входные параметры, где каждое имя поля соответствует входному названию параметра. Чтобы рассмотреть структуры как один входной параметр, задайте StructExpand как false (или 0).

Это значение свойства хранится как логическое значение.

Это свойство доступно только для чтения.

Имена аргумента заданы во входной схеме синтаксического анализатора, сохраненной как массив ячеек из символьных векторов. Каждая функция, которая добавляет входной параметр в схему, обновляет свойство Parameters. Эти функции включают addRequired, addOptional и addParameter.

Типы данных: cell

Это свойство доступно только для чтения.

Результаты, заданные как имена допустимых входных параметров и соответствующих значений, сохраненных как структура. Допустимый входной параметр один с именем, которое совпадает с аргументом, заданным во входной схеме синтаксического анализатора. Каждое поле структуры Results соответствует имени аргумента во входной схеме синтаксического анализатора. Функция parse заполняет свойство Results.

Типы данных: struct

Это свойство доступно только для чтения.

Несопоставленные входные имена и значения входных параметров, которые не совпадают с входной схемой синтаксического анализатора, сохраненной как структура. Если свойство KeepUnmatched установлено в false (или 0), который является значением по умолчанию, или если все входные параметры совпадают с входной схемой синтаксического анализатора, то Unmatched является структурой 1 на 1 без полей. В противном случае каждое поле структуры Unmatched соответствует имени входного параметра, который не совпадает с аргументами, заданными во входной схеме синтаксического анализатора.

Функция parse заполняет свойство Unmatched.

Типы данных: struct

Это свойство доступно только для чтения.

Входные параметры, не переданные явным образом функции, сохраненной как массив ячеек из символьных векторов. Эти входные параметры являются присвоенными значениями по умолчанию в свойстве Results. Функция parse заполняет свойство UsingDefaults.

Типы данных: cell

Функции объекта

addOptionalДобавьте дополнительный, позиционный параметр во входную схему синтаксического анализатора
addParameterДобавьте дополнительный аргумент пары "имя-значение" во входную схему синтаксического анализатора
addRequiredДобавьте требуемый, позиционный параметр во входную схему синтаксического анализатора
parseАнализ входных параметров функции
addParamValue(Не рекомендуемый), Добавляет дополнительный аргумент пары "имя-значение" во входную схему синтаксического анализатора

Можно задать входную схему синтаксического анализатора путем вызова addRequired, addOptional и функций addParameter в любом порядке. Однако, когда вы вызываете функцию, которая использует входной синтаксический анализатор, аргументы передаются в этом порядке:

  1. Обязательные аргументы

  2. Любые дополнительные, позиционные параметры

  3. Любые пары "имя-значение"

Примеры

свернуть все

Проверяйте валидность обязательных и дополнительных аргументов.

Создайте функцию в файле findArea.m. Функция findArea требует входного параметра width и принимает переменное количество дополнительных входных параметров. Входная схема синтаксического анализатора задает эти условия аргумента:

  • width (обязательный аргумент). Поскольку обязательные аргументы позиционны, width должен быть первым аргументом к функции findArea. Входной синтаксический анализатор проверяет, что width является положительным, скалярным, и числовым.

  • height (дополнительный аргумент). Поскольку дополнительные аргументы позиционны, если height является аргументом к функции findArea, то это должен быть второй аргумент. Входной синтаксический анализатор проверяет, что height является положительным, скалярным, и числовым.

  • 'units' и его присваиваемое значение (пара "имя-значение"). Пары "имя-значение" являются дополнительными. Когда вы вызываете функцию findArea, задаете пары "имя-значение" в любом порядке после позиционных параметров. Входной синтаксический анализатор проверяет, что значение для 'units' является строкой.

  • 'shape' и его присваиваемое значение (другая пара "имя-значение"). Входной синтаксический анализатор проверяет, что значение для 'shape' содержится в массиве expectedShapes.

function a = findArea(width,varargin)
   defaultHeight = 1;
   defaultUnits = 'inches';
   defaultShape = 'rectangle';
   expectedShapes = {'square','rectangle','parallelogram'};

   p = inputParser;
   validScalarPosNum = @(x) isnumeric(x) && isscalar(x) && (x > 0);
   addRequired(p,'width',validScalarPosNum);
   addOptional(p,'height',defaultHeight,validScalarPosNum);
   addParameter(p,'units',defaultUnits,@isstring);
   addParameter(p,'shape',defaultShape,...
                 @(x) any(validatestring(x,expectedShapes)));
   parse(p,width,varargin{:});
   
   a = p.Results.width*p.Results.height; 
end

Вызывайте функцию findArea несколько раз. Входной синтаксический анализатор не выдает ошибку ни для одного из этих вызовов функции.

a = findArea(7);
a = findArea(7,3);
a = findArea(13,'shape','square');
a = findArea(13,'units',"miles",'shape','square');

Вызовите функцию с аргументами, которые не совпадают с входной схемой синтаксического анализатора. Задайте нечисловое значение для входа width:

a = findArea('text')
Error using findArea (line 14)
The value of 'width' is invalid. It must satisfy the function: @(x)isnumeric(x)&&isscalar(x)&&(x>0).

Задайте неподдерживаемое значение для 'shape'.

a = findArea(4,12,'shape','circle')
Error using findArea (line 14)
The value of 'shape' is invalid. Expected input to match one of these values:

'square', 'rectangle', 'parallelogram'

The input, 'circle', did not match any of the valid values.
Скрипт Open Live Script

Сохраните название параметра и входные параметры значения, которые не находятся во входной схеме вместо того, чтобы выдать ошибку. 

default = 0;
value = 1;

p = inputParser;
p.KeepUnmatched = true;
addOptional(p,'expectedInputName',default)
parse(p,'extraInput',value);

Просмотрите несопоставленное название параметра и значение: 

p.Unmatched
ans = struct with fields:
    extraInput: 1

Осуществите чувствительность к регистру при проверке входных параметров функции.

p = inputParser;
p.CaseSensitive = true;
defaultValue = 0;
addParameter(p,'InputName',defaultValue)

parse(p,'inputname',10)
'inputname' is not a recognized parameter. For a list of valid name-value pair arguments, see the documentation for this function.
Скрипт Open Live Script

Расширьте аргумент структуры в пары "имя-значение". 

s.input1 = 10;
s.input2 = 20;
default = 0;

p = inputParser;
addParameter(p,'input1',default)
addParameter(p,'input2',default)
parse(p,s)

p.Results
ans = struct with fields:
    input1: 10
    input2: 20

Примите структуру как отдельный аргумент путем установки свойства StructExpand на false. 

s2.first = 1;
s2.random = rand(3,4,2);
s2.mytext = 'some text';

p = inputParser;
p.StructExpand = false;
addRequired(p,'structInput')
parse(p,s2)

results = p.Results
results = struct with fields:
    structInput: [1x1 struct]


fieldList = fieldnames(p.Results.structInput)
fieldList = 3x1 cell array
    {'first' }
    {'random'}
    {'mytext'}

Создайте функцию, которая анализирует информацию о людях и, при парсинге передач, добавляет информацию в массив ячеек.

Создайте функциональный addPerson и включайте входную схему синтаксического анализатора, которая использует функцию validateattributes. Функция addPerson принимает список людей, изменяет список при необходимости, и затем возвращает список. Используйте персистентный объект inputParser постараться не создавать из нового объекта с каждым вызовом функции.

function mlist = addPerson(mlist,varargin)
    persistent p
    if isempty(p)
        p = inputParser;
        p.FunctionName = 'addPerson';
        addRequired(p,'name',@(x)validateattributes(x,{'char'},...
            {'nonempty'}))
        addRequired(p,'id',@(x)validateattributes(x,{'numeric'},...
            {'nonempty','integer','positive'}))
        addOptional(p,'birthyear',9999,@(x)validateattributes(x,...
            {'numeric'},{'nonempty'}))
        addParameter(p,'nickname','-',@(x)validateattributes(x,...
            {'char'},{'nonempty'}))
        addParameter(p,'favColor','-',@(x)validateattributes(x,...
            {'char'},{'nonempty'}))
    end
    
    parse(p,varargin{:})
    
    if isempty(mlist)
        mlist = fieldnames(p.Results)';
    end
    mlist = [mlist; struct2cell(p.Results)'];
end

Создайте пустой список и добавьте человека в него.

pList = {};
pList = addPerson(pList,78,'Joe');
Error using addPerson
The value of 'name' is invalid. Expected input to be one of these types:

char

Instead its type was double.

Error in addPerson (line 19)
parse(p,varargin{:})

Парсинг перестал работать, потому что функция получает аргументы в неправильном порядке и попытках присвоить name значение 78. Эта запись не добавляется к pList.

Добавьте еще несколько людей в список.

pList = addPerson(pList,'Joe',78);
pList = addPerson(pList,'Mary',3,1942,'favColor','red');
pList = addPerson(pList,'James',182,1970,'nickname','Jimmy')
pList =

  4×5 cell array

    'birthyear'    'favColor'    'id'     'name'     'nickname'
    [     9999]    '-'           [ 78]    'Joe'      '-'       
    [     1942]    'red'         [  3]    'Mary'     '-'       
    [     1970]    '-'           [182]    'James'    'Jimmy'

Советы

  • Аргументы, добавленные к входной схеме синтаксического анализатора с функцией addOptional, позиционны. Поэтому добавьте их во входную схему синтаксического анализатора в том же порядке, они передаются в функцию.

  • Используйте addOptional, чтобы добавить отдельный аргумент во входную схему синтаксического анализатора. Если вы хотите проанализировать дополнительную пару "имя-значение", то используйте функцию addParameter.

Смотрите также

| |

Темы

Представленный в R2007a

Документация MATLAB
Поддержка
Для просмотра документации необходимо авторизоваться на сайте