Module: ROXML::ClassMethods::Declarations

Defined in:
lib/roxml.rb

Overview

:nodoc:

Instance Method Summary collapse

Instance Method Details

#roxml_naming_convention ⇒ Object

:nodoc:



177
178
179
 
# File 'lib/roxml.rb', line 177

def roxml_naming_convention # :nodoc:
  (@roxml_naming_convention || superclass.try(:roxml_naming_convention)).freeze
end

#xml(sym, writable = false, type_and_or_opts = nil, opts = nil, &block) ⇒ Object

:nodoc:



453
454
455
 
# File 'lib/roxml.rb', line 453

def xml(sym, writable = false, type_and_or_opts = nil, opts = nil, &block) #:nodoc:
  send(writable ? :xml_accessor : :xml_reader, sym, type_and_or_opts, opts, &block)
end

#xml_accessor(sym, type_and_or_opts = nil, opts = nil, &block) ⇒ Object

Declares a writable xml reference. See xml_attr for details.

Note that while xml_accessor does create a setter for this attribute, you can use the :frozen option to prevent its value from being modified indirectly via methods.



473
474
475
476
477
 
# File 'lib/roxml.rb', line 473

def xml_accessor(sym, type_and_or_opts = nil, opts = nil, &block)
  attr = xml_attr sym, type_and_or_opts, opts, &block
  add_reader(attr)
  attr_writer(attr.variable_name)
end

#xml_attr(sym, type_and_or_opts = nil, opts = nil, &block) ⇒ Object

Declares a reference to a certain xml element, whether an attribute, a node, or a typed collection of nodes. This method does not add a corresponding accessor to the object. For that behavior see the similar methods: .xml_reader and .xml_accessor.

Sym Option

sym

Symbol representing the name of the accessor.

Default naming

This name will be the default node or attribute name searched for, if no other is declared. For example,

xml_reader   :bob
xml_accessor :pony, :from => :attr

are equivalent to:

xml_reader   :bob, :from => 'bob'
xml_accessor :pony, :from => '@pony'

Boolean attributes

If the name ends in a ?, ROXML will attempt to coerce the value to true or false, with True, TRUE, true and 1 mapping to true and False, FALSE, false and 0 mapping to false, as shown below:

xml_reader :desirable?
xml_reader :bizzare?, :from => '@BIZZARE'

x = #from_xml(%{
  <object BIZZARE="1">
    <desirable>False</desirable>
  </object>
})
x.desirable?
=> false
x.bizzare?
=> true

If an unexpected value is encountered, the attribute will be set to nil, unless you provide a block, in which case the block will recived the actual unexpected value.

#from_xml(%{
  <object>
    <desirable>Dunno</desirable>
  </object>
}).desirable?
=> nil

xml_reader :strange? do |val|
  val.upcase
end

#from_xml(%{
  <object>
    <strange>Dunno</strange>
  </object>
}).strange?
=> DUNNO

Blocks

You may also pass a block which manipulates the associated parsed value.

class Muffins
  include ROXML

  xml_reader(:count, :from => 'bakers_dozens') {|val| val.to_i * 13 }
end

For hash types, the block recieves the key and value as arguments, and they should be returned as an array of [key, value]

For array types, the entire array is passed in, and must be returned in the same fashion.

Options

:as

Basic Types

Allows you to specify one of several basic types to return the value as. For example

xml_reader :count, :as => Integer

is equivalent to:

xml_reader(:count) {|val| Integer(val) unless val.empty? }

Such block shorthands for Integer, Float, Fixnum, BigDecimal, Date, Time, and DateTime are currently available, but only for non-Hash declarations.

To reference many elements, put the desired type in a literal array. e.g.:

xml_reader :counts, :as => [Integer]

Even an array of :text nodes can be specified with :as => []

xml_reader :quotes, :as => []

Other ROXML Class

Declares an accessor that represents another ROXML class as child XML element (one-to-one or composition) or array of child elements (one-to-many or aggregation) of this type. Default is one-to-one. For one-to-many, simply pass the class as the only element in an array.

Composition example:

<book>
 <publisher>
   <name>Pragmatic Bookshelf</name>
 </publisher>
</book>

Can be mapped using the following code:

