- •Table of Contents
- •Chapter 1. Introduction
- •1.1. Goals
- •1.2. Prior Art
- •1.3. Relation to XML
- •1.4. Terminology
- •Chapter 2. Preview
- •2.1. Collections
- •2.2. Structures
- •2.3. Scalars
- •2.4. Tags
- •2.5. Full Length Example
- •Chapter 3. Processing YAML Information
- •3.1. Processes
- •3.1.1. Represent
- •3.1.2. Serialize
- •3.1.3. Present
- •3.1.4. Parse
- •3.1.5. Compose
- •3.1.6. Construct
- •3.2. Information Models
- •3.2.1. Representation Graph
- •3.2.1.1. Nodes
- •3.2.1.2. Tags
- •3.2.1.3. Nodes Comparison
- •3.2.2. Serialization Tree
- •3.2.2.1. Keys Order
- •3.2.2.2. Anchors and Aliases
- •3.2.3. Presentation Stream
- •3.2.3.1. Node Styles
- •3.2.3.2. Scalar Formats
- •3.2.3.3. Comments
- •3.2.3.4. Directives
- •3.3. Loading Failure Points
- •3.3.1. Well-Formed and Identified
- •3.3.2. Resolved
- •3.3.3. Recognized and Valid
- •3.3.4. Available
- •Chapter 4. Syntax
- •4.1. Characters
- •4.1.1. Character Set
- •4.1.2. Character Encoding
- •4.1.3. Indicator Characters
- •4.1.4. Line Break Characters
- •4.1.5. Miscellaneous Characters
- •4.1.6. Escape Sequences
- •4.2. Syntax Primitives
- •4.2.1. Production Parameters
- •4.2.2. Indentation Spaces
- •4.2.3. Comments
- •4.2.4. Separation Spaces
- •4.2.5. Ignored Line Prefix
- •4.2.6. Line Folding
- •4.3. YAML Character Stream
- •4.3.1. Directives
- •4.3.1.2.1. Tag Prefixes
- •4.3.1.2.2. Tag Handles
- •4.3.2. Document Boundary Markers
- •4.3.3. Documents
- •4.3.4. Complete Stream
- •4.4. Nodes
- •4.4.1. Node Anchors
- •4.4.2. Node Tags
- •4.4.3. Node Content
- •4.4.4. Alias Nodes
- •4.4.5. Complete Nodes
- •4.4.5.1. Flow Nodes
- •4.4.5.2. Block Nodes
- •4.5. Scalar Styles
- •4.5.1. Flow Scalar Styles
- •4.5.1.1. Double Quoted
- •4.5.1.2. Single Quoted
- •4.5.1.3. Plain
- •4.5.2. Block Scalar Header
- •4.5.2.1. Block Style Indicator
- •4.5.2.2. Block Indentation Indicator
- •4.5.2.3. Block Chomping Indicator
- •4.5.3. Block Scalar Styles
- •4.5.3.1. Literal
- •4.5.3.2. Folded
- •4.6. Collection Styles
- •4.6.1. Sequence Styles
- •4.6.1.1. Flow Sequences
- •4.6.1.2. Block Sequences
- •4.6.2. Mapping Styles
- •4.6.2.1. Flow Mappings
- •4.6.2.2. Block Mappings
- •Terms Index
Syntax
4.5.1.3. Plain
The plain style uses no identifying indicators, and is therefore the most most limited and most context sensitive scalar style. Plain scalars can never contain any tab characters. They also must not contain the “: ” and “ #” character sequences as these combinations cause ambiguity with key: value pairs and comments. Inside flow collections, plain scalars are further restricted to avoid containing the “[”, “]”, “{”, “}” and “,” characters as these would cause ambiguity with the flow collection structure (hence the need for the flow-in context and the flow-out context).
[153] nb-plain-char(c) ::= c |
= flow-out |
Þ nb-plain-char-out |
c |
= flow-in |
Þ nb-plain-char-in |
c |
= flow-key |
Þ nb-plain-char-in |
( nb-char - “:” - “#” - #x9 /*TAB*/ ) | ( ns-plain-char(flow-out) “#” )
| ( “:” ns-plain-char(flow-out) )
[155]nb-plain-char-in ::= nb-plain-char-out - “,” - “[” - “]” - “{” - “}”
[156]ns-plain-char(c) ::= nb-plain-char(c) - #x20 /*SP*/
The first plain character is further restricted to avoid most indicators as these would cause ambiguity with various YAML structures. However, the first character may be “-”, “?” or “:” provided it is followed by a non-space character.
[157] ns-plain-first-char(c) ::= |
( |
ns-plain-char(c) - c-indicator ) |
|
| ( |
( “-” | “?” | “:” ) ns-plain-char(c) ) |
Example 4.63. Plain Characters
# Outside flow collection:
- :: std::vector
- U p , up and away!
- -1 23
# Inside flow collection:
-[ :: std::vector, "Up , up and away!", -1 23 ]
Legend:
ns-plain-first-char(c)
ns-plain-char(c)Not ns-plain-char(c)
%YAML 1.1
---
!!seq [
!!str "::std::vector", !!str "Up, up and away!", !!int "-123",
!!seq [
!!str "::std::vector", !!str "Up, up and away!", !!int "-123",
]
]
Plain scalars are restricted to a single line when contained inside a simple key.
[158] ns-plain(n,c) ::= c |
= flow-out |
Þ ns-plain-multi(n,c)? |
c |
= flow-in |
Þ ns-plain-multi(n,c)? |
c |
= flow-key |
Þ ns-plain-single(c) |
57
XSL• FO
RenderX
Syntax
Example 4.64. Plain Scalars
simple key : {
also simple : value,
? not a
simple key : any
value
}
Legend:
ns-plain-single(c)ns-plain-multi(n,c)
%YAML 1.1
---
!!map {
? !!str "simple key"
:!!map {
?!!str "also simple" : !!str "value",
?!!str "not a simple key" : !!str "any value"
}
}
The first line of any flow scalar is indented according to the collection it is contained in. Therefore, there are two cases where a plain scalar begins on the first column of a line, without any preceding indentation spaces: a plain scalar used as a simple key of a non-indented block mapping, and any plain scalar nested in a non-indented flow collection. In these cases, the first line of the plain scalar must not conflict with a document boundary marker.
[159] l-forbidden-content ::= /* |
start |
of |
line */ |
( c-document-start | c-document-end ) |
|||
/* |
space |
or |
end of line */ |
Example 4.65. Forbidden Non-Indented Plain Scalar Content
---
---· ||| : foo
...· >>>: bar
---
[
---↓
,
...· ,
{
---· :
...· # Nested
}
]
...
ERROR:
The --- and ... document start and end markers must not be specified as the first content line of a non-indented plain scalar.
58
XSL• FO
RenderX
Syntax
YAML provides several easy ways to present such content without conflicting with the document boundary markers. For example:
Example 4.66. Document Marker Scalar Content
---
" --- " : foo ... : bar
---
[
--- ,
... ,
{
? --- : ...
}
]
...
Legend:
Content --- and ...
Document marker --- and ...
%YAML 1.1
---
!!map {
?!!str "---" : !!str "foo",
?!!str "...", : !!str "bar"
}
%YAML 1.1
---
!!seq [
!!str "---", !!str "...", !!map {
? !!str "---" : !!str "..."
}
]
Thus, a single line plain scalar is a sequence of valid plain non-break printable characters, beginning and ending with nonspace character and not conflicting with a document boundary markers. All characters are considered content, including any inner space characters.
[160] ns-plain-single(c) ::= |
( ns-plain-first-char(c) |
|
( nb-plain-char(c)* ns-plain-char(c) )? ) |
- l-forbidden-content
In a multi-line plain scalar, line breaks are subject to (flow) line folding. Any prefix and trailing spaces are excluded from the content. Like single quoted scalars, in plain scalars it is impossible to force the inclusion of the leading or trailing spaces in the content. Therefore, plain scalars lines can only be broken where a single space character separates two nonspace characters.
[161] s-l-plain-break(n) ::= s-ignored-white* b-l-folded-any(n,plain)
59
XSL• FO
RenderX