jarrett-quarto 0.3.1 → 1.1.0

data/README

@@ -5,7 +5,7 @@ Quarto was built with HTML output in mind, but there's nothing to prevent you fr
 to any other format. You could even output to an interpolated scripting language like PHP.
 
 Why Quarto?
-============
+===========
 
 Say you have a book in XML format, and you want to make a web site from it. You could transform it
 to HTML using XSLT. But what if you need logic that can't be implemented in XSLT?
@@ -13,7 +13,13 @@ to HTML using XSLT. But what if you need logic that can't be implemented in XSLT
 Enter Quarto. Instead of writing a series of XSLT sheets, you write ERB templates. You implement
 whatever custom logic you need in classes that wrap the DOM elements, then you pass variables to the templates.
 
+Installation
+============
+
+  gem sources -a http://gems.github.com
+  sudo gem install jarrett-quarto
+
 Using Quarto
-=============
+============
 
-Thorough documentation doesn't exist yet. For now, see spec/sample_project.
+Thorough documentation doesn't exist yet. For now, see spec/sample_project and the RDoc.

data/Rakefile

@@ -10,6 +10,7 @@ begin
 		gemspec.authors = ['Jarrett Colby']
 		gemspec.files = FileList['[A-Z]*', '{bin,lib,test}/**/*']
 		gemspec.executables = 'quarto'
+		gemspec.add_dependency('activesupport', '>= 2.3.2')
 	end
 rescue LoadError
 	puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"

data/VERSION

@@ -1 +1 @@
-0.3.1
+1.1.0

data/lib/quarto/children.rb

@@ -1,152 +1,240 @@
 module Quarto
-	# ElementWrapper subclasses can define parent and child elements, resulting
-	# in handy accessor methods. For example:
-	#
-	#   class Company < ElementWrapper
-	#     children :employees
-	#   end
-	#   
-	#   class Employee < ElementWrapper
-	#     parent :company
-	#     element_attr 'name'
-	#   end
-	#   
-	#   # in generate.rb:
-	#   company = Company.find :first
-	#   company.employees.each do |employee|
-	#     puts employee.name
-	#   end
-	
-	module ElementWrapperChildren
-		def self.included(base) # :nodoc:
-			base.extend(ClassMethods)
-			base.class_eval do
-				alias_method :method_missing_without_children, :method_missing
-				alias_method :method_missing, :method_missing_with_children
-				
-				alias_method :respond_to_without_children?, :respond_to?
-				alias_method :respond_to?, :respond_to_with_children?
+	module ElementWrapper # :nodoc:
+		module Children # :nodoc:
+			def self.included(base)
+				base.extend(ClassMethods)
+				base.class_eval do
+					alias_method :method_missing_without_children, :method_missing
+					alias_method :method_missing, :method_missing_with_children
+					
+					alias_method :respond_to_without_children?, :respond_to?
+					alias_method :respond_to?, :respond_to_with_children?
+				end
 			end
-		end
-		
-		def method_missing_with_children(meth, *args) # :nodoc:
-			if self.class.has_children_named?(meth)
-				children_proxy(meth)
-			elsif self.class.has_parent_named?(meth)
-				wrapped_parent
-			else
-				method_missing_without_children(meth, *args)
+			
+			def method_missing_with_children(meth, *args)
+				if self.class.has_child_named?(meth)
+					child_obj(meth)
+				elsif self.class.has_children_named?(meth)
+					children_proxy(meth)
+				elsif self.class.has_parent_named?(meth)
+					wrapped_parent
+				else
+					method_missing_without_children(meth, *args)
+				end
 			end
-		end
-		
-		def respond_to_with_children?(meth, include_private = false) # :nodoc:
-			if self.class.has_children_named?(meth) or self.class.has_parent_named?(meth)
-				true
-			else
-				respond_to_without_children?(meth, include_private)
+			
+			def respond_to_with_children?(meth, include_private = false)
+				if self.class.has_child_named?(meth) or self.class.has_children_named?(meth) or self.class.has_parent_named?(meth)
+					true
+				else
+					respond_to_without_children?(meth, include_private)
+				end
 			end
-		end
 		
-		protected
-		
-		def children_proxy(collection_el_name) # :nodoc:
-			@children_proxies ||= {}
-			@children_proxies[collection_el_name.to_s] ||= Children.new(self, collection_el_name.to_s.singularize)
-		end
+			protected
 		
-		def wrapped_parent # :nodoc:
-			parent_el_name = self.class.read_inheritable_attribute(:parent)
-			parent_class_name = parent_el_name.classify
-			Kernel.const_get(parent_class_name).new(@element.parent.parent) # Go up two levels, since each child is expected to be inside a collection element
-		end
-		
-		module ClassMethods # :nodoc:
-			# :singleton-method:
-			# Define children. +el_name+ must be the singular form. In the XML, all children must be
-			# wrapped in a collection element whose name is the plural form.
-			#
-			#  Example:
-			#
-			#   <company>
-			#     <employees>
-			#       <employee>
-			#       </employee>
-			#     </employees>
-			#   </company>
-			#   
-			#   class Company < ElementWrapper
-			#     children :employees
-			#   end
-			def children(el_name)
-				write_inheritable_array(:children, [el_name.to_s])
+			def child_obj(meth)
+				options = self.class.read_inheritable_attribute(:singleton_children)[meth.to_sym]
+				el_name = (options[:element_name] || meth).to_s
+				child_class = Kernel.const_get(options[:wrapper_class] || el_name.classify)
+				child_element = @element.elements[el_name]
+				return nil if child_element.nil?
+				@singleton_children ||= {}
+				@singleton_children[meth] ||= child_class.new(child_element)
 			end
 			
