Configuration - YAML

Configuration - YAML

I. Introduction

The design goal of the YAML language (pronounced /ˈjæməl/) is to facilitate human readability and writability. It is essentially a general-purpose data serialization format.

The basic syntax rules are as follows.

Case sensitive

Use indentation to represent hierarchical relationships

Tabs are not allowed for indentation, only spaces are permitted.

The number of spaces for indentation is not important, as long as elements at the same level are aligned to the left

# indicates a comment, from this character to the end of the line will be ignored by the parser.

YAML supports three data structures.

Object: A collection of key-value pairs, also known as mapping/hashes/dictionary

Array: An ordered sequence of values, also known as sequence/list

Scalars: Single, indivisible values

These three structures are described below.

II. Object

A set of key-value pairs in an object is represented using a colon structure.

``` animal: pets


Converted to JavaScript as follows.

> ```
{ animal: 'pets' }

YAML also allows another notation, writing all key-value pairs as an inline object.

``` hash: { name: Steve, foo: bar }


Converted to JavaScript as follows.

> ```
{ hash: { name: 'Steve', foo: 'bar' } }

III. Array

A set of lines starting with a hyphen constitutes an array.

``` - Cat - Dog - Goldfish


Converted to JavaScript as follows.

> ```
[ 'Cat', 'Dog', 'Goldfish' ]

If the sub-member of the data structure is an array, you can indent a space under that item.

> ```

Cat
Dog
Goldfish


Converted to JavaScript as follows.

> ```
[ [ 'Cat', 'Dog', 'Goldfish' ] ]

Arrays can also be represented using inline notation.

``` animal: [Cat, Dog]


Converted to JavaScript as follows.

> ```
{ animal: [ 'Cat', 'Dog' ] }

IV. Composite Structures

Objects and arrays can be combined to form composite structures.

``` languages: - Ruby - Perl - Python websites: YAML: yaml.org Ruby: ruby-lang.org Python: python.org Perl: use.perl.org


Converted to JavaScript as follows.

> ```
{ languages: [ 'Ruby', 'Perl', 'Python' ],
  websites:
   { YAML: 'yaml.org',
     Ruby: 'ruby-lang.org',
     Python: 'python.org',
     Perl: 'use.perl.org' } }

V. Scalars

Scalars are the most basic, indivisible values. The following data types belong to JavaScript scalars.

String

Boolean

Integer

Float

Null

Time

Date

Values are represented in literal form.

``` number: 12.30


Converted to JavaScript as follows.

> ```
{ number: 12.30 }

Boolean values are represented by true and false.

``` isSet: true


Converted to JavaScript as follows.

> ```
{ isSet: true }

null is represented by ~.

``` parent: ~


Converted to JavaScript as follows.

> ```
{ parent: null }

Time is represented in ISO8601 format.

``` iso8601: 2001-12-14t21:59:43.10-05:00


Converted to JavaScript as follows.

> ```
{ iso8601: new Date('2001-12-14t21:59:43.10-05:00') }

Date is represented using the composite ISO8601 format of year, month, and day.

``` date: 1976-07-31


Converted to JavaScript as follows.

> ```
{ date: new Date('1976-07-31') }

YAML allows the use of two exclamation points to forcefully convert data types.

``` e: !!str 123 f: !!str true


Converted to JavaScript as follows.

> ```
{ e: '123', f: 'true' }

VI. Strings

Strings are the most common and also the most complex data type.

Strings are not quoted by default.

``` str: 这是一行字符串


Converted to JavaScript as follows.

> ```
{ str: '这是一行字符串' }

If a string contains spaces or special characters, it needs to be enclosed in quotes.

``` str: '内容：字符串'


Converted to JavaScript as follows.

> ```
{ str: '内容: 字符串' }

Both single and double quotes can be used, and double quotes will not escape special characters.

``` s1: '内容\n字符串' s2: "内容\n字符串"


Converted to JavaScript as follows.

> ```
{ s1: '内容\\n字符串', s2: '内容\n字符串' }

If there are single quotes within single quotes, two consecutive single quotes must be used to escape.

``` str: 'labor''s day'


Converted to JavaScript as follows.

> ```
{ str: 'labor\'s day' }

Strings can be written in multiple lines, and starting from the second line, there must be a single space indentation. Line breaks will be converted into spaces.

``` str: 这是一段多行字符串


Converted to JavaScript as follows.

> ```
{ str: '这是一段 多行 字符串' }

Multiline strings can use | to preserve line breaks or > to fold line breaks.

``` this: | Foo Bar that: > Foo Bar


Converted to JavaScript as follows.

> ```
{ this: 'Foo\nBar\n', that: 'Foo Bar\n' }

+ indicates preserving the ending line breaks of text blocks, and - indicates removing the ending line breaks of strings.

``` s1: | Foo s2: |+ Foo s3: |- Foo


Converted to JavaScript as follows.

> ```
{ s1: 'Foo\n', s2: 'Foo\n\n\n', s3: 'Foo' }

HTML tags can be inserted within strings.

``` message: |

段落


Converted to JavaScript as follows.

> ```
{ message: '\n<p style="color: red">\n  段落\n</p>\n' }

VII. References

Anchors & and aliases * can be used for references.

``` defaults: &defaults adapter: postgres host: localhost development: database: myapp_development <<: defaults test: database: myapp_test <<: defaults


Equivalent to the following code.

> ```
defaults:
  adapter:  postgres
  host:     localhost
development:
  database: myapp_development
  adapter:  postgres
  host:     localhost
test:
  database: myapp_test
  adapter:  postgres
  host:     localhost

& is used to create an anchor (defaults), << indicates merging into current data, and * is used to reference the anchor.

Here is another example.

``` - &showell Steve - Clark - Brian - Oren - *showell


Converted to JavaScript as follows.

> ```
[ 'Steve', 'Clark', 'Brian', 'Oren', 'Steve' ]