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

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