The YAML_VALUE function creates a new YAML_Value object, which can be used to hold a scalar value and an optional anchor. A YAML_Value object will automatically be returned from the YAML_PARSE function for a scalar value with an anchor.
Note: In most cases you will not need to use a YAML_Value object. Scalar values in a YAML file will typically be returned as a regular IDL variable of type integer, double, or string. YAML_Values will only be returned for scalar values with an anchor, or scalar values with an unknown tag.
Examples
Create a YAML_Value containing a scalar float value and anchor, and a YAML_Alias that references it:
yvalue = YAML_Value(1.234, ANCHOR='myanchor')
yalias = YAML_Alias('myanchor')
mymap = YAML_Map('key1', yvalue, 'key2', yalias)
print, yaml_serialize(mymap)
IDL prints:
key1: &myanchor 1.23400
key2: *myanchor
Now call YAML_PARSE with the PRESERVE_ALIAS keyword and examine the map keys:
yaml = `key1: &myanchor 1.23400\nkey2: *myanchor`
yp = yaml_parse(yaml, /preserve_alias)
help, yp['key1'], yp['key2']
print, yp['key1'].value
IDL prints:
<Expression> YAML_VALUE <ID=5> VALUE='myanchor' VALUE='1.23400'
<Expression> YAML_ALIAS <ID=6> ALIAS='myanchor'
1.23400
Note: If YAML_PARSE is called without the PRESERVE_ALIAS keyword, then all anchors and aliases will be resolved and will not be returned.
Syntax
Result = YAML_Value( [Value], ANCHOR=string, TAG=string)
Return Value
Returns a reference to the newly-created YAML_Value.
Arguments
Value
Set this argument to a string giving the scalar value associated with this anchor. If a value is not supplied then the value will be set to "null" in the YAML stream.
Keywords
ANCHOR
Set this keyword to a string containing the YAML anchor associated with this scalar value. Do not include the "&"; it will be added automatically when serializing to YAML.
TAG
Set this keyword to a string containing the YAML tag value associated with this scalar value. See the TAG property below for details.
Properties
All properties can be set and retrieved using the dot "." operator.
ANCHOR
Set this property to a string containing the YAML anchor associated with this scalar value. This anchor can then be referenced using an alias later on in the YAML stream. Conversely, when a YAML stream gets parsed with the PRESERVE_ALIAS keyword, if there is a YAML scalar value with an anchor, then the resulting YAML_Value will have the ANCHOR property set. See above for an example.
TAG
Set this property to a string containing the optional YAML tag associated with this anchor. For example, here we force the value to be treated as a string using the !!str tag:
yvalue = YAML_Value(1.234, ANCHOR='myanchor', TAG="!!str")
mymap = YAML_Map('key1', yvalue)
print, yaml_serialize(mymap)
IDL prints:
key1: !!str &myanchor 1.23400
Conversely, when a YAML stream is parsed with PRESERVE_ALIAS, if there is a scalar anchor with a tag, then the resulting YAML_Value will have the TAG property set. For example:
yaml = 'key1: !!str &myanchor 1.23400'
yp = yaml_parse(yaml, /preserve_alias)
help, yp['key1']
IDL prints:
<Expression> YAML_VALUE <ID=39> VALUE='myanchor' TAG='!!str' VALUE='1.23400'
VALUE
Set this property to a string containing the scalar value. This value will then be output in the YAML stream for both the anchor and any aliases. If a value is not supplied then the value will be set to "null" in the YAML stream. Conversely, when a YAML stream is parsed with the PRESERVE_ALIAS keyword, if there is a YAML scalar value with an anchor, then the resulting YAML_Value will have the VALUE property set to the associated value. See above for an example.
Note: When a YAML stream is parsed with the PRESERVE_ALIAS keyword, any YAML_Values that get returned will have their VALUE property set to a string, regardless of any implicit or explicit tags that might force the value to integer or float. To retrieve the actual values, simply call YAML_PARSE again without the keyword.
Variable Information
HELP
The HELP procedure provides general information:
IDL> yaml = 'key1: !!str &myanchor 1.23400'
IDL> yp = yaml_parse(yaml, /preserve_alias)
IDL> help, yp['key1']
<Expression> YAML_VALUE <ID=39> VALUE='myanchor' TAG='!!str' VALUE='1.23400'
PRINT and Implied Print
The PRINT procedure and Implied Print serialize the output in YAML format:
IDL> yvalue = YAML_Value(1.234, ANCHOR='myanchor')
IDL> print, yvalue
IDL> yvalue
In both cases IDL prints:
key1: &myanchor 1.23400
Version History
See Also
YAML_Alias, YAML_PARSE, YAML_SERIALIZE