summaryrefslogtreecommitdiffhomepage
diff options
context:
space:
mode:
authorAdam Brenecki <adam@brenecki.id.au>2014-03-02 12:01:54 +1030
committerAdam Brenecki <adam@brenecki.id.au>2014-03-02 12:01:54 +1030
commitff5e64f4043fa06461ef422885444e837bfab6c9 (patch)
tree62784d357728d182d7a97876d05951692409198a
parentb5939602c6ca9a941bb47a0c00da23e57221ffbf (diff)
Add YAML guide
-rw-r--r--yaml.html.markdown139
1 files changed, 139 insertions, 0 deletions
diff --git a/yaml.html.markdown b/yaml.html.markdown
new file mode 100644
index 00000000..c5d15895
--- /dev/null
+++ b/yaml.html.markdown
@@ -0,0 +1,139 @@
+---
+language: yaml
+filename: learnyaml.yaml
+contributors:
+ - ["Adam Brenecki", "https://github.com/adambrenecki"]
+---
+
+YAML is a data serialisation language designed to be directly writable and
+readable by humans.
+
+It's a strict superset of JSON, with the addition of syntactically
+significant newlines and indentation, like Python. Unlike Python, however,
+YAML doesn't allow literal tab characters at all.
+
+```yaml
+# Comments in YAML look like this.
+
+################
+# SCALAR TYPES #
+################
+
+# Our root object (which continues for the entire document) will be a map,
+# which is equivalent to a dictionary, hash or object in other languages.
+key: value
+another_key: Another value goes here.
+a_number_value: 100
+scientific_notation: 1e+12
+boolean: true
+null_value: null
+key with spaces: value
+# 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."
+
+# Multiple-line strings can be written either as a 'literal block' (using |),
+# or a 'folded block' (using '>')
+literal_block: |
+ 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.
+
+ 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.
+
+ Blank lines, like above, are converted to a newline character.
+
+ 'More-indented' lines keep their newlines, too -
+ this text will appear over two lines.
+
+####################
+# COLLECTION TYPES #
+####################
+
+# Nesting is achieved by indentation.
+a_nested_map:
+ key: value
+ another_key: Another Value
+ another_nested_map:
+ hello: hello
+
+# Maps don't have to have string keys.
+0.25: a float key
+
+# Keys can also be multi-line objects, using ? to indicate the start of a key
+? |
+ This is a key
+ that has multiple lines
+: and this is its value
+
+# YAML also allows collection types in keys, but many programming languages
+# will complain.
+
+# Sequences (equivalent to lists or arrays) look like this:
+a_sequence:
+ - Item 1
+ - Item 2
+ - 0.5 # sequences can contain disparate types
+ - Item 4
+ - key: value
+ another_key: another_value
+ -
+ - This is a sequence
+ - inside another sequence
+
+# 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"]
+
+#######################
+# 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:
+anchored_content: &anchor_name This string will appear as the value of two keys.
+other_anchor: *anchor_name
+
+# YAML also has tags, which you can use to explicitly declare types.
+explicit_string: !!str 0.5
+# Some parsers implement language specific tags, like this one for Python's
+# complex number type.
+python_complex_number: !!python/complex 1+2j
+
+####################
+# EXTRA YAML TYPES #
+####################
+
+# 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
+
+# The !!binary tag indicates that a string is actually a base64-encoded
+# representation of a binary blob.
+gif_file: !!binary |
+ R0lGODlhDAAMAIQAAP//9/X17unp5WZmZgAAAOfn515eXvPz7Y6OjuDg4J+fn5
+ OTk6enp56enmlpaWNjY6Ojo4SEhP/++f/++f/++f/++f/++f/++f/++f/++f/+
+ +f/++f/++f/++f/++f/++SH+Dk1hZGUgd2l0aCBHSU1QACwAAAAADAAMAAAFLC
+ AgjoEwnuNAFOhpEMTRiggcz4BNJHrv/zCFcLiwMWYNG84BwwEeECcgggoBADs=
+
+# YAML also has a set type, which looks like this:
+set:
+ ? item1
+ ? item2
+ ? item3
+
+# Like Python, sets are just maps with null values; the above is equivalent to:
+set2:
+ item1: null
+ item2: null
+ item3: null
+```