class Book
  xml_reader :publisher, :as => Publisher
end

Aggregation example:

<library>
 <books>
  <book/>
  <book/>
 </books>
</library>

Can be mapped using the following code:

class Library
  xml_reader :books, :as => [Book], :in => "books"
end

If you don’t have the <books> tag to wrap around the list of <book> tags:

<library>
 <name>Ruby books</name>
 <book/>
 <book/>
</library>

You can skip the wrapper argument:

xml_reader :books, :as => [Book]

Hash

Somewhere between the simplicity of a :text/:attr mapping, and the complexity of a full Object/Type mapping, lies the Hash mapping. It serves in the case where you have a collection of key-value pairs represented in your xml. You create a hash declaration by passing a hash mapping as the type argument. A few examples:

Hash of :texts

For xml such as this:

<dictionary>
  <definition>
    <word/>
    <meaning/>
  </definition>
  <definition>
    <word/>
    <meaning/>
  </definition>
</dictionary>

You can individually declare your key and value names:

xml_reader :definitions, :as => {:key => 'word',
                                 :value => 'meaning'}
Hash of :content &c.

For xml such as this:

<dictionary>
  <definition word="quaquaversally">adjective: (of a geological formation) sloping downward from the center in all directions.</definition>
  <definition word="tergiversate">To use evasions or ambiguities; equivocate.</definition>
</dictionary>

You can individually declare the key and value, but with the attr, you need to provide both the type and name of that type (i.e. => :word), because omitting the type will result in ROXML defaulting to :text

xml_reader :definitions, :as => {:key => {:attr => 'word'},
                                 :value => :content}
Hash of :name &c.

For xml such as this:

<dictionary>
  <quaquaversally>adjective: (of a geological formation) sloping downward from the center in all directions.</quaquaversally>
  <tergiversate>To use evasions or ambiguities; equivocate.</tergiversate>
</dictionary>

You can pick up the node names (e.g. quaquaversally) using the :name keyword:

xml_reader :definitions, :as => {:key => :name,
                                 :value => :content}

:from

The name by which the xml value will be found, either an attribute or tag name in XML. Default is sym, or the singular form of sym, in the case of arrays and hashes.

This value may also include XPath notation.

:from => :content

When :from is set to :content, this refers to the content of the current node, rather than a sub-node. It is equivalent to :from => ‘.’

Example:

class Contributor
  xml_reader :name, :from => :content
  xml_reader :role, :from => :attr
end

To map:

<contributor role="editor">James Wick</contributor>

:from => :attr

When :from is set to :attr, this refers to the content of an attribute, rather than a sub-node. It is equivalent to :from => ‘@attribute_name’

Example:

class Book
  xml_reader :isbn, :from => "@ISBN"
  xml_accessor :title, :from => :attr # :from defaults to '@title'
end

To map:

<book ISBN="0974514055" title="Programming Ruby: the pragmatic programmers' guide" />

:from => :text

The default source, if none is specified, this means the accessor represents a text node from XML. This is documented for completeness only. You should just leave this option off when you want the default behavior, as in the examples below.

:text is equivalent to :from => accessor_name, and you should specify the actual node name if it differs, as in the case of :author below.

Example:

class Book
  xml_reader :author, :from => 'Author
  xml_accessor :description, :cdata => true
  xml_reader :title
end

To map:

<book>
 <title>Programming Ruby: the pragmatic programmers' guide</title>
 <description><![CDATA[Probably the best Ruby book out there]]></description>
 <Author>David Thomas</Author>
</book>

Likewise, a number of :text node values can be collected in an array like so:

Example:

class Library
  xml_reader :books, :as => []
end

To map:

<library>
    <book>To kill a mockingbird</book>
    <book>House of Leaves</book>
  <book>G

Other Options

:in

An optional name of a wrapping tag for this XML accessor. This can include other xpath values, which will be joined with :from with a ‘/’

:else

Default value for attribute, if missing from the xml on .from_xml

:required

If true, throws RequiredElementMissing when the element isn’t present

:frozen

