Module: Syck

Defined in:
lib/syck.rb,
lib/syck/tag.rb,
lib/syck/syck.rb,
lib/syck/error.rb,
lib/syck/types.rb,
lib/syck/ypath.rb,
lib/syck/loader.rb,
lib/syck/stream.rb,
lib/syck/basenode.rb,
lib/syck/encoding.rb,
lib/syck/yamlnode.rb,
lib/syck/constants.rb,
lib/syck/baseemitter.rb,
lib/yaml/engine_manager.rb

Overview

Constants used throughout the library

Defined Under Namespace

Modules: BaseEmitter, BaseNode Classes: DomainType, Error, Loader, Mapping, Node, Object, Omap, Pairs, ParseError, PrivateType, Sequence, Set, SpecialHash, Stream, TypeError, YPath, YamlNode

Constant Summary collapse

ERROR_NO_HEADER_NODE =

Error messages

"With UseHeader=false, the node Array or Hash must have elements"
ERROR_NEED_HEADER = 
"With UseHeader=false, the node must be an Array or Hash"
ERROR_BAD_EXPLICIT = 
"Unsupported explicit transfer: '%s'"
ERROR_MANY_EXPLICIT = 
"More than one explicit transfer"
ERROR_MANY_IMPLICIT = 
"More than one implicit request"
ERROR_NO_ANCHOR = 
"No anchor for alias '%s'"
ERROR_BAD_ANCHOR = 
"Invalid anchor: %s"
ERROR_MANY_ANCHOR = 
"More than one anchor"
ERROR_ANCHOR_ALIAS = 
"Can't define both an anchor and an alias"
ERROR_BAD_ALIAS = 
"Invalid alias: %s"
ERROR_MANY_ALIAS = 
"More than one alias"
ERROR_ZERO_INDENT = 
"Can't use zero as an indentation width"
ERROR_UNSUPPORTED_VERSION = 
"This release of YAML.rb does not support YAML version %s"
ERROR_UNSUPPORTED_ENCODING = 
"Attempt to use unsupported encoding: %s"
VERSION =

Constants

'1.0.5'
SUPPORTED_YAML_VERSIONS = 
['1.0']
WORD_CHAR =

Parser tokens

'A-Za-z0-9'
PRINTABLE_CHAR = 
'-_A-Za-z0-9!?/()$\'". '
NOT_PLAIN_CHAR = 
'\x7f\x0-\x1f\x80-\x9f'
ESCAPE_CHAR = 
'[\\x00-\\x09\\x0b-\\x1f]'
INDICATOR_CHAR = 
'*&!|\\\\^@%{}[]='
SPACE_INDICATORS = 
'-#:,?'
RESTRICTED_INDICATORS = 
'#:,}]'
DNS_COMP_RE = 
"\\w(?:[-\\w]*\\w)?"
DNS_NAME_RE = 
"(?:(?:#{DNS_COMP_RE}\\.)+#{DNS_COMP_RE}|#{DNS_COMP_RE})"
ESCAPES = 
%w{\x00   \x01	\x02	\x03	\x04	\x05	\x06	\a
 \x08	\t		\n		\v		\f		\r		\x0e	\x0f
				 \x10	\x11	\x12	\x13	\x14	\x15	\x16	\x17
				 \x18	\x19	\x1a	\e		\x1c	\x1d	\x1e	\x1f
}
UNESCAPES = 
{
				'a' => "\x07", 'b' => "\x08", 't' => "\x09",
				'n' => "\x0a", 'v' => "\x0b", 'f' => "\x0c",
				'r' => "\x0d", 'e' => "\x1b", '\\' => '\\',
}
DEFAULTS =

Default settings

{
	:Indent => 2, :UseHeader => false, :UseVersion => false, :Version => '1.0',
	:SortKeys => false, :AnchorFormat => 'id%03d', :ExplicitTypes => false,
	:WidthType => 'absolute', :BestWidth => 80,
	:UseBlock => false, :UseFold => false, :Encoding => :None
}
ENGINE = 
YAML::ENGINE
@@tagged_classes =

