MATLAB Spoken Here

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.

5 CommentsOldest to Newest

I have recently discovered and deployed inputParser in some code. I wonder if I am the only one who thinks that it would be improved by accepting custom error messages as an argument?

@Nate,
I let the developers know your suggestion. I’m not sure what’s a better workaround, using a TRY/CATCH block and throwing your own ERROR, or just doing the validation yourself with an IF to throw a custom message.

Hi, do you know how i can parse a NC Code?

That is like this:

N10 O005

N130 X7 Z-2

N20 G21

N140 Z-5.5

N30 [BILLET X19 Z50

N150 G03 X11 Z-7.5 R2

N40 G98

N160 G02 X16 Z-10 R2.5

N50 G28 U0 W0

N170 G01 Z-15

N60 M06 T01

N180 X18.7 Z-18

N70 G97 S2500 M03

Because i need to split the values in colums like

x | y | z | G | M | F | S |

And the values in each point

These postings are the author's and don't necessarily represent the opinions of MathWorks.