From 7aa536ff0dae8ca981ac0476b502cd7bf43e6ff3 Mon Sep 17 00:00:00 2001 From: Alex Golub Date: Mon, 17 Oct 2022 18:51:39 +0300 Subject: [yaml/en] Add more information/examples about YAML capabilities --- yaml.html.markdown | 112 ++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 81 insertions(+), 31 deletions(-) (limited to 'yaml.html.markdown') 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 } - " + +# 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/) -- cgit v1.2.3