MATLAB^®

inputParser - Construct input parser object

Syntax

p = inputParser

Description

p = inputParser constructs an empty inputParser object. Use this utility object to parse and validate input arguments to the functions that you develop. The input parser object follows handle semantics; that is, methods called on it affect the original object, not a copy of it.

The MATLAB software configures inputParser objects to recognize an input schema. Use any of the following methods to create the schema for parsing a particular function.

For more information on the inputParser class, see Parsing Inputs with inputParser in the MATLAB Programming Fundamentals documentation.

Methods

Method	Description
`addOptional`	Add an optional argument to the schema
`addParamValue`	Add a parameter-value pair argument to the schema
`addRequired`	Add a required argument to the schema
`createCopy`	Create a copy of the `inputParser` object
`parse`	Parse and validate the named inputs

Properties

Property	Description
`CaseSensitive`	Enable or disable case-sensitive matching of argument names
`FunctionName`	Function name to be included in error messages
`KeepUnmatched`	Enable or disable errors on unmatched arguments
`Parameters`	Names of arguments defined in `inputParser` schema
`Results`	Names and values of arguments passed in function call that are in the schema for this function
`StructExpand`	Enable or disable passing arguments in a structure
`Unmatched`	Names and values of arguments passed in function call that are not in the schema for this function
`UsingDefaults`	Names of arguments not passed in function call that are given default values

Property Descriptions

Properties of the inputParser class are described below.

CaseSensitive

Purpose — Enable or disable case sensitive matching of argument names

p.CaseSensitive = TF enables or disables case-sensitivity when matching entries in the argument list with argument names in the schema. Set CaseSensitive to logical 1 (true) to enable case-sensitive matching, or to logical 0 (false) to disable it. By default, case-sensitive matching is disabled.

FunctionName

Purpose — Function name to be included in error messages

p.FunctionName = name stores a function name that is to be included in error messages that might be thrown in the process of validating input arguments to the function. The name input is a string containing the name of the function for which you are parsing inputs with inputParser.

KeepUnmatched

Purpose — Enable or disable errors on unmatched arguments

p.KeepUnmatched = TF controls whether MATLAB throws an error when the function being called is passed an argument that has not been defined in the inputParser schema for this file. When this property is set to logical 1 (true), MATLAB does not throw an error, but instead stores the names and values of unmatched arguments in the Unmatched property of object p. When KeepUnmatched is set to logical 0 (false), MATLAB does throw an error whenever this condition is encountered and the Unmatched property is not affected.

Parameters

Purpose — Names of arguments defined in inputParser schema

c = p.Parameters is a cell array of strings containing the names of those arguments currently defined in the schema for the object. Each row of the Parameters cell array is a string containing the full name of a known argument.

Results

Purpose — Names and values of arguments passed in function call that are in the schema for this function

arglist = p.Results is a structure containing the results of the most recent parse of the input argument list. Each argument passed to the function is represented by a field in the Results structure, and the value of that argument is represented by the value of that field.

StructExpand

Purpose — Enable or disable passing arguments in a structure

p.StructExpand = TF, when set to logical 1 (true), tells MATLAB to accept a structure as an input in place of individual parameter-value arguments. If StructExpand is set to logical 0 (false), a structure is treated as a regular, single input.

Unmatched

Purpose — Names and values of arguments passed in function call that are not in the schema for this function

c = p.Unmatched is a structure array containing the names and values of all arguments passed in a call to the function that are not included in the schema for the function. Unmatched only contains this list of the KeepUnmatched property is set to true. If KeepUnmatched is set to false, MATLAB throws an error when unmatched arguments are passed in the function call. The Unmatched structure has the same format as the Results property of the inputParser class.

UsingDefaults

Purpose — Names of arguments not passed in function call that are given default values

defaults = p.UsingDefaults is a cell array of strings containing the names of those arguments that were not passed in the call to this function and consequently are set to their default values.

Examples

Write an M-file function called publish_ip, based on the MATLAB publish function, to illustrate the use of the inputParser class. Construct an instance of inputParser and assign it to variable p:

function publish_ip(script, varargin)
p = inputParser;   % Create instance of inputParser class.

Add arguments to the schema. See the reference pages for the addRequired, addOptional, and addParamValue methods for help with this:

p.addRequired('script', @ischar);
p.addOptional('format', 'html', ...
    @(x)any(strcmpi(x,{'html','ppt','xml','latex'})));
p.addParamValue('outputDir', pwd, @ischar);
p.addParamValue('maxHeight', [], @(x)x>0 && mod(x,1)==0);
p.addParamValue('maxWidth', [], @(x)x>0 && mod(x,1)==0);

Call the parse method of the object to read and validate each argument in the schema:

p.parse(script, varargin{:});

Execution of the parse method validates each argument and also builds a structure from the input arguments. The name of the structure is Results, which is accessible as a property of the object. To get the value of any input argument, type

p.Results.argname

Continuing with the publish_ip exercise, add the following lines to your M-file:

% Parse and validate all input arguments.
p.parse(script, varargin{:});

% Display the value for maxHeight.
disp(sprintf('\nThe maximum height is %d.\n', ...
              p.Results.maxHeight))

% Display all arguments.
disp 'List of all arguments:'
disp(p.Results)

When you call the program, MATLAB assigns those values you pass in the argument list to the appropriate fields of the Results structure. Save the M-file and execute it at the MATLAB command prompt with this command:

publish_ip('ipscript.m', 'ppt', 'outputDir', ...
    'C:/matlab/test', 'maxWidth', 500, 'maxHeight', 300);

The maximum height is 300.

List of all arguments:
              format: 'ppt'
           maxHeight: 300
            maxWidth: 500
           outputDir: 'C:/matlab/test'
              script: 'ipscript.m'