Public Member Functions | Static Public Member Functions

MArgParser Class Reference

This reference page is linked to from the following overview topics: Command Arguments and Flags, Syntax objects, MPxToolCommand, Using the Maya Python API, Differences Between Maya's C++ and Python APIs.


Search for all occurrences

Detailed Description

Command argument list parser.

This class is used to parse and store all of the flags, arguments and objects which are passed to a command. The MArgParser constructor accepts an MSyntax object, which describes the format for a command, and uses it to parse the command arguments into a form which is easy to query. The documentation for MSyntax describes three types of arguments to commands:

A command may accept either command arguments or objects, but not both.

The flag names, numbers and types of parameters accepted by each flag, number and types of command arguments, range of objects accepted and whether Maya's current selection can be used in place of missing objects, are all determined by the MSyntax object passed to MArgParser's constructor.

In normal usage a command's doIt method would create an MArgParser object by passing it an MSyntax object which describes the command's syntax and an MArgList containing the command line arguments specified in the command's invocation. A successful return status from the constructor would mean that command invocation was syntactically correct and the other MArgList methods could be used to extract the values of the arguments to the command. A failure return status would mean that the command invocation was syntactically incorrect and the command should return without attempting any further processing of its arguments. Note that in the case of a failure MArgParser will automatically display an appropriate error message in the Script Editor so the command is freed from having to do that itself.

The isFlagSet method can be used to find out if a particular flag argument was provided in the command invocation.

If a flag accepts one or more parameters, the getFlagArgument and flagArgument* methods can be used to return its parameters.

If the same flag appears multiple times in the command line (i.e. it was specified with MSyntax::makeFlagMultiUse() to allow multiple uses per command invocation) the getFlagArgument and flagArgument* methods will only be able to return parameters for the first use of the flag. However, getFlagArgumentList() provides the ability to access any of a multi-use flag's instances.

If the command requires command arguments (i.e. the addArg method was used to construct the syntax object), then getCommandArgument and commandArgument* methods can be used to return the values of those arguments.

If the command requires objects then the getObjects method can be used to return those objects as an array of strings.

Examples:

helixTool.cpp, hlslShader.cpp, and narrowPolyViewerCmd.cpp.

#include <MArgParser.h>

Inheritance diagram for MArgParser:
Inheritance graph
[legend]

List of all members.

Public Member Functions

 MArgParser ()
 The default class constructor.
 MArgParser (const MSyntax &syntax, const MArgList &argList, MStatus *ReturnStatus=NULL)
 Creates an MArgParser object by using the data in 'syntax' to parse the argList.
virtual ~MArgParser ()
 The class destructor.
bool isFlagSet (const char *flag, MStatus *ReturnStatus=NULL) const
 Queries the arguments to the command to determine if the given flag is set.
bool isEdit (MStatus *ReturnStatus=NULL) const
 Determines if the edit flag was one of the arguments to the command.
bool isQuery (MStatus *ReturnStatus=NULL) const
 Determines if the query flag was one of the arguments to the command.
unsigned int numberOfFlagsUsed () const
 Returns the number of flags given on the command line.
unsigned int numberOfFlagUses (const char *flag) const
 Returns the number of times the given flag was used on the command line.
MStatus getFlagArgument (const char *flag, unsigned int index, bool &result) const
 Gets the value of the 'index'th parameter of the given flag as a boolean.
MStatus getFlagArgument (const char *flag, unsigned int index, int &result) const
 Gets the value of the 'index'th parameter of the given flag as an int.
MStatus getFlagArgument (const char *flag, unsigned int index, double &result) const
 Gets the value of the 'index'th parameter of the given flag as a double.
MStatus getFlagArgument (const char *flag, unsigned int index, MString &result) const
 Gets the value of the 'index'th parameter of the given flag as an MString.
MStatus getFlagArgument (const char *flag, unsigned int index, unsigned int &result) const
 Gets the value of the 'index'th parameter of the given flag as an unsigned int.
MStatus getFlagArgument (const char *flag, unsigned int index, MDistance &result) const
 Gets the value of the 'index'th parameter of the given flag as an MDistance.
MStatus getFlagArgument (const char *flag, unsigned int index, MAngle &result) const
 Gets the value of the 'index'th parameter of the given flag as an MAngle.
MStatus getFlagArgument (const char *flag, unsigned int index, MTime &result) const
 Gets the value of the 'index'th parameter of the given flag as an MTime.
bool flagArgumentBool (const char *flag, unsigned int index, MStatus *ReturnStatus=NULL) const
 Gets the value of the 'index'th parameter of the given flag as a boolean.
