Title: Theory / Unimportant / CS / Descriptive / yaml

Name: YAML
Definition: a human-friendly data serialization language for all programming languages.
Etymology: Yaml Ain't Markup Language

Question: What are the primary use cases of YAML
Answer: configuration files,
Chapter: 1
Answer2: log files,
Answer3: interprocess messaging,
Answer4: cross-language data sharing,
Answer5: object persistence
Answer6: debugging of complex data structures

Question: What are the primary goals of YAML
Answer: should be easily readable by humans.
Chapter: 1
Answer2: data should be portable between programming languages.
Answer3: should match the native data structures of dynamic languages.
Answer4: should have a consistent model to support generic tools.
Answer5: should support one-pass processing.
Answer6: should be expressive and extensible.
Answer7: should be easy to implement and use.

Instruction: # foo
Page: https://yaml.org/spec/1.2.2/
Effect: none. Comment with text foo

Instruction: - foo_1
...
- foo_n
Page: https://yaml.org/spec/1.2.2/
Language: yaml
Returns: a sequence with elements foo_1. ... foo_n
Abbreviation: [foo_1, ..., foo_n]

Instruction: key_1: value_1
...
key_n: value_n
Page: https://yaml.org/spec/1.2.2/
Language: yaml
Returns: a mapping assigning value_i to key_
Abbreviation: {key_1: value_1, ...,  key_n: value_n}

Instruction: ---
Page: https://yaml.org/spec/1.2.2/
Effect: start a new document (ends the current one if any)
Language: yaml
Chapter: 2

Instruction: ...
Page: https://yaml.org/spec/1.2.2/
Effect: End the current document
Language: yaml

Instruction: &foo bar
Page: https://yaml.org/spec/1.2.2/
Language: yaml
Chapter: 2
Identifier: foo
Name: anchor
Initialization: bar

Instruction: *foo
Page: https://yaml.org/spec/1.2.2/
Language: yaml
Chapter: 2
Returns: the value assigned to the last anchor &foo seen

Instruction: |
Page: https://yaml.org/spec/1.2.2/
Effect: Switch to literal style (by default in clip mode)
Language: yaml
Chapter: 2

Instruction: >
Page: https://yaml.org/spec/1.2.2/
Effect: Switch to folded style
Language: yaml
Chapter: 2

Name: literal style
Definition: all text are kept as is (except for the starting indentation?) until going back to previous indentation level
Page: https://yaml.org/spec/1.2.2/
Chapter: 2
Context: yml

Name: folded style
Definition: all text are kept as is, except for newline which are transformed into space, except for empty line and greater more indented line
Page: https://yaml.org/spec/1.2.2/
Context: yml

Name: The quoted style
Definition: The single-quoted style and the double-quoted style
Page: https://yaml.org/spec/1.2.2/
Context: yml

Instruction: "foo"
Page: https://yaml.org/spec/1.2.2/
Language: yml
Chapter: 2
Section: 3
Returns: the string foo, where escaped sequences are interpreted as unicode, binary, hexadecimal, according to how they are escaped
Name: double-quoted style

Instruction: 'foo'
Page: https://yaml.org/spec/1.2.2/
Language: yml
Chapter: 2
Section: 3
Returns: the string foo, where escape are ignored
Name: single-quoted style

Instruction: .inf
Page: https://yaml.org/spec/1.2.2/
Language: yml
Chapter: 2
Section: 4
Returns: infinity float point

Instruction: .nan
Page: https://yaml.org/spec/1.2.2/
Language: yml
Chapter: 2
Section: 4
Returns: Not a Number
Typ: floating point

Instruction: !!type foo
Page: https://yaml.org/spec/1.2.2/
Language: yml
Chapter: 2
Section: 4
Returns: foo with type
Typ: floating point

Typ: ordered map
Meaning: a map, with key-value pair in a fixed order
Page: https://yaml.org/spec/1.2.2/
Language: yml
Chapter: 2
Section: 4
Implementation: a sequence of mappings with a single element each

Name: A YAML stream
Definition: A series of character representing a YAML data objects
Page: https://yaml.org/spec/1.2.2/
Chapter: 3

Name: A YAML representation
Definition: how YAML views native data structures to achieve portability between programming environments
Page: https://yaml.org/spec/1.2.2/
Definition2: A complete YAML representation

Name: Serialization
Definition: turning a YAML representation into a serial form
Page: https://yaml.org/spec/1.2.2/
Context: YAML

Name: A serial form
Definition: A form with seqential access constraints
Page: https://yaml.org/spec/1.2.2/
Context: YAML

Name: Dumping
Definition: Transforming a native data structure into a character stream
Page: https://yaml.org/spec/1.2.2/
Chapter: 3
Section: 1.1
Context: YAML

Name: Loading
Definition: Transforming a character stream into a native data structure
Page: https://yaml.org/spec/1.2.2/
Context: YAML

