oxmlk 0.3.2 → 0.3.3

data/README.rdoc

@@ -1,6 +1,108 @@
-= oxmlk
+=OxMlk (Object XML Kit or something like that)
 
-OxMlk is a simple lightweight XML mapper. Its structure is inspired by happymapper and its syntax takes after ROXML. Right now there is one example to get things going. More features, examples and documentation will be coming soon.
+OxMlk is a flexible, lightweight, Object to XML mapper. It gives you a dsl for describing the relationship between your object and an XML structure. Once defined you can use the from_xml to create objects from an XML file and the to_xml file to export you objects as XML. Full documentation is hosted at {http://rdoc.info/projects/hexorx/oxmlk rdoc.info}.
+
+==Why?
+
+Aren't there already XML mappers out there? Yes! Some really good ones. {http://github.com/Empact/roxml ROXML} has a great syntax and wonderful documentation. But .... it wasn't able to do something that I really needed it to do. You see OxMlk is an extraction from a parser for PhrkML. PhrkML is used to control call flow on VoIP systems. It has a list of action tags that tell the call what to do. They have to happen in order and each one is its own object. I found some hacks I could do to make ROXML kinda do what I wanted but it was pretty ugly. So I looked for something else and found {http://github.com/jnunemaker/happymapper HappyMapper}. It had an impressively simple design but it also didn't do what I need. So I made OxMlk. It tries to combine the syntax of {http://github.com/Empact/roxml ROXML} and the simple design of {http://github.com/jnunemaker/happymapper HappyMapper} while adding some features to make it extra flexible.
+
+==Acknowledgements
+
+The syntax and even the documentation borrow heavily from {http://github.com/Empact/roxml ROXML} and the design is inspired by {http://github.com/jnunemaker/happymapper HappyMapper}.
+
+=Quick Start Guide
+
+This is a short tutorial based on the ROXML Quick Start Guide. The full rdoc is hosted at {http://rdoc.info/projects/hexorx/oxmlk rdoc.info} and has more detail in OxMlk::Attr and OxMlk::Elem.
+
+==Basic Mapping
+
+Consider an XML document representing a Library containing a number of Books. You can map this structure to Ruby classes that provide addition useful behavior. With OxMlk, you can annotate the Ruby classes as follows:
+
+  class Book
+    include OxMlk
+
+    ox_attr :isbn, :from => 'ISBN' # attribute with name 'ISBN'
+    ox_elem :title
+    ox_elem :description
+    ox_elem :author
+  end
+
+  class Library
+    include OxMlk
+
+    ox_elem :name, :from => 'NAME'
+    ox_elem :books, :as => [Book] # by default oxmlk will use Book.tag to determine what to search for.
+  end
+
+To create a library and put a number of books in it we could run the following code:
+
+  book = Book.new
+  book.isbn = "0201710897"
+  book.title = "The PickAxe"
+  book.description = "Best Ruby book out there!"
+  book.author = "David Thomas, Andrew Hunt, Dave Thomas"
+
+  lib = Library.new
+  lib.name = "Favorite Books"
+  lib.books = [book]
+
+To save this information to an XML file:
+
+  doc = ROXML::XML::Document.new
+  doc.root = lib.to_xml
+  doc.save("library.xml")
+
+To later populate the library object from the XML file:
+
+  lib = Library.from_xml(File.read("library.xml"))
+
+Similarly, to do a one-to-one mapping between XML objects, such as book and publisher,
+you would add a reference to another ROXML class. For example:
+
+  <book isbn="0974514055">
+    <title>Programming Ruby - 2nd Edition</title>
+    <description>Second edition of the great book.</description>
+    <publisher>
+      <name>Pragmatic Bookshelf</name>
+    </publisher>
+  </book>
+
+can be mapped using the following code:
+
+  class Publisher
+    include OxMlk
+    
+    ox_tag :downcase
+    xml_elem :name
+
+    # other important functionality
+  end
+
+  class BookWithPublisher
+    include OxMlk
+
+    ox_tag 'book'
+    ox_elem :publisher, :as => Publisher
+
+    #  or, alternatively, if no class is needed to hang functionality on:
+    # ox_elem :publisher, :from => 'name', :in => 'publisher'
+  end
+
+Note: In the above example, _ox_tag_ annotation tells OxMlk to set the element name for the BookWithPublisher class to 'book' for mapping to XML. The default XML element name is the class name, so 'BookWithPublisher' in this case. In the Publisher class it is set to the symbol :downcase, this tells OxMlk to take the class name and attempt to convert it to all lower case. That means OxMlk will look for <publisher> instead of <Publisher> This behavior will be inherited by the attrs and elems in the class as well. So (ox_elem :Name) would look for a <name> instead of <Name>.
+
+== Manipulation
+
+Extending the above examples, say you want to parse a book's page count and have it available as an Integer. In such a case, you can extend any object with a block to manipulate it's value at parse time. For example:
+
+  class Dog
+    include OxMlk
+
+    ox_attr(:age, :from => :human_years, :as => Integer) {|years| years * 7 }
+  end
+
+The result of the block above is stored, rather than the actual value parsed from the document. It is important to keep in mind that manipulating data in this manner is one way. So when to_xml is ran you will get an age attribute not a human_years attribute.
+
+= Extra Stuff
 
 == Note on Patches/Pull Requests
  
@@ -10,9 +112,9 @@ OxMlk is a simple lightweight XML mapper. Its structure is inspired by happymapp
   future version unintentionally.
 * Commit, do not mess with rakefile, version, or history.
   (if you want to have your own version, that is fine but
-   bump version in a commit by itself I can ignore when I pull)
+  bump version in a commit by itself I can ignore when I pull)
 * Send me a pull request. Bonus points for topic branches.
 
 == Copyright
 
-Copyright (c) 2009 Josh Robinson. See LICENSE for details.
+Copyright (c) 2009 Josh Robinson. See LICENSE for details.

data/VERSION

@@ -1 +1 @@
-0.3.2
+0.3.3

data/examples/amazon.rb

@@ -10,17 +10,17 @@ class Item
   ox_elem :point, :from => 'georss:point'
 end
 
-class Response
+class ItemSearchResponse
   include OxMlk
   
-  ox_tag 'ItemSearchResponse'
+  ox_tag :camelcase
   
-  ox_elem :total_results, :from => 'TotalResults', :as => Integer, :in => 'Items'
-  ox_elem :total_pages, :from => 'TotalPages', :as => Integer, :in => 'Items'
+  ox_elem :total_results, :as => Integer, :in => 'Items'
+  ox_elem :total_pages, :as => Integer, :in => 'Items'
   ox_elem :items, :as => [Item], :in => 'Items'
 end
 
-response = Response.from_xml(xml_for(:amazon))
+response = ItemSearchResponse.from_xml(xml_for(:amazon))
 
 puts response.total_results, response.total_pages
 

data/examples/phrk.rb

@@ -0,0 +1,173 @@
+#!/usr/bin/env ruby
+require File.expand_path(File.dirname(__FILE__) + '/../spec/spec_helper')
+
+## This example is pretty ugly. It should be pretty when moved to the phrk gem.
+
+class Say
+  include OxMlk
+  
+  ox_elem :phrase, :from => :content
+  
+  def description
+    "Say '#{phrase}'"
+  end
+end
+
+class Play
+  include OxMlk
+  
+  ox_elem :file, :from => :content
+  
+  def description
+    "Play #{file}"
+  end
+end
+
+class Gather
+  include OxMlk
+  
+  ox_attr :action
+  ox_attr :method
+  ox_attr :timeout, :as => Integer
+  ox_attr :finish_on_key, :from => 'finishOnKey'
+  ox_attr :num_digits, :from => 'numDigits', :as => Integer
+  
+  ox_elem :verbs, :as => [Say,Play]
+  
+  def description
+    "Gather #{num_digits} keypresses ending on key '#{finish_on_key}' or timing out at #{timeout} seconds, then send #{method} to #{action}:\n\t#{verbs.map(&:description).join("\n\t")}"
+  end
+end
+
+class Record
+  include OxMlk
+  
+  ox_attr :action
+  ox_attr :method
+  ox_attr :max_length, :from => 'maxLength', :as => Integer
+  ox_attr :finish_on_key, :from => 'finishOnKey'
+  
+  def description
+    "Record for #{max_length} seconds max ending on keys '#{finish_on_key}' then send #{method} to #{action}"
+  end
+end
+
+class Redirect
+  include OxMlk
+  
+  ox_elem :destination, :from => :content
+  
+  def description
+    "Redirect to #{destination}"
+  end
+end
+
+class Pause
+  include OxMlk
+  
+  ox_attr :length
+  
+  def description
+    "Pause for #{length} seconds"
+  end
+end
+
+class Hangup
+  include OxMlk
+  
+  def description
+    'Hangup'
+  end
+end
+
+class Number
+  include OxMlk
+  
+  ox_attr :send_digits, :from => 'sendDigits'
+  ox_elem :number, :from => :content
+  
+  def description
+    "Call #{number} and send digits '#{send_digits}'"
+  end
+end
+
+class Dial
+  include OxMlk
+  
+  ox_attr :callerid
+  ox_elem :numbers, :as => [Number]
+  
+  def description
+    "Dial numbers with caller id #{callerid}:\n\t#{numbers.map(&:description).join("\n\t")}"
+  end
+end
+
+class Tag
+  include OxMlk
+  
+  ox_elem :tag, :from => :content
+  
+  def description
+    "Add tag '#{tag}'"
+  end
+end
+
+class Tags
+  include OxMlk
+  
+  ox_attr :mode
+  ox_attr :include
+  ox_attr :exclude
+  
+  def description
+    "Tagged with (#{include}) but not (#{exclude}) using match mode(#{mode})"
+  end
+end
+
+class Schedule
+  include OxMlk
+  
+  ox_attr :mode 
+  ox_attr :tz_offset
+  ox_attr :time
+  ox_attr :year
+  ox_attr :month
+  ox_attr :day_of_week
+  ox_attr :day_of_month
+  
+  def description
+    "Schedule: mode(#{mode}) tz_offset(#{tz_offset}) time(#{time}) year(#{year}) month(#{month}) day_of_week(#{day_of_week} day_of_month(#{day_of_month}))"
+  end
+end
+
+VERBS = [Say,Play,Gather,Record,Redirect,Pause,Hangup,Dial,Tag]
+
+class Rule
+  include OxMlk
+  
+  ox_attr :name
+  ox_attr :mode
+  ox_elem :conditions, :as => [Schedule,Tags], :in => 'Conditions'
+  ox_elem :match_verbs, :as => VERBS, :in => 'Match'
+  ox_elem :no_match_verbs, :as => VERBS, :in => 'NoMatch'
+  
+  def description
+    "Rule #{name} - match mode(#{mode})\n\tConditions:\n\t#{conditions.map(&:description).join("\n\t")}\n\n\tOn Match:\n\t#{match_verbs.map(&:description).join("\n\t")}\n\n\tNo Match:\n\t#{no_match_verbs.map(&:description).join("\n\t")}"
+  end
+end
+
+class Response
+  include OxMlk
+  
+  ox_elem :verbs, :as => VERBS + [Rule]
+end
+
+class String
+  def description
+    self
+  end
+end
+
+response = Response.from_xml(xml_for(:phrk))
+
+puts *response.verbs.map{|x| [x,'']}.flatten.map(&:description)

data/examples/posts.rb

@@ -3,7 +3,6 @@ require File.expand_path(File.dirname(__FILE__) + '/../spec/spec_helper')
 
 class Post
   include OxMlk
-  
   ox_tag :post
   
   ox_attr :href
@@ -17,7 +16,6 @@ end
 
 class Response
   include OxMlk
-  
   ox_tag :posts
   
   ox_attr :user

data/examples/twitter.rb

@@ -4,7 +4,7 @@ require File.expand_path(File.dirname(__FILE__) + '/../spec/spec_helper')
 class User
   include OxMlk
   
-  ox_tag :user
+  ox_tag :downcase
   
   ox_elem :id, :as => Integer
   ox_elem :name
@@ -20,7 +20,7 @@ end
 class Status
   include OxMlk
   
-  ox_tag :status
+  ox_tag :downcase
      
   ox_elem :id, :as => Integer
   ox_elem :text
@@ -36,7 +36,7 @@ end
 class Response
   include OxMlk
   
-  ox_tag 'statuses'
+  ox_tag :statuses
   
   ox_elem :statuses, :as => [Status]
 end

data/examples/xml/phrk.xml

@@ -5,11 +5,10 @@
     <Say>Robinson</Say>
     <Play>http://foo.com/cowbell.mp3</Play>
   </Gather>
-  <Record action="http://foo.edu/handleRecording.php" method="GET" maxLength="20" finishOnKey="123*"/>
-  <Say voice="man" loop="4" language="en">Josh</Say>
+  <Record action="http://foo.edu/handleRecording" method="GET" maxLength="20" finishOnKey="123*"/>
+  <Say voice="man" loop="4" language="en">AHHHHHH</Say>
   <Redirect>http://www.foo.com/nextInstructions</Redirect>
   <Pause length="10"/>
-  <Hangup/>
   <Dial callerid="1234567">
     <Number sendDigits="ww3">344444</Number>
   </Dial>
@@ -29,4 +28,5 @@
       <Tag>closed</Tag>
     </NoMatch>
   </Rule>
+  <Hangup/>
 </Response>

data/lib/oxmlk/attr.rb

@@ -1,5 +1,9 @@
 module OxMlk
   class Attr
+    
+    attr_reader :accessor, :setter,:from, :as, :procs, :tag_proc, :tag
+    
+    # Named Procs for use in :as option.
     PROCS = (Hash.new {|h,k| k.to_proc rescue nil}).merge(
       Integer => :to_i.to_proc,
       Float => :to_f.to_proc,
@@ -7,8 +11,28 @@ module OxMlk
       Symbol => :to_sym.to_proc,
       :bool => proc {|a| fetch_bool(a)})
     
-    attr_reader :accessor, :setter,:from, :as, :procs, :tag_proc, :tag
-    
+    # Creates a new instance of Attr to be used as a template for converting
+    # XML to objects and from objects to XML
+    # @param [Symbol,String] name Sets the accessor methods for this attr.
+    #   It is also used to guess defaults for :from and :as.
+    #   For example if it ends with '?' and :as isn't set
+    #   it will treat it as a boolean.
+    # @param [Hash] o the options for the new attr definition
+    # @option o [Symbol,String] :from (tag_proc.call(name))
+    #   Tells OxMlk what the name of the XML attribute is.
+    #   It defaults to name processed by the tag_proc. 
+    # @option o [Symbol,String,Proc,Array<Symbol,String,Proc>] :as
+    #   Tells OxMlk how to translate the XML.
+    #   The argument is coerced into a Proc and applied to the string found in the XML attribute.
+    #   If an Array is passed each Proc is applied in order with the results
+    #   of the first being passed to the second and so on. If it isn't set
+    #   and name ends in '?' it processes it as if :bool was passed otherwise
+    #   it treats it as a string with no processing.
+    #   Includes the following named Procs: Integer, Float, String, Symbol and :bool.
+    # @option o [Proc] :tag_proc (proc {|x| x}) Proc used to guess :from.
+    #   The Proc is applied to name and the results used to find the XML attribute
+    #   if :from isn't set.
+    # @yield [String] Adds anothe Proc that is applied to the value.
     def initialize(name,o={},&block)
       name = name.to_s
       @accessor = name.chomp('?').intern
@@ -20,10 +44,18 @@ module OxMlk
       @procs = ([*as].map {|k| PROCS[k]} + [block]).compact
     end
     
+  private
+    
+    # Finds @tag in data and applies procs.
     def from_xml(data)
       procs.inject(XML::Node.from(data)[tag]) {|d,p| p.call(d) rescue d}
     end
     
+    # Converts a value to a Boolean.
+    # @param [Symbol,String,Integer] value Value to convert
+    # @return [Boolean] Returns true if value is 'true', 'yes', 't' or 1.
+    #   Returns false if value is 'false', 'no', 'f' or 0.
+    #   If can't be convertet to a Boolean then the value is returned.
     def self.fetch_bool(value)
       value = value.to_s.downcase
       return true if %w{true yes 1 t}.include? value

data/lib/oxmlk.rb

@@ -8,7 +8,11 @@ require File.join(dir, 'oxmlk/xml')
 require File.join(dir, 'oxmlk/attr')
 require File.join(dir, 'oxmlk/elem')
 
+# Mixin to add annotation methods to you ruby classes.
+# See {ClassMethods#ox_tag ox_tag}, {ClassMethods#ox_attr ox_attr} and {ClassMethods#ox_elem ox_elem} for available annotations.
 module OxMlk
+
+private
   
   def self.included(base)
     base.class_eval do
@@ -21,26 +25,359 @@ module OxMlk
   end
   
   module InstanceMethods
+    
+    # Returns a LibXML::XML::Node representing this object
     def to_xml
       self.class.to_xml(self)
     end
   end
   
+  # This class defines the annotation methods that are mixed into your Ruby classes for XML mapping information and behavior.
+  # See {ClassMethods#ox_tag ox_tag}, {ClassMethods#ox_attr ox_attr} and {ClassMethods#ox_elem ox_elem} for available annotations.
   module ClassMethods
     attr_accessor :ox_attrs, :ox_elems, :tag_proc
     
-    def ox_attr(name,o={})
-      new_attr =  Attr.new(name, o.reverse_merge(:tag_proc => @tag_proc))
+    # Declares a reference to a certain xml attribute.
+    #
+    # == Sym Option
+    # [sym] Symbol representing the name of the accessor
+    #
+    # === Default naming
+    # This is what it will use to lookup the attribute if a name isn't defined in :from. For example:
+    #
+    #  ox_attr :bob
+    #  ox_attr :pony
+    #
+    # are equivalent to:
+    #
+    #  ox_attr :bob, :from => 'bob'
+    #  ox_attr :pony, :from => 'pony'
+    #
+    # === Boolean attributes
+    # If the name ends in a ?, OxMlk will attempt to coerce the value to true or false,
+    # with true, yes, t and 1 mapping to true and false, no, f and 0 mapping
+    # to false, as shown below:
+    #
+    #  ox_elem :desirable?
+    #  ox_attr :bizzare?, :from => 'BIZZARE'
+    #
+    #  x = #from_xml(%{
+    #    <object BIZZARE="1">
+    #      <desirable>False</desirable>
+    #    </object>
+    #  })
+    #
+    #  x.desirable?
+    #  => false
+    #  x.bizzare?
+    #  => true
+    #
+    # When a block is provided the value will be passed to the block 
+    # where unexpected values can be handled. If no block is provided
+    # the unexpected value will be returned.
+    #
+    #  #from_xml(%{
+    #    <object BIZZARE="Dunno"\>
+    #  }).desirable?
+    #  => "Dunno"
+    #
+    #  ox_attr :bizzare? do |val|
+    #    val.upcase
+    #  end
+    #
+    #  #from_xml(%{
+    #    <object BIZZARE="Dunno"\>
+    #  }).strange?
+    #  => "DUNNO"
+    #
+    # == Blocks
+    # You may also pass a block which manipulates the associated parsed value.
+    #
+    #  class Muffins
+    #    include OxMlk
+    #
+    #    ox_attr(:count, :from => 'bakers_dozens') {|val| val.to_i * 13 }
+    #  end
+    #
+    # Blocks are always passed the value after being manipulated by the :as option 
+    # and are the last thing to manipulate the XML. This is different than the 
+    # ox_elem annotation that is passed an Array.
+    #
+    # == Options
+    # === :as
+    # ==== Basic Types
+    # Allows you to specify one of several basic types to return the value as. For example
+    #
+    #  ox_elem :count, :as => Integer
+    #
+    # is equivalent to:
+    #
+    #  ox_elem(:count) {|val| Integer(val) unless val.empty?}
+    #
+    # Such block shorthands for Integer, Float, String, Symbol and Time
+    # are currently available.
+    #
+    # If an Array is passed each Type in the array will be applied to the value in order.
+    #
+    # === :from
+    # The name by which the xml value will be found in XML. Default is sym.
+    def ox_attr(name,o={},&block)
+      new_attr =  Attr.new(name, o.reverse_merge(:tag_proc => @tag_proc),&block)
       @ox_attrs << new_attr
       attr_accessor new_attr.accessor
     end
     
-    def ox_elem(name,o={})
-      new_elem =  Elem.new(name, o.reverse_merge(:tag_proc => @tag_proc))
+    # Declares a reference to a certain xml element or a typed collection of elements.
+    #
+    # == Sym Option
+    # [sym] Symbol representing the name of the accessor.
+    #
+    # === Default naming
+    # This name will be the default node searched for, if no other is declared. For example:
+    #
+    #  ox_elem :bob
+    #  ox_elem :pony
+    #
+    # are equivalent to:
+    #
+    #  ox_elem :bob, :from => 'bob'
+    #  ox_elem :pony, :from => 'pony'
+    #
+    # === Boolean attributes
+    # If the name ends in a ?, OxMlk will attempt to coerce the value to true or false,
+    # with true, yes, t and 1 mapping to true and false, no, f and 0 mapping
+    # to false, as shown below:
+    #
+    #  ox_elem :desirable?
+    #  ox_attr :bizzare?, :from => 'BIZZARE'
+    #
+    #  x = #from_xml(%{
+    #    <object BIZZARE="1">
+    #      <desirable>False</desirable>
+    #    </object>
+    #  })
+    #
+    #  x.desirable?
+    #  => false
+    #  x.bizzare?
+    #  => true
+    #
+    # When a block is provided the value will be passed to the block 
+    # where unexpected values can be handled. If no block is provided
+    # the unexpected value will be returned.
+    #
+    #  #from_xml(%{
+    #    <object>
+    #      <desirable>Dunno</desirable>
+    #    </object>
+    #  }).desirable?
+    #  => "Dunno"
+    #
+    #  ox_elem :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 OxMlk
+    #
+    #    ox_elem(:count, :from => 'bakers_dozens') {|val| val.first.to_i * 13 }
+    #  end
+    #
+    # Blocks are always passed an Array and are the last thing to manipulate the XML.
+    # The array will include all elements already manipulated by anything passed to
+    # the :as option. If the :as option is an Array and no block is passed then the 
+    # Array is returned unmodified. If the :as option is nil or is not an Array then 
+    # only the first element is returned.
+    #
+    # == Options
+    # === :as
+    # ==== Basic Types
+    # Allows you to specify one of several basic types to return the value as. For example
+    #
+    #  ox_elem :count, :as => Integer
+    #
+    # is equivalent to:
+    #
+    #  ox_elem(:count) {|val| Integer(val.first) unless val.first.empty?}
+    #
+    # Such block shorthands for Integer, Float, String, Symbol and Time
+    # are currently available.
+    #
+    # To reference many elements, put the desired type in a literal array. e.g.:
+    #
+    #   ox_elem :counts, :as => [Integer]
+    #
+    # Even an array of text nodes can be specified with :as => []
+    #
+    #   ox_elem :quotes, :as => []
+    #
+    # === Other OxMlk Classes
+    # Declares an accessor that represents another OxMlk 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. You can also put several OxMlk classes in an Array that
+    # will act like a polymorphic one-to-many association.
+    #
+    # Composition example:
+    #  <book>
+    #   <publisher>
+    #     <name>Pragmatic Bookshelf</name>
+    #   </publisher>
+    #  </book>
+    #
+    # Can be mapped using the following code:
+    #   class Book
+    #     include OxMlk
+    #     ox_elem :publisher, :as => Publisher
+    #   end
+    #
+    # Aggregation example:
+    #  <library>
+    #   <books>
+    #    <book/>
+    #    <book/>
+    #   </books>
+    #  </library>
+    #
+    # Can be mapped using the following code:
+    #   class Library
+    #     include OxMlk
+    #     ox_elem :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:
+    #    ox_elem :books, :as => [Book]
+    #
+    # ==== Hash
+    # Unlike ROXML, OxMlk doesn't do anything special for hashes. However OxMlk
+    # applies :as to each element and the block once to the Array of elements.
+    # This means OxMlk can support setting hashes but it is more of a manual process.
+    # I am looking for a easier method but for now here are a few examples:
+    #
+    # ===== Hash of element contents
+    # For xml such as this:
+    #
+    #    <dictionary>
+    #      <definition>
+    #        <word/>
+    #        <meaning/>
+    #      </definition>
+    #      <definition>
+    #        <word/>
+    #        <meaning/>
+    #      </definition>
+    #    </dictionary>
+    #
+    # This is actually one of the more complex ones. It uses the :raw keyword to pass the block an array of LibXML::XML::Nodes
+    #   ox_elem(:definitions, :from => 'definition', :as => [:raw]) do |vals|
+    #     Hash[*vals.map {}|val| [val.search('word').content,val.search('meaning').content]}.flatten]
+    #   end
+    #
+    # ===== Hash of :content
+    # 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>
+    #
+    # This one can also be accomplished with the :raw keyword and a fancy block.
+    #   ox_elem(:definitions, :from => 'definition', :as => [:raw]) {|x| Hash[*x.map {|val| [val['word'],val.content] }.flatten]}
+    #
+    # ===== Hash of :name
+    # 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>
+    #
+    # This one requires some fancy xpath in :from to grab all the elements
+    #    ox_elem(:definitions, :from => './*', :as => [:raw]) {|x| Hash[*x.map {|val| [val.name,val.content] }.flatten]}
+    #
+    # === :from
+    # The name by which the xml value will be found in XML. Default is sym.
+    #
+    # 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
+    #    ox_elem :name, :from => :content
+    #    ox_attr :role
+    #  end
+    #
+    # To map:
+    #  <contributor role="editor">James Wick</contributor>
+    #
+    # === :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 '/'
+    def ox_elem(name,o={},&block)
+      new_elem =  Elem.new(name, o.reverse_merge(:tag_proc => @tag_proc),&block)
       @ox_elems << new_elem
       attr_accessor new_elem.accessor
     end
     
+    # Sets the name of the XML element that represents this class. Use this
+    # to override the default camelcase class name.
+    #
+    # Example:
+    #  class BookWithPublisher
+    #   ox_tag 'book'
+    #  end
+    #
+    # Without the ox_tag annotation, the XML mapped tag would have been 'BookWithPublisher'.
+    #
+    # Most xml documents have a consistent naming convention, for example, the node and
+    # and attribute names might appear in CamelCase. ox_tag enables you to adapt
+    # the oxmlk default names for this object to suit this convention.  For example,
+    # if I had a document like so:
+    #
+    #  <XmlDoc>
+    #    <MyPreciousData />
+    #    <MoreToSee />
+    #  </XmlDoc>
+    #
+    # Then I could access it's contents by defining the following class:
+    #
+    #  class XmlDoc
+    #    include OxMlk
+    #
+    #    ox_tag :camelcase
+    #    ox_elem :my_precious_data
+    #    ox_elem :more_to_see
+    #  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:
+    #
+    #  ox_tag :upcase
+    #  ox_tag &:camelcase
+    #  ox_tag {|val| val.gsub('_', '').downcase }
+    #
+    # See ActiveSupport::CoreExtensions::String::Inflections for more prepackaged formats
     def ox_tag(tag=nil,&block)
       raise 'you can only set tag or a block, not both.' if tag && block
 
@@ -56,10 +393,16 @@ module OxMlk
       end
     end
     
+    # Used to tell if this is an OxMlk Object.
     def ox?
       true
     end
     
+    # Returns a new instance from XML
+    # @param [XML::Document,XML::Node,File,Pathname,URI,String] data
+    #   The xml data used to create a new instance.
+    # @return New instance generated from xml data passed in.
+    #   Attr and Elem definitions are used to translate the xml to new object.
     def from_xml(data)
       xml = XML::Node.from(data)
       raise 'invalid XML' unless xml.name == ox_tag
@@ -69,6 +412,9 @@ module OxMlk
       ox
     end
     
+    # Returns XML generated from an instance based on Attr & Elem definitions.
+    # @param [Object] data An instance used to populate XML
+    # @return [XML::Node] Generated XML::Node  
     def to_xml(data)
       ox = XML::Node.new(ox_tag)
       ox_elems.each do |elem|
@@ -80,10 +426,6 @@ module OxMlk
       end
       ox
     end
-    
-    def xml_convention(converter=nil)
-      @xml_convention = converter
-    end
   end
   
 end

data/oxmlk.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{oxmlk}
-  s.version = "0.3.2"
+  s.version = "0.3.3"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Josh Robinson"]
-  s.date = %q{2009-09-03}
+  s.date = %q{2009-09-08}
   s.description = %q{OxMlk gives you a simple way to map you ruby objects to XML and then convert one to the other.}
   s.email = %q{hexorx@gmail.com}
   s.extra_rdoc_files = [
@@ -24,6 +24,7 @@ Gem::Specification.new do |s|
      "VERSION",
      "examples/amazon.rb",
      "examples/example.rb",
+     "examples/phrk.rb",
      "examples/posts.rb",
      "examples/twitter.rb",
      "examples/xml/amazon.xml",
@@ -57,6 +58,7 @@ Gem::Specification.new do |s|
      "spec/xml_spec.rb",
      "examples/amazon.rb",
      "examples/example.rb",
+     "examples/phrk.rb",
      "examples/posts.rb",
      "examples/twitter.rb"
   ]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: oxmlk
 version: !ruby/object:Gem::Version 
-  version: 0.3.2
+  version: 0.3.3
 platform: ruby
 authors: 
 - Josh Robinson
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-09-03 00:00:00 -06:00
+date: 2009-09-08 00:00:00 -06:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -59,6 +59,7 @@ files:
 - VERSION
 - examples/amazon.rb
 - examples/example.rb
+- examples/phrk.rb
 - examples/posts.rb
 - examples/twitter.rb
 - examples/xml/amazon.xml
@@ -114,5 +115,6 @@ test_files:
 - spec/xml_spec.rb
 - examples/amazon.rb
 - examples/example.rb
+- examples/phrk.rb
 - examples/posts.rb
 - examples/twitter.rb