int flagArgumentInt (const char *flag, unsigned int index, MStatus *ReturnStatus=NULL) const
 Gets the value of the 'index'th parameter of the given flag as an int.
double flagArgumentDouble (const char *flag, unsigned int index, MStatus *ReturnStatus=NULL) const
 Gets the value of the 'index'th parameter of the given flag as a double.
MString flagArgumentString (const char *flag, unsigned int index, MStatus *ReturnStatus=NULL) const
 Gets the value of the 'index'th parameter of the given flag as an MString.
MDistance flagArgumentMDistance (const char *flag, unsigned int index, MStatus *ReturnStatus=NULL) const
 Gets the value of the 'index'th parameter of the given flag as an MDistance.
MAngle flagArgumentMAngle (const char *flag, unsigned int index, MStatus *ReturnStatus=NULL) const
 Gets the value of the 'index'th parameter of the given flag as an MAngle.
MTime flagArgumentMTime (const char *flag, unsigned int index, MStatus *ReturnStatus=NULL) const
 Gets the value of the 'index'th parameter of the given flag as an MTime.
MStatus getFlagArgumentPosition (const char *flag, unsigned int i, unsigned int &position) const
 Returns the position in the command line of the i'th usage of the specified flag.
MStatus getFlagArgumentList (const char *flag, unsigned int i, MArgList &args) const
 Returns an MArgList containing the parameters to the i'th usage of the specified flag.
MStatus getCommandArgument (unsigned int index, bool &result) const
 Gets the value of the requested command argument to the command as a boolean.
MStatus getCommandArgument (unsigned int index, int &result) const
 Gets the value of the requested command argument to the command as an int.
MStatus getCommandArgument (unsigned int index, double &result) const
 Gets the value of the requested command argument to the command as a double.
MStatus getCommandArgument (unsigned int index, MString &result) const
 Gets the value of the requested command argument to the command as an MString.
MStatus getCommandArgument (unsigned int index, MDistance &result) const
 Gets the value of the requested command argument to the command as an MDistance.
MStatus getCommandArgument (unsigned int index, MAngle &result) const
 Gets the value of the requested command argument to the command as an MAngle.
MStatus getCommandArgument (unsigned int index, MTime &result) const
 Gets the value of the requested command argument to the command as an MTime.
bool commandArgumentBool (unsigned int index, MStatus *ReturnStatus=NULL) const
 Gets the value of the requested command argument as a boolean.
int commandArgumentInt (unsigned int index, MStatus *ReturnStatus=NULL) const
 Gets the value of the requested command argument as an int.
double commandArgumentDouble (unsigned int index, MStatus *ReturnStatus=NULL) const
 Gets the value of the requested command argument as a double.
MString commandArgumentString (unsigned int index, MStatus *ReturnStatus=NULL) const
 Gets the value of the requested command argument as a string.
MDistance commandArgumentMDistance (unsigned int index, MStatus *ReturnStatus=NULL) const
 Gets the value of the requested command argument as a MDistance.
MAngle commandArgumentMAngle (unsigned int index, MStatus *ReturnStatus=NULL) const
 Gets the value of the requested command argument as a MAngle.
MTime commandArgumentMTime (unsigned int index, MStatus *ReturnStatus=NULL) const
 Gets the value of the requested command argument as a MTime.
MStatus getObjects (MStringArray &result) const
 Gets the list of objects passed to the command as an array of strings.

Static Public Member Functions

static const char * className ()
 Returns the name of this class.

Constructor & Destructor Documentation

MArgParser ( const MSyntax syntax,
const MArgList argList,
MStatus ReturnStatus = NULL 
)

Creates an MArgParser object by using the data in 'syntax' to parse the argList.

Parameters:
[in]syntaxthe syntax object
[in]argListthe argument list
[out]ReturnStatusthe status codes
Status Codes:

Member Function Documentation

bool isFlagSet ( const char *  flag,
MStatus ReturnStatus = NULL 
) const

Queries the arguments to the command to determine if the given flag is set.

Parameters:
[in]flagthe flag whose state is to be queried
[out]ReturnStatusthe return status
Returns:
  • true if given flag is set
  • false if given flag is not set
Status Codes:
Examples:
flipUVCmd.cpp, fxManagerCmd.cpp, helixTool.cpp, narrowPolyViewerCmd.cpp, nodeCreatedCBCmd.cpp, renderViewInteractiveRenderCmd.cpp, renderViewRenderCmd.cpp, and renderViewRenderRegionCmd.cpp.
bool isEdit ( MStatus ReturnStatus = NULL) const

