ROXML 3.0.0

data/.gitignore

@@ -0,0 +1,6 @@
+spec/**/*.xml
+build
+doc
+Rake.config
+pkg
+.project

data/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "vendor/override_rake_task"]
+	path = vendor/override_rake_task
+	url = git://github.com/Empact/override_rake_task.git

data/History.txt

@@ -0,0 +1,299 @@
+== 3.1 (On Github)
+
+* major enhancements
+
+  * Add support for registering XML namespace prefixes via the xml_namespaces method
+
+* bug fix
+
+  * References to arrays of attributes were only returning the first.  No more.
+
+== 3.0 (October 14, 2009)
+
+* major enhancements
+
+  * Add Nokogiri support
+  * Remove previously deprecated functionality
+  * Remove REXML support
+  * Error on any unrecognized options
+  * Normalize hash declaration syntax:
+    * for :key => '@string', string is taken to be the :from argument
+    * for :key => {:from => '@string', :as => Type}, the arguments are just the same as a regular declaration
+
+* minor enhancements
+
+  * Include 't' and 'f' in the list of possible boolean values, since rails uses them
+  * Remove :attrs hash syntax.  Not particularly helpful & somewhat obfuscatory.  Use :key, :value instead.
+  * Default attrs ending in '_at' to DateTime.  This can be overriden via :as
+  * Default attrs ending in '_on' to Date.  This can be overriden via :as
+  * Don't require rubygems within the library
+  * Don't mess with the load path
+
+== 2.5.4 (October 4, 2009)
+
+* bug fix
+
+  * Rely on REXML's #add_child and LibXML's <<, rather than #child_add which had been removed from REXML and deprecated from LibXML
+
+== 2.5.3 (March 22, 2009)
+
+* minor enhancement
+
+  * Work around apparently unintentional breaking change in libxml-ruby 1.1.3
+
+== 2.5.2 (March 12, 2009)
+
+* minor enhancements
+
+  * Remove dependency on an Object#try which conflicted with ActiveSupport 2.3's version
+  * Document the :to_xml option for attr references
+  * Require active_support directly,  as it's less brittle and plays nicer with other libraries
+
+== 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/rails.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
+
+  * Fix roxml to work in ruby 1.8.6, which has been broken since the removal of
+    extensions in version 2.4.1.  Thanks Pat! [Pat Nakajima]
+
+== 2.4.2 (January 31, 2009)
+
+* 1 major enhancement
+
+  * xml_namespace for declaring Class-level, inheritable default namespaces.
+
+* 4 minor enhancements
+
+  * add :as => Time, DateTime, and Date support
+  * support Pathname, IO and URI objects as #from_xml arguments
+  * :as => :bool now supports all capitalizations of 'true', 'false', 'yes', 'no', as well as '1' and '0'
+  * For basic types (:as => Integer, Float, Date, &c.), interpret empty strings just
+    as missing elements (by returning nil), rather than raising.  Raise behavior can be
+    accessed by supplying your own block or using the :required option.
+
+ * 3 bug fixes
+
+  * Arrays of attrs or elements :as => :bool weren't previously supported.  An oversight.
+  * Don't apply xml_convention if name is explicitly set
+  * Protect xpath operators : and / from modification via String#camelcase & such
+
+== 2.4.1 (January 28, 2009)
+
+* 3 minor enhancements
+
+  * remove dependency on 'extensions' gem, as we weren't using it much and it
+    was causing problems for some
+  * deprecate the 'xml' declaration in favor of the more explicit 'xml_reference'
+    declaration.  Reorder params to make for cleaner 3.0 transition.
+  * deprecate '#tag_name' in favor of 'self.class.tag_name', as it's a class-specific value
+
+== 2.4.0 (January 15, 2009)
+
+* 1 major enhancement
+
+  * Add xml_convention to enable easy defaulting to common naming formats, such as camel-case and
+    underscored [Ben Woosley]
+
+* 6 minor enhancements
+
+  * Add :frozen option for freezing values on parse [Ben Woosley]
+  * Attempt to minimize node creation by better matching wrappers [Ben Woosley]
+  * Preserve hash values where a single key maps to multiple values, return them as an array rather
+    any single one of them at random (as in group_by rather than index_by) [Ben Woosley]
+  * Deprecate #xml_name? as it's only used for triggering the xml_name warning [Ben Woosley]
+  * REXML parser ignores whitespace, which doesn't matter to us anyway [Ben Woosley]
+  * xml_name is inherited by default [Ben Woosley]
+
+* 2 bug fixes
+
+  * Don't detect objects which define their own empty? as being absent for the purposes
+    of :default and :required [Ben Woosley]
+  * Sub-objects pick up their parent's attributes, even if they're added after
+    the child's use [Ben Woosley]
+
+== 2.3.2 (December 11, 2008)
+
+* Fix that both false and nil values were excluded from to_xml output, when only nil values should be [Ben Woosley]
+
+== 2.3.1 (December 9, 2008)
+
+* Add missing dependencies to extensions/enumerable and Symbol.to_proc,
+  which are as-yet inexplicably pre-included on my system... [Ben Woosley, Per Melin]
+
+== 2.3 (December 7, 2008)
+
+* Fix a bug in the application of blocks to array types [Ben Woosley]
+
+* Objects now inherit xml attributes from their parents, as they should [Ben Woosley, Per Melin]
+
+* Add #xml_initialize, which is called at the end of #from_xml, after the xml attributes
+  are set. Deprecate the half-baked xml_construct in it's favor. [Ben Woosley]
+
+* Fix a bug in the handling of empty Hash types [Ben Woosley]
+
+* Implement automatic bool-ification when the accessor name ends with ?. [Ben Woosley]
+
+* Add missing dependency ActiveSupport [Ben Woosley]
+
+* Remove support for installing as a rails plugin [Ben Woosley]
+
+* Fix a bug where xml_construct was using the refs' names rather than their accessor names for comparison [Ben Woosley]
+
+* Significantly reduce our footprint by selectively including smaller parts of ActiveSupport and Extensions.
+  This avoids problems such as the conflict between ActiveSupport's #to_json and the JSON gem's #to_json.
+  Thanks to Per Melin for reporting this problem. [Ben Woosley]
+
+* Rationalize sub-element xml naming by enforcing the following precedence for the containing xml of an object:
+  :from of parent, xml_name of child, parent's accessor name.  The previous fallback did not include xml_name.
+  This new behavior is more consistent, explicit, predictable, and DRY, but it is a breaking change, so a warning
+  is printed to alert others of this behavior change. ROXML::SILENCE_XML_NAME_WARNING may be used to deactivate this
+  warning. [Ben Woosley, James W. Thompson, Delynn Berry]
+
+== 2.2 (November 2, 2008)
+
+* fix gem dependencies [James Healy]
+
+* Add block shorthands for Float and Integer, which precede the block argume if present [Ben Woosley]
+
+* Add :required option to throw on absence [Ben Woosley]
+
+* Deprecate the non-specific #parse in favor of #from_xml [Ben Woosley]
+
+* Fix a bug whereby the default value was carrying over information from one object to another [James Healy, Ben Woosley]
+
+* Fix support for :in on :attr elements [Ben Woosley]
+
+* Deprecate Array#to_h in favor of Array#to_hash [Ben Woosley]
+
+* Deprecate Object#to_latin and Object#to_utf in favor of the same methods on String [Ben Woosley]
+
+== 2.1 (October 3, 2008)
+
+* rake test now uses the default parser selection [Ben Woosley]
+
+* Added rcov code coverage for tests [Anders Engström]
+
+* Accommodate that libxml requires you to name the default namespace when available [Ben Woosley]
+
+* Enable optional selection of a parser through the early definition of ROXML::XML_PARSER
+  [Ben Woosley]
+
+* Enable fallback to the REXML parser if LibXML is unavailable [Ben Woosley]
+
+== 2.0 (September 20, 2008)
+
+* :text_content becomes simply :content, and is joined by :name  [Ben Woosley]
+
+* Allow hash mapping from node names and contents: [Ben Woosley]
+
+  xml_reader :name, {:key => :name,
+                     :value => :content}, :in => 'container'
+
+* Allow supplying a default via the :else option [Ben Woosley]
+
+* Allow hash mapping of text and attr elements: [Ben Woosley]
+
+  xml_reader :name, {:key => {:text => 'key_name'},
+                     :value => {:attr => 'attr_name'}}, :in => 'container'
+
+* Allow 'xml_reader :name, [Type]' as an alternative to 'xml_reader :name, Type, :as => :array'
+  [Ben Woosley]
+
+* Allow attaching a block for manipulating a value on fetch: [Ben Woosley]
+
+  xml_accessor :count, :attr => 'my_int' do |val|
+    Integer(val)
+  end
+
+* Collapse xml_attr, xml_text and xml_object into a single api: xml, patterned after the standard
+  attr, and offer xml_reader and xml_accessor as well.  Remove the :readonly arg in the process
+  [Ben Woosley]
+
+* Attach string extensions (#to_latin, #to_utf) to Object rather than String, so we don't have to
+  call #to_s first every time [Ben Woosley]
+
+* Allow a ROXML object to call its constructor on initialization with the xml_construct function
+  [Ben Woosley]
+
+* Use symbols (e.g. :text_content) rather than TAG_CONSTANTS (e.g. TEXT_CONTENT) for readability
+  [Ben Woosley]
+
+* Use named arguments (e.g. :as, :in) rather than positional for clarity,
+  position-independence, and invisible exclusion [Ben Woosley]
+
+* Split out rails_plugin_package_task_gem [Ben Woosley]
+
+* Increase testing significantly, particularly on new functionality & to_xml [Ben Woosley]
+
+== 1.2 (October 10, 2007)
+
+* Fix a bug such that the TEXT_CONTENT tag is no longer also READ_ONLY [Russ Olsen]
+
+== 1.1 (September 24, 2006)
+
+* Initial design & development [Zak Mandhro & Anders Engstrom]

data/MIT-LICENSE

@@ -0,0 +1,18 @@
+The MIT License
+
+Copyright (c) 2004-2009 by Ben Woosley, Zak Mandhro and Anders Engstrom
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software
+and associated documentation files (the "Software"), to deal in the Software without restriction,
+including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,161 @@
+ROXML Ruby Object to XML mapping library.
+
+For more information visit:
+
+    http://roxml.rubyforge.org/rdoc/
+    http://empact.github.com/roxml/
+    http://rubyforge.org/projects/roxml/
+
+Please submit bugs here:
+
+    http://github.com/Empact/roxml/issues
+
+=Quick Start Guide
+
+This is a short usage example. See ROXML::ClassMethods::Declarations and packaged test cases for more information.
+
+==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
+ROXML, you can annotate the Ruby classes as follows:
+
+  class Book
+    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
+  end
+
+  class Library
+    include ROXML
+
+    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.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 ROXML
+
+    xml_accessor :name
+
+    # other important functionality
+  end
+
+  class BookWithPublisher
+    include ROXML
+
+    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
+name to "book" for mapping to XML. The default is XML element name is the class name in lowercase; "bookwithpublisher"
+in this case.
+
+=== Namespace Support
+
+Namespaces are supported via the xml_namespace declaration and the :from and :namespace attr options.  See spec/xml/namespace_spec.rb for usage.
+
+== 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 ROXML
+
+    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
+
+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, :from => :attr
+    xml_reader :value, :from => :content
+
+    def initialize(value = 0, units = 'meters')
+      to_metric
+    end
+
+  private
+    def after_parse
+      # xml attributes of self are already valid
+      to_metric
+    end
+
+    def to_metric
+      # translate units & value into metric, for example
+    end
+  end
+
+One important use of this approach is to make ROXML object which may or may not include an xml backing,
+which may be used via _new_ construction as well as _from_xml_ construction.
+
+== Selecting a parser
+
+By default, ROXML will use Nokogiri if it is available, followed by LibXML.  If you'd like to
+explicitly require one or the other, you may do the following:
+
+  module ROXML
+    XML_PARSER = 'nokogiri' # or 'libxml'
+  end
+  require 'roxml'
+
+For more information on available annotations, see ROXML::ClassMethods::Declarations