Public Member Functions | Static Public Member Functions

MArgParser Class Reference

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, 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] syntax the syntax object
[in] argList the argument list
[out] ReturnStatus the 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] flag the flag whose state is to be queried
[out] ReturnStatus the 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] ReturnStatus the 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] ReturnStatus the 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] flag the 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] flag flag whose parameter is being requested
[in] index index of the parameter to retrieve
[out] result value 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] flag flag whose parameter is being requested
[in] index index of the parameter to retrieve
[out] result value 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] flag flag whose parameter is being requested
[in] index index of the parameter to retrieve
[out] result value 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] flag flag whose parameter is being requested
[in] index index of the parameter to retrieve
[out] result value 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] flag flag whose parameter is being requested
[in] index index of the parameter to retrieve
[out] result value 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] flag flag whose parameter is being requested
[in] index index of the parameter to retrieve
[out] result value 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] flag flag whose parameter is being requested
[in] index index of the parameter to retrieve
[out] result value 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] flag flag whose parameter is being requested
[in] index index of the parameter to retrieve
[out] result value 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] flag flag whose parameter is being requested
[in] index index of the parameter to retrieve
[out] ReturnStatus the 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] flag flag whose parameter is being requested
[in] index index of the parameter to retrieve
[out] ReturnStatus the 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] flag flag whose parameter is being requested
[in] index index of the parameter to retrieve
[out] ReturnStatus the 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] flag flag whose parameter is being requested
[in] index index of the parameter to retrieve
[out] ReturnStatus the 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] flag flag whose parameter is being requested
[in] index index of the parameter to retrieve
[out] ReturnStatus the 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] flag flag whose parameter is being requested
[in] index index of the parameter to retrieve
[out] ReturnStatus the 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] flag flag whose parameter is being requested
[in] index index of the parameter to retrieve
[out] ReturnStatus the 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] flag flag whose position is being requested
[in] i desired instance of the flag on the command line
[out] position position 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] flag the flag whose parameters are being requested
[in] i the desired instance of the flag on the command line
[out] args the 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] index the index of the argument of the command
[out] result the 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] index the index of the argument of the command
[out] result the 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] index the index of the argument of the command
[out] result the 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] index the index of the argument of the command
[out] result the 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] index the index of the argument of the command
[out] result the 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] index the index of the argument of the command
[out] result the 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] index the index of the argument of the command
[out] result the 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] index the index of the argument to the command
[out] ReturnStatus the 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] index the index of the argument to the command
[out] ReturnStatus the 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] index the index of the argument to the command
[out] ReturnStatus the 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] index the index of the argument to the command
[out] ReturnStatus the 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] index the index of the argument to the command
[out] ReturnStatus the 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] index the index of the argument to the command
[out] ReturnStatus the 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] index the index of the argument to the command
[out] ReturnStatus the 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] result the 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