Determines if the edit flag was one of the arguments to the command.

The edit flag in its short form is "-e", and in its int form is "-edit".

Parameters:
[out]ReturnStatusthe return status
Returns:
  • true if edit flag is set
  • false if edit flag is not set
Status Codes:
bool isQuery ( MStatus ReturnStatus = NULL) const

Determines if the query flag was one of the arguments to the command.

The query flag in its short form is "-q", and in its int form is "-query".

Parameters:
[out]ReturnStatusthe return status
Returns:
  • true if query flag is set
  • false if query flag is not set
Status Codes:
unsigned int numberOfFlagsUsed ( ) const

Returns the number of flags given on the command line.

If a given flag appears multiple times it is only counted once. The numberOfFlagUses() method can be used to determine the number of times that a multi-use flag appears in the command line.

Returns:
Number of flags on the command line
unsigned int numberOfFlagUses ( const char *  flag) const

Returns the number of times the given flag was used on the command line.

Parameters:
[in]flagthe flag whose argument is being requested
Returns:
Number of times the given flag was used on the command line
MStatus getFlagArgument ( const char *  flag,
unsigned int  index,
bool &  result 
) const

Gets the value of the 'index'th parameter of the given flag as a boolean.

Python Notes

This method is not available in Python. Please see the flagArgumentBool() method

Parameters:
[in]flagflag whose parameter is being requested
[in]indexindex of the parameter to retrieve
[out]resultvalue of the parameter as a boolean
Returns:

Reimplemented in MArgDatabase.

Examples:
helixTool.cpp, and narrowPolyViewerCmd.cpp.
MStatus getFlagArgument ( const char *  flag,
unsigned int  index,
int &  result 
) const

Gets the value of the 'index'th parameter of the given flag as an int.

Python Notes

This method is not available in Python. Please see the flagArgumentInt() method

Parameters:
[in]flagflag whose parameter is being requested
[in]indexindex of the parameter to retrieve
[out]resultvalue of the parameter as an int
Returns:

Reimplemented in MArgDatabase.

MStatus getFlagArgument ( const char *  flag,
unsigned int  index,
double &  result 
) const

Gets the value of the 'index'th parameter of the given flag as a double.

Python Notes

This method is not available in Python. Please see the flagArgumentDouble() method

Parameters:
[in]flagflag whose parameter is being requested
[in]indexindex of the parameter to retrieve
[out]resultvalue of the parameter as a double
Returns:

Reimplemented in MArgDatabase.

MStatus getFlagArgument ( const char *  flag,
unsigned int  index,
MString result 
) const

Gets the value of the 'index'th parameter of the given flag as an MString.

Python Notes

This method is not available in Python. Please see the flagArgumentString() method

Parameters:
[in]flagflag whose parameter is being requested
[in]indexindex of the parameter to retrieve
[out]resultvalue of the parameter as an MString
Returns:

Reimplemented in MArgDatabase.

MStatus getFlagArgument ( const char *  flag,
unsigned int  index,
unsigned int &  result 
) const

Gets the value of the 'index'th parameter of the given flag as an unsigned int.

Python Notes

This method is not available in Python. Please see the flagArgumentInt() method

Parameters:
[in]flagflag whose parameter is being requested
[in]indexindex of the parameter to retrieve
[out]resultvalue of the parameter as an unsigned int
Returns:

Reimplemented in MArgDatabase.

MStatus getFlagArgument ( const char *  flag,
unsigned int  index,
MDistance result 
) const

Gets the value of the 'index'th parameter of the given flag as an MDistance.

Python Notes

This method is not available in Python. Please see the flagArgumentMDistance() method

Parameters:
[in]flagflag whose parameter is being requested
[in]indexindex of the parameter to retrieve
[out]resultvalue of the parameter as an MDistance
Returns:

Reimplemented in MArgDatabase.

MStatus getFlagArgument ( const char *  flag,
unsigned int  index,
MAngle result 
) const

Gets the value of the 'index'th parameter of the given flag as an MAngle.

Python Notes

This method is not available in Python. Please see the flagArgumentMAngle() method

Parameters:
[in]flagflag whose parameter is being requested
[in]indexindex of the parameter to retrieve
[out]resultvalue of the parameter as an MAngle
Returns:

Reimplemented in MArgDatabase.

MStatus getFlagArgument ( const char *  flag,
unsigned int  index,
MTime result 
) const

Gets the value of the 'index'th parameter of the given flag as an MTime.

Python Notes

This method is not available in Python. Please see the flagArgumentMTime() method