A dictionary of taguris which map to Ruby classes.

{}

Class Method Summary collapse

Class Method Details

.add_builtin_type(type_tag, &transfer_proc) ⇒ Object

Add a transfer method for a builtin type



321
322
323
 
# File 'lib/syck.rb', line 321

def self.add_builtin_type( type_tag, &transfer_proc )
    resolver.add_type( "tag:yaml.org,2002:#{ type_tag }", transfer_proc )
end

.add_domain_type(domain, type_tag, &transfer_proc) ⇒ Object

Add a global handler for a YAML domain type.



314
315
316
 
# File 'lib/syck.rb', line 314

def self.add_domain_type( domain, type_tag, &transfer_proc )
    resolver.add_type( "tag:#{ domain }:#{ type_tag }", transfer_proc )
end

.add_private_type(type_re, &transfer_proc) ⇒ Object

Add a private document type



336
337
338
339
 
# File 'lib/syck.rb', line 336

def self.add_private_type( type_re, &transfer_proc )
    warn "#{caller[0]}: YAML.add_private_type is deprecated, use add_domain_type" if $VERBOSE && !caller[0].start_with?(File.dirname(__FILE__))
    resolver.add_type( "x-private:" + type_re, transfer_proc )
end

.add_ruby_type(type_tag, &transfer_proc) ⇒ Object

Add a transfer method for a builtin type



328
329
330
331
 
# File 'lib/syck.rb', line 328

def self.add_ruby_type( type_tag, &transfer_proc )
    warn "#{caller[0]}: YAML.add_ruby_type is deprecated, use add_domain_type" if $VERBOSE && !caller[0].start_with?(File.dirname(__FILE__))
    resolver.add_type( "tag:ruby.yaml.org,2002:#{ type_tag }", transfer_proc )
end

.detect_implicit(val) ⇒ Object

Detect typing of a string



344
345
346
347
 
# File 'lib/syck.rb', line 344

def self.detect_implicit( val )
    warn "#{caller[0]}: YAML.detect_implicit is deprecated" if $VERBOSE && !caller[0].start_with?(File.dirname(__FILE__))
    resolver.detect_implicit( val )
end

.dump(obj, io = nil) ⇒ Object

Converts obj to YAML and writes the YAML result to io.

File.open( 'animals.yaml', 'w' ) do |out|
  YAML.dump( ['badger', 'elephant', 'tiger'], out )
end

If no io is provided, a string containing the dumped YAML is returned.

YAML.dump( :locked )
   #=> "--- :locked"



128
129
130
131
 
# File 'lib/syck.rb', line 128

def self.dump( obj, io = nil )
    obj.to_yaml( io || io2 = StringIO.new )
    io || ( io2.rewind; io2.read )
end

.dump_stream(*objs) ⇒ Object

Returns a YAML stream containing each of the items in objs, each having their own document.

YAML.dump_stream( 0, [], {} )
  #=> --- 0
      --- []
      --- {}



303
304
305
306
307
308
309
 
# File 'lib/syck.rb', line 303

def self.dump_stream( *objs )
    d = Stream.new
    objs.each do |doc|
        d.add( doc )
    end
    d.emit
end

.each_document(io, &block) ⇒ Object

Calls block with each consecutive document in the YAML stream contained in io.

File.open( 'many-docs.yaml' ) do |yf|
  YAML.each_document( yf ) do |ydoc|
    ## ydoc contains the single object
    ## from the YAML document
  end
end



228
229
230
231
 
# File 'lib/syck.rb', line 228

def self.each_document( io, &block )
    warn "#{caller[0]}: YAML.each_document is deprecated" if $VERBOSE && !caller[0].start_with?(File.dirname(__FILE__))
    parser.load_documents( io, &block )
