Module: Psych
- Defined in:
- lib/psych.rb,
lib/psych/set.rb,
lib/psych/json.rb,
lib/psych/omap.rb,
lib/psych/coder.rb,
lib/psych/nodes.rb,
lib/psych/parser.rb,
lib/psych/stream.rb,
lib/psych/handler.rb,
lib/psych/streaming.rb,
lib/psych/deprecated.rb,
lib/psych/nodes/node.rb,
lib/psych/json/stream.rb,
lib/psych/nodes/alias.rb,
lib/psych/nodes/scalar.rb,
lib/psych/nodes/stream.rb,
lib/psych/tree_builder.rb,
lib/psych/nodes/mapping.rb,
lib/psych/nodes/document.rb,
lib/psych/nodes/sequence.rb,
lib/psych/scalar_scanner.rb,
lib/psych/json/ruby_events.rb,
lib/psych/json/yaml_events.rb,
lib/psych/visitors/emitter.rb,
lib/psych/visitors/visitor.rb,
lib/psych/json/tree_builder.rb,
lib/psych/visitors/json_tree.rb,
lib/psych/visitors/yaml_tree.rb,
lib/psych/visitors/depth_first.rb,
ext/psych/psych.c,
ext/psych/parser.c,
ext/psych/emitter.c,
ext/psych/to_ruby.c,
ext/psych/yaml_tree.c,
lib/psych/visitors/to_ruby.rb
Overview
Overview
Psych is a YAML parser and emitter. Psych leverages libyaml for it’s YAML parsing and emitting capabilities. In addition to wrapping libyaml, Psych also knows how to serialize and de-serialize most Ruby objects to and from the YAML format.
I NEED TO PARSE OR EMIT YAML RIGHT NOW!
# Parse some YAML
Psych.load("--- foo") # => "foo"
# Emit some YAML
Psych.dump("foo") # => "--- foo\n...\n"
{ :a => 'b'}.to_yaml # => "---\n:a: b\n"
Got more time on your hands? Keep on reading!
YAML Parsing
Psych provides a range of interfaces for parsing a YAML document ranging from low level to high level, depending on your parsing needs. At the lowest level, is an event based parser. Mid level is access to the raw YAML AST, and at the highest level is the ability to unmarshal YAML to ruby objects.
Low level parsing
The lowest level parser should be used when the YAML input is already known, and the developer does not want to pay the price of building an AST or automatic detection and conversion to ruby objects. See Psych::Parser for more information on using the event based parser.
Mid level parsing
Psych provides access to an AST produced from parsing a YAML document. This tree is built using the Psych::Parser and Psych::TreeBuilder. The AST can be examined and manipulated freely. Please see Psych::parse_stream, Psych::Nodes, and Psych::Nodes::Node for more information on dealing with YAML syntax trees.
High level parsing
The high level YAML parser provided by Psych simply takes YAML as input and returns a Ruby data structure. For information on using the high level parser see Psych.load
YAML Emitting
Psych provides a range of interfaces ranging from low to high level for producing YAML documents. Very similar to the YAML parsing interfaces, Psych provides at the lowest level, an event based system, mid-level is building a YAML AST, and the highest level is converting a Ruby object straight to a YAML document.
Low level emitting
The lowest level emitter is an event based system. Events are sent to a Psych::Emitter object. That object knows how to convert the events to a YAML document. This interface should be used when document format is known in advance or speed is a concern. See Psych::Emitter for more information.
Mid level emitting
At the mid level is building an AST. This AST is exactly the same as the AST used when parsing a YAML document. Users can build an AST by hand and the AST knows how to emit itself as a YAML document. See Psych::Nodes, Psych::Nodes::Node, and Psych::TreeBuilder for more information on building a YAML AST.
High level emitting
The high level emitter has the easiest interface. Psych simply takes a Ruby data structure and converts it to a YAML document. See Psych.dump for more information on dumping a Ruby data structure.
Defined Under Namespace
Modules: DeprecatedMethods, JSON, Nodes, Streaming, Visitors Classes: BadAlias, Coder, Emitter, Exception, Handler, Omap, Parser, ScalarScanner, Set, Stream, SyntaxError, TreeBuilder
Constant Summary collapse
- VERSION =
The version is Psych you’re using
'1.2.2'
- LIBYAML_VERSION =
The version of libyaml Psych is using
Psych.libyaml_version.join '.'
- DEPRECATED =
:nodoc:
__FILE__
Class Attribute Summary collapse
-
.domain_types ⇒ Object
Returns the value of attribute domain_types.
-
.dump_tags ⇒ Object
Returns the value of attribute dump_tags.
-
.load_tags ⇒ Object
Returns the value of attribute load_tags.
Class Method Summary collapse
- .add_builtin_type(type_tag, &block) ⇒ Object
- .add_domain_type(domain, type_tag, &block) ⇒ Object
- .add_private_type(type_tag, &block) ⇒ Object
- .add_ruby_type(type_tag, &block) ⇒ Object
- .add_tag(tag, klass) ⇒ Object
- .detect_implicit(thing) ⇒ Object
-
.dump(o, io = nil, options = {}) ⇒ Object
call-seq: Psych.dump(o) -> string of yaml Psych.dump(o, options) -> string of yaml Psych.dump(o, io) -> io object passed in Psych.dump(o, io, options) -> io object passed in.
-
.dump_stream(*objects) ⇒ Object
Dump a list of objects as separate documents to a document stream.
-
.libyaml_version ⇒ Object
Returns the version of libyaml being used.
-
.load(yaml) ⇒ Object
Load
yaml
in to a Ruby data structure. - .load_documents(yaml, &block) ⇒ Object
-
.load_file(filename) ⇒ Object
Load the document contained in
filename
. -
.load_stream(yaml) ⇒ Object
Load multiple documents given in
yaml
. - .object_maker(klass, hash) ⇒ Object
-
.parse(yaml) ⇒ Object
Parse a YAML string in
yaml
. -
.parse_file(filename) ⇒ Object
Parse a file at
filename
. -
.parse_stream(yaml) ⇒ Object
Parse a YAML string in
yaml
. -
.parser ⇒ Object
Returns a default parser.
-
.quick_emit(thing, opts = {}, &block) ⇒ Object
:nodoc:.
- .read_type_class(type, reference) ⇒ Object
- .remove_type(type_tag) ⇒ Object
- .tagurize(thing) ⇒ Object
-
.to_json(o) ⇒ Object
Dump Ruby object
o
to a JSON string.
Class Attribute Details
.domain_types ⇒ Object
Returns the value of attribute domain_types.
263 264 265 |
# File 'lib/psych.rb', line 263 def domain_types @domain_types end |
.dump_tags ⇒ Object
Returns the value of attribute dump_tags.
262 263 264 |
# File 'lib/psych.rb', line 262 def @dump_tags end |
.load_tags ⇒ Object
Returns the value of attribute load_tags.
261 262 263 |
# File 'lib/psych.rb', line 261 def @load_tags end |
Class Method Details
.add_builtin_type(type_tag, &block) ⇒ Object
243 244 245 246 247 |
# File 'lib/psych.rb', line 243 def self.add_builtin_type type_tag, &block domain = 'yaml.org,2002' key = ['tag', domain, type_tag].join ':' @domain_types[key] = [key, block] end |
.add_domain_type(domain, type_tag, &block) ⇒ Object
237 238 239 240 241 |
# File 'lib/psych.rb', line 237 def self.add_domain_type domain, type_tag, &block key = ['tag', domain, type_tag].join ':' @domain_types[key] = [key, block] @domain_types["tag:#{type_tag}"] = [key, block] end |
.add_private_type(type_tag, &block) ⇒ Object
47 48 49 50 51 52 |
# File 'lib/psych/deprecated.rb', line 47 def self.add_private_type type_tag, &block warn "#{caller[0]}: add_private_type is deprecated, use add_domain_type" if $VERBOSE domain = 'x-private' key = [domain, type_tag].join ':' @domain_types[key] = [key, block] end |
.add_ruby_type(type_tag, &block) ⇒ Object
40 41 42 43 44 45 |
# File 'lib/psych/deprecated.rb', line 40 def self.add_ruby_type type_tag, &block warn "#{caller[0]}: add_ruby_type is deprecated, use add_domain_type" if $VERBOSE domain = 'ruby.yaml.org,2002' key = ['tag', domain, type_tag].join ':' @domain_types[key] = [key, block] end |
.add_tag(tag, klass) ⇒ Object
255 256 257 258 |
# File 'lib/psych.rb', line 255 def self.add_tag tag, klass @load_tags[tag] = klass @dump_tags[klass] = tag end |
.detect_implicit(thing) ⇒ Object
33 34 35 36 37 38 |
# File 'lib/psych/deprecated.rb', line 33 def self.detect_implicit thing warn "#{caller[0]}: detect_implicit is deprecated" if $VERBOSE return '' unless String === thing return 'null' if '' == thing ScalarScanner.new.tokenize(thing).class.name.downcase end |
.dump(o, io = nil, options = {}) ⇒ Object
call-seq:
Psych.dump(o) -> string of yaml
Psych.dump(o, options) -> string of yaml
Psych.dump(o, io) -> io object passed in
Psych.dump(o, io, options) -> io object passed in
Dump Ruby object o
to a YAML string. Optional options
may be passed in to control the output format. If an IO object is passed in, the YAML will be dumped to that IO object.
Example:
# Dump an array, get back a YAML string
Psych.dump(['a', 'b']) # => "---\n- a\n- b\n"
# Dump an array to an IO object
Psych.dump(['a', 'b'], StringIO.new) # => #<StringIO:0x000001009d0890>
# Dump an array with indentation set
Psych.dump(['a', ['b']], :indentation => 3) # => "---\n- a\n- - b\n"
# Dump an array to an IO with indentation set
Psych.dump(['a', ['b']], StringIO.new, :indentation => 3)
185 186 187 188 189 190 191 192 193 194 |
# File 'lib/psych.rb', line 185 def self.dump o, io = nil, = {} if Hash === io = io io = nil end visitor = Psych::Visitors::YAMLTree.new visitor << o visitor.tree.yaml io, end |
.dump_stream(*objects) ⇒ Object
Dump a list of objects as separate documents to a document stream.
Example:
Psych.dump_stream("foo\n ", {}) # => "--- ! \"foo\\n \"\n--- {}\n"
202 203 204 205 206 207 208 |
# File 'lib/psych.rb', line 202 def self.dump_stream *objects visitor = Psych::Visitors::YAMLTree.new {} objects.each do |o| visitor << o end visitor.tree.yaml end |
.libyaml_version ⇒ Object
Returns the version of libyaml being used
7 8 9 10 11 12 13 14 15 16 17 18 19 |
# File 'ext/psych/psych.c', line 7
static VALUE libyaml_version(VALUE module)
{
int major, minor, patch;
VALUE list[3];
yaml_get_version(&major, &minor, &patch);
list[0] = INT2NUM((long)major);
list[1] = INT2NUM((long)minor);
list[2] = INT2NUM((long)patch);
return rb_ary_new4((long)3, list);
}
|
.load(yaml) ⇒ Object
114 115 116 117 |
# File 'lib/psych.rb', line 114 def self.load yaml result = parse(yaml) result ? result.to_ruby : result end |
.load_documents(yaml, &block) ⇒ Object
24 25 26 27 28 29 30 31 |
# File 'lib/psych/deprecated.rb', line 24 def self.load_documents yaml, &block if $VERBOSE warn "#{caller[0]}: load_documents is deprecated, use load_stream" end list = load_stream yaml return list unless block_given? list.each(&block) end |
.load_file(filename) ⇒ Object
Load the document contained in filename
. Returns the yaml contained in filename
as a ruby object
231 232 233 |
# File 'lib/psych.rb', line 231 def self.load_file filename self.load File.open(filename) end |
.load_stream(yaml) ⇒ Object
Load multiple documents given in yaml
. Returns the parsed documents as a list. For example:
Psych.load_stream("--- foo\n...\n--- bar\n...") # => ['foo', 'bar']
224 225 226 |
# File 'lib/psych.rb', line 224 def self.load_stream yaml parse_stream(yaml).children.map { |child| child.to_ruby } end |
.object_maker(klass, hash) ⇒ Object
70 71 72 73 74 75 |
# File 'lib/psych/deprecated.rb', line 70 def self.object_maker klass, hash warn "#{caller[0]}: object_maker is deprecated" if $VERBOSE klass.allocate.tap do |obj| hash.each { |k,v| obj.instance_variable_set(:"@#{k}", v) } end end |
.parse(yaml) ⇒ Object
Parse a YAML string in yaml
. Returns the first object of a YAML AST.
Example:
Psych.parse("---\n - a\n - b") # => #<Psych::Nodes::Sequence:0x00>
See Psych::Nodes for more information about YAML AST.
127 128 129 130 |
# File 'lib/psych.rb', line 127 def self.parse yaml children = parse_stream(yaml).children children.empty? ? false : children.first.children.first end |
.parse_file(filename) ⇒ Object
Parse a file at filename
. Returns the YAML AST.
134 135 136 137 138 |
# File 'lib/psych.rb', line 134 def self.parse_file filename File.open filename do |f| parse f end end |
.parse_stream(yaml) ⇒ Object
Parse a YAML string in yaml
. Returns the full AST for the YAML document. This method can handle multiple YAML documents contained in yaml
.
Example:
Psych.parse_stream("---\n - a\n - b") # => #<Psych::Nodes::Stream:0x00>
See Psych::Nodes for more information about YAML AST.
155 156 157 158 159 |
# File 'lib/psych.rb', line 155 def self.parse_stream yaml parser = self.parser parser.parse yaml parser.handler.root end |
.parser ⇒ Object
Returns a default parser
142 143 144 |
# File 'lib/psych.rb', line 142 def self.parser Psych::Parser.new(TreeBuilder.new) end |
.quick_emit(thing, opts = {}, &block) ⇒ Object
:nodoc:
11 12 13 14 15 16 17 18 19 20 21 22 |
# File 'lib/psych/deprecated.rb', line 11 def self.quick_emit thing, opts = {}, &block # :nodoc: warn "#{caller[0]}: YAML.quick_emit is deprecated" if $VERBOSE && !caller[0].start_with?(File.dirname(__FILE__)) target = eval 'self', block.binding target.extend DeprecatedMethods = class << target; self; end .send(:define_method, :encode_with) do |coder| target.taguri = coder.tag target.to_yaml_style = coder.style block.call coder end target.psych_to_yaml unless opts[:nodump] end |
.read_type_class(type, reference) ⇒ Object
60 61 62 63 64 65 66 67 68 |
# File 'lib/psych/deprecated.rb', line 60 def self.read_type_class type, reference warn "#{caller[0]}: read_type_class is deprecated" if $VERBOSE _, _, type, name = type.split ':', 4 reference = name.split('::').inject(reference) do |k,n| k.const_get(n.to_sym) end if name [type, reference] end |
.remove_type(type_tag) ⇒ Object
249 250 251 |
# File 'lib/psych.rb', line 249 def self.remove_type type_tag @domain_types.delete type_tag end |
.tagurize(thing) ⇒ Object
54 55 56 57 58 |
# File 'lib/psych/deprecated.rb', line 54 def self.tagurize thing warn "#{caller[0]}: add_private_type is deprecated, use add_domain_type" if $VERBOSE return thing unless String === thing "tag:yaml.org,2002:#{thing}" end |