Name: Composing
Definition: Transforming a serialization tree into a representation graph
Page: https://yaml.org/spec/1.2.2/
Context: YAML

Name: A serialization tree
Definition: A representation of the yaml structure, using only a tree
Page: https://yaml.org/spec/1.2.2/
Context: YAML
Intuition: How the structure can be represented in a file, with identing related to indentation

Name: A representation graph
Definition: A representation of the yaml structure, using a graph
Page: https://yaml.org/spec/1.2.2/
Context: YAML

Question: Constraint about YAML representation graph
Answer: All nodes must be reachable from the root node
Page: https://yaml.org/spec/1.2.2/
Chapter: 3
Section: 2.1
Context: YAML

Name: A collection
Definition: sequence
Page: https://yaml.org/spec/1.2.2/
Chapter: 3
Section: 2.1
Context: YAML graph
Definition2: mapping
Conjdef: Either
DefType: A node defined in term of other nodes.

Name: A scalar
Definition: A node that is independent of any other node
Page: https://yaml.org/spec/1.2.2/
Chapter: 3
Section: 2.1
Context: YAML graph

Name: A node
Definition: a tag
Page: https://yaml.org/spec/1.2.2/
Chapter: 3
Section: 2.1.1
Context: YAML graph
Definition2: a content (scalar, sequence or mapping)
Conjdef: A pair with

Name: A global tag
Definition: a tag globally unique across all applications
Page: https://yaml.org/spec/1.2.2/
Chapter: 3
Section: 2.1.1
Context: YAML graph
Denoted by: Tag starting with "tag:"

Name: A local tag
Definition: a tag specific to the program
Page: https://yaml.org/spec/1.2.2/
Chapter: 3
Section: 2.1.1
Context: YAML graph
Denoted by: tag starting with !

Question: How does YAML test for equality?
Answer: Both node must have the same tag (character-by-character)
Page: https://yaml.org/spec/1.2.2/
Chapter: 3
Section: 2.1.3
Context: YAML
Answer2: Sequences must have the same length and the i-th node of both sequences are equal
Answer3: Mappings must have the same set of keys, and each key are associated to equal elements
Answer4: Each scalar tag must specify a mechanism for producing a canonical form as a unicode character string. It is used to test for equality
Answer5: in case of cyclic graph, equality is implementation dependant

Name: A YAML presentation
Definition: a stream of Unicode characters making use of styles, scalar content formats, comments, directives and other presentation details to present a YAML serialization in a human readable way.
Page: https://yaml.org/spec/1.2.2/
Chapter: 3
Section: 2.1.3
Context: YAML

Name: A node style
Definition: The way a node is displayed in a presentation
Page: https://yaml.org/spec/1.2.2/
Chapter: 3
Section: 2.3.1
Context: YAML

Name: A directive
Definition: A name
Page: https://yaml.org/spec/1.2.2/
Chapter: 3
Section: 2.3.4
Context: YAML
Definition2: an optional sequence of parameters
Conjdef: All of
Example2: TAG
Intuition: instructions to the YAML processor

Name: A partial representation
Definition: A YAML data structure, similar to representatino, with tag that may not resolve and some canonical form unavailable
Page: https://yaml.org/spec/1.2.2/
Chapter: 3
Context: YAML
Intuition: Data that remains accessible when composing failed

Question: What are the failure points
Answer: The character stream may be ill-formed,
Page: https://yaml.org/spec/1.2.2/
Chapter: 3
Context: YAML
Answer2: aliases may be unidentified,
Answer3: unspecified tags may be unresolvable,
Answer4: tags may be unrecognized,
Answer5: the content may be invalid,
Answer6: mapping keys may not be unique and
Answer7: a native type may be unavailable

Question: What does a YAML processor in case of syntax error
Answer: It must report error
Page: https://yaml.org/spec/1.2.2/
Chapter: 3
Context: YAML
Answer2: it may pursue and ignore broken part of the input or halt

Name: A non-specific tag
Definition: ! for non-(plain scalars)
Page: https://yaml.org/spec/1.2.2/
Chapter: 3
Context: YAML
Definition2: "?" for all other nodes

Question: What can be used to resolve a tag
Answer: the non-specific tag of teh node
Page: https://yaml.org/spec/1.2.2/
Chapter: 3
Section: 3.2
Context: YAML
Answer2: the path leading from the root to the node
Answer3: the content of the node

Name: A valid node
Definition: with a tag recognized by the YAML processor
Page: https://yaml.org/spec/1.2.2/
Chapter: 3
Section: 3.2
Context: YAML
Definition2: whose content satisfy the constraints imposed by this tag
DefType: A node

Name: An indicator character
Definition: characters that have special semantics. Any of - ? : , [ ] { } # & * ! | > ' " % @ `
Page: https://yaml.org/spec/1.2.2/
Chapter: 4
Context: YAML

