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 свойство. Эти функции включают addRequiredaddOptional, и 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(Не рекомендуемый), Добавляет дополнительный аргумент пары "имя-значение" во входную схему синтаксического анализатора

Можно задать входную схему синтаксического анализатора путем вызова addRequiredaddOptional, и 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
Поддержка