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( [Value₁, Value₂, ... Value_n])

Return Value

---

Returns a reference to a newly-created YAML_Multidoc object.

Arguments

---

Value_n

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

---

8.9	Introduced

See Also

---

YAML_Map, YAML_Sequence, YAML_Stream_Map, YAML_Stream_Sequence, YAML_Value, YAML_PARSE, YAML_SERIALIZE