Empact-roxml 2.4.3 → 2.5.1

data/History.txt

@@ -1,3 +1,68 @@
+== 2.5.1 (March 2, 2009)
+
+* minor enhancements
+
+   * Add Document#save to REXML support, complete with XMLDecl output
+
+* bug fixes
+
+   * rexml support has been fixed
+   * the first example in the readme was broken and has been fixed
+
+== 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,14 @@ README.rdoc
 Rakefile
 TODO
 config/website.yml
+examples/active_record.rb
 examples/amazon.rb
 examples/current_weather.rb
 examples/dashed_elements.rb
+examples/library.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 +34,20 @@ 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/library_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 +85,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,36 +14,36 @@ ROXML, you can annotate the Ruby classes as follows:
   class Book
     include ROXML
 
-    xml_reader :isbn, :attr => "ISBN" # attribute with name 'ISBN'
-    xml_reader :title
-    xml_reader :description, :as => :cdata  # text node with cdata protection
-    xml_reader :author
+    xml_accessor :isbn, :from => "@ISBN" # attribute with name 'ISBN'
+    xml_accessor :title
+    xml_accessor :description, :cdata => true  # text node with cdata protection
+    xml_accessor :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] # by default roxml searches for books for in <book> child nodes, then, if none are present, in ./books/book children
   end
 
 To create a library and put a number of books in it we could run the following code:
 
-  book = Book.new()
+  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 = Library.new
   lib.name = "Favorite Books"
-  lib << book
+  lib.books = [book]
 
 To save this information to an XML file:
 
-  File.open("library.xml", "w") do |f|
-    lib.to_xml.write(f, 0)
-  end
+  doc = ROXML::XML::Document.new
+  doc.root = lib.to_xml
+  doc.save("library.xml")
 
 To later populate the library object from the XML file:
 
@@ -62,11 +62,22 @@ you would add a reference to another ROXML class. For example:
 
 can be mapped using the following code:
 
+  class Publisher
+    include ROXML
+
+    xml_accessor :name
+
+    # other important functionality
+  end
+
   class BookWithPublisher
     include ROXML
 
-    xml_name :book
-    xml_reader :publisher, Publisher
+    xml_name 'book'
+    xml_reader :publisher, :as => Publisher
+
+    #  or, alternatively, if no class is needed to hang functionality on:
+    # xml_reader :publisher, :from => 'name', :in => 'publisher'
   end
 
 Note: In the above example, _xml_name_ annotation tells ROXML to set the element
@@ -78,34 +89,45 @@ 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 life-cycle is as follows: .from_xml is called with a first argument representing the xml
+in file, string, or path form, and with optional initialization_args following.
+
+Firt .new and thus #initialize, is called with those same initialization_args, or no args if none
+are present.  Then the object is populated with the attribute values from xml.  Then the
+#after_parse callback is called, with no arguments.
+
+In #after_parse 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,10 +16,13 @@ $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}"]
+    ['newgem', ">= #{::Newgem::VERSION}"],
+    ['sqlite3-ruby', '>= 1.2.4' ],
+    ['activerecord', '>= 2.2.2' ]
   ]
 
   p.summary = "Ruby Object to XML mapping library"

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,70 @@
+#!/usr/bin/env ruby
+require File.expand_path(File.dirname(__FILE__) + '/../spec/spec_helper')
+require 'sqlite3'
+require 'activerecord'
+
+DB_PATH = File.join(File.dirname(__FILE__), 'active_record.sqlite3')
+ActiveRecord::Base.establish_connection(
+  :adapter  => 'sqlite3',
+  :database => DB_PATH
+)
+
+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/library.rb

@@ -0,0 +1,40 @@
+class Publisher
+  include ROXML
+
+  xml_accessor :name
+  
+  def initialize(name = nil)
+    @name = name
+  end
+  
+  def ==(other)
+    name == other.name
+  end
+  
+  # other important functionality
+end
+
+class Novel
+  include ROXML
+
+  xml_accessor :isbn, :from => "@ISBN" # attribute with name 'ISBN'
+  xml_accessor :title
+  xml_accessor :description, :cdata => true  # text node with cdata protection
+  xml_accessor :author
+  xml_accessor :publisher, :as => Publisher # singular object reference for illustrative purposes.
+  
+  def ==(other)
+    self.class.roxml_attrs.map(&:accessor).all? {|attr| send(attr) == other.send(attr) }
+  end
+end
+
+class Library
+  include ROXML
+
+  xml_accessor :name, :from => "NAME", :cdata => true
+  xml_accessor :novels, :as => [Novel] # by default roxml searches for books for in <novel> children, then, if none are present, in ./novels/novel children
+  
+  def ==(other)
+    name == other.name && novels == other.novels
+  end
+end