end

.each_node(io, &doc_proc) ⇒ Object

Calls block with a tree of YAML::BaseNodes, one tree for each consecutive document in the YAML stream contained in io.

File.open( 'many-docs.yaml' ) do |yf|
  YAML.each_node( yf ) do |ydoc|
    ## ydoc contains a tree of nodes
    ## from the YAML document
  end
end



259
260
261
262
 
# File 'lib/syck.rb', line 259

def self.each_node( io, &doc_proc )
    warn "#{caller[0]}: YAML.each_node is deprecated" if $VERBOSE && !caller[0].start_with?(File.dirname(__FILE__))
    generic_parser.load_documents( io, &doc_proc )
end

.emitter ⇒ Object

Returns a new default emitter



110
111
112
113
 
# File 'lib/syck.rb', line 110

def self.emitter
    warn "#{caller[0]}: YAML.emitter is deprecated" if $VERBOSE && !caller[0].start_with?(File.dirname(__FILE__))
    Emitter.new.set_resolver( self.resolver )
end

.escape(value, skip = "") ⇒ Object

Escape the string, condensing common escapes



10
11
12
13
14
15
16
17
 
# File 'lib/syck/encoding.rb', line 10

def self.escape( value, skip = "" )
             warn "#{caller[0]}: YAML.escape is deprecated" if $VERBOSE
	value.gsub( /\\/, "\\\\\\" ).
             gsub( /"/, "\\\"" ).
             gsub( /([\x00-\x1f])/ ) do
                skip[$&] || ESCAPES[ $&.unpack("C")[0] ]
            end
end

.generic_parser ⇒ Object

Returns a new generic parser



98
99
100
101
 
# File 'lib/syck.rb', line 98

def self.generic_parser
    warn "#{caller[0]}: YAML.generic_parser is deprecated, switch to psych" if $VERBOSE && !caller[0].start_with?(File.dirname(__FILE__))
    Parser.new.set_resolver( GenericResolver )
end

.load(io) ⇒ Object

Load a document from the current io stream.

File.open( 'animals.yaml' ) { |yf| YAML::load( yf ) }
   #=> ['badger', 'elephant', 'tiger']

Can also load from a string.

YAML.load( "--- :locked" )
   #=> :locked



144
145
146
 
# File 'lib/syck.rb', line 144

def self.load( io )
    parser.load( io )
end

.load_documents(io, &doc_proc) ⇒ Object

Calls block with each consecutive document in the YAML stream contained in io.

File.open( 'many-docs.yaml' ) do |yf|
  YAML.load_documents( yf ) do |ydoc|
    ## ydoc contains the single object
    ## from the YAML document
  end
end



244
245
246
 
# File 'lib/syck.rb', line 244

def self.load_documents( io, &doc_proc )
    parser.load_documents( io, &doc_proc )
end

.load_file(filepath) ⇒ Object

Load a document from the file located at filepath.

YAML.load_file( 'animals.yaml' )
   #=> ['badger', 'elephant', 'tiger']



154
155
156
157
158
 
# File 'lib/syck.rb', line 154

def self.load_file( filepath )
    File.open( filepath ) do |f|
        load( f )
    end
end

.load_stream(io) ⇒ Object

Loads all documents from the current io stream, returning a YAML::Stream object containing all loaded documents.



285
286
287
288
289
290
291
292
 
# File 'lib/syck.rb', line 285

def self.load_stream( io )
    d = nil
    parser.load_documents( io ) do |doc|
        d = Stream.new if not d
        d.add( doc )
    end
    return d
end

.object_maker(obj_class, val) ⇒ Object

Allocate blank object



387
388
389
390
391
392
393
394
395
396
397
398
 
# File 'lib/syck.rb', line 387

def self.object_maker( obj_class, val )
    warn "#{caller[0]}: YAML.object_maker is deprecated" if $VERBOSE && !caller[0].start_with?(File.dirname(__FILE__))
    if Hash === val
        o = obj_class.allocate
        val.each_pair { |k,v|
            o.instance_variable_set("@#{k}", v)
        }
        o
    else
        raise Error, "Invalid object explicitly tagged !ruby/Object: " + val.inspect
    end
end

.parse(io) ⇒ Object

Parse the first document from the current io stream

File.open( 'animals.yaml' ) { |yf| YAML::load( yf ) }
   #=> #<YAML::Syck::Node:0x82ccce0
        @kind=:seq,
        @value=
         [#<YAML::Syck::Node:0x82ccd94
           @kind=:scalar,
           @type_id="str",
           @value="badger">,
          #<YAML::Syck::Node:0x82ccd58
           @kind=:scalar,
           @type_id="str",
           @value="elephant">,
          #<YAML::Syck::Node:0x82ccd1c
           @kind=:scalar,
           @type_id="str",
           @value="tiger">]>

Can also load from a string.

YAML.parse( "--- :locked" )
   #=> #<YAML::Syck::Node:0x82edddc
         @type_id="tag:ruby.yaml.org,2002:sym",
         @value=":locked", @kind=:scalar>



187
188
189
 
# File 'lib/syck.rb', line 187

def self.parse( io )
    generic_parser.load( io )
end

.parse_documents(io, &doc_proc) ⇒ Object

Calls block with a tree of YAML::BaseNodes, one tree for each consecutive document in the YAML stream contained in io.

File.open( 'many-docs.yaml' ) do |yf|
  YAML.parse_documents( yf ) do |ydoc|
    ## ydoc contains a tree of nodes
    ## from the YAML document
  end
end



275
276
277
278
 
# File 'lib/syck.rb', line 275

def self.parse_documents( io, &doc_proc )
    warn "#{caller[0]}: YAML.parse_documents is deprecated, use load_stream" if $VERBOSE && !caller[0].start_with?(File.dirname(__FILE__))
    self.each_node( io, &doc_proc )
end

.parse_file(filepath) ⇒ Object

Parse a document from the file located at filepath.

YAML.parse_file( 'animals.yaml' )
   #=> #<YAML::Syck::Node:0x82ccce0
        @kind=:seq,
        @value=
         [#<YAML::Syck::Node:0x82ccd94
           @kind=:scalar,
           @type_id="str",
           @value="badger">,
          #<YAML::Syck::Node:0x82ccd58
           @kind=:scalar,
           @type_id="str",
           @value="elephant">,
          #<YAML::Syck::Node:0x82ccd1c
           @kind=:scalar,
           @type_id="str",
           @value="tiger">]>



211
212
213
214
215
 
# File 'lib/syck.rb', line 211

def self.parse_file( filepath )
    File.open( filepath ) do |f|
        parse( f )
    end
end

.parser ⇒ Object

Returns a new default parser



95
 
# File 'lib/syck.rb', line 95

def self.parser; Parser.new.set_resolver( self.resolver ); end

.quick_emit(oid, opts = {}, &e) ⇒ Object

Allocate an Emitter if needed



403
404
405
406
407
408
409
410
411
412
 
# File 'lib/syck.rb', line 403

def self.quick_emit( oid, opts = {}, &e )
    warn "#{caller[0]}: YAML.quick_emit is deprecated" if $VERBOSE && !caller[0].start_with?(File.dirname(__FILE__))
    out =
        if opts.is_a? Emitter
            opts
        else
            emitter.reset( opts )
        end
    out.emit( oid, &e )
end

.read_type_class(type, obj_class) ⇒ Object

Method to extract colon-seperated type and class, returning the type and the constant of the class



377
378
379
380
381
382
 
# File 'lib/syck.rb', line 377

def self.read_type_class( type, obj_class )
    warn "#{caller[0]}: YAML.read_type_class is deprecated" if $VERBOSE && !caller[0].start_with?(File.dirname(__FILE__))
    type, tclass = type.split( ':', 4 ).last(2)
    tclass.split( "::" ).each { |c| obj_class = obj_class.const_get( c ) } if tclass
    return [ type, obj_class ]
end

.resolver ⇒ Object

Returns the default resolver



104
105
106
107
 
# File 'lib/syck.rb', line 104

def self.resolver
    warn "#{caller[0]}: YAML.resolver is deprecated" if $VERBOSE && !caller[0].start_with?(File.dirname(__FILE__))
    DefaultResolver
end

.tag_class(tag, cls) ⇒ Object

Associates a taguri tag with a Ruby class cls. The taguri is used to give types to classes when loading YAML. Taguris are of the form:

tag:authorityName,date:specific

The authorityName is a domain name or email address. The date is the date the type was issued in YYYY or YYYY-MM or YYYY-MM-DD format. The specific is a name for the type being added.

For example, built-in YAML types have ‘yaml.org’ as the authorityName and ‘2002’ as the date. The specific is simply the name of the type:

tag:yaml.org,2002:int
tag:yaml.org,2002:float
tag:yaml.org,2002:timestamp

The domain must be owned by you on the date declared. If you don’t own any domains on the date you declare the type, you can simply use an e-mail address.

tag:[email protected],2004:notes/personal



35
36
37
38
39
40
 
# File 'lib/syck/tag.rb', line 35

def self.tag_class( tag, cls )
    if @@tagged_classes.has_key? tag
        warn "class #{ @@tagged_classes[tag] } held ownership of the #{ tag } tag"
    end
    @@tagged_classes[tag] = cls
end

.tagged_classes ⇒ Object

Returns the complete dictionary of taguris, paired with classes. The key for the dictionary is the full taguri. The value for each key is the class constant associated to that taguri.

YAML.tagged_classes["tag:yaml.org,2002:int"] => Integer



48
49
50
 
# File 'lib/syck/tag.rb', line 48

def self.tagged_classes
    @@tagged_classes
end

.tagurize(val) ⇒ Object

Convert a type_id to a taguri



352
353
354
355
 
# File 'lib/syck.rb', line 352

def self.tagurize( val )
    warn "#{caller[0]}: YAML.tagurize is deprecated" if $VERBOSE && !caller[0].start_with?(File.dirname(__FILE__))
    resolver.tagurize( val )
end

.transfer(type_id, obj) ⇒ Object

Apply a transfer method to a Ruby object



360
361
362
363
 
# File 'lib/syck.rb', line 360

def self.transfer( type_id, obj )
    warn "#{caller[0]}: YAML.transfer is deprecated" if $VERBOSE && !caller[0].start_with?(File.dirname(__FILE__))
    resolver.transfer( tagurize( type_id ), obj )
end

.try_implicit(obj) ⇒ Object

Apply any implicit a node may qualify for



368
369
370
371
 
# File 'lib/syck.rb', line 368

def self.try_implicit( obj )
    warn "#{caller[0]}: YAML.try_implicit is deprecated" if $VERBOSE && !caller[0].start_with?(File.dirname(__FILE__))
    transfer( detect_implicit( obj ), obj )
end

.unescape(value) ⇒ Object

Unescape the condenses escapes



22
23
24
25
26
27
28
29
30
31
32
33
 
# File 'lib/syck/encoding.rb', line 22

def self.unescape( value )
             warn "#{caller[0]}: YAML.unescape is deprecated" if $VERBOSE
	value.gsub( /\\(?:([nevfbart\\])|0?x([0-9a-fA-F]{2})|u([0-9a-fA-F]{4}))/ ) {
		if $3
			["#$3".hex ].pack('U*')
		elsif $2
			[$2].pack( "H2" )
		else
			UNESCAPES[$1]
		end
	}
end