-			def has_children_named?(collection_el_name) # :nodoc:
-				return false if read_inheritable_attribute(:children).nil?
-				read_inheritable_attribute(:children).include?(collection_el_name.to_s)
+			def children_proxy(meth)
+				options = self.class.read_inheritable_attribute(:children)[meth.to_sym]
+				@children_proxies ||= {}
+				@children_proxies[meth] ||= ChildrenProxy.new(self, options[:element_name], options)
 			end
 			
-			def has_parent_named?(parent_el_name) # :nodoc:
-				read_inheritable_attribute(:parent) == parent_el_name.to_s
+			def wrapped_parent
+				options = self.class.read_inheritable_attribute(:parent)
+				parent_class = Kernel.const_get(options[:wrapper_class] || options[:element_name].classify)
+				parent_el = @element
+				while parent_el.name != options[:element_name]
+					parent_el = parent_el.parent
+				end
+				parent_class.new(parent_el) # Go up two levels, since each child is expected to be inside a collection element
 			end
 			
-			# :singleton-method:
-			# Defines the element's parent. Example:
-			#  Example:
+			# ElementWrapper::Base subclasses can define parent and child elements, resulting
+			# in handy accessor methods. For example:
 			#
-			#   <company>
-			#     <employees>
-			#       <employee>
-			#       </employee>
-			#     </employees>
-			#   </company>
+			#   class Company < ElementWrapper::Base
+			#     children :employees
+			#   end
 			#   
-			#   class Employee < ElementWrapper
+			#   class Employee < ElementWrapper::Base
 			#     parent :company
+			#     element_attr 'name'
+			#   end
+			#   
+			# and in generate.rb:
+			#   company = Company.find :first
+			#   company.employees.each do |employee|
+			#     puts employee.name
 			#   end
-			def parent(el_name)
-				write_inheritable_attribute(:parent, el_name.to_s)
+			
+			module ClassMethods 
+				# Creates an attribute for a child element. +el_name+ must be the singular form.
+				#
+				# Options:
+				# * <tt>:element_name</tt> - The name of the child element. Defaults to +method_name+.
+				# * <tt>:wrapper_class</tt> - <tt>:wrapper_class</tt> - The subclass of ElementWrapper::Base to use.
+				#   Defaults to the element name.
+				#
+				# Example:
+				#
+				#   <company>
+				#     <boss>
+				#       <name>Joe Schmoe</name>
+				#     </boss>
+				#   </company>
+				#
+				#   class Company
+				#     child :boss
+				#   end
+				def child(method_name, options = {})
+					write_inheritable_hash(:singleton_children, {method_name.to_sym => options})
+				end
+				
+				# Creates an attribute for child elements.
+				# 
+				# Options:
+				# * <tt>:element_name</tt> - The XML element of each individual child. Default
+				#   to the singular form of +method_name+.
+				# * <tt>:collection_element</tt> - By default, ElementWrapper assums that all
+				#   children are wrapped in a collection element whose name is +method_name+.
+				#   You can override this with <tt>:collection_element</tt>. If
+				#   the child elements are not wrapped in a collection element at all,
+				#   use <tt>:collection_element => nil</tt>.
+				# * <tt>:wrapper_class</tt> - The subclass of ElementWrapper::Base to use.
+				#   Defaults to the singular form of the element name.
+				#
+				# Example:
+				#
+				#   <company>
+				#     <employees>
+				#       <employee>
+				#       </employee>
+				#     </employees>
+				#   </company>
+				#   
+				#   class Company < ElementWrapper::Base
+				#     children :employees
+				#   end
+				def children(method_name, options = {})
+					write_inheritable_hash(:children, {method_name.to_sym => {
+						:element_name => method_name.to_s.singularize,
+						:collection_element => method_name.to_s
+					}.merge(options)})
+				end
+				
+				def has_child_named?(method_name) # :nodoc:
+					return false if read_inheritable_attribute(:singleton_children).nil?
+					read_inheritable_attribute(:singleton_children).has_key?(method_name.to_sym)
+				end
+				
+				def has_children_named?(method_name) # :nodoc:
+					return false if read_inheritable_attribute(:children).nil?
+					read_inheritable_attribute(:children).has_key?(method_name.to_sym)
+				end
+				
+				def has_parent_named?(method_name) # :nodoc:
+					return false if read_inheritable_attribute(:parent).nil?
+					read_inheritable_attribute(:parent)[:method] == method_name.to_sym
+				end
+				
+				# Defines the element's parent. Options:
+				#
+				# * <tt>:element_name</tt> - The name of the parent element. Defaults to +method_name+.
+				# * <tt>:wrapper_class</tt> - The subclass of ElementWrapper::Base to use.
+				#   Defaults to the element name.
+				#
+				# Example:
+				#
+				#   <company>
+				#     <employees>
+				#       <employee>
+				#       </employee>
+				#     </employees>
+				#   </company>
+				#   
+				#   class Employee < ElementWrapper::Base
+				#     parent :company
+				#   end
+				def parent(method_name, options = {})
+					write_inheritable_attribute(:parent, {:method => method_name.to_sym, :element_name => method_name.to_s}.merge(options))
+				end
 			end
 		end
-	end
-	
-	class Children
-		include Enumerable
-		
-		# Returns the REXML::Element for the children collection.
-		attr_reader :collection_element
-		
-		# Iterate over all children.
-		def each
-			to_a.each { |child| yield child }
-		end
-		
-		# Returns true if there are no children.
-		def empty?
-			to_a.empty?
-		end
 		
