YAML_MULTIDOC

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