Exponenta Banner

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.

Типы данных: ячейка

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

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

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

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

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

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

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

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

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

Типы данных: ячейка

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

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

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

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

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

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

Примеры

свернуть все

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

Создайте функцию в файле findArea.m 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
Поддержка