1require 'psych/nodes/node'
2require 'psych/nodes/stream'
3require 'psych/nodes/document'
4require 'psych/nodes/sequence'
5require 'psych/nodes/scalar'
6require 'psych/nodes/mapping'
7require 'psych/nodes/alias'
8
9module Psych
10  ###
11  # = Overview
12  #
13  # When using Psych.load to deserialize a YAML document, the document is
14  # translated to an intermediary AST.  That intermediary AST is then
15  # translated in to a Ruby object graph.
16  #
17  # In the opposite direction, when using Psych.dump, the Ruby object graph is
18  # translated to an intermediary AST which is then converted to a YAML
19  # document.
20  #
21  # Psych::Nodes contains all of the classes that make up the nodes of a YAML
22  # AST.  You can manually build an AST and use one of the visitors (see
23  # Psych::Visitors) to convert that AST to either a YAML document or to a
24  # Ruby object graph.
25  #
26  # Here is an example of building an AST that represents a list with one
27  # scalar:
28  #
29  #   # Create our nodes
30  #   stream = Psych::Nodes::Stream.new
31  #   doc    = Psych::Nodes::Document.new
32  #   seq    = Psych::Nodes::Sequence.new
33  #   scalar = Psych::Nodes::Scalar.new('foo')
34  #
35  #   # Build up our tree
36  #   stream.children << doc
37  #   doc.children    << seq
38  #   seq.children    << scalar
39  #
40  # The stream is the root of the tree.  We can then convert the tree to YAML:
41  #
42  #   stream.to_yaml => "---\n- foo\n"
43  #
44  # Or convert it to Ruby:
45  #
46  #   stream.to_ruby => [["foo"]]
47  #
48  # == YAML AST Requirements
49  #
50  # A valid YAML AST *must* have one Psych::Nodes::Stream at the root.  A
51  # Psych::Nodes::Stream node must have 1 or more Psych::Nodes::Document nodes
52  # as children.
53  #
54  # Psych::Nodes::Document nodes must have one and *only* one child.  That child
55  # may be one of:
56  #
57  # * Psych::Nodes::Sequence
58  # * Psych::Nodes::Mapping
59  # * Psych::Nodes::Scalar
60  #
61  # Psych::Nodes::Sequence and Psych::Nodes::Mapping nodes may have many
62  # children, but Psych::Nodes::Mapping nodes should have an even number of
63  # children.
64  #
65  # All of these are valid children for Psych::Nodes::Sequence and
66  # Psych::Nodes::Mapping nodes:
67  #
68  # * Psych::Nodes::Sequence
69  # * Psych::Nodes::Mapping
70  # * Psych::Nodes::Scalar
71  # * Psych::Nodes::Alias
72  #
73  # Psych::Nodes::Scalar and Psych::Nodes::Alias are both terminal nodes and
74  # should not have any children.
75  module Nodes
76  end
77end
78