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
See Also
YAML_Map, YAML_Multidoc, YAML_Stream_Sequence, YAML_Sequence, YAML_Value, YAML_PARSE, YAML_SERIALIZE