The YAML_STREAM_MAP function creates a new YAML_Stream_Map object, which can be used to hold a complete YAML document with a top-level set of mapping key/value pairs. The mapping values consist of variables of type YAML_Map, YAML_Sequence, YAML_Value, YAML_Alias, Hash, List, or a regular IDL array or scalar, including !NULL. YAML_Stream_Map is a subclass of YAML_Map, and inherits all of the methods and properties of that class.

Note: Printing a YAML_Stream_Map object will automatically call YAML_SERIALIZE and the output will be in YAML format.

Example


Create a YAML_Stream_Map and print out in YAML format:

stream = YAML_Stream_Map()
stream.comments = 'my yaml comment'
stream['key1'] = YAML_Sequence(1, 2)
stream['key2'] = YAML_Map('test', 123)
print, stream

In the output, note the three dashes ---, indicating the start of the document:

# my yaml comment
---
key1:
  - 1
  - 2
key2:
  test: 123

If you parse a YAML stream with a single document containing a mapping, then the result will be a YAML_Stream_Map. For example:

yaml = [ $
'---', $
'abc: 5', $
'def: hello']
yp = yaml_parse(yaml)
help, yp, yp['abc'], yp['def']

IDL prints:

YP              YAML_STREAM_MAP  <ID=122  NELEMENTS=2>
<Expression>    LONG64    =                      5
<Expression>    STRING    = 'hello'

Syntax


Result = YAML_Stream_Map(Key1, Value1, Key2, Value2, ... Keyn, Valuen , /EXTRACT, /NO_COPY )

Return Value


Returns a reference to a newly-created YAML_Stream_Map object.

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


Note: The HASH class also contains the FOLD_CASE and LOWERCASE keywords. Since YAML keys are case sensitive, it is recommended that you do not use these 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.

COMMENTS

Set this property to a string or string array containing the global YAML comments for this stream. This will include any comments that start with a "#" at the beginning of the line, as well as any "%YAML" lines. For example:

yp = yaml_stream_map('key', 123)
yp.comments = ['My File', '%YAML 1.1']
print, yp

IDL prints:

# My File
%YAML 1.1
---
key: 123

Conversely, when a YAML stream gets parsed, if there are any global comments, then the resulting YAML_Stream_Map will have the COMMENTS property set. For example:

yaml = [ $
'# YAML is fun', $
'%YAML 1.1', $
'---', $
'123']
yp = yaml_parse(yaml)
help, yp
print, yp.comments

IDL prints:

YP              YAML_STREAM_MAP  <ID=14  NELEMENTS=1>
YAML is fun
%YAML 1.1

Note: The "#" character will automatically be prepended to comments when serializing, and will automatically be removed when parsing.

GLOBAL_TAGS

Set this property to a string or string array containing up to four global YAML %TAG values for this stream. For example:

stream = YAML_Stream_Map('Creator', '!idl!David Stern')
stream.global_tags = '!idl! tag:rsinc.com,1977:'
print, stream

IDL prints:

%TAG !idl! tag:rsinc.com,1977:
---
Creator: !idl!David Stern

Conversely, when a YAML stream gets parsed, if there are any global tags, then the resulting YAML_Stream_Map will have the GLOBAL_TAGS property set. For example:

yaml = [ $
'%TAG !idl! tag:rsinc.com,1977:', $
'---', $
'Creator: !idl!David Stern']
yp = yaml_parse(yaml)
help, yp, yp.global_tags

IDL prints:

YP              YAML_STREAM_MAP  <ID=31  NELEMENTS=1>  GLOBAL_TAGS=1
<Expression>    STRING    = '!idl! tag:rsinc.com,1977:'

Note: You can have a maximum of four global tags.

TAG

Set this property to a string containing the local YAML tag values for this mapping. For example, the ASDF file format header has both a global and a local tag:

stream = YAML_Stream_Map()
stream.global_tags = '! tag:stsci.edu:asdf/'
stream.tag = '!core/asdf-1.1.0'
print, stream

IDL prints:

%TAG ! tag:stsci.edu:asdf/
--- !core/asdf-1.1.0

Conversely, when a YAML stream gets parsed, if there is a local tag, then the resulting YAML_Stream_Map will have the TAG property set. For example:

yaml = [ $
'%TAG ! tag:stsci.edu:asdf/', $
'--- !core/asdf-1.1.0']
yp = yaml_parse(yaml)
help, yp, yp.tag

IDL prints:

YP              YAML_STREAM_MAP  <ID=16  NELEMENTS=0>  TAG='!core/asdf-1.1.0' GLOBAL_TAGS=1
<Expression>    STRING    = '!core/asdf-1.1.0'

Methods and Additional Information

See YAML_Map.

Variable Information


HELP

The HELP procedure provides general information:

IDL> stream = YAML_Stream_Map('Creator', '!idl!David Stern')
IDL> stream.global_tags = '!idl! tag:rsinc.com,1977:'
IDL> help, stream
STREAM          YAML_STREAM_MAP  <ID=17  NELEMENTS=1>  GLOBAL_TAGS=1

PRINT and Implied Print

The PRINT procedure and Implied Print serialize the output in YAML format. Using the stream from above:

IDL> print, stream
IDL> stream

In both cases IDL prints:

%TAG !idl! tag:rsinc.com,1977:
---
Creator: !idl!David Stern

Version History


8.9

Introduced

See Also


YAML_Map, YAML_Multidoc, YAML_Stream_Sequence, YAML_Sequence, YAML_Value, YAML_PARSE, YAML_SERIALIZE