Instruction: %foo
Page: https://yaml.org/spec/1.2.2/
Effect: give directive foo to the program
Context: YAML
Chapter: 4
Name: Directive

Name: A presentation detail
Definition: Some part of the implementation that must be igored during parsing
Example: Comments
Example2: Number of space in identation and separator
Example3: Order of map entries
Example4: Use of flow or block style

Question: Difference between yaml syntax as input and output
Answer: YAML output must end with a line break. The parser must accept the last line not having a line break
Page: https://yaml.org/spec/1.2.2/
Chapter: 6, 7, 8
Section: 6, 4.2, 1.1.1
Answer2: key-value pair may have spaces around : in output. It may be omitted in input (but may be ambiguous for the reader)
Answer3: explicit indentation indicator should not be used in output unless no other choice

Question: What does a YAML director should do on unknown directive
Answer: Emit a warning and ignore them
Page: https://yaml.org/spec/1.2.2/
Chapter: 6
Section: 8

Instruction: %YAML n
Page: https://yaml.org/spec/1.2.2/
Effect: state that the current document uses yaml version n
Language: YAML
Chapter: 6
Section: 8
Assuming: Unique for the document

Instruction: %TAG !shortand! full_tag
Page: https://yaml.org/spec/1.2.2/
Meaning: full_tag
Language: YAML
Chapter: 6
Section: 8
Identifier: shortand
Assuming: At most one such tag by shorthand

Instruction: %TAG ! foo
Page: https://yaml.org/spec/1.2.2/
Effect: the primary tag handle is foo. E.g. `!bar` is interpreted as foobar
Language: YAML
Chapter: 6
Assuming: At most one such tag by shorthand

Name: A serialization detail
Definition: Some detail present in the serialization tree but must be ignored by the representation
Page: https://yaml.org/spec/1.2.2/
Chapter: 6
Section: 9.2
Example: name of the anchors

Instruction: null
Page: https://yaml.org/spec/1.2.2/
Chapter: 7
Section: 2
Abbreviation: nothing (but in a place where a node must be)
Name: The empty node

Name: An explicit entry
Definition: A map entry starting with ?
Page: https://yaml.org/spec/1.2.2/
Chapter: 7
Section: 4.2
Context: YAML
Intuition: Can be anything, in particular multiline

Name: An implicit entry
Definition: A map entry not starting with ?
Page: https://yaml.org/spec/1.2.2/
Chapter: 7
Section: 4.2
Context: YAML
Denoted by: At most 1024 characters and single line

Instruction: -
Page: https://yaml.org/spec/1.2.2/
Effect: Switch to literal style in strip mode
Language: YAML
Chapter: 7
Section: 4.2

Instruction: +
Page: https://yaml.org/spec/1.2.2/
Effect: Switch to literal style in keep mode
Language: YAML
Chapter: 7
Section: 4.2

Name: Strip mode
Definition: the final line break and any trailing empty lines are excluded from the scalar’s content.
Page: https://yaml.org/spec/1.2.2/
Chapter: 7
Section: 4.2
Context: YAML

Name: clip mode
Definition: the final line break character is preserved in the scalar’s content. However, any trailing empty lines are excluded from the scalar’s content.
Page: https://yaml.org/spec/1.2.2/
Chapter: 7
Section: 4.2
Context: YAML

Name: Keep mode
Definition: the final line break and any trailing empty lines are considered to be part of the scalar’s content. These additional lines are not subject to folding.
Page: https://yaml.org/spec/1.2.2/
Chapter: 7
Section: 4.2
Context: YAML

Name: A bare document
Definition: A document that does not begin with any directives or marker lines
Page: https://yaml.org/spec/1.2.2/
Chapter: 9
Section: 1
Context: YAML

Name: An explicit document
Definition: A document that begins with an explicit directives end marker line but no directives.
Page: https://yaml.org/spec/1.2.2/
Chapter: 9
Section: 1
Context: YAML

Name: A directive document
Definition: A document that begins with some directives followed by an explicit directives end marker line
Page: https://yaml.org/spec/1.2.2/
Chapter: 9
Section: 1
Context: YAML

Name: A YAML stream
Definition: Zero or more YAML document, seperated by document or directives end marker line
Page: https://yaml.org/spec/1.2.2/
Chapter: 9
Section: 1
Context: YAML

Name: A YAML schemata
Definition: a combination of a set of tags and a mechanism for resolving non-specific tags.
Page: https://yaml.org/spec/1.2.2/
Chapter: 10
Context: YAML

Name: the failsafe schemata
Definition: Schemata guaranteed to work with any YAML document.
Page: https://yaml.org/spec/1.2.2/
Chapter: 10
Context: YAML
Intuition: recommended schema for generic YAML tools.

Name: todo:
Definition: End with tags once better understood in details
Page: https://yaml.org/spec/1.2.2/
Chapter: 10
Context: YAML