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
% 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.addParamValue('title','Default title',@isstr);


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.


Comments are closed.

5 CommentsOldest to Newest

James Myatt replied on : 1 of 5

That looks great. I’ve created functions and classes to do something very similar in the past. When was this functionality added?

Nate replied on : 3 of 5

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?

Michael Katz replied on : 4 of 5

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.

Felipe replied on : 5 of 5

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