Add YAML guide

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
+```