lib/yaml.rb

   1 # -*- mode: ruby; ruby-indent-level: 4; tab-width: 4 -*- vim: sw=4 ts=4
   2 # $Id$
   3 #
   4 # = yaml.rb: top-level module with methods for loading and parsing YAML documents
   5 #
   6 # Author:: why the lucky stiff
   7 #
   8
   9 require 'stringio'
  10 require 'yaml/error'
  11 require 'yaml/syck'
  12 require 'yaml/tag'
  13 require 'yaml/stream'
  14 require 'yaml/constants'
  15
  16 # == YAML
  17 #
  18 # YAML(tm) (rhymes with 'camel') is a
  19 # straightforward machine parsable data serialization format designed for
  20 # human readability and interaction with scripting languages such as Perl
  21 # and Python. YAML is optimized for data serialization, formatted
  22 # dumping, configuration files, log files, Internet messaging and
  23 # filtering. This specification describes the YAML information model and
  24 # serialization format. Together with the Unicode standard for characters, it
  25 # provides all the information necessary to understand YAML Version 1.0
  26 # and construct computer programs to process it.
  27 #
  28 # See http://yaml.org/ for more information.  For a quick tutorial, please
  29 # visit YAML In Five Minutes (http://yaml.kwiki.org/?YamlInFiveMinutes).
  30 #
  31 # == About This Library
  32 #
  33 # The YAML 1.0 specification outlines four stages of YAML loading and dumping.
  34 # This library honors all four of those stages, although data is really only
  35 # available to you in three stages.
  36 #
  37 # The four stages are: native, representation, serialization, and presentation.
  38 #
  39 # The native stage refers to data which has been loaded completely into Ruby's
  40 # own types. (See +YAML::load+.)
  41 #
  42 # The representation stage means data which has been composed into
  43 # +YAML::BaseNode+ objects.  In this stage, the document is available as a
  44 # tree of node objects.  You can perform YPath queries and transformations
  45 # at this level.  (See +YAML::parse+.)
  46 #
  47 # The serialization stage happens inside the parser.  The YAML parser used in
  48 # Ruby is called Syck.  Serialized nodes are available in the extension as
  49 # SyckNode structs.
  50 #
  51 # The presentation stage is the YAML document itself.  This is accessible
  52 # to you as a string.  (See +YAML::dump+.)
  53 #
  54 # For more information about the various information models, see Chapter
  55 # 3 of the YAML 1.0 Specification (http://yaml.org/spec/#id2491269).
  56 #
  57 # The YAML module provides quick access to the most common loading (YAML::load)
  58 # and dumping (YAML::dump) tasks.  This module also provides an API for registering
  59 # global types (YAML::add_domain_type).
  60 #
  61 # == Example
  62 #
  63 # A simple round-trip (load and dump) of an object.
  64 #
  65 #     require "yaml"
  66 #
  67 #     test_obj = ["dogs", "cats", "badgers"]
  68 #
  69 #     yaml_obj = YAML::dump( test_obj )
  70 #                         # -> ---
  71 #                              - dogs
  72 #                              - cats
  73 #                              - badgers
  74 #     ruby_obj = YAML::load( yaml_obj )
  75 #                         # => ["dogs", "cats", "badgers"]
  76 #     ruby_obj == test_obj
  77 #                         # => true
  78 #
  79 # To register your custom types with the global resolver, use +add_domain_type+.
  80 #
  81 #     YAML::add_domain_type( "your-site.com,2004", "widget" ) do |type, val|
  82 #         Widget.new( val )
  83 #     end
  84 #
  85 module YAML
  86
  87     Resolver = YAML::Syck::Resolver
  88     DefaultResolver = YAML::Syck::DefaultResolver
  89     DefaultResolver.use_types_at( @@tagged_classes )
  90     GenericResolver = YAML::Syck::GenericResolver
  91     Parser = YAML::Syck::Parser
  92     Emitter = YAML::Syck::Emitter
  93
  94     # Returns a new default parser
  95     def YAML.parser; Parser.new.set_resolver( YAML.resolver ); end
  96     # Returns a new generic parser
  97     def YAML.generic_parser; Parser.new.set_resolver( GenericResolver ); end
  98     # Returns the default resolver
  99     def YAML.resolver; DefaultResolver; end
 100     # Returns a new default emitter
 101     def YAML.emitter; Emitter.new.set_resolver( YAML.resolver ); end
 102
 103         #
 104         # Converts _obj_ to YAML and writes the YAML result to _io_.
 105     #
 106     #   File.open( 'animals.yaml', 'w' ) do |out|
 107     #     YAML.dump( ['badger', 'elephant', 'tiger'], out )
 108     #   end
 109     #
 110     # If no _io_ is provided, a string containing the dumped YAML
 111     # is returned.
 112         #
 113     #   YAML.dump( :locked )
 114     #      #=> "--- :locked"
 115     #
 116         def YAML.dump( obj, io = nil )
 117         obj.to_yaml( io || io2 = StringIO.new )
 118         io || ( io2.rewind; io2.read )
 119         end
 120
 121         #
 122         # Load a document from the current _io_ stream.
 123         #
 124     #   File.open( 'animals.yaml' ) { |yf| YAML::load( yf ) }
 125     #      #=> ['badger', 'elephant', 'tiger']
 126     #
 127     # Can also load from a string.
 128     #
 129     #   YAML.load( "--- :locked" )
 130     #      #=> :locked
 131     #
 132         def YAML.load( io )
 133                 yp = parser.load( io )
 134         end
 135
 136     #
 137     # Load a document from the file located at _filepath_.
 138     #
 139     #   YAML.load_file( 'animals.yaml' )
 140     #      #=> ['badger', 'elephant', 'tiger']
 141     #
 142     def YAML.load_file( filepath )
 143         File.open( filepath ) do |f|
 144             load( f )
 145         end
 146     end
 147
 148         #
 149         # Parse the first document from the current _io_ stream
 150         #
 151     #   File.open( 'animals.yaml' ) { |yf| YAML::load( yf ) }
 152     #      #=> #<YAML::Syck::Node:0x82ccce0
 153     #           @kind=:seq,
 154     #           @value=
 155     #            [#<YAML::Syck::Node:0x82ccd94
 156     #              @kind=:scalar,
 157     #              @type_id="str",
 158     #              @value="badger">,
 159     #             #<YAML::Syck::Node:0x82ccd58
 160     #              @kind=:scalar,
 161     #              @type_id="str",
 162     #              @value="elephant">,
 163     #             #<YAML::Syck::Node:0x82ccd1c
 164     #              @kind=:scalar,
 165     #              @type_id="str",
 166     #              @value="tiger">]>
 167     #
 168     # Can also load from a string.
 169     #
 170     #   YAML.parse( "--- :locked" )
 171     #      #=> #<YAML::Syck::Node:0x82edddc
 172     #            @type_id="tag:ruby.yaml.org,2002:sym",
 173     #            @value=":locked", @kind=:scalar>
 174     #
 175         def YAML.parse( io )
 176                 yp = generic_parser.load( io )
 177         end
 178
 179     #
 180     # Parse a document from the file located at _filepath_.
 181     #
 182     #   YAML.parse_file( 'animals.yaml' )
 183     #      #=> #<YAML::Syck::Node:0x82ccce0
 184     #           @kind=:seq,
 185     #           @value=
 186     #            [#<YAML::Syck::Node:0x82ccd94
 187     #              @kind=:scalar,
 188     #              @type_id="str",
 189     #              @value="badger">,
 190     #             #<YAML::Syck::Node:0x82ccd58
 191     #              @kind=:scalar,
 192     #              @type_id="str",
 193     #              @value="elephant">,
 194     #             #<YAML::Syck::Node:0x82ccd1c
 195     #              @kind=:scalar,
 196     #              @type_id="str",
 197     #              @value="tiger">]>
 198     #
 199     def YAML.parse_file( filepath )
 200         File.open( filepath ) do |f|
 201             parse( f )
 202         end
 203     end
 204
 205         #
 206         # Calls _block_ with each consecutive document in the YAML
 207     # stream contained in _io_.
 208     #
 209     #   File.open( 'many-docs.yaml' ) do |yf|
 210     #     YAML.each_document( yf ) do |ydoc|
 211     #       ## ydoc contains the single object
 212     #       ## from the YAML document
 213     #     end
 214     #   end
 215         #
 216         def YAML.each_document( io, &block )
 217                 yp = parser.load_documents( io, &block )
 218     end
 219
 220         #
 221         # Calls _block_ with each consecutive document in the YAML
 222     # stream contained in _io_.
 223     #
 224     #   File.open( 'many-docs.yaml' ) do |yf|
 225     #     YAML.load_documents( yf ) do |ydoc|
 226     #       ## ydoc contains the single object
 227     #       ## from the YAML document
 228     #     end
 229     #   end
 230         #
 231         def YAML.load_documents( io, &doc_proc )
 232                 YAML.each_document( io, &doc_proc )
 233     end
 234
 235         #
 236         # Calls _block_ with a tree of +YAML::BaseNodes+, one tree for
 237     # each consecutive document in the YAML stream contained in _io_.
 238     #
 239     #   File.open( 'many-docs.yaml' ) do |yf|
 240     #     YAML.each_node( yf ) do |ydoc|
 241     #       ## ydoc contains a tree of nodes
 242     #       ## from the YAML document
 243     #     end
 244     #   end
 245         #
 246         def YAML.each_node( io, &doc_proc )
 247                 yp = generic_parser.load_documents( io, &doc_proc )
 248     end
 249
 250         #
 251         # Calls _block_ with a tree of +YAML::BaseNodes+, one tree for
 252     # each consecutive document in the YAML stream contained in _io_.
 253     #
 254     #   File.open( 'many-docs.yaml' ) do |yf|
 255     #     YAML.parse_documents( yf ) do |ydoc|
 256     #       ## ydoc contains a tree of nodes
 257     #       ## from the YAML document
 258     #     end
 259     #   end
 260         #
 261         def YAML.parse_documents( io, &doc_proc )
 262                 YAML.each_node( io, &doc_proc )
 263     end
 264
 265         #
 266         # Loads all documents from the current _io_ stream,
 267     # returning a +YAML::Stream+ object containing all
 268     # loaded documents.
 269         #
 270         def YAML.load_stream( io )
 271                 d = nil
 272                 parser.load_documents( io ) do |doc|
 273                         d = YAML::Stream.new if not d
 274                         d.add( doc )
 275         end
 276                 return d
 277         end
 278
 279         #
 280     # Returns a YAML stream containing each of the items in +objs+,
 281     # each having their own document.
 282     #
 283     #   YAML.dump_stream( 0, [], {} )
 284     #     #=> --- 0
 285     #         --- []
 286     #         --- {}
 287     #
 288         def YAML.dump_stream( *objs )
 289                 d = YAML::Stream.new
 290         objs.each do |doc|
 291                         d.add( doc )
 292         end
 293         d.emit
 294         end
 295
 296         #
 297         # Add a global handler for a YAML domain type.
 298         #
 299         def YAML.add_domain_type( domain, type_tag, &transfer_proc )
 300         resolver.add_type( "tag:#{ domain }:#{ type_tag }", transfer_proc )
 301         end
 302
 303         #
 304         # Add a transfer method for a builtin type
 305         #
 306         def YAML.add_builtin_type( type_tag, &transfer_proc )
 307             resolver.add_type( "tag:yaml.org,2002:#{ type_tag }", transfer_proc )
 308         end
 309
 310         #
 311         # Add a transfer method for a builtin type
 312         #
 313         def YAML.add_ruby_type( type_tag, &transfer_proc )
 314             resolver.add_type( "tag:ruby.yaml.org,2002:#{ type_tag }", transfer_proc )
 315         end
 316
 317         #
 318         # Add a private document type
 319         #
 320         def YAML.add_private_type( type_re, &transfer_proc )
 321             resolver.add_type( "x-private:" + type_re, transfer_proc )
 322         end
 323
 324     #
 325     # Detect typing of a string
 326     #
 327     def YAML.detect_implicit( val )
 328         resolver.detect_implicit( val )
 329     end
 330
 331     #
 332     # Convert a type_id to a taguri
 333     #
 334     def YAML.tagurize( val )
 335         resolver.tagurize( val )
 336     end
 337
 338     #
 339     # Apply a transfer method to a Ruby object
 340     #
 341     def YAML.transfer( type_id, obj )
 342         resolver.transfer( YAML.tagurize( type_id ), obj )
 343     end
 344
 345         #
 346         # Apply any implicit a node may qualify for
 347         #
 348         def YAML.try_implicit( obj )
 349                 YAML.transfer( YAML.detect_implicit( obj ), obj )
 350         end
 351
 352     #
 353     # Method to extract colon-seperated type and class, returning
 354     # the type and the constant of the class
 355     #
 356     def YAML.read_type_class( type, obj_class )
 357         scheme, domain, type, tclass = type.split( ':', 4 )
 358         tclass.split( "::" ).each { |c| obj_class = obj_class.const_get( c ) } if tclass
 359         return [ type, obj_class ]
 360     end
 361
 362     #
 363     # Allocate blank object
 364     #
 365     def YAML.object_maker( obj_class, val )
 366         if Hash === val
 367             o = obj_class.allocate
 368             val.each_pair { |k,v|
 369                 o.instance_variable_set("@#{k}", v)
 370             }
 371             o
 372         else
 373             raise YAML::Error, "Invalid object explicitly tagged !ruby/Object: " + val.inspect
 374         end
 375     end
 376
 377         #
 378         # Allocate an Emitter if needed
 379         #
 380         def YAML.quick_emit( oid, opts = {}, &e )
 381         out =
 382             if opts.is_a? YAML::Emitter
 383                 opts
 384             else
 385                 emitter.reset( opts )
 386             end
 387         oid =
 388             case oid when Fixnum, NilClass; oid
 389             else oid = "#{oid.object_id}-#{oid.hash}"
 390             end
 391         out.emit( oid, &e )
 392         end
 393
 394 end
 395
 396 require 'yaml/rubytypes'
 397 require 'yaml/types'
 398
 399 module Kernel
 400     #
 401     # ryan:: You know how Kernel.p is a really convenient way to dump ruby
 402     #        structures?  The only downside is that it's not as legible as
 403     #        YAML.
 404     #
 405     # _why:: (listening)
 406     #
 407     # ryan:: I know you don't want to urinate all over your users' namespaces.
 408     #        But, on the other hand, convenience of dumping for debugging is,
 409     #        IMO, a big YAML use case.
 410     #
 411     # _why:: Go nuts!  Have a pony parade!
 412     #
 413     # ryan:: Either way, I certainly will have a pony parade.
 414     #
 415
 416     # Prints any supplied _objects_ out in YAML.  Intended as
 417     # a variation on +Kernel::p+.
 418     #
 419     #   S = Struct.new(:name, :state)
 420     #   s = S['dave', 'TX']
 421     #   y s
 422     #
 423     # _produces:_
 424     #
 425     #   --- !ruby/struct:S
 426     #   name: dave
 427     #   state: TX
 428     #
 429     def y( object, *objects )
 430         objects.unshift object
 431         puts( if objects.length == 1
 432                   YAML::dump( *objects )
 433               else
 434                   YAML::dump_stream( *objects )
 435               end )
 436     end
 437     private :y
 438 end
 439
 440