-		def initialize(wrapped_parent, el_name, options = {}) # :nodoc:
-			@wrapped_parent = wrapped_parent
-			@el_name = el_name.to_s
-			@collection_element = @wrapped_parent.element.elements[options[:collection_el_name] ||  @el_name.pluralize]
-			@wrapper_class = options[:wrapper_class] || Kernel.const_get(@el_name.classify)
-		end
-		
-		# Returns the number of children.
-		def length
-			to_a.length
-		end
-		
-		# Returns an array of all children. Each is an instance of ElementWrapper. If +xpath+ is provided, the results will be filtered. +xpath+ is relative to the parent element
-		def to_a(xpath = nil)
-			@all ||= @collection_element.elements.to_a(xpath || @el_name).collect do |el|
-				@wrapper_class.new(el)
+		# Any call to a children accessor method returns an instance of ChildrenProxy. For example,
+		# consider this class:
+		#
+		#   class Company < ElementWrapper::Base
+		#     children :employees
+		#   end
+		#
+		# If you call <tt>#employees</tt> on an instance of Company, you'll get a ChildrenProxy
+		# object.
+	
+		class ChildrenProxy
+			include Enumerable
+			
+			# Returns the REXML::Element for the children collection.
+			attr_reader :collection_element
+			
+			# Iterates over all children.
+			def each
+				to_a.each { |child| yield child }
 			end
+			
+			# Returns true if there are no children.
+			def empty?
+				to_a.empty?
+			end
+			
+			# Returns the first child in the collection.
+			def first
+				to_a.first
+			end
+			
+			def initialize(wrapped_parent, el_name, options = {}) # :nodoc:
+				@wrapped_parent = wrapped_parent
+				@el_name = el_name.to_s
+				if options[:collection_element].nil?
+					# The subclass says there is no collection element wrapping the children
+					@collection_element = nil
+				else
+					@collection_element = @wrapped_parent.element.elements[options[:collection_element]]
+				end
+				@wrapper_class = Kernel.const_get(options[:wrapper_class] || @el_name.classify)
+			end
+			
+			# Returns the last child in the collection.
+			def last
+				to_a.last
+			end
+			
+			# Returns the number of children.
+			def length
+				to_a.length
+			end
+			
+			# Returns an array of all children. Each is an instance of ElementWrapper::Base. If +xpath+ is provided, the results will be filtered. +xpath+ is relative to the parent element
+			def to_a(xpath = nil)
+				@all ||= (@collection_element || @wrapped_parent.element).elements.to_a(xpath || @el_name).collect do |el|
+					@wrapper_class.new(el)
+				end
+			end
+			
+			alias_method :size, :length
 		end
-		
-		alias_method :size, :length
 	end
 end
 
-Quarto::ElementWrapper.send(:include, Quarto::ElementWrapperChildren)
+Quarto::ElementWrapper::Base.send(:include, Quarto::ElementWrapper::Children)

data/lib/quarto/element_wrapper.rb

@@ -1,155 +1,183 @@
 module Quarto
-	# Abstract base class for your models. Put your ElementWrapper subclasses inside the "models"
-	# directory within your project. All files in that directory will be automatically required.
-	#
-	# Each ElementWrapper subclass corresponds to exactly one XML element.
-	# You can specify the model's element name by calling element_name=, but
-	# generally, you just let ElementWrapper use the default, which is the subclass
-	# name in snake_case.
-	#
-	# Instance attributes corresponding to the XML attributes 
-	#
-	# For example, suppose you have an XML document like this:
-	#
-	#   <programmers>
-	#     <programmer skill="genius">
-	#       <name>Linus Torvalds</name>
-	#     <programmer>
-	#   </programmers>
-	#
-	# You could then subclass ElementWrapper like this:
-	#
-	#   class Programmer < ElementWrapper
-	#     element_name = 'programmer'
-	#     element_attrs 'name'
-	#   end
-	#
-	# You could then do something like this in your generate.rb file:
-	#
-	#   programmer = Programmer.find :first
-	#   puts programmer.name
-	#   puts programmer.skill
-	#
-	# Also see the documentation for Quarto::Children
+	module ElementWrapper # :nodoc:
 	
-	class ElementWrapper
-		include InheritableAttributes
-		
-		# Returns true if both instances come from the same node in the source XML document.
-		def ==(other_wrapped_element)
-			other_wrapped_element.is_a?(Quarto::ElementWrapper) and @element == other_wrapped_element.element
-		end
-		
-		# Returns the currently-loaded REXML::Document.
-		def self.xml_doc
-			Quarto.xml_doc
-		end
-		
-		# Returns the REXML::Element from which the instance was created.
-		attr_reader :element
-		
-		# Creates read-only attributes from the given strings. When a model is instantiated from an XML node,
-		# ElementWrapper will try to populate these attributes using the node's child elements.
+		# Abstract base class for your models. Put your ElementWrapper::Base subclasses inside the
+		# "models" directory within your project. All files in that directory will be automatically
+		# required.
 		#
-		# For example, if your "employee" element has a child element called "name," you can use:
+		# Each ElementWrapper::Base subclass corresponds to exactly one XML element.
+		# You can specify the model's element name by calling element_name=, but
+		# generally, you just let ElementWrapper use the default, which is the subclass
+		# name in snake_case.
 		#
-		#   element_attrs 'name'
+		# Inside each ElementWrapper::Base is a REXML::Element. ElementWrapper::Base implements
+		# <tt>method_missing</tt>, allowing you to call that REXML::Element's methods
+		# on the ElementWrapper::Base instance.
 		#
-		# ...which will then expose a #name method for every instance of your class. Also see the usage example in the class description.
+		# Instance attributes corresponding to the XML attributes will automatically
+		# be defined. Hwoever, if you want an attribute defined by the text of a child
+		# element, you have to specify it yourself.
 		#
-		# Remember, XML attributes will automatically have corresponding ElementWrapper attributes. You only need to tell
-		# ElementWrapper which child elements to use.		
-		def self.element_attrs(*element_names)
-			write_inheritable_array :element_attrs, element_names.collect { |en| en.to_sym}
-		end
-		
-		# Returns the XML element name.
-		def self.element_name
-			@element_name
-		end
-		
-		# Overrides the XML element name. The default is the class name in snake_case.
-		def self.element_name=(el_name)
-			@element_name = el_name
-		end
-		
-		# Searches the XML document and returns instances of the class. The first parameter must be either :first, :last, or :all.
-		# If it's :first or :last, the method returns a single instance or nil. If it's :all, the method returns an array (which may be empty).
+		# For example, suppose you have an XML document like this:
+		#
+		#   <programmers>
+		#     <programmer skill="genius">
+		#       <name>Linus Torvalds</name>
+		#     <programmer>
+		#   </programmers>
+		#
+		# You could then subclass ElementWrapper like this:
+		#
+		#   class Programmer < ElementWrapper::Base
+		#     element_name = 'programmer'
+		#     element_attrs 'name'
+		#   end
+		#
+		# You could then do something like this in your generate.rb file:
 		#
