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( [Value1, Value2, ... Valuen] [, /EXTRACT] [, LENGTH=value] [, /NO_COPY])

Return Value

Returns a reference to a newly-created YAML_Sequence object.

Arguments

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

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

In both cases IDL prints:

- one
- 2
- 3
- mykey: 4
- !!python/complex 1+2j
- [1,2,3,4,5]

Version History

8.9

Introduced

See Also

YAML_Alias, YAML_Map, YAML_Stream_Map, YAML_Stream_Sequence, YAML_Value, YAML_PARSE, YAML_SERIALIZE