module HappyMapper::ClassMethods

Attributes

nokogiri_config_callback[R]

The callback defined through {.with_nokogiri_config}.

@return [Proc] the proc to pass to Nokogiri to setup parse options. nil if empty.

Public Instance Methods

after_parse(&block) click to toggle source

Register a new after_parse callback, given as a block.

@yield [object] Yields the newly-parsed object to the block after parsing.

Sub-objects will be already populated.
# File lib/happymapper.rb, line 201
def after_parse(&block)
  after_parse_callbacks.push(block)
end
after_parse_callbacks() click to toggle source

The list of registered after_parse callbacks.

# File lib/happymapper.rb, line 192
def after_parse_callbacks
  @after_parse_callbacks ||= []
end
attribute(name, type, options = {}) click to toggle source

The xml has the following attributes defined.

@example

"<country code='de'>Germany</country>"

# definition of the 'code' attribute within the class
attribute :code, String

@param [Symbol] name the name of the accessor that is created @param [String,Class] type the class name of the name of the class whcih

the object will be converted upon parsing

@param [Hash] options additional parameters to send to the relationship

# File lib/happymapper.rb, line 57
def attribute(name, type, options = {})
  attribute = Attribute.new(name, type, options)
  @attributes[name] = attribute
  attr_accessor attribute.method_name.intern
end
attributes() click to toggle source

