Exponenta Banner
exponenta event 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

Индикатор соответствия для выдачи ошибки, если вход не найден во входной схеме синтаксического анализатора, указанный как 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 собственность.

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

Индикатор структуры, который интерпретирует структуру как один вход или как набор пар имя-значение параметра, указанный как 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.
Открыть сценарий в реальном времени

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

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.
Открыть сценарий в реальном времени

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

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
    {'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

Поддержка