YAML_SEQUENCE

The YAML_SEQUENCE function creates a new YAML_Sequence object, which can be used to hold values of type YAML_Map, YAML_Sequence, YAML_Value, YAML_Alias, Hash, List, or a regular IDL array or scalar, including !NULL. YAML_Sequence is a subclass of LIST, and inherits all of the methods and properties of that class.

YAML_Sequence objects have the following characteristics:

The elements are ordered, and are indexed in one dimension.
The YAML_Sequence can change its size, growing and shrinking as elements are added or deleted.
Printing a YAML_Sequence object will automatically call YAML_SERIALIZE and the output will be in YAML format.

Example

Create a YAML_Sequence and print out in YAML format:

IDL> seq = YAML_Sequence('one', 2.0, 3, YAML_Map('mykey', 4), 1 + 2i, [1:5])

IDL> print, seq

- one

- 2

- 3

- mykey: 4

- !!python/complex 1+2j

- [1,2,3,4,5]

Syntax

Result = YAML_Sequence( [Value₁, Value₂, ... Value_n] [, /EXTRACT] [, LENGTH=value] [, /NO_COPY])

Return Value

Returns a reference to a newly-created YAML_Sequence object.

Arguments

Value_n

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. If no Value argument is supplied, an empty YAML_Sequence is returned.

Note: See YAML_SERIALIZE for the list of allowed IDL types and their corresponding YAML type.

Keywords

EXTRACT

Normally, if a Value argument refers to an array or a list, that array or list is inserted into the new YAML_Sequence as a single element. If the EXTRACT keyword is specified, any Value argument that contains an array or a list will be disassembled, and each element of the array or list will be added to the new YAML_Sequence as a separate element. The EXTRACT keyword has no effect if none of the Value arguments are arrays or lists.

LENGTH

Set this keyword to an integer value to create a YAML_Sequence with the specified number of elements. If LENGTH is greater than the number of Value arguments, the Value arguments supplied are cyclically repeated to fill out the YAML_Sequence. If no Value arguments are supplied, all YAML_Sequence elements will contain the value !NULL.

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_Sequence 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.

ANCHOR

Set this property to a string containing the YAML anchor value associated with this YAML sequence. For example:

IDL> seq = YAML_Sequence('value1', 'value2')

IDL> seq.anchor = 'myref'

IDL> map = YAML_Map('a', seq)

IDL> print, map

a: &myref

- value1

- value2

Conversely, when a YAML stream gets parsed with the PRESERVE_ALIAS keyword, if there is a YAML sequence with an anchor, then the resulting YAML_Sequence will have the ANCHOR property set. For example:

yaml = [ $

'a: &myref', $

' - value1', $

' - value2']

yp = yaml_parse(yaml, /preserve_alias)

seq = yp['a']

help, seq

print, seq.anchor

IDL prints:

<Expression> YAML_SEQUENCE <ID=2 NELEMENTS=2> ANCHOR='myref'

myref

Note: If YAML_PARSE is called without the PRESERVE_ALIAS keyword, then all anchors and aliases will be resolved and will not be stored in the result.

TAG

Set this property to a string containing the YAML tag value associated with this YAML sequence. For example:

IDL> seq = YAML_Sequence('value1', 'value2')

IDL> seq.tag = 'mytag'

IDL> map = YAML_Map('a', seq)

IDL> print, map

a: !mytag

- value1

- value2

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

yaml = [ $

'a: !mytag', $

' - value1', $

' - value2']

yp = yaml_parse(yaml)

seq = yp['a']

help, seq

print, seq.tag

IDL prints:

<Expression> YAML_SEQUENCE <ID=2 NELEMENTS=2> TAG='mytag'

mytag

Methods and Additional Information

YAML_Sequence::Add method: Add a new item. See List::Add.
YAML_Sequence::Count method: Return the number of items. See List::Count.
YAML_Sequence::Filter method: Pass the items through a filter function. See List::Filter.
YAML_Sequence::IsEmpty method: Test whether the YAML_Sequence is empty. See List::IsEmpty.
YAML_Sequence::Map method: Pass the items through a user-defined function. See List::Map.
YAML_Sequence::Move method: Move items. See List::Move.
YAML_Sequence::NestedMap method: Pass the items through a user-defined function using a nested loop. See List::NestedMap.
YAML_Sequence::Reduce method: Pass each item through a function, accumulating the result. See List::Reduce.
YAML_Sequence::Remove method: Remove an item. See List::Remove.
YAML_Sequence::Reverse method: Reverse all elements. See List::Reverse.
YAML_Sequence::Sort method: Sort the items. See List::Sort.
YAML_Sequence::Swap method: Switch the positions of two items. See List::Swap.
YAML_Sequence::ToArray method: Convert the YAML_Sequence to an IDL array. See List::ToArray.
YAML_Sequence::Where method: Find where items are equal to a certain value. See List::Where.
Concatenating YAML_Sequences: See Concatenating Lists
Comparing YAML_Sequences: See Comparing Lists with EQ and NE
Element Access: See List Element Access
Information about YAML_Sequences: See Information about Lists

Variable Information

HELP

The HELP procedure provides general information:

IDL> seq = YAML_Sequence('one', 2.0, 3, YAML_Map('mykey', 4), 1 + 2i, [1:5])
IDL> help, seq

SEQ YAML_SEQUENCE <ID=2 NELEMENTS=6>

PRINT and Implied Print

The PRINT procedure and Implied Print serialize the output in YAML format: