go-gypsy: github.com/kylelemons/go-gypsy/yaml Index | Files

package yaml

import "github.com/kylelemons/go-gypsy/yaml"

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

Package Files

config.go doc.go parser.go types.go

func Render Uses

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.

type File Uses

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 Uses

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 Uses

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 Uses

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

ReadFile reads a YAML configuration file from the given filename.

func (*File) Count Uses

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 Uses

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 Uses

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

func (*File) GetInt Uses

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

func (*File) Require Uses

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 Uses

type List []Node

A List is a YAML Sequence of Nodes.

func (List) Item Uses

func (node List) Item(idx int) Node

Get the idx'th item from the List.

func (List) Len Uses

func (node List) Len() int

Get the number of items in the List.

type Map Uses

type Map map[string]Node

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

func (Map) Key Uses

func (node Map) Key(key string) Node

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

type Node Uses

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

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

func Child Uses

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 Uses

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 Uses

type NodeNotFound struct {
    Full string
    Spec string
}

func (*NodeNotFound) Error Uses

func (e *NodeNotFound) Error() string

type NodeTypeMismatch Uses

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

func (*NodeTypeMismatch) Error Uses

func (e *NodeTypeMismatch) Error() string

type Scalar Uses

type Scalar string

A Scalar is a YAML Scalar.

func (Scalar) String Uses

func (node Scalar) String() string

String returns the string represented by this Scalar.

Bugs

Multi-line strings are currently not supported.

Package yaml imports 9 packages (graph) and is imported by 141 packages. Updated 2019-07-24. Refresh now. Tools for package owners.