jarrett-quarto 0.1.0

data/README

@@ -0,0 +1,19 @@
+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.
+
+Using Quarto
+=============
+
+Thorough documentation doesn't exist yet. For now, see spec/sample_project.

data/spec/children_spec.rb

@@ -0,0 +1,68 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe Quarto::ElementWrapperChildren 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
+			@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.length.should == 2 # In the sample XML file, 37Signals has two employees.
+			@company.employees.each do |employee|
+				employee.should be_a(Employee)
+			end
+		end
+	end
+	
+	context 'an ElementWrapper instance with a parent' do
+		before :each 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
+end
+
+describe Quarto::Children do
+	before :each do
+		Quarto.xml_source = File.open(SAMPLE_DIR + '/xml/companies.xml')
+		@xml = Quarto.xml_doc
+		@element = @xml.elements['companies/company']
+		@company = Company.new(@element)
+	end
+	
+	it 'should respond to Enumerable methods' do
+		[:collect, :select, :inject, :detect, :include?].each do |meth|
+			@company.employees.should respond_to(meth)
+		end
+	end
+	
+	it 'should support empty?' do
+		@company.employees.should respond_to(:empty?)
+		@company.employees.empty?.should == false
+	end
+	
+	context '#each' do
+		it 'should iterate over each child' do
+			expected_names = ['DHH', 'Jamis Buck']
+			actual_names = []
+			@company.employees.each do |employee|
+				actual_names << employee.name
+			end
+			actual_names.should == expected_names
+		end
+	end
+end

data/spec/element_wrapper_spec.rb

@@ -0,0 +1,91 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe Quarto::ElementWrapper 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
+		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)
+		end
+		
+		it 'should define methods from specified child elements' do
+			@company.should respond_to(:name)
+			@company.name.should == '37Signals'
+		end
+		
+		it 'should define methods from XML attributes by default' do
+			@company.should respond_to(:reality)
+			@company.reality.should == 'real'
+		end
+		
+		it 'should expose methods of the underlying REXML::Element' do
+			# Just test a few methods that don't require parameters
+			[:root_node, :text, :node_type, :document, :children].each do |meth|
+				@company.should respond_to(meth)
+				@company.send(meth).should == @element.send(meth)
+			end
+		end
+		
+		it 'should set the element_name based on the class name' do
+			Company.element_name.should == 'company'
+		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|
+				lambda { Company.new(bad) }.should raise_error(ArgumentError)
+			end
+		end
+	end
+	
+	context '#find' do
+		it 'should find matching elements based on :xpath' do
+			companies = Company.find(:all, :xpath => 'companies/company')
+			companies.should be_a(Array)
+			companies.each do |company|
+				company.should be_a(Company)
+			end
+			companies = Company.find(:all, :xpath => "companies/company[@reality='real']")
+			companies.should be_a(Array)
+			companies.length.should == 1 # There is one real company in the example XML file: 37Signals
+			companies[0].name.should == '37Signals'
+			
+			companies = Company.find(:all, :xpath => "companies/company[name='Milliways']")
+			companies.should be_a(Array)
+			companies.length.should == 1
+			companies[0].name.should == 'Milliways'
+		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')
+		end
+		
+		it 'should return all matching elements when the quantifier is :all' do
+			companies = Company.find(:all, :xpath => 'companies/company')
+			companies.length.should == 5 # There are five companies in the example XML file
+		end
+		
+		it 'should return the first matching element when the quantifier is :first' do
+			company = Company.find(:first, :xpath => 'companies/company')
+			company.should be_a(Company)
+			company.name.should == '37Signals'
+		end
+		
+		it 'should return the last matching element when the quantifier is :first' do
+			company = Company.find(:last, :xpath => 'companies/company')
+			company.should be_a(Company)
+			company.name.should == 'Milliways'
+		end
+	end
+end
+

data/spec/generator_spec.rb

@@ -0,0 +1,129 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+require 'fileutils'
+
+describe Quarto do
+	context '.generatate' do
+		class MockGenerator
+			def generate(&block)
+				instance_eval(&block)
+			end
+			
+			def do_something_in_the_block; end
+		end
+		
+		before :each do
+			@mock_generator = MockGenerator.new
+			Quarto::Generator.stub!(:new).and_return(@mock_generator)
+		end
+		
+		after :each do
+			# This must happen after the mocking has been configured for each example
+			# Otherwise, none of the mocking will have any effect
+			Quarto.generate(SAMPLE_DIR) do
+				do_something_in_the_block
+			end
+		end
+		
+		it 'should call Quarto::Generator.new and pass the project directory' do
+			Quarto::Generator.should_receive(:new).with(SAMPLE_DIR).and_return(@mock_generator)
+		end
+		
+		it 'should call #generate on the Generator' do
+			@mock_generator.should_receive(:generate)
+		end
+		
+		it 'should execute the block in the context of the Generator' do
+			@mock_generator.should_receive(:do_something_in_the_block)
+		end
+	end
+end
+
+module Quarto
+	# This will be used in the specs below--see the method aliasing
+	def self.testable_generate(&block)
+		GenerationTesting.generation_block = block
+	end
+	
+	module GenerationTesting
+		def self.generation_block
+			@generation_block
+		end
+		
+		def self.generation_block=(block)
+			@generation_block = block
+		end
+	end
+end
+
+describe Quarto::Generator do
+	context '.new' do
+		it 'should accept a path to a project directory' do
+			Quarto::Generator.new(SAMPLE_DIR).should be_a(Quarto::Generator)
+		end
+	end
+	
+	context '#generate from the sample project' do
+		include Quarto::UrlHelper
+		
+		before :all do
+			# Quarto.generate will now return the passed block as a proc
+			# instead of envoking the whole framework
+			Quarto.module_eval do
+				class << self
+					
+					alias_method :untestable_generate, :generate
+					alias_method :generate, :testable_generate
+				end
+			end
+			
+			@generator = Quarto::Generator.new(SAMPLE_DIR)
+			
+			# Clear the directories
+			FileUtils.rm_rf @generator.output_path
+			
+			# Now that we've aliased the methods and load has been called GenerationTesting.generation_block should be set
+			load @generator.generate_file_path
+			@generator.generate(&Quarto::GenerationTesting.generation_block)
+		end
+		
+		after :all do
+			# Reset Quarto.generate to its old behavior
+			Quarto.module_eval do
+				class << self
+					alias_method :generate, :untestable_generate
+				end
+			end
+		end
+		
+		it 'should set #output_path' do
+			@generator.output_path.should == SAMPLE_DIR + '/output'
+		end
+		
+		it 'should create a directory under #output_path' do
+			File.exists?(@generator.output_path).should be_true
+		end
+		
+		it 'should create a single file for all the companies' do
+			Dir.glob(@generator.output_path + '/*.html').collect { |f| File.basename(f) }.should == ['companies.html']
+		end
+		
+		it 'should create one file for each employee' do
+			expected_files = ['DHH', 'Jamis Buck', 'Hank Hill', 'Buckley', 'Apu Nahasapeemapetilon', 'Kenan Thompson', 'Kel Mitchell', 'Marvin'].sort.collect { |name| urlize(name) + '.html' }
+			Dir.glob(@generator.output_path + '/employees/*.html').collect { |f| File.basename(f) }.sort.should == expected_files
+		end
+		
+		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|
+				html.should include(name)
+			end
+		end
+		
+		it 'should pass the employee names into the template' do
+			['DHH', 'Jamis Buck', 'Hank Hill', 'Buckley', 'Apu Nahasapeemapetilon', 'Kenan Thompson', 'Kel Mitchell', 'Marvin'].each do |name|
+				html = File.read(@generator.output_path + '/employees/' + urlize(name) + '.html')
+				html.should include(name)
+			end
+		end
+	end
+end

data/spec/sample_project/generate.rb

@@ -0,0 +1,11 @@
+Quarto.generate do
+	Quarto.config(:site_root => 'http://localhost/')
+
+	use_xml('companies.xml')
+
+	render 'companies.html.erb', '', 'companies.html', :companies => Company.find(:all)
+
+	Employee.find(:all).each do |employee|
+		render 'employee.html.erb', 'employees', "#{urlize(employee.name)}.html", :employee => employee
+	end
+end

data/spec/sample_project/models/company.rb

@@ -0,0 +1,9 @@
+class Company < Quarto::ElementWrapper
+	element_attrs :name, :industry
+	
+	children :employees
+	
+	def competitors
+		@competitors ||= self.class.find(:all, :xpath => "companies/company[industry='#{industry}' and name!='#{name}']")
+	end
+end

data/spec/sample_project/models/employee.rb

@@ -0,0 +1,10 @@
+class Employee < Quarto::ElementWrapper
+	element_attrs :name
+	
+	parent :company
+	
+	def self.from_element(el)
+		employee = new(el)
+		employee.ivs_from_elements('name')
+	end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,10 @@
+require 'rubygems'
+require 'test/unit'
+require 'spec'
+
+SPEC_DIR = File.expand_path(File.dirname(__FILE__))
+SAMPLE_DIR = SPEC_DIR + '/sample_project'
+
+require(File.expand_path(File.dirname(__FILE__)) + '/../lib/quarto')
+require(File.expand_path(File.dirname(__FILE__)) + '/sample_project/models/company')
+require(File.expand_path(File.dirname(__FILE__)) + '/sample_project/models/employee')

data/spec/url_helper_spec.rb

@@ -0,0 +1,23 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe Quarto::UrlHelper do
+	include Quarto::UrlHelper
+	
+	context '#urlize' do
+		it 'should automatically convert non-strings to strings' do
+			urlize(1).should == '1'
+		end
+		
+		it 'should replace spaces with dashes' do
+			urlize('John Smith').should == 'John-Smith'
+		end
+		
+		it 'should not change numbers' do
+			urlize('a10b').should == 'a10b'
+		end
+		
+		it 'should not change dashes and underscores' do
+			urlize('foo-bar_baz').should == 'foo-bar_baz'
+		end
+	end
+end

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification 
+name: jarrett-quarto
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Jarrett Colby
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-06-04 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+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: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+files: 
+- README
+has_rdoc: true
+homepage: http://github.com/jarrett/quarto
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: generates HTML or any other format from XML
+test_files: 
+- spec/children_spec.rb
+- spec/element_wrapper_spec.rb
+- spec/generator_spec.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