-		# Options:
+		#   programmer = Programmer.find :first
+		#   puts programmer.name
+		#   puts programmer.skill
 		#
-		# * <tt>:xpath</tt> - An XPath expression to limit the search. If this option is not given, the default XPath is "//element_name"
-		def self.find(quantifier, options = {})
-			raise ArgumentError, "Quantifier must be :all, :first, or :last, but got #{quantifier.inspect}" unless [:all, :first, :last].include?(quantifier)
-			raise ArgumentError, "Options must be a Hash, but got #{options.inspect}" unless options.is_a?(Hash)
-			if options.has_key?(:xpath)
-				xpath = options[:xpath]
-			else
-				xpath = "//#{@element_name}"
-				# TODO: add support for :root and :conditions (XPath predicates)
+		# Also see the documentation for ElementWrapper::Children
+		
+		class Base
+			include InheritableAttributes
+			
+			# Returns true if both instances come from the same node in the source XML document.
+			def ==(other_wrapped_element)
+				other_wrapped_element.is_a?(Quarto::ElementWrapper::Base) and @element == other_wrapped_element.element
 			end
-			all = xml_doc.elements.to_a(xpath).collect do |el|
-				new(el)
+			
+			# Returns the currently-loaded REXML::Document.
+			def self.xml_doc
+				Quarto.xml_doc
 			end
-			case quantifier
-			when :all
-				all
-			when :first
-				all.first
-			when :last
-				all.last
+			
+			# Returns the REXML::Element from which the instance was created.
+			attr_reader :element
+			
+			# Creates read-only attributes from the given strings. When a model is instantiated from an XML node,
+			# ElementWrapper will try to populate these attributes using the node's child elements.
+			#
+			# For example, if your "employee" element has a child element called "name," you can use:
+			#
+			#   element_attrs 'name'
+			#
+			# ...which will then expose a #name method for every instance of your class. Also see the usage example in the class description.
+			#
+			# Remember, XML attributes will automatically have corresponding ElementWrapper attributes. You only need to tell
+			# ElementWrapper which child elements to use.		
+			def self.element_attrs(*element_names)
+				write_inheritable_array :element_attrs, element_names.collect { |en| en.to_sym}
 			end
-		end
-		
-		def self.inherited(subclass) # :nodoc:
-			subclass.element_name = subclass.to_s.underscore
-		end
-		
-		def initialize(el) # :nodoc:
-			unless el.is_a?(REXML::Element)
-				raise ArgumentError, "Quarto::ElementWrapper.new must be passed a REXML::Element, but got #{el.inspect}"
+			
+			# Returns the XML element name.
+			def self.element_name
+				@element_name
 			end
-			@element = el
-			@attributes = {}
-			@element.attributes.each do |a_name, value|
-				@attributes[a_name.to_sym] = typecast_text(value)
+			
+			# Overrides the XML element name. The default is the class name in snake_case.
+			def self.element_name=(el_name)
+				@element_name = el_name
 			end
-			self.class.read_inheritable_attribute(:element_attrs).each do |el_name|
-				raise ArgumentError, "Expected <#{@element.name}> to contain <#{el_name}>" if @element.elements[el_name.to_s].nil?
-				@attributes[el_name.to_sym] = typecast_text(@element.elements[el_name.to_s].text)
+			
+			# Searches the XML document and returns instances of the class. The first parameter must be either :first, :last, or :all.
+			# If it's :first or :last, the method returns a single instance or nil. If it's :all, the method returns an array (which may be empty).
+			#
+			# Options:
+			#
+			# * <tt>:xpath</tt> - An XPath expression to limit the search. If this option is not given, the default XPath is "//element_name"
+			def self.find(quantifier, options = {})
+				raise ArgumentError, "Quantifier must be :all, :first, or :last, but got #{quantifier.inspect}" unless [:all, :first, :last].include?(quantifier)
+				raise ArgumentError, "Options must be a Hash, but got #{options.inspect}" unless options.is_a?(Hash)
+				if options.has_key?(:xpath)
+					xpath = options[:xpath]
+				else
+					xpath = "//#{@element_name}"
+					# TODO: add support for :root and :conditions (XPath predicates)
+				end
+				all = xml_doc.elements.to_a(xpath)
+				case quantifier
+				when :all
+					all.collect { |el| new(el) }
+				when :first
+					all.empty? ? nil : new(all.first)
+				when :last
+					all.empty? ? nil : new(all.last)
+				end
 			end
-		end
-		
-		def method_missing(meth, *args, &block) # :nodoc:
-			if @attributes.has_key?(meth.to_sym)
-				@attributes[meth.to_sym]
-			elsif @element.respond_to?(meth)
-				@element.send(meth, *args, &block)
-			else	
-				super
+			
+			def self.inherited(subclass) # :nodoc:
+				subclass.element_name = subclass.to_s.underscore
 			end
-		end
-		
-		def respond_to?(meth, include_private = false) # :nodoc:
-			if @element.respond_to?(meth, include_private) or @attributes.has_key?(meth.to_sym)
-				true
-			else
-				super
+			
+			def initialize(el) # :nodoc:
+				unless el.is_a?(REXML::Element)
+					raise ArgumentError, "Quarto::ElementWrapper.new must be passed a REXML::Element, but got #{el.inspect}"
+				end
+				@element = el
+				@attributes = {}
+				@element.attributes.each do |a_name, value|
+					@attributes[a_name.to_sym] = typecast_text(value)
+				end
+				if element_attrs = self.class.read_inheritable_attribute(:element_attrs)
+					element_attrs.each do |el_name|
+						raise ArgumentError, "Expected <#{@element.name}> to have child <#{el_name}>" if @element.elements[el_name.to_s].nil?
+						@attributes[el_name.to_sym] = typecast_text(@element.elements[el_name.to_s].text)
+					end
+				end
+				if text_attr = self.class.read_inheritable_attribute(:text_attr)
+					@attributes[text_attr.to_sym] = typecast_text(@element.text)
+				end
 			end
-		end
-		
-		protected
-		
-		# When an ElementWrapper is instantiated from an XML node, all values start out as strings. This method typecasts those values.
-		def typecast_text(t)
-			if t.nil? or (t.is_a?(String) and t.empty?)
-				nil
-			elsif t =~ /^-?[0-9]+$/
-				t.to_i
-			elsif t =~ /^-?[0-9]*\.[0-9]+$/
-				t.to_f
-			else
-				t
+			
+			def method_missing(meth, *args, &block) # :nodoc:
+				if @attributes.has_key?(meth.to_sym)
+					@attributes[meth.to_sym]
+				elsif @element.respond_to?(meth)
+					@element.send(meth, *args, &block)
+				else	
+					super
+				end
+			end
+			
+			def respond_to?(meth, include_private = false) # :nodoc:
+				if @element.respond_to?(meth, include_private) or @attributes.has_key?(meth.to_sym)
+					true
+				else
+					super
+				end
+			end
+			
+			# Creates a read-only attribute from the wrapped element's text.
+			# +attr_name+ can be anything you want; it doesn't have to correspond
+			# to anything in the XML. Example:
+			#
+			#   <company>
+			#     <product>Shoes</product>
+			#   <company>
+			#
+			#   class Product < ElementWrapper
+			#     text_attr :name
+			#   end
+			def self.text_attr(attr_name)
+				write_inheritable_attribute(:text_attr, attr_name)
+			end
+			
+			protected
+			
+			# When an ElementWrapper is instantiated from an XML node, all values start out as strings. This method typecasts those values.
+			def typecast_text(t)
+				if t.nil? or (t.is_a?(String) and t.empty?)
+					nil
+				elsif t =~ /^-?[0-9]+$/
+					t.to_i
+				elsif t =~ /^-?[0-9]*\.[0-9]+$/
+					t.to_f
+				else
+					t
+				end
 			end
 		end
 	end

data/lib/quarto/inheritable_attributes.rb

@@ -1,5 +1,3 @@
-# Thanks to ActiveSupport for this stuff
-
 module Quarto
 	module InheritableAttributes # :nodoc: all
 		def self.included(base)

data/lib/quarto/url_helper.rb

@@ -1,6 +1,9 @@
 require 'cgi'
 
 module Quarto
+	
+	# This module is included in Generator and thus made available in <tt>generate.rb</tt> files.
+	
 	module UrlHelper
 		# Generates an absolute URL, using the <tt>:site_root</tt> config value. (To change <tt>:site_root</tt>,
 		# put something like this in <tt>generate.rb</tt>:

data/lib/quarto.rb

@@ -13,4 +13,30 @@ require 'quarto/element_wrapper'
 require 'quarto/children'
 require 'quarto/rendering'
 require 'quarto/generator'
-require 'quarto/init_project'
+require 'quarto/init_project'
+
+# Quarto is a Ruby framework for generating collections of documents from XML. Potential applications
+# include web sites and e-books. It's built on top of ERB and REXML.
+#
+# Quarto was built with HTML output in mind, but there's nothing to prevent you from outputting
+# to any other format. You could even output to an interpolated scripting language like PHP.
+#
+# =Why Quarto?
+#
+# Say you have a book in XML format, and you want to make a web site from it. You could transform it
+# to HTML using XSLT. But what if you need logic that can't be implemented in XSLT?
+#
+# Enter Quarto. Instead of writing a series of XSLT sheets, you write ERB templates. You implement
+# whatever custom logic you need in classes that wrap the DOM elements, then you pass variables to the templates.
+#
+# =Installation
+#
+#   gem sources -a http://gems.github.com
+#   sudo gem install jarrett-quarto
+#
+# =Using Quarto
+#
+# Thorough documentation doesn't exist yet. For now, see spec/sample_project and the RDoc.
+
+module Quarto
+end

data/spec/children_spec.rb

@@ -1,22 +1,18 @@
 require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
-require File.expand_path(File.dirname(__FILE__) + '/sample_project/models/company')
-require File.expand_path(File.dirname(__FILE__) + '/sample_project/models/employee')
+require File.expand_path(File.dirname(__FILE__) + '/sample_models')
 
-describe Quarto::ElementWrapperChildren do
+describe Quarto::ElementWrapper::Children do
 	before :each do
 		Quarto.xml_source = File.open(SAMPLE_DIR + '/xml/companies.xml')
 		@xml = Quarto.xml_doc
 	end
 	
-	context 'an ElementWrapper instance with children' do
-		before :each do
+	context '.children' do
+		it 'should create a children accessor' do
 			@element = @xml.elements['companies/company']
 			@company = Company.new(@element)
-		end
-		
-		it 'should know its children' do
 			@company.should respond_to(:employees)
-			@company.employees.should be_a(Quarto::Children)
+			@company.employees.should be_a(Quarto::ElementWrapper::ChildrenProxy)
 			@company.employees.length.should == 2 # In the sample XML file, 37Signals has two employees.
 			@company.employees.each do |employee|
 				employee.should be_a(Employee)
@@ -24,21 +20,177 @@ describe Quarto::ElementWrapperChildren do
 		end
 	end
 	
-	context 'an ElementWrapper instance with a parent' do
-		before :each do
+	context '.children given :wrapper_class' do
+		it 'should use the specified class instead of the default' do
+			class CompanyWithWrapperClass < Quarto::ElementWrapper::Base
+				element_name = 'company'
+				children :employees, :wrapper_class => 'CrazyEmployee'
+			end
+			
+			class CrazyEmployee < Quarto::ElementWrapper::Base; end
+			
+			@element = @xml.elements['companies/company']
+			@company = CompanyWithWrapperClass.new(@element)
+			@company.employees.each do |employee|
+				employee.should be_a(CrazyEmployee)
+			end
+			
+			Object.class_eval do
+				remove_const :CompanyWithWrapperClass
+				remove_const :CrazyEmployee
+			end
+		end
+	end
+	
+	context '.children given :collection_element' do
+		it 'should use the specified collection element instead of the default' do
+			@company = Company.find(:first, :xpath => "//company[name='Mega-lo-Mart']")
+			@company.should respond_to(:products)
+			@company.products.should be_a(Quarto::ElementWrapper::ChildrenProxy)
+			@company.products.length.should == 2
+			@company.products.each do |product|
+				product.should be_a(Product)
+			end
+		end
+	end
+	
+	context '.children given :collection_element => nil' do
+		it 'should create a children accessor that uses immediate children of the element' do
+			@company = Company.find(:first, :xpath => "//company[name='Mega-lo-Mart']")
+			@company.should respond_to(:locations)
+			@company.locations.should be_a(Quarto::ElementWrapper::ChildrenProxy)
+			@company.locations.length.should == 2
+			@company.locations.each do |location|
+				location.should be_a(Location)
+			end
+		end
+	end
+	
+	context '.chldren given :element_name' do
+		it 'should use the specified element instead of the default' do
+			class CompanyWithElementName < Quarto::ElementWrapper::Base
+				children :the_employees, :element_name => 'employee'
+			end
+			
+			@element = @xml.elements['companies/company']
+			@company = CompanyWithElementName.new(@element)
+			@company.the_employees.each do |employee|
+				employee.should be_a(Employee)
+				employee.element.name.should == 'employee'
+			end
+			
+			Object.class_eval do
+				remove_const :CompanyWithElementName
+			end
+		end
+	end
+	
+	context '.parent for an element in a collection' do
+		it 'should create an accessor for the parent object' do
 			@element = @xml.elements['companies/company/employees/employee']
 			@employee = Employee.new(@element)
-		end
-		
-		it 'should have children which know their parent' do
 			@employee.should respond_to(:company)
 			@employee.company.should be_a(Company)
 			@employee.company.name.should == '37Signals'
 		end
 	end
+	
+	context '.parent for an element that\'s not in a collection' do
+		it 'should create an accessor for the parent object' do
+			@company = Company.find(:first, :xpath => "//company[name='Mega-lo-Mart']")
+			@location= @company.locations.first
+			@location.company.should == @company
+		end
+	end
+	
+	context '.parent given :element_name' do
+		it 'should test for something' do
+			# create classes
+			class EmployeeWithElementName < Quarto::ElementWrapper::Base
+				parent :the_company, :element_name => 'company'
+			end
+			
+			@element = @xml.elements['//employee']
+			@employee = EmployeeWithElementName.new(@element)
+			@employee.the_company.should be_a(Company)
+			@employee.the_company.element.name.should == 'company'
+			
+			Object.class_eval do
+				remove_const :EmployeeWithElementName
+			end
+		end
+	end
+	
+	context '.parent given :wrapper_class' do
+		it 'should use the specified class instead of the default' do
+			class EmployeeWithWrapperClass < Quarto::ElementWrapper::Base
+				parent :company, :wrapper_class => 'CrazyCompany'
+			end
+			
+			class CrazyCompany < Quarto::ElementWrapper::Base; end
+			
+			@element = @xml.elements['//employee']
+			@employee = EmployeeWithWrapperClass.new(@element)
+			@employee.company.should be_a(CrazyCompany)
+			
+			Object.class_eval do
+				remove_const :EmployeeWithWrapperClass
+				remove_const :CrazyCompany
+			end
+		end
+	end
+	
+	context '.child' do
+		before :each do
+			@company = Company.find(:first, :xpath => "//company[name='Mega-lo-Mart']")
+		end
+		
+		it 'should create an accessor that returns the child if it exists' do
+			@company.mascot.should be_a(Mascot)
+		end
+		
+		it 'should create an accessor that returns nil if the child does not exist' do
+			@company = Company.find :first
+			@company.mascot.should == nil
+		end
+	end
+	
+	context '.child given :wrapper_class' do
+		it 'should use the specified class instead of the default' do
+			class CompanyWithWrapperClass < Quarto::ElementWrapper::Base
+				child :mascot, :wrapper_class => 'CrazyMascot'
+			end
+			
+			class CrazyMascot < Quarto::ElementWrapper::Base; end
+			
+			@company = CompanyWithWrapperClass.find(:first, :xpath => "//company[name='Mega-lo-Mart']")
+			@company.mascot.should be_a(CrazyMascot)
+			
+			Object.class_eval do
+				remove_const :CompanyWithWrapperClass
+				remove_const :CrazyMascot
+			end
+		end
+	end
+	
+	context '.child given :element_name' do
+		it 'should use the specified element name instead of the default' do
+			class CompanyWithElementName < Quarto::ElementWrapper::Base
+				child :the_mascot, :element_name => 'mascot'
+			end
+			
+			@company = CompanyWithElementName.find(:first, :xpath => "//company[name='Mega-lo-Mart']")
+			@company.the_mascot.should be_a(Mascot)
+			@company.the_mascot.element.name.should == 'mascot'
+			
+			Object.class_eval do
+				remove_const :CompanyWithElementName
+			end
+		end
+	end
 end
 
-describe Quarto::Children do
+describe Quarto::ElementWrapper::ChildrenProxy do
 	before :each do
 		Quarto.xml_source = File.open(SAMPLE_DIR + '/xml/companies.xml')
 		@xml = Quarto.xml_doc
@@ -52,7 +204,17 @@ describe Quarto::Children do
 		end
 	end
 	
-	it 'should support empty?' do
+	it 'should support #first' do
+		@company.employees.should respond_to(:first)
+		@company.employees.first.should == @company.employees.to_a.first
+	end
+	
+	it 'should support #last' do
+		@company.employees.should respond_to(:last)
+		@company.employees.last.should == @company.employees.to_a.last
+	end
+	
+	it 'should support #empty?' do
 		@company.employees.should respond_to(:empty?)
 		@company.employees.empty?.should == false
 	end

data/spec/element_wrapper_spec.rb

@@ -1,24 +1,23 @@
 require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
-require File.expand_path(File.dirname(__FILE__) + '/sample_project/models/company')
-require File.expand_path(File.dirname(__FILE__) + '/sample_project/models/employee')
+require File.expand_path(File.dirname(__FILE__) + '/sample_models')
 
-describe Quarto::ElementWrapper do
+describe Quarto::ElementWrapper::Base do
 	before :each do
 		Quarto.xml_source = File.open(SAMPLE_DIR + '/xml/companies.xml')
 		@xml = Quarto.xml_doc
 	end
 	
-	context 'wrapping an element with attributes and children' do
+	context 'wrapping an element with attributes' do
 		before :each do
 			@element = @xml.elements['companies/company']
 			@company = Company.new(@element)
 		end
 		
-		it 'should instantiate a subclass of Quarto::ElementWrapper' do
-			@company.should be_a(Quarto::ElementWrapper)
+		it 'should instantiate a subclass of Quarto::ElementWrapper::Base' do
+			@company.should be_a(Quarto::ElementWrapper::Base)
 		end
 		
-		it 'should define methods from specified child elements' do
+		it 'should define attributes from specified elements' do
 			@company.should respond_to(:name)
 			@company.name.should == '37Signals'
 		end
@@ -41,6 +40,16 @@ describe Quarto::ElementWrapper do
 		end
 	end
 	
+	context 'wrapping an element that only contains text' do
+		before :each do
+			@product = Product.find(:first, :xpath => "//product[text()='Propane']")
+		end
+		
+		it 'should link an attribute to the element\'s text' do
+			@product.name.should == 'Propane'
+		end
+	end
+	
 	context '.new' do
 		it 'should raise ArgumentError if it is passed anything other than a REXML::Element' do
 			[nil, 'foo', 1].each do |bad|
@@ -53,6 +62,7 @@ describe Quarto::ElementWrapper do
 		it 'should find matching elements based on :xpath' do
 			companies = Company.find(:all, :xpath => 'companies/company')
 			companies.should be_a(Array)
+			companies.length.should == 5
 			companies.each do |company|
 				company.should be_a(Company)
 			end
@@ -67,6 +77,15 @@ describe Quarto::ElementWrapper do
 			companies[0].name.should == 'Milliways'
 		end
 		
+		it 'should return an empty array with :all and an XPath that yields nothing' do
+			Company.find(:all, :xpath => "companies/company[foo='bar']").should == []
+		end
+		
+		it 'should return nil with :first or :last and an XPath that yields nothing' do
+			Company.find(:first, :xpath => "companies/company[foo='bar']").should == nil
+			Company.find(:last, :xpath => "companies/company[foo='bar']").should == nil
+		end
+		
 		it 'should work without the :xpath parameter' do
 			Company.find(:all).should == Company.find(:all, :xpath => '//company')
 			Employee.find(:all).should == Employee.find(:all, :xpath => '//employee')
@@ -89,5 +108,24 @@ describe Quarto::ElementWrapper do
 			company.name.should == 'Milliways'
 		end
 	end
+	
+	context '#==' do
+		before :each do
+			@element_1 = @xml.elements['companies/company']
+			@element_2 = @xml.elements['companies/company[last()]']
+		end
+		
+		it 'should return true for two ElementWrapper::Base instances that wrap the same element' do
+			Quarto::ElementWrapper::Base.new(@element_1).should == Quarto::ElementWrapper::Base.new(@element_1)
+		end
+		
+		it 'should return false for two ElementWrapper::Base instaces that wrap different elements' do
+			Quarto::ElementWrapper::Base.new(@element_1).should_not == Quarto::ElementWrapper::Base.new(@element_2)
+		end
+		
+		it 'should return false if the second object is not an instance of ElementWrapper::Base' do
+			Quarto::ElementWrapper::Base.new(@element_1).should_not == 'foo'
+		end
+	end
 end
 

data/spec/generator_spec.rb

@@ -32,7 +32,7 @@ describe Quarto do
 			@mock_generator.should_receive(:generate)
 		end
 		
-		it 'should execute the block in the context of the Generator' do
+		it 'should pass the block to the Generator' do
 			@mock_generator.should_receive(:do_something_in_the_block)
 		end
 	end
@@ -114,7 +114,7 @@ describe Quarto::Generator do
 		
 		it 'should pass the companies into the template' do
 			html = File.read(@generator.output_path + '/companies.html')
-			['37Signals', 'Mega-lo-mart', 'Kwik-E-Mart', 'Good Burger', 'Milliways'].each do |name|
+			['37Signals', 'Mega-lo-Mart', 'Kwik-E-Mart', 'Good Burger', 'Milliways'].each do |name|
 				html.should include(name)
 			end
 		end

data/spec/sample_models.rb

@@ -0,0 +1,5 @@
+require File.expand_path(File.dirname(__FILE__) + '/sample_project/models/company')
+require File.expand_path(File.dirname(__FILE__) + '/sample_project/models/employee')
+require File.expand_path(File.dirname(__FILE__) + '/sample_project/models/product')
+require File.expand_path(File.dirname(__FILE__) + '/sample_project/models/location')
+require File.expand_path(File.dirname(__FILE__) + '/sample_project/models/mascot')

data/spec/sample_project/models/company.rb

@@ -1,8 +1,14 @@
-class Company < Quarto::ElementWrapper
+class Company < Quarto::ElementWrapper::Base
 	element_attrs :name, :industry
 	
 	children :employees
 	
+	children :products, :collection_element => 'selling'
+	
+	children :locations, :collection_element => nil
+	
+	child :mascot
+	
 	def competitors
 		@competitors ||= self.class.find(:all, :xpath => "companies/company[industry='#{industry}' and name!='#{name}']")
 	end

data/spec/sample_project/models/employee.rb

@@ -1,4 +1,4 @@
-class Employee < Quarto::ElementWrapper
+class Employee < Quarto::ElementWrapper::Base
 	element_attrs :name
 	
 	parent :company

data/spec/sample_project/models/location.rb

@@ -0,0 +1,5 @@
+class Location < Quarto::ElementWrapper::Base
+	parent :company
+	
+	element_attrs 'city', 'state'
+end

data/spec/sample_project/models/mascot.rb

@@ -0,0 +1,5 @@
+class Mascot < Quarto::ElementWrapper::Base
+	parent :company
+	
+	element_attrs 'name'
+end

data/spec/sample_project/models/product.rb

@@ -0,0 +1,5 @@
+class Product < Quarto::ElementWrapper::Base
+	parent :company
+	
+	text_attr :name
+end

data/spec/spec_helper.rb

@@ -9,4 +9,8 @@ require(File.expand_path(File.dirname(__FILE__)) + '/../lib/quarto')
 
 Dir.glob(SPEC_DIR + '/matchers/*.rb').each do |matcher_lib|
 	require matcher_lib
+end
+
+def puts(str)
+	raise "puts('#{str}') called"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: jarrett-quarto
 version: !ruby/object:Gem::Version 
-  version: 0.3.1
+  version: 1.1.0
 platform: ruby
 authors: 
 - Jarrett Colby
@@ -9,10 +9,19 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-06-05 00:00:00 -07:00
+date: 2009-06-06 00:00:00 -07:00
 default_executable: quarto
-dependencies: []
-
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 2.3.2
+    version: 
 description: Quarto is a Ruby framework for generating collections of documents from XML. It steps in where XSLT just won't cut it. Potential applications include web sites and e-books. It's built on top of ERB and REXML.
 email: jarrett@uchicago.edu
 executables: 
@@ -36,8 +45,7 @@ files:
 - lib/quarto/rendering.rb
 - lib/quarto/url_helper.rb
 - lib/quarto/xml_doc.rb
-- quarto.gemspec
-has_rdoc: true
+has_rdoc: false
 homepage: http://github.com/jarrett/quarto
 post_install_message: 
 rdoc_options: 
@@ -61,7 +69,7 @@ requirements: []
 rubyforge_project: 
 rubygems_version: 1.2.0
 signing_key: 
-specification_version: 2
+specification_version: 3
 summary: generates HTML or any other format from XML
 test_files: 
 - spec/children_spec.rb
@@ -69,8 +77,12 @@ test_files:
 - spec/generator_spec.rb
 - spec/init_project_spec.rb
 - spec/matchers/file_matchers.rb
+- spec/sample_models.rb
 - spec/sample_project/generate.rb
 - spec/sample_project/models/company.rb
 - spec/sample_project/models/employee.rb
+- spec/sample_project/models/location.rb
+- spec/sample_project/models/mascot.rb
+- spec/sample_project/models/product.rb
 - spec/spec_helper.rb
 - spec/url_helper_spec.rb

data/quarto.gemspec

@@ -1,62 +0,0 @@
-# -*- encoding: utf-8 -*-
-
-Gem::Specification.new do |s|
-  s.name = %q{quarto}
-  s.version = "0.3.1"
-
-  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
-  s.authors = ["Jarrett Colby"]
-  s.date = %q{2009-06-05}
-  s.default_executable = %q{quarto}
-  s.description = %q{Quarto is a Ruby framework for generating collections of documents from XML. It steps in where XSLT just won't cut it. Potential applications include web sites and e-books. It's built on top of ERB and REXML.}
-  s.email = %q{jarrett@uchicago.edu}
-  s.executables = ["quarto"]
-  s.extra_rdoc_files = [
-    "README"
-  ]
-  s.files = [
-    "README",
-     "Rakefile",
-     "VERSION",
-     "bin/quarto",
-     "lib/quarto.rb",
-     "lib/quarto/children.rb",
-     "lib/quarto/config.rb",
-     "lib/quarto/element_wrapper.rb",
-     "lib/quarto/generator.rb",
-     "lib/quarto/inheritable_attributes.rb",
-     "lib/quarto/init_project.rb",
-     "lib/quarto/rendering.rb",
-     "lib/quarto/url_helper.rb",
-     "lib/quarto/xml_doc.rb",
-     "quarto.gemspec"
-  ]
-  s.has_rdoc = true
-  s.homepage = %q{http://github.com/jarrett/quarto}
-  s.rdoc_options = ["--charset=UTF-8"]
-  s.require_paths = ["lib"]
-  s.rubygems_version = %q{1.3.1}
-  s.summary = %q{generates HTML or any other format from XML}
-  s.test_files = [
-    "spec/children_spec.rb",
-     "spec/element_wrapper_spec.rb",
-     "spec/generator_spec.rb",
-     "spec/init_project_spec.rb",
-     "spec/matchers/file_matchers.rb",
-     "spec/sample_project/generate.rb",
-     "spec/sample_project/models/company.rb",
-     "spec/sample_project/models/employee.rb",
-     "spec/spec_helper.rb",
-     "spec/url_helper_spec.rb"
-  ]
-
-  if s.respond_to? :specification_version then
-    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
-    s.specification_version = 2
-
-    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
-    else
-    end
-  else
-  end
-end