YAML_MAP
The YAML_MAP function creates a new YAML_Map object, which can be used to hold YAML mapping key/value pairs. YAML_Map is a subclass of OrderedHash, and inherits all of the methods and properties of that class as well as the Hash class.
YAML_Map objects have the following characteristics:
- Elements are kept in their insert order and are indexed by a scalar key.
- The key can be a scalar string or number. String keys are case sensitive.
- You can retrieve elements using the bracket array notation.
- YAML_Map objects can change their size, growing and shrinking as elements are added or deleted.
- Printing a YAML_Map object will automatically call YAML_SERIALIZE and the output will be in YAML format.
Examples
Create a YAML_Map and print out in YAML format:
map = YAML_Map('key1', 'value1', 'key2', 2.5, 'key3', [1,2,3])
top = YAML_Map('mymap', map)
print, top
IDL prints:
mymap:
key1: value1
key2: 2.5
key3: [1,2,3]
Syntax
Result = YAML_Map( Key1, Value1, Key2, Value2, ... Keyn, Valuen , /EXTRACT, /NO_COPY )
or
Result = YAML_Map( Keys, Values, /EXTRACT )
or
Result = YAML_Map( Keys )
or
Result = YAML_Map( Structure, /EXTRACT )
Return Value
Returns a reference to a newly-created YAML_Map.
Arguments
Keyn
Each Key argument can be a scalar string or number.
Each Key argument can also be an array or list, in which case the corresponding Value must be a scalar, an array or a list. If Value is a scalar, then that value is copied into every key. Otherwise, if Value is an array or a list, it must contain the same number of elements as the keys. In this case each element of the Key and Value is inserted as a separate key-value pair. If a given key occurs more than once within the input arguments, the last value will be retained.
If only Keys is supplied (as either a scalar, an array, or a list), then the corresponding values will be set to the default value of !NULL.
If no keys or values are supplied, an empty YAML_Map is returned.
Valuen
Each Value argument can be a variable or expression of type YAML_Map, YAML_Sequence, YAML_Value, YAML_Alias, Hash, List, or a regular IDL array or scalar, including !NULL.
Note: See YAML_SERIALIZE for the list of allowed IDL types and their corresponding YAML type.
Structure
Instead of passing in keys or values, a single IDL structure may be passed in. In this case, each tag/value pair within the structure will be inserted within the YAML_Map.
Note: Even though the structure itself is decomposed into key/value pairs, any substructures within the structure will be passed in as a single "value" for that particular key, unless you set the EXTRACT keyword.
Note: See YAML_SERIALIZE for the list of allowed IDL types and their corresponding YAML type.
Keywords
EXTRACT
By default, all values are put into the YAML_Map unchanged. If the EXTRACT keyword is set, then for any value which is a structure, that structure will be decomposed into key/value pairs (and also recursively for any substructures).
NO_COPY
If the NO_COPY keyword is set, the value data is taken away from the Value variable and attached directly to the YAML_Map variable. The default behavior is to make a copy of the input values.
Properties
All properties can be set and retrieved using the dot "." operator.
ANCHOR
Set this property to a string containing the YAML anchor value associated with this YAML map. This anchor can then be referenced using an alias later on in the YAML stream. For example:
IDL> defmap = YAML_Map('key1', 'value1', 'key2', 1.5)
IDL> defmap.anchor = 'myref'
IDL> map = YAML_Map('defaults', defmap)
IDL> print, map
defaults: &myref
key1: value1
key2: 1.5
Conversely, when a YAML stream gets parsed with the PRESERVE_ALIAS keyword, if there is a YAML map with an anchor, then the resulting YAML_Map will have the ANCHOR property set. For example:
yaml = [ $
'defaults: &myref', $
' key1: value1', $
' key2: 1.5']
yp = yaml_parse(yaml, /preserve_alias)
help, yp['defaults']
print, yp['defaults'].anchor
IDL prints:
<Expression> YAML_MAP <ID=24 NELEMENTS=2> ANCHOR='myref'
myref
Note: If YAML_PARSE is called without the PRESERVE_ALIAS keyword, then all anchors and aliases will be resolved and will not be stored in the result.
TAG
Set this property to a string containing the YAML tag value associated with this YAML sequence. For example:
IDL> defmap = YAML_Map('key1', 'value1', 'key2', 1.5)
IDL> defmap.tag = 'myclass'
IDL> map = YAML_Map('defaults', defmap)
IDL> print, map
defaults: !myclass
key1: value1
key2: 1.5
Conversely, when a YAML stream gets parsed, if there is a YAML sequence with a tag, then the resulting YAML_Sequence will have the TAG property set. For example:
yaml = [ $
'defaults: !myclass', $
' key1: value1', $
' key2: 1.5']
yp = yaml_parse(yaml)
help, yp['defaults']
print, yp['defaults'].tag
IDL prints:
<Expression> YAML_MAP <ID=16 NELEMENTS=2> TAG='!myclass'
myref
Methods and Additional Information
- YAML_Map::Count method: see Hash::Count
- YAML_Map::Filter method: see Hash::Filter
- YAML_Map::HasKey method: see Hash::HasKey
- YAML_Map::IsEmpty method: see Hash::IsEmpty
- YAML_Map::Keys method: see Hash::Keys
- YAML_Map::Map method: see Hash::Map
- YAML_Map::Reduce method: see Hash::Reduce
- YAML_Map::Remove method: see Hash::Remove
- YAML_Map::ToStruct method: see Hash::ToStruct
- YAML_Map::Values method: see Hash::Values
- YAML_Map::Where method: see Hash::Where
- Concatenating: See Concatenating Hashes
- Comparing: See Comparing Hashes
- Access to elements: See Hash Access
- Additional information: See Information about Hashes
Variable Information
HELP
The HELP procedure provides general information:
IDL> mymap = YAML_Map('key1', 4, 'key2', 5)
IDL> help, mymap
MYMAP YAML_MAP <ID=1 NELEMENTS=2>
PRINT and Implied Print
The PRINT procedure and Implied Print serialize the output in YAML format:
IDL> mymap = YAML_Map('key1', 4, 'key2', 5)
IDL> print, mymap
IDL> mymap
In both cases IDL prints:
key1: 4
key2: 5
Version History
|
8.9 |
Introduced |
See Also
YAML_Alias, YAML_Sequence, YAML_Stream_Map, YAML_Stream_Sequence, YAML_Value, YAML_PARSE, YAML_SERIALIZE