If true, all results are frozen (using #freeze) at parse-time.

:cdata

True for values which should be input from or output as cdata elements



444
445
446
447
448
449
450
451
 
# File 'lib/roxml.rb', line 444

def xml_attr(sym, type_and_or_opts = nil, opts = nil, &block)
  returning Definition.new(sym, *[type_and_or_opts, opts].compact, &block) do |attr|
    if roxml_attrs.map(&:accessor).include? attr.accessor
      raise "Accessor #{attr.accessor} is already defined as XML accessor in class #{self.name}"
    end
    @roxml_attrs << attr
  end
end

#xml_construct(*args) ⇒ Object

This method is deprecated, please use xml_initialize instead



480
481
482
483
484
485
486
487
488
489
 
# File 'lib/roxml.rb', line 480

def xml_construct(*args) # :nodoc:
  present_tags = tag_refs_without_deprecation.map(&:accessor)
  missing_tags = args - present_tags
  unless missing_tags.empty?
    raise ArgumentError, "All construction tags must be declared first using xml, " +
                         "xml_reader, or xml_accessor. #{missing_tags.join(', ')} is missing. " +
                         "#{present_tags.join(', ')} are declared."
  end
  @xml_construction_args = args
end

#xml_convention(to_proc_able = nil, &block) ⇒ Object

Most xml documents have a consistent naming convention, for example, the node and and attribute names might appear in CamelCase. xml_convention enables you to adapt the roxml default names for this object to suit this convention. For example, if I had a document like so:

<XmlDoc>
  <MyPreciousData />
  <MoreToSee InAttrs="" />
</XmlDoc>

Then I could access it’s contents by defining the following class:

class XmlDoc
  include ROXML
  xml_convention :camelcase
  xml_reader :my_precious_data
  xml_reader :in_attrs, :in => 'MoreToSee'
end

You may supply a block or any #to_proc-able object as the argument, and it will be called against the default node and attribute names before searching the document. Here are some example declaration:

xml_convention :upcase
xml_convention &:camelcase
xml_convention {|val| val.gsub('_', '').downcase }

See ActiveSupport::CoreExtensions::String::Inflections for more prepackaged formats

Note that the xml_convention is also applied to the default root-level tag_name, but in this case an underscored version of the name is applied, for convenience.

Raises:

  • (ArgumentError) 


170
171
172
173
174
175
 
# File 'lib/roxml.rb', line 170

def xml_convention(to_proc_able = nil, &block)
  raise ArgumentError, "conventions are already set" if @roxml_naming_convention
  raise ArgumentError, "only one conventions can be set" if to_proc_able.respond_to?(:to_proc) && block_given?
  @roxml_naming_convention = to_proc_able.try(:to_proc)
  @roxml_naming_convention = block if block_given?
end

#xml_name(name) ⇒ Object

Sets the name of the XML element that represents this class. Use this to override the default lowercase class name.

Example:

class BookWithPublisher
 xml_name :book
end

Without the xml_name annotation, the XML mapped tag would have been “bookwithpublisher”.



113
114
115
 
# File 'lib/roxml.rb', line 113

def xml_name(name)
  @roxml_tag_name = name
end

#xml_namespace(namespace) ⇒ Object

Sets the namemespace for attributes and elements of this class. You can override this value on individual elements via the :from option

Example:

class Book
 xml_namespace :aws

 xml_reader :default_namespace
 xml_reader :different_namespace, :from => 'different:namespace'
 xml_reader :no_namespace, :from => ':no_namespace'
end

<aws:book xmlns:aws=“www.aws.com/aws” xmlns:different=“www.aws.com/different”>

<aws:default_namespace>value</aws:default_namespace>
<different:namespace>value</different:namespace>
<no_namespace>value</no_namespace>

</aws:book>



135
136
137
 
# File 'lib/roxml.rb', line 135

def xml_namespace(namespace)
  @roxml_namespace = namespace.to_s
end

#xml_reader(sym, type_and_or_opts = nil, opts = nil, &block) ⇒ Object

Declares a read-only xml reference. See xml_attr for details.

Note that while xml_reader does not create a setter for this attribute, its value can be modified indirectly via methods. For more complete protection, consider the :frozen option.



463
464
465
466
 
# File 'lib/roxml.rb', line 463

def xml_reader(sym, type_and_or_opts = nil, opts = nil, &block)
  attr = xml_attr sym, type_and_or_opts, opts, &block
  add_reader(attr)
end