MArgParser Class Reference
[OpenMaya - API module for common classes]

#include <MArgParser.h>

Inheritance diagram for MArgParser:

[legend]

List of all members.

---

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 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 the MSyntax command contains the details on three types of arguments to commands:

• flags arguments preceded by a '-' character.
• command arguments required parameters that follow the flags
• objects an optional list of Maya objects or the contents of the selection list.

Once the syntax for your command has been specified, when the doIt method for the command it called, the provided MArgList instance can be passed to the MArgParser constructor along with the command's syntax object to parse those arguments. If the parsing is unsuccessful, then the provided command was syntactically invalid. If successful, the methods in this class can be used to extract the values of the arguments to the command.

The isFlagSet method can be used to find out if a particular flag argument was provided in the command invocation, and the getFlagArgument methods are used to return the value of that flag.

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

If the command requires objects then the getObjects methods are used to return those objects either as a selection list of as a list of strings.

Note:

command arguments and objects are incompatible and must not be combined in the syntax definition of a command. If both have been specified to the Syntax object, then neither the getCommandArgument() or getObjects() methods will work predictably.

Examples:

helixTool.cpp, and narrowPolyViewerCmd.cpp.

Public Member Functions
	MArgParser ()
	MArgParser (const MSyntax &syntax, const MArgList &argList, MStatus *ReturnStatus=NULL)
virtual	~MArgParser ()
bool	isFlagSet (const char *flag, MStatus *ReturnStatus=NULL) const
bool	isEdit (MStatus *ReturnStatus=NULL) const
bool	isQuery (MStatus *ReturnStatus=NULL) const
unsigned int	numberOfFlagsUsed () const
unsigned int	numberOfFlagUses (const char *flag) const
MStatus	getFlagArgument (const char *flag, unsigned int index, bool &result) const
MStatus	getFlagArgument (const char *flag, unsigned int index, int &result) const
MStatus	getFlagArgument (const char *flag, unsigned int index, double &result) const
MStatus	getFlagArgument (const char *flag, unsigned int index, MString &result) const
MStatus	getFlagArgument (const char *flag, unsigned int index, unsigned int &result) const
MStatus	getFlagArgument (const char *flag, unsigned int index, MDistance &result) const
MStatus	getFlagArgument (const char *flag, unsigned int index, MAngle &result) const
MStatus	getFlagArgument (const char *flag, unsigned int index, MTime &result) const
bool	flagArgumentBool (const char *flag, unsigned int index, MStatus *ReturnStatus=NULL) const
int	flagArgumentInt (const char *flag, unsigned int index, MStatus *ReturnStatus=NULL) const
double	flagArgumentDouble (const char *flag, unsigned int index, MStatus *ReturnStatus=NULL) const
MString	flagArgumentString (const char *flag, unsigned int index, MStatus *ReturnStatus=NULL) const
MDistance	flagArgumentMDistance (const char *flag, unsigned int index, MStatus *ReturnStatus=NULL) const
MAngle	flagArgumentMAngle (const char *flag, unsigned int index, MStatus *ReturnStatus=NULL) const
MTime	flagArgumentMTime (const char *flag, unsigned int index, MStatus *ReturnStatus=NULL) const
MStatus	getFlagArgumentPosition (const char *flag, unsigned int i, unsigned int &position) const
MStatus	getFlagArgumentList (const char *flag, unsigned int i, MArgList &args) const
MStatus	getCommandArgument (unsigned int index, bool &result) const
MStatus	getCommandArgument (unsigned int index, int &result) const
MStatus	getCommandArgument (unsigned int index, double &result) const
MStatus	getCommandArgument (unsigned int index, MString &result) const
MStatus	getCommandArgument (unsigned int index, MDistance &result) const
MStatus	getCommandArgument (unsigned int index, MAngle &result) const
MStatus	getCommandArgument (unsigned int index, MTime &result) const
bool	commandArgumentBool (unsigned int index, MStatus *ReturnStatus=NULL) const
int	commandArgumentInt (unsigned int index, MStatus *ReturnStatus=NULL) const
double	commandArgumentDouble (unsigned int index, MStatus *ReturnStatus=NULL) const
MString	commandArgumentString (unsigned int index, MStatus *ReturnStatus=NULL) const
MDistance	commandArgumentMDistance (unsigned int index, MStatus *ReturnStatus=NULL) const
MAngle	commandArgumentMAngle (unsigned int index, MStatus *ReturnStatus=NULL) const
MTime	commandArgumentMTime (unsigned int index, MStatus *ReturnStatus=NULL) const
MStatus	getObjects (MStringArray &result) const

---

Constructor & Destructor Documentation

MArgParser::MArgParser

(

)

The default class constructor.

MArgParser::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:

• MS::kSuccess operation successful
• MS::kFailure operation failed

MArgParser::~MArgParser

(

)

[virtual]

