summaryrefslogtreecommitdiffhomepage
path: root/yaml.html.markdown
diff options
context:
space:
mode:
authorAlex Golub <a12thu@gmail.com>2022-10-17 18:51:39 +0300
committerAlex Golub <a12thu@gmail.com>2022-10-17 18:51:39 +0300
commit7aa536ff0dae8ca981ac0476b502cd7bf43e6ff3 (patch)
tree94b9b25665ede6e33e9d83e14a8eb686edb38b2c /yaml.html.markdown
parent5c1d67e81502b0b212ba0961d2a7df731cfb3667 (diff)
[yaml/en] Add more information/examples about YAML capabilities
Diffstat (limited to 'yaml.html.markdown')
-rw-r--r--yaml.html.markdown112
1 files changed, 81 insertions, 31 deletions
diff --git a/yaml.html.markdown b/yaml.html.markdown
index 6dc5905e..5c898148 100644
--- a/yaml.html.markdown
+++ b/yaml.html.markdown
@@ -2,8 +2,10 @@
language: yaml
filename: learnyaml.yaml
contributors:
+
- [Leigh Brenecki, 'https://leigh.net.au']
- [Suhas SG, 'https://github.com/jargnar']
+
---
YAML is a data serialisation language designed to be directly writable and
@@ -17,6 +19,7 @@ YAML doesn't allow literal tab characters for indentation.
--- # document start
# Comments in YAML look like this.
+# YAML support single-line comments.
################
# SCALAR TYPES #
@@ -28,11 +31,23 @@ key: value
another_key: Another value goes here.
a_number_value: 100
scientific_notation: 1e+12
-# The number 1 will be interpreted as a number, not a boolean. if you want
-# it to be interpreted as a boolean, use true
+hex_notation: 0x123 # evaluates to 291
+octal_notation: 0123 # evaluates to 83
+
+# The number 1 will be interpreted as a number, not a boolean.
+# If you want it to be interpreted as a boolean, use true.
boolean: true
null_value: null
key with spaces: value
+
+# Yes and No (doesn't matter the case) will be evaluated to boolean
+# true and false values respectively.
+# To use the actual value use single or double quotes.
+no: no # evaluates to "false": false
+yes: No # evaluates to "true": false
+not_enclosed: yes # evaluates to "not_enclosed": true
+enclosed: "yes" # evaluates to "enclosed": yes
+
# Notice that strings don't need to be quoted. However, they can be.
however: 'A string, enclosed in quotes.'
'Keys can be quoted too.': "Useful if you want to put a ':' in your key."
@@ -41,25 +56,49 @@ double quotes: "have many: \", \0, \t, \u263A, \x0d\x0a == \r\n, and more."
# UTF-8/16/32 characters need to be encoded
Superscript two: \u00B2
-# Multiple-line strings can be written either as a 'literal block' (using |),
+# Special characters must be enclosed in single or double quotes
+special_characters: "[ John ] & { Jane } - <Doe>"
+
+# Multiple-line strings can be written either as a 'literal block' (using |),
# or a 'folded block' (using '>').
+# Literal block turn every newline within the string into a literal newline (\n).
+# Folded block removes newlines within the string.
literal_block: |
- This entire block of text will be the value of the 'literal_block' key,
- with line breaks being preserved.
+ 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.
+ 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.
+ Any lines that are 'more-indented' keep the rest of their indentation -
+ these lines will be indented by 4 spaces.
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.
+ 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.
+ Blank lines, like above, are converted to a newline character.
- 'More-indented' lines keep their newlines, too -
- this text will appear over two lines.
+ 'More-indented' lines keep their newlines, too -
+ this text will appear over two lines.
+
+# |- and >- removes the trailing blank lines (also called literal/block "strip")
+literal_strip: |-
+ This entire block of text will be the value of the 'literal_block' key,
+ with trailing blank line being stripped.
+block_strip: >-
+ This entire block of text will be the value of 'folded_style', but this
+ time, all newlines will be replaced with a single space and
+ trailing blank line being stripped.
+
+# |+ and >+ keeps trailing blank lines (also called literal/block "keep")
+literal_keep: |+
+ This entire block of text will be the value of the 'literal_block' key,
+ with trailing blank line being kept.
+
+block_keep: >+
+ This entire block of text will be the value of 'folded_style', but this
+ time, all newlines will be replaced with a single space and
+ trailing blank line being kept.
####################
# COLLECTION TYPES #
@@ -87,7 +126,7 @@ a_nested_map:
# An example
? - Manchester United
- Real Madrid
-: [2001-01-01, 2002-02-02]
+: [ 2001-01-01, 2002-02-02 ]
# Sequences (equivalent to lists or arrays) look like this
# (note that the '-' counts as indentation):
@@ -98,24 +137,26 @@ a_sequence:
- Item 4
- key: value
another_key: another_value
- -
- - This is a sequence
+ - - This is a 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
# sequences:
-json_map: {"key": "value"}
-json_seq: [3, 2, 1, "takeoff"]
-and quotes are optional: {key: [3, 2, 1, takeoff]}
+json_map: { "key": "value" }
+json_seq: [ 3, 2, 1, "takeoff" ]
+and quotes are optional: { key: [ 3, 2, 1, takeoff ] }
#######################
# EXTRA YAML FEATURES #
#######################
# YAML also has a handy feature called 'anchors', which let you easily duplicate
-# content across your document. Both of these keys will have the same value:
+# content across your document.
+# Anchors identified by & character which define the value.
+# Aliases identified by * character which acts as "see above" command.
+# Both of these keys will have the same value:
anchored_content: &anchor_name This string will appear as the value of two keys.
other_anchor: *anchor_name
@@ -123,28 +164,35 @@ other_anchor: *anchor_name
base: &base
name: Everyone has same name
-# The regexp << is called Merge Key Language-Independent Type. It is used to
+# The regexp << is called 'Merge Key Language-Independent Type'. It is used to
# indicate that all the keys of one or more specified maps should be inserted
# into the current map.
-
+# NOTE: If key already exists alias will not be merged
foo:
- <<: *base
+ <<: *base # doesn't merge the anchor
age: 10
-
+ name: John
bar:
- <<: *base
+ <<: *base # base anchor will be merged
age: 20
# foo and bar would also have name: Everyone has same name
# YAML also has tags, which you can use to explicitly declare types.
+# Syntax: !![typeName] [value]
+explicit_boolean: !!bool true
+explicit_integer: !!int 42
+explicit_float: !!float -42.24
explicit_string: !!str 0.5
+explicit_datetime: !!timestamp 2022-11-17 12:34:56.78 +9
+explicit_null: !!null null
+
# Some parsers implement language specific tags, like this one for Python's
# complex number type.
python_complex_number: !!python/complex 1+2j
# We can also use yaml complex keys with language specific tags
-? !!python/tuple [5, 7]
+? !!python/tuple [ 5, 7 ]
: Fifty Seven
# Would be {(5, 7): 'Fifty Seven'} in Python
@@ -154,9 +202,10 @@ python_complex_number: !!python/complex 1+2j
# Strings and numbers aren't the only scalars that YAML can understand.
# ISO-formatted date and datetime literals are also parsed.
-datetime: 2001-12-15T02:59:43.1Z
-datetime_with_spaces: 2001-12-14 21:59:43.10 -5
-date: 2002-12-14
+datetime_canonical: 2001-12-15T02:59:43.1Z
+datetime_space_seperated_with_time_zone: 2001-12-14 21:59:43.10 -5
+date_implicit: 2002-12-14
+date_explicit: !!timestamp 2002-12-14
# The !!binary tag indicates that a string is actually a base64-encoded
# representation of a binary blob.
@@ -171,7 +220,7 @@ set:
? item1
? item2
? item3
-or: {item1, item2, item3}
+or: { item1, item2, item3 }
# Sets are just maps with null values; the above is equivalent to:
set2:
@@ -186,3 +235,4 @@ set2:
+ [YAML official website](https://yaml.org/)
+ [Online YAML Validator](http://www.yamllint.com/)
++ [JSON ⇆ YAML](https://www.json2yaml.com/)