Command argument list parser. More...

#include <MArgParser.h>

Inheritance diagram for MArgParser:

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. More...

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. More...

bool	isEdit (MStatus *ReturnStatus=NULL) const
	Determines if the edit flag was one of the arguments to the command. More...

bool	isQuery (MStatus *ReturnStatus=NULL) const
	Determines if the query flag was one of the arguments to the command. More...

unsigned int	numberOfFlagsUsed () const
	Returns the number of flags given on the command line. More...

unsigned int	numberOfFlagUses (const char *flag) const
	Returns the number of times the given flag was used on the command line. More...

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. More...

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. More...

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. More...

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. More...

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. More...

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. More...

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. More...

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. More...

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. More...

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. More...

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. More...

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. More...

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. More...

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. More...

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. More...

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. More...

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. More...

MStatus	getCommandArgument (unsigned int index, bool &result) const
	Gets the value of the requested command argument to the command as a boolean. More...

MStatus	getCommandArgument (unsigned int index, int &result) const
	Gets the value of the requested command argument to the command as an int. More...

MStatus	getCommandArgument (unsigned int index, double &result) const
	Gets the value of the requested command argument to the command as a double. More...

MStatus	getCommandArgument (unsigned int index, MString &result) const
	Gets the value of the requested command argument to the command as an MString. More...

MStatus	getCommandArgument (unsigned int index, MDistance &result) const
	Gets the value of the requested command argument to the command as an MDistance. More...

MStatus	getCommandArgument (unsigned int index, MAngle &result) const
	Gets the value of the requested command argument to the command as an MAngle. More...

MStatus	getCommandArgument (unsigned int index, MTime &result) const
	Gets the value of the requested command argument to the command as an MTime. More...

bool	commandArgumentBool (unsigned int index, MStatus *ReturnStatus=NULL) const
	Gets the value of the requested command argument as a boolean. More...

int	commandArgumentInt (unsigned int index, MStatus *ReturnStatus=NULL) const
	Gets the value of the requested command argument as an int. More...

double	commandArgumentDouble (unsigned int index, MStatus *ReturnStatus=NULL) const
	Gets the value of the requested command argument as a double. More...

MString	commandArgumentString (unsigned int index, MStatus *ReturnStatus=NULL) const
	Gets the value of the requested command argument as a string. More...

MDistance	commandArgumentMDistance (unsigned int index, MStatus *ReturnStatus=NULL) const
	Gets the value of the requested command argument as a MDistance. More...

MAngle	commandArgumentMAngle (unsigned int index, MStatus *ReturnStatus=NULL) const
	Gets the value of the requested command argument as a MAngle. More...

MTime	commandArgumentMTime (unsigned int index, MStatus *ReturnStatus=NULL) const
	Gets the value of the requested command argument as a MTime. More...

MStatus	getObjects (MStringArray &result) const
	Gets the list of objects passed to the command as an array of strings. More...

Static Public Member Functions
static const char *	className ()
	Returns the name of this class. More...

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:

flag arguments preceded by a '-' character. Each flag can be followed by a fixed number of parameters.
command arguments a fixed number of typed arguments
objects a range of Maya objects or the contents of Maya's current selection.

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:: AbcBullet/AbcBullet.cpp, AbcExport/AbcExport.cpp, AbcImport/AbcImport.cpp, dx11Shader/dx11ShaderCmd.cpp, glslShader/GLSLShaderCmd.cpp, grabUVMain.cpp, helixTool/helixTool.cpp, hlslShader/hlslShader.cpp, hwApiTextureTest/hwApiTextureTest.cpp, and workspaceControlCmd.cpp.

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:

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

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:

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

Examples:: flipUVCmd/flipUVCmd.cpp, gpuCache/gpuCacheCmd.h, grabUVMain.cpp, helixTool/helixTool.cpp, MetadataSample/cmdUtils.h, nodeCreatedCBCmd/nodeCreatedCBCmd.cpp, renderViewInteractiveRenderCmd/renderViewInteractiveRenderCmd.cpp, renderViewRenderCmd/renderViewRenderCmd.cpp, renderViewRenderRegionCmd/renderViewRenderRegionCmd.cpp, sceneAssembly/adskRepresentationCmd.h, and sceneAssembly/adskSceneMetadataCmd.h.

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:

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

Examples:: MetadataSample/metadataBase.cpp.

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:

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

Examples:: MetadataSample/metadataBase.cpp.

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

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

Examples:: grabUVMain.cpp, and helixTool/helixTool.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

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

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

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

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

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

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

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

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

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

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

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

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

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

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:

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

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:

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

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:

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

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:

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

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:

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

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:

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

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:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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:

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

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:

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

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:

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

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:

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

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:

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

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:

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

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:

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

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

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

const char * className ( )

static

Returns the name of this class.

Returns: Name of this class.

The documentation for this class was generated from the following files:

MArgParser.h
MArgParser.cpp

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation