yaml

Documentation

Overview

Gypsy is a simplified YAML parser written in Go. It is intended to be used as a simple configuration file, and as such does not support a lot of the more nuanced syntaxes allowed in full-fledged YAML. YAML does not allow indent with tabs, and GYPSY does not ever consider a tab to be a space character. It is recommended that your editor be configured to convert tabs to spaces when editing Gypsy config files.

Gypsy understands the following to be a list:

• one
• two
• three

This is parsed as a `yaml.List`, and can be retrieved from the `yaml.Node.List()` method. In this case, each element of the `yaml.List` would be a `yaml.Scalar` whose value can be retrieved with the `yaml.Scalar.String()` method.

Gypsy understands the following to be a mapping:

key:     value
foo:     bar
running: away

A mapping is an unordered list of `key:value` pairs. All whitespace after the colon is stripped from the value and is used for alignment purposes during export. If the value is not a list or a map, everything after the first non-space character until the end of the line is used as the `yaml.Scalar` value.

Gypsy allows arbitrary nesting of maps inside lists, lists inside of maps, and maps and/or lists nested inside of themselves.

A map inside of a list:

• name: John Smith age: 42
• name: Jane Smith age: 45

A list inside of a map:

schools:
  - Meadow Glen
  - Forest Creek
  - Shady Grove
libraries:
  - Joseph Hollingsworth Memorial
  - Andrew Keriman Memorial

A list of lists:

• - one
• two
• three
• - un
• deux
• trois
• - ichi
• ni
• san

A map of maps:

google:
  company: Google, Inc.
  ticker:  GOOG
  url:     http://google.com/
yahoo:
  company: Yahoo, Inc.
  ticker:  YHOO
  url:     http://yahoo.com/

In the case of a map of maps, all sub-keys must be on subsequent lines and indented equally. It is allowable for the first key/value to be on the same line if there is more than one key/value pair, but this is not recommended.

Values can also be expressed in long form (leading whitespace of the first line is removed from it and all subsequent lines). In the normal (baz) case, newlines are treated as spaces, all indentation is removed. In the folded case (bar), newlines are treated as spaces, except pairs of newlines (e.g. a blank line) are treated as a single newline, only the indentation level of the first line is removed, and newlines at the end of indented lines are preserved. In the verbatim (foo) case, only the indent at the level of the first line is stripped. The example:

foo: |
  lorem ipsum dolor
  sit amet
bar: >
  lorem ipsum

    dolor

  sit amet
baz:
  lorem ipsum
   dolor sit amet

The YAML subset understood by Gypsy can be expressed (loosely) in the following grammar (not including comments):

        OBJECT = MAPPING | SEQUENCE | SCALAR .
  SHORT-OBJECT = SHORT-MAPPING | SHORT-SEQUENCE | SHORT-SCALAR .
           EOL = '\n'

       MAPPING = { LONG-MAPPING | SHORT-MAPPING } .
      SEQUENCE = { LONG-SEQUENCE | SHORT-SEQUENCE } .
        SCALAR = { LONG-SCALAR | SHORT-SCALAR } .

  LONG-MAPPING = { INDENT KEY ':' OBJECT EOL } .
 SHORT-MAPPING = '{' KEY ':' SHORT-OBJECT { ',' KEY ':' SHORT-OBJECT } '}' EOL .

 LONG-SEQUENCE = { INDENT '-' OBJECT EOL } EOL .
SHORT-SEQUENCE = '[' SHORT-OBJECT { ',' SHORT-OBJECT } ']' EOL .

   LONG-SCALAR = ( '|' | '>' | ) EOL { INDENT SHORT-SCALAR EOL }
  SHORT-SCALAR = { alpha | digit | punct | ' ' | '\t' } .

           KEY = { alpha | digit }
        INDENT = { ' ' }

Any line where the first non-space character is a sharp sign (#) is a comment. It will be ignored. Only full-line comments are allowed.

Index

• func Render(node Node) string
• type File
  • func Config(yamlconf string) *File
  • func ConfigFile(filename string) *File
  • func ReadFile(filename string) (*File, error)
  • func (f *File) Count(spec string) (int, error)
  • func (f *File) Get(spec string) (string, error)
  • func (f *File) GetBool(spec string) (bool, error)
  • func (f *File) GetInt(spec string) (int64, error)
  • func (f *File) Require(spec string) string
• type List
  • func (node List) Item(idx int) Node
  • func (node List) Len() int
• type Map
  • func (node Map) Key(key string) Node
• type Node
  • func Child(root Node, spec string) (Node, error)
  • func Parse(r io.Reader) (node Node, err error)
• type NodeNotFound
  • func (e *NodeNotFound) Error() string
• type NodeTypeMismatch
  • func (e *NodeTypeMismatch) Error() string
• type Scalar
  • func (node Scalar) String() string
• Bugs

Functions

func Render

func Render(node Node) string

Render returns a string of the node as a YAML document. Note that Scalars will have a newline appended if they are rendered directly.

Types

type File

type File struct {
	Root Node
}

A File represents the top-level YAML node found in a file. It is intended for use as a configuration file.

func Config

func Config(yamlconf string) *File

Config reads a YAML configuration from a static string. If an error is found, it will panic. This is a utility function and is intended for use in initializers.

func ConfigFile

func ConfigFile(filename string) *File

ConfigFile reads a YAML configuration file from the given filename and panics if an error is found. This is a utility function and is intended for use in initializers.

func ReadFile

func ReadFile(filename string) (*File, error)

ReadFile reads a YAML configuration file from the given filename.

func (*File) Count

func (f *File) Count(spec string) (int, error)

Count retrieves a the number of elements in the specified list from the file using the same format as that expected by Child. If the final node is not a List, Count will return an error.

func (*File) Get

func (f *File) Get(spec string) (string, error)

Get retrieves a scalar from the file specified by a string of the same format as that expected by Child. If the final node is not a Scalar, Get will return an error.

func (*File) GetBool

func (f *File) GetBool(spec string) (bool, error)

func (*File) GetInt

func (f *File) GetInt(spec string) (int64, error)

func (*File) Require

func (f *File) Require(spec string) string

Require retrieves a scalar from the file specified by a string of the same format as that expected by Child. If the final node is not a Scalar, String will panic. This is a convenience function for use in initializers.

type List

type List []Node

A List is a YAML Sequence of Nodes.

func (List) Item

func (node List) Item(idx int) Node

Get the idx'th item from the List.

func (List) Len

func (node List) Len() int

Get the number of items in the List.

type Map

type Map map[string]Node

A Map is a YAML Mapping which maps Strings to Nodes.

func (Map) Key

func (node Map) Key(key string) Node

Key returns the value associeted with the key in the map.

type Node

type Node interface {
	// contains filtered or unexported methods
}

A Node is a YAML Node which can be a Map, List or Scalar.

func Child

func Child(root Node, spec string) (Node, error)

Child retrieves a child node from the specified node as follows:

.mapkey   - Get the key 'mapkey' of the Node, which must be a Map
[idx]     - Choose the index from the current Node, which must be a List

The above selectors may be applied recursively, and each successive selector applies to the result of the previous selector. For convenience, a "." is implied as the first character if the first character is not a "." or "[". The node tree is walked from the given node, considering each token of the above format. If a node along the evaluation path is not found, an error is returned. If a node is not the proper type, an error is returned. If the final node is not a Scalar, an error is returned.

func Parse

func Parse(r io.Reader) (node Node, err error)

Parse returns a root-level Node parsed from the lines read from r. In general, this will be done for you by one of the File constructors.

type NodeNotFound

type NodeNotFound struct {
	Full string
	Spec string
}

func (*NodeNotFound) Error

func (e *NodeNotFound) Error() string

type NodeTypeMismatch

type NodeTypeMismatch struct {
	Full     string
	Spec     string
	Token    string
	Node     Node
	Expected string
}

func (*NodeTypeMismatch) Error

func (e *NodeTypeMismatch) Error() string

type Scalar

type Scalar string

A Scalar is a YAML Scalar.

func (Scalar) String

func (node Scalar) String() string

String returns the string represented by this Scalar.

Notes

Bugs

• Multi-line strings are currently not supported.