Go to: Synopsis. Return value. Keywords. Related. Flags. Python examples.

Synopsis

dataStructure([asFile=string], [asString=string], [dataType=boolean], [format=string], [listMemberNames=string], [name=string], [remove=boolean], [removeAll=boolean])

Note: Strings representing object names and arguments must be separated by commas. This is not depicted in the synopsis.

dataStructure is undoable, queryable, and NOT editable.

Takes in a description of the structure and creates it, adding it to the list of available data structures. The structure definition can either be supplied in the asString flag or exist in a file that is referenced by the asFile flag.

If the remove flag is specified with a name flag then the data structure will be removed. This is to keep all structure operations in a single command rather than create separate commands to create, remove, and query the data structures. When you use the removeAll flag then every existing metadata structure is removed. Use with care! Note that removed structures may still be in use in metadata Streams after removal, they are just no longer available for the creation of new Streams.

Both the creation modes and the remove mode are undoable.

Creation of an exact duplicate of an existing structure (including name) will succeed silently without actually creating a new structure. Attempting to create a new non-duplicate structure with the same name as an existing structure will fail as there is no way to disambiguate two structures with the same name.

Querying modes are defined to show information both on the created structures and the structure serialization formats that have been registered. The serialization formats preserve the structure information as text (e.g. raw, XML, JSON). Since the raw structure type is built in it will be assumed when none are specified.

General query with no flags will return the list of names of all currently existing structures.

Querying the format flag will return the list of all registered structure serialization formats.

Querying with the format supplied before the query flag will show the detailed description of that particular structure serialization format.

Querying the asString flag with a structure name and serialization format supplied before the query flag will return a string representing the named data structure in the serialization format specified by the format flag. Even if the format is the same as the one that created the structure the query return string may not be identical since the queried value is formatted in a standard way - original formatting is not preserved.

Querying the asFile flag with a structure name supplied before the query flag will return the original file from which the structure was generated. If the structure was created using the asString flag or through the API then an empty string will be returned.

Querying the name flag returns the list of all structures created so far.

Return value

stringName of the resulting structure, should match the name defined in the structure description
string[]Name(s) of the removed structures.

In query mode, return type is based on queried flag.

Keywords

metadata, component

Related

addMetadata, applyMetadata, editMetadata, getMetadata, hasMetadata

Flags

asFile, asString, dataType, format, listMemberNames, name, remove, removeAll
Long name (short name) Argument types Properties
asFile(af) string createquery
Specify a file that contains the serialized data which describes the structure. The format of the data is specified by the 'format' flag.
asString(asString) string createquery
Specify the string containing the serialized data which describes the structure. The format of the data is specified by the 'format' flag.
dataType(dt) boolean createquery
Used with the flag 'listMemberNames' to query the type of the member. The type is appended after each relative member in the array. For example, if the format is "name=idStructure:int32=id:string=name" the returned array is "id int32 name string".
format(fmt) string createquery
Format of data to expect in the structure description. "raw" is supported natively and will be assumed if the format type is omitted. Others are available via plug-in. You can query the available formats by using this flag in query mode.

In query mode, this flag can accept a value.
listMemberNames(lmn) string createquery
Query the member names in the dataStructure. The member names will be returned in an array. The name of the data structure will not be returned. To get the type of each member, use 'dataType' together. Then the type of the member will be appended in the array after their relative member. For example, if the format is "name=idStructure:int32=id:string=name" the returned array is "id int32 name string".
name(n) string query
Query mode only. Name of the data structure to be queried, or set to list the available names.

In query mode, this flag can accept a value.
remove(rem) boolean create
Remove the named data structure. It's an error if it doesn't exist.
removeAll(ral) boolean create
Remove all metadata structures. This flag can not be used in conjunction with any other flags.
Flag can appear in Create mode of command Flag can appear in Edit mode of command
Flag can appear in Query mode of command Flag can have multiple arguments, passed either as a tuple or a list.

Python examples

import maya.cmds as cmds

import maya.cmds as cmds
cmds.dataStructure( query=True, format=True )
# Result: ['raw', 'debug'] #
cmds.dataStructure( format='raw', asString='name=NameAndID:string=name:int32=ID' )
# Result: 'NameAndID' #
# Note that this file doesn't exist, it's just an example of how to read
# from the file after you've created it. The file contents should look
# like this:
#		name=FileBasedStructure
#		string=fileInformation
cmds.dataStructure( asFile='someFile.raw' )
cmds.dataStructure( query=True )
# Result: ['NameAndID', 'FileBasedStructure'] #
cmds.dataStructure( name='NameAndID', format='raw', query=True, asString=True )
# Result: 'name=NameAndID:string=name:int32=ID' #
cmds.dataStructure( name='NameAndID', query=True, listMemberNames=True )
# Result: [u'name', u'ID'] #
cmds.dataStructure( name='NameAndID', query=True, listMemberNames=True, dataType=True )
# Result: [u'name', u'string', u'ID', u'int32'] #
cmds.dataStructure( remove=True, name='NameAndID' )
# Result: 'NameAndID' #
cmds.dataStructure( query=True )
# Result: ['FileBasedStructure'] #
cmds.dataStructure( removeAll=True )
# Result: ['FileBasedStructure'] #