The elements defined through {#attribute}.

@return [Array<Attribute>] a list of the attributes defined for this class;

an empty array is returned when there have been no attributes defined.
# File lib/happymapper.rb, line 69
def attributes
  @attributes.values
end
content(name, type = String, options = {}) click to toggle source

The value stored in the text node of the current element.

@example

"<firstName>Michael Jackson</firstName>"

# definition of the 'firstName' text node within the class

content :first_name, String

@param [Symbol] name the name of the accessor that is created @param [String,Class] type the class name of the name of the class whcih

the object will be converted upon parsing. By Default String class will be taken.

@param [Hash] options additional parameters to send to the relationship

# File lib/happymapper.rb, line 145
def content(name, type = String, options = {})
  @content = TextNode.new(name, type, options)
  attr_accessor @content.method_name.intern
end
defined_content() click to toggle source

@private

# File lib/happymapper.rb, line 387
def defined_content
  @content if defined? @content
end
element(name, type, options = {}) click to toggle source

An element defined in the XML that is parsed.

@example

"<address location='home'>
   <city>Oldenburg</city>
 </address>"

# definition of the 'city' element within the class

element :city, String

@param [Symbol] name the name of the accessor that is created @param [String,Class] type the class name of the name of the class whcih

the object will be converted upon parsing

@param [Hash] options additional parameters to send to the relationship

# File lib/happymapper.rb, line 112
def element(name, type, options = {})
  element = Element.new(name, type, options)
  attr_accessor element.method_name.intern unless @elements[name]
  @elements[name] = element
end
elements() click to toggle source

The elements defined through {#element}, {#has_one}, and {#has_many}.

@return [Array<Element>] a list of the elements contained defined for this

class; an empty array is returned when there have been no elements
defined.
# File lib/happymapper.rb, line 125
def elements
  @elements.values
end
has_many(name, type, options = {}) click to toggle source

The object has many of these elements in the XML.

@param [Symbol] name the name of accessor that is created @param [String,Class] type the class name or the name of the class which

the object will be converted upon parsing.

@param [Hash] options additional parameters to send to the relationship

@see element

# File lib/happymapper.rb, line 185
def has_many(name, type, options = {})
  element name, type, { single: false }.merge(options)
end
has_one(name, type, options = {}) click to toggle source

The object has one of these elements in the XML. If there are multiple, the last one will be set to this value.

@param [Symbol] name the name of the accessor that is created @param [String,Class] type the class name of the name of the class whcih

the object will be converted upon parsing

@param [Hash] options additional parameters to send to the relationship

@see element

# File lib/happymapper.rb, line 171
def has_one(name, type, options = {})
  element name, type, { single: true }.merge(options)
end
has_xml_content() click to toggle source

Sets the object to have xml content, this will assign the XML contents that are parsed to the attribute accessor xml_content. The object will respond to the method xml_content and will return the XML data that it has parsed.

# File lib/happymapper.rb, line 156
def has_xml_content
  attr_accessor :xml_content
end
namespace(namespace = nil) click to toggle source

Specify a namespace if a node and all its children are all namespaced elements. This is simpler than passing the :namespace option to each defined element.

@param [String] namespace the namespace to set as default for the class

element.
# File lib/happymapper.rb, line 213
def namespace(namespace = nil)
  @namespace = namespace if namespace
  @namespace if defined? @namespace
end
parse(xml, options = {}) { |part| ... } click to toggle source

@param [Nokogiri::XML::Node,Nokogiri:XML::Document,String] xml the XML

contents to convert into Object.

@param [Hash] options additional information for parsing.

:single => true if requesting a single object, otherwise it defaults
to retuning an array of multiple items.
:xpath information where to start the parsing
:namespace is the namespace to use for additional information.
# File lib/happymapper.rb, line 293
def parse(xml, options = {})
  # Capture any provided namespaces and merge in any namespaces that have
  # been registered on the object.
  namespaces = options[:namespaces] || {}
  namespaces = namespaces.merge(@registered_namespaces)

  # If the XML specified is an Node then we have what we need.
  if xml.is_a?(Nokogiri::XML::Node) && !xml.is_a?(Nokogiri::XML::Document)
    node = xml
  else

    unless xml.is_a?(Nokogiri::XML::Document)
      # Attempt to parse the xml value with Nokogiri XML as a document
      # and select the root element
      xml = Nokogiri::XML(
        xml, nil, nil,
        Nokogiri::XML::ParseOptions::STRICT,
        &nokogiri_config_callback
      )
    end
    # Now xml is certainly an XML document: Select the root node of the document
    node = xml.root

    # merge any namespaces found on the xml node into the namespace hash
    namespaces = namespaces.merge(xml.collect_namespaces)

    # if the node name is equal to the tag name then the we are parsing the
    # root element and that is important to record so that we can apply
    # the correct xpath on the elements of this document.

    root = node.name == tag_name
  end

  # If the :single option has been specified or we are at the root element
  # then we are going to return a single element or nil if no nodes are found
  single = root || options[:single]

  # if a namespace has been provided then set the current namespace to it
  # or use the namespace provided by the class
  # or use the 'xmlns' namespace if defined

  namespace = options[:namespace] || self.namespace || namespaces.key?('xmlns') && 'xmlns'

  # from the options grab any nodes present and if none are present then
  # perform the following to find the nodes for the given class

  nodes = options.fetch(:nodes) do
    find_nodes_to_parse(options, namespace, tag_name, namespaces, node, root)
  end

  # Nothing matching found, we can go ahead and return
  return (single ? nil : []) if nodes.empty?

  # If the :limit option has been specified then we are going to slice
  # our node results by that amount to allow us the ability to deal with
  # a large result set of data.

  limit = options[:in_groups_of] || nodes.size

  # If the limit of 0 has been specified then the user obviously wants
  # none of the nodes that we are serving within this batch of nodes.

  return [] if limit == 0

  collection = []

  nodes.each_slice(limit) do |slice|
    part = slice.map do |n|
      parse_node(n, options, namespace, namespaces)
    end

    # If a block has been provided and the user has requested that the objects
    # be handled in groups then we should yield the slice of the objects to them
    # otherwise continue to lump them together

    if block_given? && options[:in_groups_of]
      yield part
    else
      collection += part
    end
  end

  # If we're parsing a single element then we are going to return the first
  # item in the collection. Otherwise the return response is going to be an
  # entire array of items.

  if single
    collection.first
  else
    collection
  end
end
register_namespace(name, href) click to toggle source

Register a namespace that is used to persist the object namespace back to XML.

@example

register_namespace 'prefix', 'http://www.unicornland.com/prefix'

# the output will contain the namespace defined

"<outputXML xmlns:prefix="http://www.unicornland.com/prefix">
...
</outputXML>"

@param [String] name the xml prefix @param [String] href url for the xml namespace

# File lib/happymapper.rb, line 90
def register_namespace(name, href)
  @registered_namespaces.merge!(name => href)
end
tag(new_tag_name) click to toggle source

@param [String] new_tag_name the name for the tag

# File lib/happymapper.rb, line 221
def tag(new_tag_name)
  @tag_name = new_tag_name.to_s unless new_tag_name.nil? || new_tag_name.to_s.empty?
end
tag_name() click to toggle source

The name of the tag

@return [String] the name of the tag as a string, downcased

# File lib/happymapper.rb, line 230
def tag_name
  @tag_name ||= name && name.to_s.split('::')[-1].downcase
end
with_nokogiri_config(&blk) click to toggle source

Register a config callback according to the block Nokogori expects when calling Nokogiri::XML::Document.parse().

See nokogiri.org/Nokogiri/XML/Document.html#method-c-parse

@param [Proc] the proc to pass to Nokogiri to setup parse options

# File lib/happymapper.rb, line 280
def with_nokogiri_config(&blk)
  @nokogiri_config_callback = blk
end
wrap(name, &blk) click to toggle source

There is an XML tag that needs to be known for parsing and should be generated during a to_xml. But it doesn't need to be a class and the contained elements should be made available on the parent class

@param [String] name the name of the element that is just a place holder @param [Proc] blk the element definitions inside the place holder tag

# File lib/happymapper.rb, line 241
    def wrap(name, &blk)
      # Get an anonymous HappyMapper that has 'name' as its tag and defined
      # in '&blk'.  Then save that to a class instance variable for later use
      wrapper = AnonymousWrapperClassFactory.get(name, &blk)
      wrapper_key = wrapper.inspect
      @wrapper_anonymous_classes[wrapper_key] = wrapper

      # Create getter/setter for each element and attribute defined on the anonymous HappyMapper
      # onto this class. They get/set the value by passing thru to the anonymous class.
      passthrus = wrapper.attributes + wrapper.elements
      passthrus.each do |item|
        class_eval <<-RUBY, __FILE__, __LINE__ + 1
          def #{item.method_name}
            @#{name} ||= self.class.instance_variable_get('@wrapper_anonymous_classes')['#{wrapper_key}'].new
            @#{name}.#{item.method_name}
          end
          def #{item.method_name}=(value)
            @#{name} ||= self.class.instance_variable_get('@wrapper_anonymous_classes')['#{wrapper_key}'].new
            @#{name}.#{item.method_name} = value
          end
        RUBY
      end

      has_one name, wrapper
    end

Private Instance Methods

find_nodes_to_parse(options, namespace, tag_name, namespaces, node, root) click to toggle source
# File lib/happymapper.rb, line 393
def find_nodes_to_parse(options, namespace, tag_name, namespaces, node, root)
  # when at the root use the xpath '/' otherwise use a more gready './/'
  # unless an xpath has been specified, which should overwrite default
  # and finally attach the current namespace if one has been defined
  #

  xpath = if options[:xpath]
            options[:xpath].to_s.sub(%r{([^/])$}, '\1/')
          elsif root
            '/'
          else
            './/'
          end
  if namespace
    return [] unless namespaces.find { |name, _url| ["xmlns:#{namespace}", namespace].include? name }

    xpath += "#{namespace}:"
  end

  nodes = []

  # when finding nodes, do it in this order:
  # 1. specified tag if one has been provided
  # 2. name of element
  # 3. tag_name (derived from class name by default)

  # If a tag has been provided we need to search for it.

  if options.key?(:tag)
    nodes = node.xpath(xpath + options[:tag].to_s, namespaces)
  else

    # This is the default case when no tag value is provided.
    # First we use the name of the element `items` in `has_many items`
    # Second we use the tag name which is the name of the class cleaned up

    [options[:name], tag_name].compact.each do |xpath_ext|
      nodes = node.xpath(xpath + xpath_ext.to_s, namespaces)
      break if nodes && !nodes.empty?
    end

  end

  nodes
end
parse_node(node, options, namespace, namespaces) click to toggle source
# File lib/happymapper.rb, line 439
def parse_node(node, options, namespace, namespaces)
  # If an existing HappyMapper object is provided, update it with the
  # values from the xml being parsed.  Otherwise, create a new object

  obj = options[:update] || new

  attributes.each do |attr|
    value = attr.from_xml_node(node, namespace, namespaces)
    value = attr.default if value.nil?
    obj.send("#{attr.method_name}=", value)
  end

  elements.each do |elem|
    obj.send("#{elem.method_name}=", elem.from_xml_node(node, namespace, namespaces))
  end

  if (content = defined_content)
    obj.send("#{content.method_name}=", content.from_xml_node(node, namespace, namespaces))
  end

  # If the HappyMapper class has the method #xml_value=,
  # attr_writer :xml_value, or attr_accessor :xml_value then we want to
  # assign the current xml that we just parsed to the xml_value

  if obj.respond_to?('xml_value=')
    obj.xml_value = node.to_xml(save_with: Nokogiri::XML::Node::SaveOptions::AS_XML)
  end

  # If the HappyMapper class has the method #xml_content=,
  # attr_write :xml_content, or attr_accessor :xml_content then we want to
  # assign the child xml that we just parsed to the xml_content

  if obj.respond_to?('xml_content=')
    node = node.children if node.respond_to?(:children)
    obj.xml_content = node.to_xml(save_with: Nokogiri::XML::Node::SaveOptions::AS_XML)
  end

  # Call any registered after_parse callbacks for the object's class

  obj.class.after_parse_callbacks.each { |callback| callback.call(obj) }

  # collect the object that we have created

  obj
end