Parameters:
[in]flagflag whose parameter is being requested
[in]indexindex of the parameter to retrieve
[out]resultvalue of the parameter as an MTime
Returns:

Reimplemented in MArgDatabase.

bool flagArgumentBool ( const char *  flag,
unsigned int  index,
MStatus ReturnStatus = NULL 
) const

Gets the value of the 'index'th parameter of the given flag as a boolean.

Parameters:
[in]flagflag whose parameter is being requested
[in]indexindex of the parameter to retrieve
[out]ReturnStatusthe return status
Returns:
The value of the parameter as a boolean
Status Codes:
int flagArgumentInt ( const char *  flag,
unsigned int  index,
MStatus ReturnStatus = NULL 
) const

Gets the value of the 'index'th parameter of the given flag as an int.

Parameters:
[in]flagflag whose parameter is being requested
[in]indexindex of the parameter to retrieve
[out]ReturnStatusthe return status
Returns:
The value of the parameter as an int
Status Codes:
double flagArgumentDouble ( const char *  flag,
unsigned int  index,
MStatus ReturnStatus = NULL 
) const

Gets the value of the 'index'th parameter of the given flag as a double.

Parameters:
[in]flagflag whose parameter is being requested
[in]indexindex of the parameter to retrieve
[out]ReturnStatusthe return status
Returns:
The value of the parameter as a double
Status Codes:
MString flagArgumentString ( const char *  flag,
unsigned int  index,
MStatus ReturnStatus = NULL 
) const

Gets the value of the 'index'th parameter of the given flag as an MString.

Parameters:
[in]flagflag whose parameter is being requested
[in]indexindex of the parameter to retrieve
[out]ReturnStatusthe return status
Returns:
The value of the parameter as a string
Status Codes:
MDistance flagArgumentMDistance ( const char *  flag,
unsigned int  index,
MStatus ReturnStatus = NULL 
) const

Gets the value of the 'index'th parameter of the given flag as an MDistance.

Parameters:
[in]flagflag whose parameter is being requested
[in]indexindex of the parameter to retrieve
[out]ReturnStatusthe return status
Returns:
The value of the parameter as an MDistance
Status Codes:
MAngle flagArgumentMAngle ( const char *  flag,
unsigned int  index,
MStatus ReturnStatus = NULL 
) const

Gets the value of the 'index'th parameter of the given flag as an MAngle.

Parameters:
[in]flagflag whose parameter is being requested
[in]indexindex of the parameter to retrieve
[out]ReturnStatusthe return status
Returns:
The value of the parameter as an MAngle
Status Codes:
MTime flagArgumentMTime ( const char *  flag,
unsigned int  index,
MStatus ReturnStatus = NULL 
) const

Gets the value of the 'index'th parameter of the given flag as an MTime.

Parameters:
[in]flagflag whose parameter is being requested
[in]indexindex of the parameter to retrieve
[out]ReturnStatusthe return status
Returns:
The value of the parameter as an MTime
Status Codes:
MStatus getFlagArgumentPosition ( const char *  flag,
unsigned int  i,
unsigned int &  position 
) const

Returns the position in the command line of the i'th usage of the specified flag.

This call is only valid if the flag has been marked as available for multi-usage with MSyntax::makeFlagMultiUse

Parameters:
[in]flagflag whose position is being requested
[in]idesired instance of the flag on the command line
[out]positionposition in the command line of the i'th usage of the specified flag
Returns:
MStatus getFlagArgumentList ( const char *  flag,
unsigned int  i,
MArgList args 
) const

Returns an MArgList containing the parameters to the i'th usage of the specified flag.

This call is only valid if the flag has been marked as available for multi-usage with MSyntax::makeFlagMultiUse

Parameters:
[in]flagthe flag whose parameters are being requested
[in]ithe desired instance of the flag on the command line
[out]argsthe parameters to the i'th usage of the specified flag
Returns:
MStatus getCommandArgument ( unsigned int  index,
bool &  result 
) const

Gets the value of the requested command argument to the command as a boolean.

Python Notes

This method is not available in Python. Please see the commandArgumentBool() method

Parameters:
[in]indexthe index of the argument of the command
[out]resultthe value of the argument as a boolean
Returns:

Reimplemented in MArgDatabase.

MStatus getCommandArgument ( unsigned int  index,
int &  result 
) const

Gets the value of the requested command argument to the command as an int.

Python Notes

This method is not available in Python. Please see the commandArgumentBool() method

Parameters:
[in]indexthe index of the argument of the command
[out]resultthe value of the argument as a int
Returns:

