The YAML_MULTIDOC function creates a new YAML_Multidoc object, which can be used to hold multiple YAML documents, each consisting of variables of type YAML_Map, YAML_Sequence, YAML_Value, YAML_Alias, Hash, List, or a regular IDL array or scalar, including !NULL. YAML_Multidoc is a subclass of YAML_Sequence, and inherits all of the methods and properties of that class.
Note: Printing a YAML_Multidoc object will automatically call YAML_SERIALIZE and the output will be in YAML format.
Example
Create a YAML_Multidoc with two documents and print out in YAML format:
doc = YAML_Multidoc()
doc.Add, YAML_Map('doc1key', YAML_Sequence(1, 2))
doc.Add, YAML_Map('doc2key', YAML_Map('test', 123))
print, doc
In the output, note that the two documents are separated by --- characters, which is the standard YAML notation for multiple documents:
---
doc1key:
- 1
- 2
---
doc2key:
test: 123
If you parse a YAML stream with two or more documents, then the documents will be returned as separate items within a YAML_Multidoc. For example:
yaml = [ $
'---', $
'abcd', $
'---', $
'1234']
yp = yaml_parse(yaml)
help, yp, yp[0], yp[1]
IDL prints:
YP YAML_MULTIDOC <ID=41 NELEMENTS=2>
<Expression> STRING = 'abcd'
<Expression> LONG64 = 1234
Note: If you parse a YAML stream with a single document, then the result will be a YAML_Stream_Map or YAML_Stream_Sequence object, depending up whether the document contains a mapping or sequence.
Syntax
Result = YAML_Multidoc( [Value1, Value2, ... Valuen])
Return Value
Returns a reference to a newly-created YAML_Multidoc object.
Arguments
Valuen
Each Value argument can be a variable or expression of type YAML_Map, YAML_Sequence, YAML_Value, Hash, List, or a regular IDL array or scalar, including !NULL. If no Value argument is supplied, an empty YAML_Multidoc is returned.
Note: See YAML_SERIALIZE for the list of allowed IDL types and their corresponding YAML type.
Keywords
None
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()
yp.Add, 123
yp.comments = ['# My File', '%YAML 1.1']
print, yaml_serialize(yp)
IDL prints:
# My File
%YAML 1.1
--- 123
Conversely, when a YAML stream gets parsed, if there are any global comments, then the resulting YAML_Multidoc will have the COMMENT 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_MULTIDOC <ID=14 NELEMENTS=1>
# YAML is fun
%YAML 1.1
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_Multidoc(YAML_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_Multidoc 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_MULTIDOC <ID=31 NELEMENTS=1> GLOBAL_TAGS=1
<Expression> STRING = '!idl! tag:rsinc.com,1977:'
Note: You can have a maximum of four global tags.
Methods and Additional Information
See YAML_Sequence.
Variable Information
HELP
The HELP procedure provides general information:
IDL> stream = YAML_Multidoc(YAML_Map('Creator', '!idl!David Stern'))
IDL> stream.tag = '!idl! tag:rsinc.com,1977:'
IDL> help, stream
MULTIDOC YAML_MULTIDOC <ID=35 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_Sequence, YAML_Stream_Map, YAML_Stream_Sequence, YAML_Value, YAML_PARSE, YAML_SERIALIZE