LRM yaml Support

Yaml Parser

LRM supports YAML 1.2 and uses the snakeyaml1.2 engine to parse files. Information on snakeyaml can be found at snakeyaml. Information about learning YAML can be found at LearnYAML

Supported YAML syntax

The following syntax is supported by LRM.

Ordered Map

 # Explicitly typed ordered map (dictionary).
 Bestiary: !!omap
   - aardvark: African pig-like ant eater. Ugly.
   - anteater: South-American ant eater. Two species.
   - anaconda: South-American constrictor snake. Scaly.
 # Flow style
 Numbers: !!omap [ 1: one, 2: two, 
        3: three ]
 
 #Implicit ordered map
 Numbers:
   - {1: one}
   - {2: two}
   - {3: three}
 
 #Block style ordered map with duplicate keys
 Block style tasks:
   - meeting: with team.
   - meeting: with boss.
   - break: lunch.
   - meeting: with client.
 
 #Flow style ordered map with duplicate keys
 Flow tasks: [ meeting: with team, meeting: with boss ]

Lists

 twobytwotable:
 - - 'a1'
   - "a2"
 - - b1
   - b2
 twobytwotable2:
 - [a1, a2]
 - ['b1', "b2"]
 list:
 - - 'a1'
 - - "b1"
 - - c1

Literal Blocks

 # Multiple-line strings can be written either as a 'literal block' (using |),
  literal_block: |
     This entire block of text will be the value of the 'literal_block' key,
     with line breaks being preserved.
     
     The literal continues until de-dented, and the leading indentation is
     stripped.
  
       Any lines that are 'more-indented' keep the rest of their indentation -
       these lines will be indented by 4 spaces.

Unordered Set

 Block style:
   login : Log In
   logout : "Log Out"
   name  : 'Name'
 Flow style: { login: 'Log In', logout: Log Out, name: "Name" }

LRM parsing for Unordered Set

Nested keys have a separator of _^o^_.

The key/value pairs created by LRM are:

	Key	Value
	Block style_^o^_login	Log In
	Block style_^o^_logout	"Log Out"
	Block style_^o^_name	'Name'
	Flow style_^o^_login	'Log In'
	Flow style_^o^_logout	Log Out
	Flow style_^o^_name	"Name"

Multi-line Keys

 # Keys can also be complex, like multi-line objects
 # We use ? followed by a space to indicate the start of a complex key.
 ? |
   This is a key
   that has multiple lines
 : "and this is its value"

LRM parsing for Multi-line Keys

The key/value pairs created by LRM are:

	Key	Value
	This is a key that has multiple lines	"and this is its value"

JSON style

 # Since YAML is a superset of JSON, you can also write JSON-style maps and
 # sequences:
 json_map: {"key": "value"}
 json_seq: [3, 2, 1, 'takeoff']
 and quotes are optional: {key: [3, 2, 1, takeoff]}

LRM parsing for JSON style

Nested keys have a separator of _^o^_. Sequences have a separator of _^a^_

The key/value pairs created by LRM are:

	Key	Value
	json_map_^o^_key	"value"
	json_seq_^a1^_	3
	json_seq_^a2^_	2
	json_seq_^a3^_	1
	json_seq_^a4^_	'takeoff'
	and quotes are optional_^o^_key_^a1^_	3
	and quotes are optional_^o^_key_^a2^_	2
	and quotes are optional_^o^_key_^a3^_	1
	and quotes are optional_^o^_key_^a4^_	takeoff

Topmost List

A topmost list is a list that does not have a parent key. If a file contains a topmost list, then no other syntax type can be included.

 - key: login
   msg: "Log In"
 - key: logout
   msg: 'Log Out'

LRM parsing for Topmost list

Nested keys have a separator of _^o^_. Sequences have a separator of _^a^_

The key/value pairs created by LRM are:

	Key	Value
	_^a1^__^o^_key	login
	_^a1^__^o^_msg	"Log In"
	_^a2^__^o^_key	logout
	_^a2^__^o^_msg	'Log Out'

Unsupported YAML syntax

The following syntax is not supported by LRM. If a file contains unsupported syntax then an error will occur when reading the file.

Set format

A set is an unordered collection of nodes such that no two nodes are equal.

 baseball players: !!set
   ? Mark McGwire
   ? Sammy Sosa
   ? Ken Griffey
 # Flow style
 baseball teams: !!set { Boston Red Sox, Detroit Tigers, New York Yankees }

Sequence format

A sequence is a collection indexed by sequential integers starting with zero.

 Block style: !!seq
 :- Mercury
 :- Pluto  
 
 Flow style: !!seq [ Mercury,  Pluto ]

Multiple Documents

A file that contains multiple documents, indicated by '---' and '...' is not supported.

 ---
 doc1: value1
 ...
 ---
 doc2: value2
 ...

Blank Values

An empty string, such as is allowed but a blank value is not.

 this_is_valid: ""
 this_is_invalid:
 this_is_valid2: 

Multi-lines that are not literal strings

 key1: 'this\n'
    is \n
   a test'

Folded Style (>)

 folded_style: >
     This entire block of text will be the value of 'folded_style', but this
     time, all newlines will be replaced with a single space.
     
     Blank lines, like above, are converted to a newline character.
      
       'More-indented' lines keep their newlines, too -
       this text will appear over two lines.

Mixing sequence with simple key/values

Sequence and simple key/values cannot be in the same file

 - key: login
   msg: "Log In"
 - key: logout
   msg: 'Log Out'
 simplekey: Simple value