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
See Also
YAML_Alias, YAML_Map, YAML_Stream_Map, YAML_Stream_Sequence, YAML_Value, YAML_PARSE, YAML_SERIALIZE