parse (inputParser) - Parse and validate named inputs

Syntax

p.parse(arglist)
parse(p, arglist)

Description

p.parse(arglist) is part of the input argument checking mechanism employed by the MATLAB Input Parser utility. Input Parser code residing in a function that receives data from calling functions identifies what types of arguments are acceptable. The parse function parses and validates the inputs named in arglist.

parse(p, arglist)is functionally the same as the syntax above.

For more information on the inputParser class, see Validating Inputs with Input Parser in the MATLAB Programming Fundamentals documentation.

Examples

This example writes a function called photoPrint that uses the Input Parser to check arguments passed to it. This function accepts up to eight input arguments. When called with the full set of inputs, the syntax is:

photoPrint(filename, format, finish, colorCode, ...
   'horizDim', hDim, 'vertDim', vDim);

Only the first two of these inputs are defined as required arguments; the rest are optional. The 'horizDim' and 'vertDim' arguments are in parameter name/value format. Pair the 'horizDim' parameter name with its value hDim, and likewise the 'vertDim' name with its value vDim. Here are several possible calling syntaxes for the function:

photoPrint(filename, format);
photoPrint(filename, format, finish)
photoPrint(filename, format, finish, colorCode)
photoPrint(filename, format, finish, colorCode, ...
   'horizDim', hDim)
photoPrint(filename, format, finish, colorCode, ...
   'vertDim', vDim)

Begin writing the example function photoPrint by entering the following two statements into a file named photoPrint.m. The second statement calls the class constructor for inputParser to create an instance p of the class. This class instance, or object, gives you access to all of the methods and properties of the class:

function photoPrint(filename, format, varargin)
p = inputParser;    % Create an instance of the class.

Add the following code to the photoPrint function. These statements call the addRequired, addOptional, and addParamValue methods to define the types of input data one can pass to this function:

p.addRequired('filename', @ischar);
p.addRequired('format', @(x)strcmp(x,'jpeg') 
   || strcmp(x,'tiff'));

p.addOptional('finish', 'glossy', @(x)strcmpi(x,'flat') ...
   || strcmpi(x,'glossy'));
p.addOptional('colorCode', 'CMYK', @(x)strcmpi(x,'CMYK') ...
   || strcmpi(x,'RGB'));

p.addParamValue('horizDim', 6, @(x)isnumeric(x) && x<=20));
p.addParamValue('vertDim', 4, @(x)isnumeric(x) && x<=20));

Just after this, call the parse method to parse and validate the inputs. MATLAB puts the results of the parse into a property named Results:

p.parse(filename, format, varargin{:});
p.Results

Save and execute the file, passing the required and any number of the optional input arguments. Examining p.Results displays the name of each input as a field, and the value of each input as the value of that field:

photoPrint('myPhoto', 'tiff', 'flat', 'RGB', ...
           'horizDim', 10, 'vertDim', 8)

The following inputs have been received and validated:
    colorCode: 'RGB'
     filename: 'myPhoto'
       finish: 'flat'
       format: 'tiff'
     horizDim: 10
      vertDim: 8

See Also

addOptional(inputParser) | addParamValue(inputParser) | addRequired(inputParser) | createCopy(inputParser) | inputParser

© 1984-2012- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS