MATLAB Function Reference

addOptional (inputParser) - Add optional argument to inputParser schema

Syntax

p.addOptional(argname, default, validator)
addOptional(p, argname, default, validator)

Description

p.addOptional(argname, default, validator) updates the schema for inputParser object p by adding an optional argument, argname. Specify the argument name in a string enclosed within single quotation marks. The default input specifies the value to use when the optional argument argname is not present in the actual inputs to the function. The optional validator input is a handle to a function that MATLAB uses during parsing to validate the input arguments. If the validator function returns false or errors, the parsing fails and MATLAB throws an error.

MATLAB parses parameter-value arguments after required arguments and optional arguments.

addOptional(p, argname, default, validator) is functionally the same as the syntax above.

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

Examples

Write an M-file function called publish_ip, based on the MATLAB publish function, to illustrate the use of the inputParser class.

There are three calling syntaxes for this function:

publish_ip('script')
publish_ip('script', 'format')
publish_ip('script', options)

From these three syntaxes, you can see that there is one required argument (script), one optional argument (format), and some number of optional arguments that are specified as parameter-value pairs (options).

Begin writing the example publish_ip M-file by entering the following two statements. The second statement calls the class constructor for inputParser to create an instance of the class. This class instance, or object, gives you access to all of the methods and properties of the class:

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

Following the constructor, add this block of code to the M-file. This code uses the addRequired(inputParser), addOptional, and addParamValue(inputParser) methods to define the input arguments to the function:

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);

Also add the next two lines to the M-file. The Parameters property of inputParser lists all of the arguments that belong to the object p:

disp 'The input parameters for this program are
disp(p.Parameters)'

Save the M-file using the Save option on the MATLAB File menu, and then run it to see the following list displayed:

The input parameters for this program are
    'format'
    'maxHeight'
    'maxWidth'
    'outputDir'
    'script'

See Also

inputParser, addRequired(inputParser), addParamValue(inputParser), parse(inputParser), createCopy(inputParser)

addlistener (handle)

addParamValue (inputParser)