The class destructor.

---

Member Function Documentation

bool MArgParser::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:

• MS::kSuccess operation successful
• MS::kFailure operation failed

Examples:

flipUVCmd.cpp, fxManagerCmd.cpp, helixTool.cpp, narrowPolyViewerCmd.cpp, nodeCreatedCBCmd.cpp, renderViewInteractiveRenderCmd.cpp, renderViewRenderCmd.cpp, and renderViewRenderRegionCmd.cpp.

bool MArgParser::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:

• MS::kSuccess operation successful
• MS::kFailure operation failed

bool MArgParser::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:

• MS::kSuccess operation successful
• MS::kFailure operation failed

unsigned int MArgParser::numberOfFlagsUsed

(

)

const

Returns the number of flags given on the command line command line.

Returns:

Number of flags on the command line

unsigned int MArgParser::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 MArgParser::getFlagArgument	(	const char *	flag,
		unsigned int	index,
		bool &	result
	)			const

Gets the value of the requested flag argument to the given flag as a boolean.

Python Notes

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

Parameters:

[in]	flag	the flag whose argument is being requested
[in]	index	the index of the argument to the flag
[out]	result	the value of the argument as a boolean

Returns:

• MS::kSuccess operation successful
• MS::kFailure operation failed

Reimplemented in MArgDatabase.

Examples:

helixTool.cpp, and narrowPolyViewerCmd.cpp.

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

Gets the value of the requested flag argument to the given flag as a int.

Python Notes

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

Parameters:

[in]	flag	the flag whose argument is being requested
[in]	index	the index of the argument to the flag
[out]	result	the value of the argument as a int

Returns:

• MS::kSuccess operation successful
• MS::kFailure operation failed

Reimplemented in MArgDatabase.

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

Gets the value of the requested flag argument to the given flag as a double.

Python Notes

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

Parameters:

[in]	flag	the flag whose argument is being requested
[in]	index	the index of the argument to the flag
[out]	result	the value of the argument as a double

Returns:

• MS::kSuccess operation successful
• MS::kFailure operation failed

Reimplemented in MArgDatabase.

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

Gets the value of the requested flag argument to the given flag as an MString.

Python Notes

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

Parameters:

[in]	flag	the flag whose argument is being requested
[in]	index	the index of the argument to the flag
[out]	result	the value of the argument as an MString

Returns:

• MS::kSuccess operation successful
• MS::kFailure operation failed

Reimplemented in MArgDatabase.

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

Gets the value of the requested flag argument to the given flag as an unsigned int.

Python Notes

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

Parameters:

[in]	flag	the flag whose argument is being requested
[in]	index	the index of the argument to the flag
[out]	result	the value of the argument as an unsigned int

Returns:

• MS::kSuccess operation successful
• MS::kFailure operation failed

Reimplemented in MArgDatabase.

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

Gets the value of the requested flag argument to the given flag as an MDistance.

Python Notes

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

Parameters:

[in]	flag	the flag whose argument is being requested
[in]	index	the index of the argument to the flag
[out]	result	the value of the argument as an MDistance

Returns:

• MS::kSuccess operation successful
• MS::kFailure operation failed

Reimplemented in MArgDatabase.

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

Gets the value of the requested flag argument to the given flag as an MAngle.

Python Notes

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

Parameters:

[in]	flag	the flag whose argument is being requested
[in]	index	the index of the argument to the flag
[out]	result	the value of the argument as an MAngle

Returns:

• MS::kSuccess operation successful
• MS::kFailure operation failed

Reimplemented in MArgDatabase.

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

Gets the value of the requested flag argument to the given flag as an MTime.

Python Notes

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

Parameters:

[in]	flag	the flag whose argument is being requested
[in]	index	the index of the argument to the flag
[out]	result	the value of the argument as an MTime

Returns:

• MS::kSuccess operation successful
• MS::kFailure operation failed

Reimplemented in MArgDatabase.

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

Gets the value of the requested flag argument to the given flag as a boolean.

Parameters:

[in]	flag	the flag whose argument is being requested
[in]	index	the index of the argument to the flag
[out]	ReturnStatus	the return status

Returns:

The value of the argument as a boolean

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure operation failed

int MArgParser::flagArgumentInt	(	const char *	flag,
		unsigned int	index,
		MStatus *	ReturnStatus = NULL
	)			const

Gets the value of the requested flag argument to the given flag as a int.

Parameters:

[in]	flag	the flag whose argument is being requested
[in]	index	the index of the argument to the flag
[out]	ReturnStatus	the return status

Returns:

The value of the argument as an int

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure operation failed

double MArgParser::flagArgumentDouble	(	const char *	flag,
		unsigned int	index,
		MStatus *	ReturnStatus = NULL
	)			const

Gets the value of the requested flag argument to the given flag as a double.

Parameters:

[in]	flag	the flag whose argument is being requested
[in]	index	the index of the argument to the flag
[out]	ReturnStatus	the return status

Returns:

The value of the argument as a double

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure operation failed

MString MArgParser::flagArgumentString	(	const char *	flag,
		unsigned int	index,
		MStatus *	ReturnStatus = NULL
	)			const

Gets the value of the requested flag argument to the given flag as an MString.

Parameters:

[in]	flag	the flag whose argument is being requested
[in]	index	the index of the argument to the flag
[out]	ReturnStatus	the return status

Returns:

The value of the argument as a string

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure operation failed

MDistance MArgParser::flagArgumentMDistance	(	const char *	flag,
		unsigned int	index,
		MStatus *	ReturnStatus = NULL
	)			const

Gets the value of the requested flag argument to the given flag as an MDistance.

Parameters:

[in]	flag	the flag whose argument is being requested
[in]	index	the index of the argument to the flag
[out]	ReturnStatus	the return status

Returns:

The value of the argument as an MDistance

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure operation failed

MAngle MArgParser::flagArgumentMAngle	(	const char *	flag,
		unsigned int	index,
		MStatus *	ReturnStatus = NULL
	)			const

Gets the value of the requested flag argument to the given flag as an MAngle.

Parameters:

[in]	flag	the flag whose argument is being requested
[in]	index	the index of the argument to the flag
[out]	ReturnStatus	the return status

Returns:

The value of the argument as an MAngle

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure operation failed

MTime MArgParser::flagArgumentMTime	(	const char *	flag,
		unsigned int	index,
		MStatus *	ReturnStatus = NULL
	)			const

Gets the value of the requested flag argument to the given flag as an MTime.

Parameters:

[in]	flag	the flag whose argument is being requested
[in]	index	the index of the argument to the flag
[out]	ReturnStatus	the return status

Returns:

The value of the argument as an MTime

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure operation failed

MStatus MArgParser::getFlagArgumentPosition	(	const char *	flag,
		unsigned int	i,
		unsigned int &	position
	)			const

Returns the position in the command line of the i'th usage of a specified flag. This call is only valid if the flags has been marked as available for multi-usage with MSyntax::makeFlagMultiUse

Parameters:

[in]	flag	the flag whose argument is being requested
[in]	i	the desired instance of the flag on the command line
[out]	position	on return the position in the command line of the i'th usage of the specified flag

Returns:

• MS::kSuccess operation successful
• MS::kFailure operation failed

MStatus MArgParser::getFlagArgumentList	(	const char *	flag,
		unsigned int	i,
		MArgList &	args
	)			const

Returns an MArgList containing the arguments to the i'th usage of the specified flag. This call is only valid if the flags has been marked as available for multi-usage with MSyntax::makeFlagMultiUse

Parameters:

[in]	flag	the flag whose argument is being requested
[in]	i	the desired instance of the flag on the command line
[out]	args	on return the arguments to the i'th usage of the specified flag

Returns:

• MS::kSuccess operation successful
• MS::kFailure operation failed

MStatus MArgParser::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:

• MS::kSuccess operation successful
• MS::kFailure operation failed

Reimplemented in MArgDatabase.

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

Gets the value of the requested command argument to the command as a 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:

• MS::kSuccess operation successful
• MS::kFailure operation failed

Reimplemented in MArgDatabase.

MStatus MArgParser::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:

• MS::kSuccess operation successful
• MS::kFailure operation failed

Reimplemented in MArgDatabase.

MStatus MArgParser::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:

• MS::kSuccess operation successful
• MS::kFailure operation failed

Reimplemented in MArgDatabase.

MStatus MArgParser::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:

• MS::kSuccess operation successful
• MS::kFailure operation failed

Reimplemented in MArgDatabase.

MStatus MArgParser::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:

• MS::kSuccess operation successful
• MS::kFailure operation failed

Reimplemented in MArgDatabase.

MStatus MArgParser::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:

• MS::kSuccess operation successful
• MS::kFailure operation failed

Reimplemented in MArgDatabase.

bool MArgParser::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:

• MS::kSuccess operation successful
• MS::kFailure operation failed

int MArgParser::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:

• MS::kSuccess operation successful
• MS::kFailure operation failed

double MArgParser::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:

• MS::kSuccess operation successful
• MS::kFailure operation failed

MString MArgParser::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:

• MS::kSuccess operation successful
• MS::kFailure operation failed

MDistance MArgParser::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:

• MS::kSuccess operation successful
• MS::kFailure operation failed

MAngle MArgParser::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:

• MS::kSuccess operation successful
• MS::kFailure operation failed

MTime MArgParser::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:

• MS::kSuccess operation successful
• MS::kFailure operation failed

MStatus MArgParser::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:

• MS::kSuccess operation successful
• MS::kFailure operation failed

Reimplemented in MArgDatabase.