MATLAB Community

MATLAB, community & more

Parsing Inputs 5

Posted by Michael Katz,

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.

76 views (last 30 days)  | |

Comments

To leave a comment, please click here to sign in to your MathWorks Account or create a new one.