Have you ever wondered how MATLAB functions make sense of variable function arguments? Many MATLAB functions take multiple optional arguments, or arguments specified as param-value pairs. A param-value pair is usually supplied with a string parameter name, such as ‘Position’ or ‘Color’ followed by the value of that parameter such as [0 0 1 1] or ‘on’ or some such. You may have seen this paradigm with the graphics functions.

With the help of the inputParser class, it’s easy to add param-value pairs to your own functions. This class has two great uses: (1) validation of function inputs and (2) collation of all those inputs into an easy-to-use struct.

InputParser is used in three easy steps:

1. Create an InputParser instance
2. Specify all the inputs. Three input types are supported:
   • Required Inputs. These must always be supplied when calling your function, otherwise there is an error.
   • Optional Inputs. These can be left off if desired.
   • Param-Value pairs. These require a paramater name and value.
3. Parse the inputs and read the results.

Create an InputParser
This step is easy. Just create a new instance.

p = inputParser

p = 

Input Parser object with:
CaseSensitive: false
StructExpand : true
KeepUnmatched: false
FunctionName : ''

Specify All The Inputs
Once you have an input parser object, you need to specify each input that you want to parse. In the follow example I add one required, one optional, and one param-value pair parameter. For each input you have to specify a validation function. In these examples I’ve provided an in-line anonymous function or function handle. A handy approve-all function, if you don’t care about validation, is “@(x) true.”

% add required needs the parameter name and a validator anonymous function
p.addRequired('mainVector',@(x) length(x)>1);
% add optional needs the name, default value, and validator
p.addOptional('ntimes',1,@isscalar);
% add paramValue needs the parameter name, default value, and validator
p.addParamValue('title','Default title',@isstr);

Run the Parser on the inputs
The next step is to actually use the inputParser object with a function’s input. In this exmaple example I’m using it to illustrate how the object parses different combinations of inputs.

disp('parse all options');
p.parse([1 2 3 4],2,'title','mytitle');
inputs = p.Results

% parse without specifying a title
disp('parse without specifing title param-value pair');
p.parse([1 2 3 4], 3);
inputs = p.Results

%parse with title, no ntimes
disp('parse without optional ntimes');
p.parse([5 6 7 8], 'title','mytitle');
inputs = p.Results

parse all options

inputs = 

    mainVector: [1 2 3 4]
        ntimes: 2
         title: 'mytitle'

parse without specifing title param-value pair

inputs = 

    mainVector: [1 2 3 4]
        ntimes: 3
         title: 'Default title'

parse without optional ntimes

inputs = 

    mainVector: [5 6 7 8]
        ntimes: 1
         title: 'mytitle'

You can see that the result is a struct with all the inputs broken out into fields. If an optional input was not specified, the default value is placed in the struct.

Use with a function
Of course, the purpose of this is easy input validation and organization within a function. Here’s a sample function and example of validation failure:

function myfun(input1,varargin)
p = inputParser;
p.addRequired('mainVector',@(x) length(x)>1);
p.addOptional('ntimes',1,@isscalar);
p.addParamValue('title','Default title',@isstr);

p.parse(input1,varargin{:})

Here we call the function with invalid arguments:

myfun([1 2 3],[1 2])

Error using myfun (line 7)
Argument 'ntimes' failed validation isscalar.

Our validation serves it purpose!

Let us know how if you use inputParser or another method for checking function input.