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