An Introduction to YAML
Author: Manuela Hutter
Introduction
YAML: A data serialization format

- uses an indented outline
- avoids enclosures (quotation marks, brackets, open/close tags)
- uses a hierarchical representation (tree)
- common data types (scalars, lists and maps)
- also allows for the representation of relational data

Data Types: Scalars
Scalars are simple data types, like strings, integers, boolean values or dates.
Examples:

    A simple string

    42

    true

Data Types: Lists
For exmaple: a list of widgets

    - Button
    - Edit
    - Label
    - CheckBox

Data Types: Maps
A map spedifies a bunch of 'key: value' pairs.
For example: the attributes of a button:

    name:  MyButton
    string: Show
    action: Show Mail Panel
    icon:   view_icon.png

Nesting Data: List in a Map
Lists and maps can be nested within each other. Here is where indentation comes in: The map value is now not a simple scalar, so it is put in the next line(s) and indented. Indentation is done using spaces. TAB indentation is not allowed.
Example: a layout object holds attributes about itself, plus a list of its child widgets

    type: StackLayout
    name: main layout
    orientation: horizontal
    elements:
      - Label
      - Edit
      - Button

Nesting Data: Maps in a List
Also, a list doesn't necessarily just hold strings. A list can again hold nested data.
Example: a list of widgets

    - type: Label
      name: name_label
      text: Enter name

    - type: Edit
      name: name_edit

    - type: Button
      name: save_button
      text: Save
      action: Save Name

Referencing Data
Sometimes you have data that you need to use in different places, and you don't want to copy&paste all content into different places. In YAML, you can set an anchor to a map ('&') in one place, and reference the map ('*') in another place. The anchor is specified in the line above the map.
Example: Use a 'Save' button twice.

    - type: Edit
      name: firstname_edit

    - &SaveButton
      type: Button
      name: save_button
      text: Save
      action: Save Name

    - type: Edit
      name: lastname_edit

    - *SaveButton

This example is automatically expanded to:

    - type: Edit
      name: firstname_edit

    - type: Button
      name: save_button
      text: Save
      action: Save Name

    - type: Edit
      name: lastname_edit

    - type: Button
      name: save_button
      text: Save
      action: Save Name

Merging Data
Sometimes you need almost the same data in different places, changing just one little thing. You can do this by copying in the map that you want to base your changes on (using '<<'), and then override or add a key/value pair.
Example: Use a 'Save' button twice, but change
its name and add an icon in the second one.

    - type: Edit
      name: firstname_edit

    - &SaveButton
      type: Button
      name: save_button
      text: Save
      action: Save Name

    - type: Edit
      name: lastname_edit

    - <<: *SaveButton
      name: save_button_2
      icon: save.png

This example is automatically expanded to:

    - type: Edit
      name: firstname_edit

    - type: Button
      name: save_button
      text: Save
      action: Save Name

    - type: Edit
      name: lastname_edit

    - type: Button
      name: save_button_2
      text: Save
      action: Save Name
      icon: save.png

Sample Dialog: Server Name Completion
As found in Tools -> Preferences -> Advanced -> Network -> Server Name Completion
Sample Dialog

    dialogs:
      - type: Dialog
        name: Name Completion Dialog
        title: DI_NAMECOMPLETION
        content:
          type: StackLayout
          elements:
            - type: CheckBox
              name: Local_machine_checkbox
              string: DI_IDM_TRY_LOCAL_TOGGLE
            - type: CheckBox
              name: Completion_checkbox
              string: DI_IDM_TRY_NAME_COMPLETION_TOGGLE
              content:
                type: GridLayout
                elements:
                  - type: GridRowLayout
                    elements:
                      - type: Label
                        name: label_for_Prefixes_edit
                        string: DI_IDM_NC_START_LABEL
                      - type: Edit
                        name: Prefixes_edit
                  - type: GridRowLayout
                    elements:
                      - type: Label
                        name: label_for_Suffixes_edit
                        string: DI_IDM_NC_END_LABEL
                      - type: Edit
                        name: Suffixes_edit
        button-strip:
          <<: *OkCancelHelpButtonStrip
          help_anchor: "server.html"

    definitions:
      buttons:
        OkButton: &OkButton
          type: Button
          name: ok_button
          string: DI_ID_OK
          action: Ok

        CancelButton: &CancelButton
          type: Button
          name: cancel_button
          string: DI_ID_CANCEL
          action: Cancel

        HelpButton: &HelpButton
          type: Button
          name: help_button
          string: DI_ID_HELP
          action: Show help

      button-strips:
        OkCancelHelpButtonStrip: &OkCancelHelpButtonStrip
          type: ButtonStrip
          buttons:
            - *OkButton
            - *CancelButton
            - *HelpButton

References

- YAML Website
- Wikipedia: YAML
- YAML Online Parser