YAML_VALUE

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

8.9

Introduced

See Also

YAML_Alias, YAML_PARSE, YAML_SERIALIZE