yob-roxml 3.1.6

data/.gitignore

@@ -0,0 +1,7 @@
+spec/**/*.xml
+rdoc
+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,354 @@
+== 3.1.6 (September 9, 2010)
+
+* bug fix
+
+  * load active_support in a way that is compatible with 2.x and 3.x
+    (fixes gh issue #27)
+  * change the way we monkey patch Nokogiri to leave the original
+    behaviour of the search() method unchanged (fixes gh issue #16)
+  * Unofficial release by James Healy, empact has stepped back from maintaining
+    roxml
+
+== 3.1.5 (December 18, 2009)
+
+* bug fix
+
+  * don't use tasks/ because those rake files are picked up by those vendoring roxml
+
+== 3.1.4 (December 18, 2009)
+
+* bug fix
+
+  * require the necessary version of active support (#tap wasn't introduced until 2.3)
+
+== 3.1.3 (October 30, 2009)
+
+* minor enhancements
+
+  * Add support for local-name() reference reading via :namespace => '*'
+    (ala http://techrageo.us/2008/11/01/wildcard-namespaces-in-xpath/)
+
+* bug fixes
+
+  * attributes collected :as => [] were previously output improperly,
+    as a single attribute on a single node
+  * don't output crazy, context-less namespaces and local-name xpaths
+    when trying to output namespaced attributes
+
+== 3.1.2 (October 18, 2009)
+
+* minor enhancements
+
+  * Retain whitespace in element contents, but still default on blank (rather than entirely empty) elements
+
+* bug fixes
+
+  * Include namespaces in xml output
+  * Fix that auto-wrapped collections weren't output with their wrappers
+    (which requires introducing the roxml_references accessor on the instance)
+
+== 3.1.1 (October 17, 2009)
+
+* bug fix
+
+  * Fix bad load paths
+
+== 3.1 (October 16, 2009)
+
+* 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/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2004-2009 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,195 @@
+ROXML Ruby Object to XML mapping library.
+
+For more information visit:
+
+    http://rdoc.info/projects/Empact/roxml
+    http://empact.github.com/roxml/
+    http://rubyforge.org/projects/roxml/
+
+Please submit bugs here:
+
+    http://github.com/Empact/roxml/issues
+
+
+=ROXML is of, by, and for all of us
+
+I've taken a lead role on ROXML these past months, but unfortunately I, Ben Woosley (Empact), am unable to continue to maintain ROXML at this time, as it no longer aligns with my other interests & efforts.  While I would very much like to fix the bugs listed on the github issues page, I'm simply not the person to do it, given my other concerns.
+
+But don't be mistaken, the library covers most cases very well, and is on the better-tested side of the spectrum (some 353 examples, all green as of this writing).
+
+If you run into a problem with ROXML, *please* take advantage of those tests, and github, by rolling up your sleeves and making a fix!  Your fellow programmers, myself included, will appreciate you for it.
+
+=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 = Nokogiri::XML::Document.new
+  doc.root = lib.to_xml
+  open("library.xml", 'w') do |file|
+    file << doc.serialize
+  end
+
+or
+
+  doc = LibXML::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
+
+Namespaced nodes are supported via the xml_namespace and xml_namespaces declarations and the :from and :namespace attr options.  See spec/xml/namespace_spec.rb for usage.
+
+Note that ROXML does not currently support outputting namespaced nodes.  This is planned for a future version.
+
+== 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
+
+== Note on Patches/Pull Requests
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add specs for it. This is important so I don't break it in a
+  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)
+* Send me a pull request. Bonus points for topic branches.
+
+== Copyright
+
+Copyright (c) 2004-2009 Ben Woosley, Zak Mandhro and Anders Engstrom. See LICENSE for details.