roxml 2.4.3 → 2.5.0

data/History.txt

@@ -1,3 +1,57 @@
+== 2.5.0 (February 24, 2009)
+
+* major enhancements
+
+   * support for mapping ActiveRecord classes.  See examples/active_record.rb.
+   * .from_xml will now use the setter for the declared variable, if one is available,
+     rather than directly setting the instance variable
+   * All declaration type arguments are now supported via the :as parameter, e.g. :as => [MyType].  Other uses are deprecated.
+   * All xml source path arguments are now supported via the :from and :in parameters, e.g. :from => :attr or :from => '@MyAttr'.  Other uses are deprecated.
+   * All other options are presented separately, e.g. :cdata => true rather than :as => :cdata.  Other uses are deprecated.
+
+* minor enhancements
+
+   * .xml_attr declaration declares neither a reader nor a writer.  With it you're left to your own devices.
+   * You can use literal [] for the [:text] object type declaration,
+    though they should be used in the :as parameter: :as => []
+   * You can use [] with your :as declarations. e.g. :as => [Float] is
+     equivalent to the old :as => [Float, :array]
+   * Show the actual call point of a deprecation, rather than some internal path
+   * Add support for BigDecimal and Fixnum as block shorthands [James Healy]
+   * Update libxml support to 0.9.6, and add it as a dependency, to ensure correct versioning, and
+     as it's an order of magnitude faster than rexml
+
+* breaking changes
+
+   * :else option only applies to instances created via .from_xml
+   * On .from_xml, #initialize is now called with the *initialization_args before extracting attributes from the xml.
+   * #xml_initialize has been replaced with the #after_parse callback, which takes no arguments.
+   * .xml_accessor will overwrite the setter for this variable if it has already been defined.  Use .xml_reader or .xml_attr,
+     or define your writer later, if this is not the behavior you want.
+
+* deprecations
+
+  * Use :cdata => true rather than :as => :cdata
+  * Use literal [] around your regular object type, rather than :as => :array
+  * Use :from => :content rather than the :content object declaration type
+  * Specifying an unknown symbol or Class for :as will raise in 3.0
+  * Specifying :as with anything other than a type argument e.g. :bool, Float, [Date],
+    will not be supported in 3.0
+  * Use :from => :attr or :from => '@attribute_name' rather than the :attr
+    object declaration type
+  * Passing any type declaration outside the :as parameter is deprecated
+  * In 3.0, attributes ending in _on and _at will default to :as => Date and DateTime, respectively,
+    rather than :text
+  * Deprecated hash :attrs declaration syntax in favor of {:key => '@attr1', :value => '@attr2'}
+  * Deprecated hash {Type => 'name'} declaration syntax in favor of {:as => Type, :from => 'name}
+  * Deprecated String#to_utf and #to_latin.
+
+* bug fixes
+
+   * xml_accessor now properly handles punctuation, such that the writer appears without '?' for boolean attributes
+   * text node contents are no longer truncated when '&' are present in the contents
+   * When using :as => Integer or Float, don't raise on missing element [James Healy]
+
 == 2.4.3 (February 1, 2009)
 
 * 1 bug fix

data/Manifest.txt

@@ -5,11 +5,13 @@ README.rdoc
 Rakefile
 TODO
 config/website.yml
+examples/active_record.rb
 examples/amazon.rb
 examples/current_weather.rb
 examples/dashed_elements.rb
 examples/posts.rb
 examples/twitter.rb
+examples/xml/active_record.xml
 examples/xml/amazon.xml
 examples/xml/current_weather.xml
 examples/xml/dashed_elements.xml
@@ -31,13 +33,19 @@ lib/roxml/xml/parsers/libxml.rb
 lib/roxml/xml/parsers/rexml.rb
 lib/roxml/xml/references.rb
 roxml.gemspec
+spec/definition_spec.rb
+spec/examples/active_record_spec.rb
 spec/examples/amazon_spec.rb
 spec/examples/current_weather_spec.rb
 spec/examples/dashed_elements_spec.rb
 spec/examples/post_spec.rb
 spec/examples/twitter_spec.rb
+spec/roxml_spec.rb
+spec/shared_specs.rb
 spec/spec.opts
 spec/spec_helper.rb
+spec/string_spec.rb
+spec/xml/parser_spec.rb
 tasks/rspec.rake
 tasks/test.rake
 test/bugs/rexml_bugs.rb
@@ -75,13 +83,8 @@ test/mocks/dictionaries.rb
 test/mocks/mocks.rb
 test/release/dependencies_test.rb
 test/test_helper.rb
-test/unit/array_test.rb
 test/unit/definition_test.rb
-test/unit/freeze_test.rb
-test/unit/inheritance_test.rb
-test/unit/overriden_output_test.rb
-test/unit/roxml_test.rb
-test/unit/string_test.rb
+test/unit/deprecations_test.rb
 test/unit/to_xml_test.rb
 test/unit/xml_attribute_test.rb
 test/unit/xml_block_test.rb

data/README.rdoc

@@ -14,17 +14,17 @@ ROXML, you can annotate the Ruby classes as follows:
   class Book
     include ROXML
 
-    xml_reader :isbn, :attr => "ISBN" # attribute with name 'ISBN'
+    xml_reader :isbn, :from => "@ISBN" # attribute with name 'ISBN'
     xml_reader :title
-    xml_reader :description, :as => :cdata  # text node with cdata protection
+    xml_reader :description, :cdata => true  # text node with cdata protection
     xml_reader :author
   end
 
   class Library
     include ROXML
 
-    xml_accessor :name, :from => "NAME", :as => :cdata
-    xml_accessor :books, [Book], :in => "books"
+    xml_accessor :name, :from => "NAME", :cdata => true
+    xml_accessor :books, :as => [Book]
   end
 
 To create a library and put a number of books in it we could run the following code:
@@ -66,7 +66,7 @@ can be mapped using the following code:
     include ROXML
 
     xml_name :book
-    xml_reader :publisher, Publisher
+    xml_reader :publisher, :as => Publisher
   end
 
 Note: In the above example, _xml_name_ annotation tells ROXML to set the element
@@ -78,34 +78,41 @@ in this case.
 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 Child
+  class Dog
     include ROXML
 
-    xml_reader :age, :attr do |val|
-      Integer(val)
-    end
+    xml_reader(: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.
 
 == Construction
 
-Complicated initialization may require action on multiple attributes of an object.  As such, you can
-define method xml_initialize to perform initialization after instantiation and parsing, including
-causing your ROXML object to call its own constructor, as in the following:
+Object lifecycle is as follows: .from_xml is called with option initialization_args.  .new,
+and thus #initialize, is called with those same args.  Then the object is populated
+with the attribute values from xml.  Then the #after_parse callback is called, with no arguments.
+In it you can ensure that your object initialization is complete, including initialization which
+requires more than one variable in concert.
+
+E.g.:
 
   class Measurement
     include ROXML
 
-    xml_reader :units, :attr
-    xml_reader :value, :content
+    xml_reader :units, :from => :attr
+    xml_reader :value, :from => :content
+
+    def initialize(value = 0, units = 'meters')
+      to_metric
+    end
 
-    def xml_initialize
+  private
+    def after_parse
       # xml attributes of self are already valid
-      initialize(value, units)
+      to_metric
     end
 
-    def initialize(value, units)
+    def to_metric
       # translate units & value into metric, for example
     end
   end

data/Rakefile

@@ -16,7 +16,8 @@ $hoe = Hoe.new('roxml', ROXML::VERSION) do |p|
   p.changes              = File.read("History.txt").split(/^==/)[1].strip
   p.rubyforge_name       = p.name
   p.extra_deps         = [
-   ['activesupport','>= 2.1.0']
+   ['activesupport','>= 2.1.0'],
+   ['libxml-ruby', '>= 0.8.6']
   ]
   p.extra_dev_deps = [
     ['newgem', ">= #{::Newgem::VERSION}"]

data/TODO

@@ -1,37 +1,10 @@
 Planned:
 
-v 2.5
- * Test out compatibility with ActiveRecord such that it's easy
-   to have both xml & database-sourced objects
-
- * provide an overridable extension point for the #to_xml-ing of
-   values.  This would enable easy accommodation of non-standard formats.
-   For example, formatting a number with leading zeros.
-
- * Ensure (perhaps optionally) that references are unambiguous. That is error/warn
-   a singular specification has multiple possible node references
-
- * Automatically use Date or DateTime for accessors ending in '_on' and '_at', respectively
-
- * Add xml_in helper to share :in declarations between several attributes. E.g.:
-
-     xml_reader :count, :in => 'Attributes', :as => Integer
-     xml_reader :something_else, :in => 'Attributes', :as => Date
-
-  becomes:
-
-    xml_in 'Attributes' do |xml|
-      xml.reader  :count, :as => Integer
-      xml.reader  :something_else, :as => Date
-    end
-
- * :self => true for sending method_missing to this attribute?
-
- * :attributes extensions ala HappyMapper?
-
 v 3.0
  * remove deprecated functionality
 
+ * Automatically use Date or DateTime for accessors ending in '_on' and '_at', respectively
+
  * Clarify API via seperation of concerns.  :as for Type, :from and :in for location,
    All other options as named options, e.g. :cdata => true rather than :as => :cdata.
    A few not so great examples...:
@@ -52,12 +25,38 @@ v 3.0
 
      xml_reader :count, :size, :number, :as => Integer, :from => :attr
 
+ * Consider class_inheritable_attribute rather than superclass.try stuff.
+
+ * Do some benchmarking
+
+v 3.1
+
+ * Back with http://xml-object.rubyforge.org/doc/ to minimize need for specifications?
+
  * Commandeer #parse to use opposite #from_xml, but in an unrooted, collection-friendly fashion,
    ala HappyMapper's parse
 
- * Back with http://xml-object.rubyforge.org/doc/ to minimize need for specifications?
+v 3.x
+
+ * :self => true for sending method_missing to this attribute?
+
+ * :attributes extensions ala HappyMapper?
+
+ * Add xml_attrs helper to share :in declarations between several attributes. E.g.:
+
+     xml_reader :count, :in => 'Attributes', :as => Integer
+     xml_reader :something_else, :in => 'Attributes', :as => Date
+
+  becomes:
+
+    xml_attrs :in => 'Attributes' do |xml|
+      xml.reader  :count, :as => Integer
+      xml.reader  :something_else, :as => Date
+    end
+
+ * Ensure (perhaps optionally) that references are unambiguous. That is error/warn
+   a singular specification has multiple possible node references
 
  * Use lazy evaluation to minimize parsing time for large files
 
- * Consider class_inheritable_attribute rather than superclass.try stuff.
 

data/examples/active_record.rb

@@ -0,0 +1,69 @@
+#!/usr/bin/env ruby
+require File.expand_path(File.dirname(__FILE__) + '/../spec/spec_helper')
+require 'sqlite3'
+require 'activerecord'
+
+ActiveRecord::Base.establish_connection(
+  :adapter  => 'sqlite3',
+  :database => "examples/active_record/active_record.sqlite3"
+)
+
+class Waypoint < ActiveRecord::Base
+  include ROXML
+
+  belongs_to :route
+
+  xml_attr :isLeg
+  xml_attr :lonlatx
+  xml_attr :lonlaty
+  xml_attr :gridReference
+  xml_attr :ascent
+  xml_attr :descent
+  xml_attr :distance
+  xml_attr :bearing
+  xml_attr :timemins
+end
+
+class Route < ActiveRecord::Base
+  include ROXML
+
+  has_many :waypoints
+
+  xml_attr :title
+  xml_attr :totalDist
+  xml_attr :totalMins
+  xml_attr :totalHg
+  xml_attr :lonlatx
+  xml_attr :lonlaty
+  xml_attr :grcenter
+
+  xml_attr :waypoints, :as => [Waypoint], :in => "waypoints"
+end
+
+# do a quick pseudo migration.  This should only get executed on the first run
+if !Waypoint.table_exists?
+  ActiveRecord::Base.connection.create_table(:waypoints) do |t|
+    t.column :route_id, :integer
+    t.column :isLeg, :string
+    t.column :lonlatx, :string
+    t.column :lonlaty, :string
+    t.column :gridReference, :string
+    t.column :ascent, :string
+    t.column :descent, :string
+    t.column :distance, :string
+    t.column :bearing, :string
+    t.column :timeMins, :string
+  end
+end
+
+if !Route.table_exists?
+  ActiveRecord::Base.connection.create_table(:routes) do |t|
+    t.column :title, :string
+    t.column :totalDist, :string
+    t.column :totalMins, :string
+    t.column :totalHg, :string
+    t.column :lonlatx, :string
+    t.column :lonlaty, :string
+    t.column :grcenter, :string
+  end
+end

data/examples/amazon.rb

@@ -21,7 +21,7 @@ module PITA
   class ItemSearchResponse < Base
     xml_reader :total_results, :as => Integer, :in => 'Items'
     xml_reader :total_pages, :as => Integer, :in => 'Items'
-    xml_reader :items, [Item]
+    xml_reader :items, :as => [Item]
   end
 end
 

data/examples/current_weather.rb

@@ -15,7 +15,7 @@ class WeatherObservation < Base
 end
 
 class Weather < Base
-  xml_reader :observation, WeatherObservation, :required => true
+  xml_reader :observation, :as => WeatherObservation, :required => true
 end
 
 unless defined?(Spec)

data/examples/posts.rb

@@ -4,19 +4,19 @@ require File.expand_path(File.dirname(__FILE__) + '/../spec/spec_helper')
 class Post
   include ROXML
   
-  xml_reader :href, :attr
-  xml_reader :hash, :attr
-  xml_reader :description, :attr
-  xml_reader :tag, :attr
-  xml_reader :time, :attr, :as => DateTime
-  xml_reader :others, :attr, :as => Integer
-  xml_reader :extended, :attr
+  xml_reader :href, :from => :attr
+  xml_reader :hash, :from => :attr
+  xml_reader :description, :from => :attr
+  xml_reader :tag, :from => :attr
+  xml_reader :time, :from => :attr, :as => DateTime
+  xml_reader :others, :from => :attr, :as => Integer
+  xml_reader :extended, :from => :attr
 end
 
 class Posts
   include ROXML
 
-  xml_reader :posts, [Post]
+  xml_reader :posts, :as => [Post]
 end
 
 unless defined?(Spec)

data/examples/twitter.rb

@@ -27,11 +27,11 @@ class Status
 	xml_reader :in_reply_to_status_id, :as => Integer
 	xml_reader :in_reply_to_user_id, :as => Integer
 	xml_reader :favorited?
-	xml_reader :user, User
+	xml_reader :user, :as => User
 end
 
 class Statuses
   include ROXML
 
-  xml_reader :statuses, [Status]
+  xml_reader :statuses, :as => [Status]
 end

data/examples/xml/active_record.xml

@@ -0,0 +1,70 @@
+<route>
+<totalDist>11185.321521477119</totalDist>
+<totalHg>640</totalHg>
+<totalMins>235.75000000000003</totalMins>
+<lonlatx>357865</lonlatx>
+<lonlaty>271635</lonlaty>
+<grcenter>SH 71635 57865</grcenter>
+<waypoints>
+     <waypoint>
+         <isLeg>false</isLeg>
+         <lonlatx>357290</lonlatx>
+         <lonlaty>271650</lonlaty>
+         <gridReference>SH 71650 57290</gridReference>
+         <ascent>81</ascent>
+         <descent>220</descent>
+         <distance>0</distance>
+         <bearing>0</bearing>
+     </waypoint>
+     <waypoint>
+         <isLeg>false</isLeg>
+         <lonlatx>357260</lonlatx>
+         <lonlaty>274600</lonlaty>
+         <gridReference>SH 74600 57260</gridReference>
+         <ascent>275</ascent>
+         <descent>48</descent>
+         <distance>2950.152538429157</distance>
+         <bearing>91</bearing>
+     </waypoint>
+     <waypoint>
+         <isLeg>false</isLeg>
+         <lonlatx>359160</lonlatx>
+         <lonlaty>273330</lonlaty>
+         <gridReference>SH 73330 59160</gridReference>
+         <ascent>73</ascent>
+         <descent>170</descent>
+         <distance>2285.3664913969487</distance>
+         <bearing>326</bearing>
+     </waypoint>
+     <waypoint>
+         <isLeg>false</isLeg>
+         <lonlatx>359170</lonlatx>
+         <lonlaty>270050</lonlaty>
+         <gridReference>SH 70050 59170</gridReference>
+         <ascent>182</ascent>
+         <descent>172</descent>
+         <distance>3280.015243867016</distance>
+         <bearing>270</bearing>
+     </waypoint>
+     <waypoint>
+         <isLeg>false</isLeg>
+         <lonlatx>357470</lonlatx>
+         <lonlaty>269740</lonlaty>
+         <gridReference>SH 69740 57470</gridReference>
+         <ascent>29</ascent>
+         <descent>107</descent>
+         <distance>1728.0335644888382</distance>
+         <bearing>190</bearing>
+     </waypoint>
+     <waypoint>
+         <isLeg>false</isLeg>
+         <lonlatx>356840</lonlatx>
+         <lonlaty>270440</lonlaty>
+         <gridReference>SH 70440 56840</gridReference>
+         <ascent>640</ascent>
+         <descent>717</descent>
+         <distance>941.7536832951597</distance>
+         <bearing>132</bearing>
+     </waypoint>
+</waypoints>
+</route>