Reimplemented in MArgDatabase.

MStatus getCommandArgument ( unsigned int  index,
double &  result 
) const

Gets the value of the requested command argument to the command as a double.

Python Notes

This method is not available in Python. Please see the commandArgumentBool() method

Parameters:
[in]indexthe index of the argument of the command
[out]resultthe value of the argument as a double
Returns:

Reimplemented in MArgDatabase.

MStatus getCommandArgument ( unsigned int  index,
MString result 
) const

Gets the value of the requested command argument to the command as an MString.

Python Notes

This method is not available in Python. Please see the commandArgumentBool() method

Parameters:
[in]indexthe index of the argument of the command
[out]resultthe value of the argument as an MString
Returns:

Reimplemented in MArgDatabase.

MStatus getCommandArgument ( unsigned int  index,
MDistance result 
) const

Gets the value of the requested command argument to the command as an MDistance.

Python Notes

This method is not available in Python. Please see the commandArgumentBool() method

Parameters:
[in]indexthe index of the argument of the command
[out]resultthe value of the argument as an MDistance
Returns:

Reimplemented in MArgDatabase.

MStatus getCommandArgument ( unsigned int  index,
MAngle result 
) const

Gets the value of the requested command argument to the command as an MAngle.

Python Notes

This method is not available in Python. Please see the commandArgumentBool() method

Parameters:
[in]indexthe index of the argument of the command
[out]resultthe value of the argument as an MAngle
Returns:

Reimplemented in MArgDatabase.

MStatus getCommandArgument ( unsigned int  index,
MTime result 
) const

Gets the value of the requested command argument to the command as an MTime.

Python Notes

This method is not available in Python. Please see the commandArgumentBool() method

Parameters:
[in]indexthe index of the argument of the command
[out]resultthe value of the argument as an MTime
Returns:

Reimplemented in MArgDatabase.

bool commandArgumentBool ( unsigned int  index,
MStatus ReturnStatus = NULL 
) const

Gets the value of the requested command argument as a boolean.

Parameters:
[in]indexthe index of the argument to the command
[out]ReturnStatusthe return status
Returns:
The value of the argument as a boolean
Status Codes:
int commandArgumentInt ( unsigned int  index,
MStatus ReturnStatus = NULL 
) const

Gets the value of the requested command argument as an int.

Parameters:
[in]indexthe index of the argument to the command
[out]ReturnStatusthe return status
Returns:
The value of the argument as an int
Status Codes:
double commandArgumentDouble ( unsigned int  index,
MStatus ReturnStatus = NULL 
) const

Gets the value of the requested command argument as a double.

Parameters:
[in]indexthe index of the argument to the command
[out]ReturnStatusthe return status
Returns:
The value of the argument as a double
Status Codes:
MString commandArgumentString ( unsigned int  index,
MStatus ReturnStatus = NULL 
) const

Gets the value of the requested command argument as a string.

Parameters:
[in]indexthe index of the argument to the command
[out]ReturnStatusthe return status
Returns:
The value of the argument as a string
Status Codes:
MDistance commandArgumentMDistance ( unsigned int  index,
MStatus ReturnStatus = NULL 
) const

Gets the value of the requested command argument as a MDistance.

Parameters:
[in]indexthe index of the argument to the command
[out]ReturnStatusthe return status
Returns:
The value of the argument as a MDistance
Status Codes:
MAngle commandArgumentMAngle ( unsigned int  index,
MStatus ReturnStatus = NULL 
) const

Gets the value of the requested command argument as a MAngle.

Parameters:
[in]indexthe index of the argument to the command
[out]ReturnStatusthe return status
Returns:
The value of the argument as a MAngle
Status Codes:
MTime commandArgumentMTime ( unsigned int  index,
MStatus ReturnStatus = NULL 
) const

Gets the value of the requested command argument as a MTime.

Parameters:
[in]indexthe index of the argument to the command
[out]ReturnStatusthe return status
Returns:
The value of the argument as a MTime
Status Codes:
MStatus getObjects ( MStringArray result) const

Gets the list of objects passed to the command as an array of strings.

Parameters:
[out]resultthe list of objects passed to the command as an MStringArray
Returns:

Reimplemented in MArgDatabase.

const char * className ( ) [static]

Returns the name of this class.

Returns:
Name of this class.

Reimplemented in MArgDatabase.


MArgParser MArgParser MArgParser MArgParser MArgParser MArgParser MArgParser MArgParser MArgParser MArgParser
MArgParser MArgParser MArgParser MArgParser MArgParser MArgParser MArgParser MArgParser MArgParser MArgParser