doc.go

// Copyright 2013 Google, Inc.  All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

// 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.
package yaml

// BUG(kevlar): Multi-line strings are currently not supported.