configInputParser: Readme for configInputParser (R2007a) - File Exchange

Code covered by the BSD License

Highlights from
configInputParser

configInputParser(xmlConfigFi... CONFIGINPUTPARSER configures InputParser based on XML file
Readme for configInputParser ...
View all files

from configInputParser by Luca Balbi
configures an inputParser object with the configuration contained in an XML file

Readme for configInputParser (R2007a)

This files gives a summary of the usage of configInputParser and of the companion argument configuration XML file.

Warning: in the author's opinion, information provided here is accurate as for the 7.4 (R2007a) release; the software may need some changes for future version, especially if the inputParser and/or XML handling functions should change.

Usage

configInputParser is used to define an inputParser object, reading its configuration from an XML file.

For an explanation of the XML syntax for the various types of configuration, see the XML file syntax section.

Example

>> MyIP = configInputParser('sampleConfig.xml');

This example parses the sampleConfig.xml file and yields an inputParser object with the settings specified in the XML file.

XML file syntax

The file is written with a fully compliant XML syntax, but some subtleties are needed in order to flexibly specify all the data types MATLAB can handle.

For instance, in principle all XML data can be considered a string, while MATLAB handles strings differently from numbers. So, as a general rule, data follow the MATLAB syntax (actually, for the technically oriented, all strings are eval'ed into MATLAB variables after parsing). Let us see the main conventions that must be followed:

MATLAB strings are enclosed in single quotes. So, the XML content for an argument which bears my name will be 'Luca' and not simply Luca.
Other types of data are not subject to a particular syntax. So, numbers and quantities as pi, empty sets as [], vectors as [1:3], function handles as @ischar and even function results such as magic(5) are no problem.
A word of caution for some characters which have a special meaning in XML and thus must be escaped, such as &; neglecting this escaping will lead to rather obscure parse error inside xmlread.

See also the sample XML file provided, it shows in practice all these conventions.

The \ParseInputConfiguration\Properties section

This section specifies the inputParser object properties, namely, at the time of the MATLAB R2007a release:

CaseSensitive (logical scalar): Specifies whether argument names are to be matched by actual arguments in a case-sensitive way (true) or in a case-sensitive way (false).
FunctionName (string): Specifies the function name to be output in argument parse error messages.
KeepUnmatched (logical scalar): Specifies whether additional unknown arguments should be kept and added to the parsing results (true), or parsing should be stopped with an error (false).
StructExpand (logical scalar): Specifies whether a structure should be accepted as an input as a replacement of a list of individual argument-value arguments (true), or the structure should be treated as a normal argument (false).

All properties are written inside an XML node named after the property.

Note: the MATLAB code parsing this section uses dynamic names. Should new properties be added in future releases of MATLAB, extending the XML with the new property names will dynamically set the new inputParses properties without need to review the MATLAB code.

The \ParseInputConfiguration\Arguments section

This section contains the settings pertaining to the various function argument which are being defined. The section may contain one or more Argument nodes, described below.

The Argument node

Each node defines a single argument. Every argument has a name, a type, a default value (if applicable) and optionally a validator function handle.

The configuration of an argument is dependent on the argument type, as is explained below.

Required arguments

Name (string): The name of the argument.
Type (string): 'Required': this kind of argument must be specified in the function call.
Validator (optional, function handle): A valid Matlab (possibly anonymous) function handle, used for validation of the argument value: it must return true if the argument is valid, false otherwise.

Optional arguments

Name (string): The name of the argument.
Type (string): 'Optional': this kind of argument may or may not be specified in the function call: in the latter case, the default value is used.
DefaultValue (any legal Matlab type): The value to be used when the argument is not specified.
Validator (optional, function handle): A valid Matlab (possibly anonymous) function handle, used for validation of the argument value: it must return true if the argument is valid, false otherwise.

Argument-value pair arguments

This kind of argument differs from the optional one in that it is passed in the function call by specifying a name-value pair.

Name (string): The name of the argument.
Type (string): 'ParameterValue': this kind of argument may or may not be specified in the function call: in the latter case, the default value is used. If specified, a parameter-value pair syntax must be used.
DefaultValue (any legal Matlab type): The value to be used when the argument is not specified.
Validator (optional, function handle): A valid Matlab (possibly anonymous) function handle, used for validation of the argument value: it must return true if the argument is valid, false otherwise.

Ancillary files

Some ancillary files are provided along with the M and XML files. They are useful for developing, checking and displaying the contents of the XML file.

configInputParser.xsd: XML Schema grammar file. An XML file valid against this Schema should work fine.
configInputParserHTML.xsl: An XSLT stylesheet for transforming the XML file into HTML, which can be displayed in a Web browser. This can be done also via Matlab:
>> xslt sampleconfig.xml configInputParserHTML.xsl -web

Luca Balbi

Highlights from configInputParser