YAML_PARSE

The YAML_PARSE function takes a YAML (YAML Ain't Markup Language) string or file and converts it into an IDL variable.

This routine is written in the IDL language. Its source code can be found in the file yaml_parse.pro in the lib/datatypes subdirectory of the IDL distribution.

Tip: The result of YAML_PARSE is a nested hierarchy of YAML objects, arrays, and scalar values. If you print out the result, the output will automatically be printed in YAML format.

Examples

Convert a YAML stream into a nested set of IDL YAML objects:

IDL> yaml = `MyYaml:\n key1: text1\n key2: [1, cat, 2.5]`

IDL> result = yaml_parse(yaml)

IDL> help, result

RESULT YAML_MAP <ID=1 NELEMENTS=1>

IDL> print, result

MyYaml:

key1: text1

key2:

- 1

- cat

- 2.5

IDL> help, result['MyYaml']

IDL> help, result['MyYaml','key2']

<Expression> YAML_SEQUENCE <ID=3 NELEMENTS=3>

Syntax

Result = YAML_PARSE(String, /PRESERVE_ALIAS )

Return Value

The result is a nested hierarchy of YAML objects, IDL arrays, and IDL scalar values. See below for the rules on converting YAML data into IDL datatypes.

Arguments

String

String must be a scalar string or string array containing a valid YAML stream.

String can also be a file name. In this case the entire file is read into memory and parsed as a single YAML string.

Keywords

PRESERVE_ALIAS

By default, YAML_PARSE automatically resolves all YAML aliases from their corresponding anchors and returns the resulting values, including any value overrides. If PRESERVE_ALIAS is set then the result will contain the original, unmodified aliases as YAML_Value and YAML_Alias objects. For example, here we have an anchor for a "planet" mapping. The "Earth" key is just a direct alias, while the "Jupiter" key overrides one of the mapping keys:

yaml = `

default: &planet

type: terrestrial

Earth: *planet

Jupiter:

<<: *planet

type: gas giant`

print, yaml_parse(yaml) ; resolve all aliases

IDL prints:

default:

type: terrestrial

Earth:

type: terrestrial

Jupiter:

type: gas giant

Now print the YAML but keep the aliases using the PRESERVE_ALIAS keyword:

print, yaml_parse(yaml, /preserve_alias)

IDL prints:

default: &planet

type: terrestrial

Earth: *planet

Jupiter:

<<: *planet

type: gas giant

Conversion Rules

When converting YAML streams into IDL variables, the following rules are used:

YAML Item	IDL Variable Type	Notes
Multiple Documents	YAML_Multidoc	Optional COMMENTS, GLOBAL_TAGS
A single document with a mapping	YAML_Stream_Map	Optional COMMENTS, GLOBAL_TAGS
A single document with a sequence	YAML_Stream_Sequence	Optional COMMENTS, GLOBAL_TAGS
Mapping	YAML_Map	Optional ANCHOR, TAG properties
!!set	YAML_Map	Mapping of keys with !NULL values
Sequence of mixed types	YAML_Sequence	Optional ANCHOR, TAG properties
Sequence of same types¹	Array	Boolean, LONG64, DOUBLE, DCOMPLEX
!!omap	YAML_Sequence	Sequence of YAML_Maps
Scalar value with unknown tag³	YAML_Value	TAG and VALUE properties
Scalar value with an anchor²	YAML_Value	ANCHOR, VALUE properties, optional TAG
Alias (reference)	YAML_Alias	ALIAS property
Quoted string	String
~, null, Null, NULL	!NULL
false, False, FALSE, true, True, TRUE	Boolean
Integer from –2⁶³ to 2⁶³–1	LONG64
Integers larger than +/–2⁶³	BigInteger
Floating-point number	DOUBLE
!!binary with base64	Byte array
!!python/complex or complex of form A+Bj	DCOMPLEX
tag:stsci.edu:asdf/core/complex-1.0.0	DCOMPLEX	ASDF file format

¹A sequence with both integers and floating-point values will be returned as an IDL array of type DOUBLE.

²A YAML scalar with an anchor will be returned as a YAML_Value object. The VALUE property will contain the scalar value as a string, and will not be converted to one of the other scalar types.

³A YAML scalar with an unknown tag will be returned as a YAML_Value object. The VALUE property will contain the scalar value as a string, and will not be converted to one of the other scalar types.

Conformance

In general, YAML_PARSE and YAML_SERIALIZE conform to the YAML 1.2 standard, with the following specific notes:

The presence of a %YAML 1.1 directive does not change any of the following behavior.
Unquoted strings On, Off, Yes, No are treated as strings (not booleans as in YAML 1.1).
Octal numbers must use the 0o prefix (YAML 1.1 treated an integer with a leading zero as octal).
Values with the form 12:34:56 are returned as strings and do not need quoting (YAML 1.1 treated them as sexigesimals).

Some exceptions to the conformance:

YAML Mappings are returned as a YAML_Map, which is an ordered hash, rather than unordered. This makes it easier to parse and serialize YAML files and have the mappings appear in the same order.
Mapping keys can only be strings or numbers. Complex mapping keys (such as maps or sequences) will produce unexpected results.
For parsing, Infinity or NaN values do not require a leading ".". For example, inf, infinity, or .inf will all be treated as floating-point Infinity, unless they are surrounded by quotes. YAML_SERIALIZE will always output these with the leading ".", for example .inf or .nan.

Additional Examples

Parsing a YAML File

First we parse a sample YAML file into YAML objects:

yaml = [ $

'Product: IDL', $

'Year: 1977', $

'Creator: David Stern', $

'Datatypes: [boolean, long, float, string]', $

'Examples: [true, 1234, 3.14, "hello"]', $

'Functions:', $

' - FFT:', $

' Arguments: [{Name: InputArray, Type: float}]', $

' Keywords: [{Name: Double, Type: boolean}]']

yp = yaml_parse(yaml)

We can use help and print to examine the contents:

help, yp

print, (yp.keys()).toArray()

IDL prints:

YP YAML_MAP <ID=3 NELEMENTS=6>

Product Year Creator Datatypes Examples Functions

We can use array indexing to drill down into the returned objects:

help, yp['Datatypes']

help, yp['Examples']

help, yp['Functions', 0, 'FFT', 'Arguments', 0, 'Name']

IDL prints:

<Expression> STRING = Array[4]

<Expression> YAML_SEQUENCE <ID=5 NELEMENTS=4>

<Expression> STRING = 'InputArray'

Convert to JSON

If the YAML file contains simple YAML_Map, YAML_Sequence, arrays, and scalars, then you can directly convert the YAML_PARSE output to JSON:

IDL> print, json_serialize(yp)

{"Product":"IDL","Year":1977,"Creator":"David Stern","Datatypes":["boolean","long","float","string"],"Examples":[true,1234,3.1400000000000001,"hello"],"Functions":[{"FFT":{"Arguments":[{"Name":"InputArray","Type":"float"}],"Keywords":[{"Name":"Double","Type":"boolean"}]}}]}

This will not work for YAML files that contain streams or special TAG values.

Create YAML Streams

You can construct YAML output from regular IDL arrays, scalars, hashes, or lists. More complex YAML files can be created using the YAML object classes such as YAML_Multidoc, YAML_Stream_Map, YAML_Stream_Sequence, YAML_Map, or YAML_Sequence. These classes allow you to add YAML comments, global tags, anchors, and tags.

For our simple example above, we can recreate the YAML by just using regular IDL variables:

h = OrderedHash()

h['Product'] = 'IDL'

h['Year'] = 1977

h['Creator'] = 'David Stern'

h['Datatypes'] = ["boolean","long","float","string"]

h['Examples'] = List(!true, 1234, 3.14d, "hello")

args = [Hash('Name', 'InputArray', 'Type', 'float')]

kw = [Hash('Name', 'Double', 'Type', 'boolean')]

fn1 = Hash('FFT', Hash('Arguments', args, 'Keywords', kw))

h['Functions'] = List(fn1)

print, yaml_serialize(h)

This will produce essentially the same YAML stream as in the beginning, although some of the YAML mappings and sequences will be written out in "block" format rather than the shorter "flow" style. Both forms are equivalent.

Version History

8.9	Introduced

YAML_PARSE

Examples

Syntax

Return Value

Arguments

String

Keywords

PRESERVE_ALIAS

Conversion Rules

Conformance

Additional Examples

Parsing a YAML File

Convert to JSON

Create YAML Streams

Version History

See Also