[yaml/en] Use preferred style; add missing uses

* YAML allows literal tabs in content, but not indentation.
* Two space indent always preferred.
  * Note: YAML dumpers always use 2 space by default.
* '- ...' doesn't need extra indentation.
  * Note: YAML dumpers don't use extra indentation.
* There was no mention of single quoted strings. They are preferred
  and should be used except when double quote semantics are actually
  required. (Best practice).
* Add flow form example for sets: `{a, b, c}`
* Show collapsed form of seq-in-seq: `- - - foo`.
This commit is contained in:
Ingy döt Net 2018-01-25 13:51:15 -08:00
parent fce4a810cb
commit 7cd43d8ad4

View File

@ -2,8 +2,8 @@
language: yaml language: yaml
filename: learnyaml.yaml filename: learnyaml.yaml
contributors: contributors:
- ["Adam Brenecki", "https://github.com/adambrenecki"] - [Adam Brenecki, 'https://github.com/adambrenecki']
- ["Suhas SG", "https://github.com/jargnar"] - [Suhas SG, 'https://github.com/jargnar']
--- ---
YAML is a data serialisation language designed to be directly writable and YAML is a data serialisation language designed to be directly writable and
@ -11,7 +11,7 @@ readable by humans.
It's a strict superset of JSON, with the addition of syntactically It's a strict superset of JSON, with the addition of syntactically
significant newlines and indentation, like Python. Unlike Python, however, significant newlines and indentation, like Python. Unlike Python, however,
YAML doesn't allow literal tab characters at all. YAML doesn't allow literal tab characters for indentation.
```yaml ```yaml
# Comments in YAML look like this. # Comments in YAML look like this.
@ -32,8 +32,10 @@ boolean: true
null_value: null null_value: null
key with spaces: value key with spaces: value
# Notice that strings don't need to be quoted. However, they can be. # Notice that strings don't need to be quoted. However, they can be.
however: "A string, enclosed in quotes." however: 'A string, enclosed in quotes.'
"Keys can be quoted too.": "Useful if you want to put a ':' in your key." 'Keys can be quoted too.': "Useful if you want to put a ':' in your key."
single quotes: 'have ''one'' escape pattern'
double quotes: "have many: \", \0, \t, \u263A, \x0d\x0a == \r\n, and more."
# Multiple-line strings can be written either as a 'literal block' (using |), # Multiple-line strings can be written either as a 'literal block' (using |),
# or a 'folded block' (using '>'). # or a 'folded block' (using '>').
@ -59,7 +61,7 @@ folded_style: >
# COLLECTION TYPES # # COLLECTION TYPES #
#################### ####################
# Nesting is achieved by indentation. # Nesting uses indentation. 2 space indent is preferred (but not required).
a_nested_map: a_nested_map:
key: value key: value
another_key: Another Value another_key: Another Value
@ -83,22 +85,26 @@ a_nested_map:
- Real Madrid - Real Madrid
: [ 2001-01-01, 2002-02-02 ] : [ 2001-01-01, 2002-02-02 ]
# Sequences (equivalent to lists or arrays) look like this: # Sequences (equivalent to lists or arrays) look like this
# (note that the '-' counts as indentation):
a_sequence: a_sequence:
- Item 1 - Item 1
- Item 2 - Item 2
- 0.5 # sequences can contain disparate types. - 0.5 # sequences can contain disparate types.
- Item 4 - Item 4
- key: value - key: value
another_key: another_value another_key: another_value
- -
- This is a sequence - This is a sequence
- inside another sequence - inside another sequence
- - - Nested sequence indicators
- can be collapsed
# Since YAML is a superset of JSON, you can also write JSON-style maps and # Since YAML is a superset of JSON, you can also write JSON-style maps and
# sequences: # sequences:
json_map: {"key": "value"} json_map: {"key": "value"}
json_seq: [3, 2, 1, "takeoff"] json_seq: [3, 2, 1, "takeoff"]
and quotes are optional: {key: [3, 2, 1, takeoff]}
####################### #######################
# EXTRA YAML FEATURES # # EXTRA YAML FEATURES #
@ -157,6 +163,7 @@ set:
? item1 ? item1
? item2 ? item2
? item3 ? item3
or: {item1, item2, item3}
# Like Python, sets are just maps with null values; the above is equivalent to: # Like Python, sets are just maps with null values; the above is equivalent to:
set2: set2: