[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,12 +61,12 @@ 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
another_nested_map: another_nested_map:
hello: hello hello: hello
# Maps don't have to have string keys. # Maps don't have to have string keys.
0.25: a float key 0.25: a float key
@ -72,8 +74,8 @@ a_nested_map:
# Keys can also be complex, like multi-line objects # Keys can also be complex, like multi-line objects
# We use ? followed by a space to indicate the start of a complex key. # We use ? followed by a space to indicate the start of a complex key.
? | ? |
This is a key This is a key
that has multiple lines that has multiple lines
: and this is its value : and this is its value
# YAML also allows mapping between sequences with the complex key syntax # YAML also allows mapping between sequences with the complex key syntax
@ -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 #
@ -111,15 +117,15 @@ other_anchor: *anchor_name
# Anchors can be used to duplicate/inherit properties # Anchors can be used to duplicate/inherit properties
base: &base base: &base
name: Everyone has same name name: Everyone has same name
foo: &foo foo: &foo
<<: *base <<: *base
age: 10 age: 10
bar: &bar bar: &bar
<<: *base <<: *base
age: 20 age: 20
# foo and bar would also have name: Everyone has same name # foo and bar would also have name: Everyone has same name
@ -147,22 +153,23 @@ date: 2002-12-14
# The !!binary tag indicates that a string is actually a base64-encoded # The !!binary tag indicates that a string is actually a base64-encoded
# representation of a binary blob. # representation of a binary blob.
gif_file: !!binary | gif_file: !!binary |
R0lGODlhDAAMAIQAAP//9/X17unp5WZmZgAAAOfn515eXvPz7Y6OjuDg4J+fn5 R0lGODlhDAAMAIQAAP//9/X17unp5WZmZgAAAOfn515eXvPz7Y6OjuDg4J+fn5
OTk6enp56enmlpaWNjY6Ojo4SEhP/++f/++f/++f/++f/++f/++f/++f/++f/+ OTk6enp56enmlpaWNjY6Ojo4SEhP/++f/++f/++f/++f/++f/++f/++f/++f/+
+f/++f/++f/++f/++f/++SH+Dk1hZGUgd2l0aCBHSU1QACwAAAAADAAMAAAFLC +f/++f/++f/++f/++f/++SH+Dk1hZGUgd2l0aCBHSU1QACwAAAAADAAMAAAFLC
AgjoEwnuNAFOhpEMTRiggcz4BNJHrv/zCFcLiwMWYNG84BwwEeECcgggoBADs= AgjoEwnuNAFOhpEMTRiggcz4BNJHrv/zCFcLiwMWYNG84BwwEeECcgggoBADs=
# YAML also has a set type, which looks like this: # YAML also has a set type, which looks like this:
set: 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:
item1: null item1: null
item2: null item2: null
item3: null item3: null
``` ```
### More Resources ### More Resources