inversion 0.0.1 → 0.0.2

data/manual/src/templates.page

@@ -0,0 +1,74 @@
+---
+# vim: set et nosta sw=4 ts=4 ft=textile :
+title: Templates
+layout: default
+index: 1
+filters:
+  - erb
+  - links
+  - api
+  - examples
+  - textile
+---
+
+h2. <%= page.config['title'] %>
+
+<div id="auto-toc"></div>
+
+Inversion <?api "templates":Inversion::Template ?> are the primary objects you'll be interacting with. Templates can be created from a string via <?api "Template#new":Inversion::Template.new ?>, or from a file with <?api "Template#load":Inversion::Template.load ?>.
+
+h3(#options). Template Options
+
+You can set Inversion's configuration options in a number of ways. 
+
+To set global options, Inversion supports the "Configurability":https://bitbucket.org/ged/configurability API, and registers itself with the @templates@ key. This means you can either add a 'templates' section to your Configurability config, or call <?api Inversion::Template.configure ?> yourself with an object that can be passed to @Hash#merge@.
+
+To set options on a per-template basis, you can pass an options hash to either @.load@ or @.new@, or set them from within the template itself using the <?link "configure tag":Tags#configure-tag ?>.
+
+The available options are:
+
+<notextile>
+<dl>
+	<dt>:ignore_unknown_tags</dt>
+	<dd>Setting to false causes unknown tags used in templates to raise an <code>Inversion::ParseError</code>.</dd>
+	<dd class="default">Default: true</dd>
+   
+	<dt>:on_render_error</dt>
+	<dd>
+		Dictates the behavior of exceptions during rendering. 
+		<dl>
+		  	<dt>:ignore</dt>
+			<dd>Exceptions are silently ignored.</dd>
+		  	<dt>:comment</dt>
+			<dd>Exceptions are rendered inline as comments.</dd>
+		  	<dt>:propagate</dt>
+			<dd>Exceptions bubble up to the caller of #render.</dd>
+		</dl>
+	</dd>
+    <dd class="default">Default: <code>:comment</code></dd>
+
+    <dt>:debugging_comments</dt>
+    <dd>Insert various Inversion parse and render statements while rendering.</dd>
+    <dd class="default">Default: <code>false</code></dd>
+
+    <dt>:comment_start</dt>
+    <dd>When rendering debugging comments, the comment is started with these characters.</dd>
+    <dd class="default">Default: <code>"&lt;!--"</code></dd>
+
+    <dt>:comment_end</dt>
+    <dd>When rendering debugging comments, the comment is finished with these characters.</dd>
+    <dd class="default">Default: <code>"--&gt;"</code></dd>
+
+    <dt>:template_paths</dt>
+    <dd>An array of filesystem paths to search for templates within, when loaded or included with a relative path.  The current working directory is always the last checked member of this.</dd>
+    <dd class="default">Default: <code>[]</code></dd>
+
+    <dt>:escape_format</dt>
+    <dd>The escaping <?api "strategy":Inversion::Escaping ?> used by tags such as <code>escape</code> and <code>pp</code>.</dd>
+    <dd class="default">Default: <code>:html</code></dd>
+
+    <dt>:strip_tag_lines</dt>
+    <dd>If a tag's presence introduces a blank line into the output, this option removes it.</dd>
+    <dd class="default">Default: <code>true</code></dd>
+</dl>
+</notextile>

data/spec/inversion/template/begintag_spec.rb

@@ -0,0 +1,217 @@
+#!/usr/bin/env rspec -cfd -b
+# vim: set noet nosta sw=4 ts=4 :
+
+BEGIN {
+	require 'pathname'
+	basedir = Pathname( __FILE__ ).dirname.parent.parent.parent
+	libdir = basedir + 'lib'
+
+	$LOAD_PATH.unshift( basedir.to_s ) unless $LOAD_PATH.include?( basedir.to_s )
+	$LOAD_PATH.unshift( libdir.to_s ) unless $LOAD_PATH.include?( libdir.to_s )
+}
+
+require 'rspec'
+require 'ostruct'
+require 'spec/lib/helpers'
+require 'inversion/template/begintag'
+require 'inversion/template/textnode'
+require 'inversion/template/attrtag'
+require 'inversion/template/rescuetag'
+require 'inversion/template/endtag'
+require 'inversion/renderstate'
+
+describe Inversion::Template::BeginTag do
+
+	before( :all ) do
+		setup_logging( :fatal )
+	end
+
+	after( :all ) do
+		reset_logging()
+	end
+
+
+	context "without any rescue clauses" do
+
+		before( :each ) do
+			@tag = Inversion::Template::BeginTag.new( ' ' )
+			@tag << Inversion::Template::AttrTag.new( 'foo.baz' )
+			@tag << Inversion::Template::TextNode.new( ':the stuff after the attr' )
+		end
+
+		it "should render its subnodes as-is if none of them raise an exception"  do
+			renderstate = Inversion::RenderState.new( :foo => OpenStruct.new(:baz => 'the body') )
+			renderstate << @tag
+			renderstate.to_s.should == 'the body:the stuff after the attr'
+		end
+
+		it "should use the configured error behavior of the template if a subnode raises any exception" do
+			renderstate = Inversion::RenderState.new
+			renderstate << @tag
+			renderstate.to_s.should =~ /NoMethodError/
+			renderstate.to_s.should_not =~ /the stuff after the attr/i
+		end
+
+	end
+
+	context "with a single rescue clause with no exception type" do
+
+		before( :each ) do
+			@tag = Inversion::Template::BeginTag.new( ' ' )
+
+			@attrtag = Inversion::Template::AttrTag.new( 'foo.baz' )
+			@normal_textnode = Inversion::Template::TextNode.new( ':the stuff after the attr' )
+			@rescue_textnode = Inversion::Template::TextNode.new( 'rescue stuff' )
+
+			@tag << @attrtag << @normal_textnode
+			@tag << Inversion::Template::RescueTag.new( '' )
+			@tag << @rescue_textnode
+
+			@renderstate = Inversion::RenderState.new
+		end
+
+		it "contains one rescue clause for RuntimeErrors" do
+			@tag.rescue_clauses.should == [ [[::RuntimeError], [@rescue_textnode]] ]
+		end
+
+		it "should render its subnodes as-is if none of them raise an exception"  do
+			renderstate = Inversion::RenderState.new( :foo => OpenStruct.new(:baz => 'the body') )
+			renderstate << @tag
+			renderstate.to_s.should == 'the body:the stuff after the attr'
+		end
+
+		it "should render the rescue section if a subnode raises a RuntimeError"  do
+			fooobj = Object.new
+			def fooobj.baz; raise "An exception"; end
+
+			renderstate = Inversion::RenderState.new( :foo => fooobj )
+			renderstate << @tag
+			renderstate.to_s.should == 'rescue stuff'
+		end
+
+		it "should use the configured error behavior of the template if a subnode raises an " +
+		   "exception other than RuntimeError" do
+			fooobj = Object.new
+			def fooobj.baz; raise Errno::ENOENT, "No such file or directory"; end
+
+			renderstate = Inversion::RenderState.new( :foo => fooobj )
+			renderstate << @tag
+			renderstate.to_s.should =~ /ENOENT/i
+			renderstate.to_s.should_not =~ /rescue stuff/i
+			renderstate.to_s.should_not =~ /the stuff after the attr/i
+		end
+	end
+
+
+	context "with a single rescue clause with an exception type" do
+		before( :each ) do
+			@tag = Inversion::Template::BeginTag.new( ' ' )
+
+			@attrtag = Inversion::Template::AttrTag.new( 'foo.baz' )
+			@normal_textnode = Inversion::Template::TextNode.new( ':the stuff after the attr' )
+			@rescue_textnode = Inversion::Template::TextNode.new( 'rescue stuff' )
+
+			@tag << @attrtag << @normal_textnode
+			@tag << Inversion::Template::RescueTag.new( 'SystemCallError' )
+			@tag << @rescue_textnode
+
+			@renderstate = Inversion::RenderState.new
+		end
+
+		it "contains one rescue clause for the specified exception type" do
+			@tag.rescue_clauses.should == [ [[::SystemCallError], [@rescue_textnode]] ]
+		end
+
+		it "should render its subnodes as-is if none of them raise an exception"  do
+			renderstate = Inversion::RenderState.new( :foo => OpenStruct.new(:baz => 'the body') )
+			renderstate << @tag
+			renderstate.to_s.should == 'the body:the stuff after the attr'
+		end
+
+		it "should render the rescue section if a subnode raises the specified exception type"  do
+			fooobj = Object.new
+			def fooobj.baz; raise Errno::ENOENT, "no such file or directory"; end
+
+			renderstate = Inversion::RenderState.new( :foo => fooobj )
+			renderstate << @tag
+			renderstate.to_s.should == 'rescue stuff'
+		end
+
+		it "should use the configured error behavior of the template if a subnode raises an " +
+		   "exception other than the specified type" do
+			fooobj = Object.new
+			def fooobj.baz; raise "SPlat!"; end
+
+			renderstate = Inversion::RenderState.new( :foo => fooobj )
+			renderstate << @tag
+			renderstate.to_s.should =~ /RuntimeError/i
+			renderstate.to_s.should_not =~ /rescue stuff/i
+			renderstate.to_s.should_not =~ /the stuff after the attr/i
+		end
+	end
+
+	context "with multiple rescue clauses" do
+		before( :each ) do
+			@tag = Inversion::Template::BeginTag.new( ' ' )
+
+			@attrtag = Inversion::Template::AttrTag.new( 'foo.baz' )
+			@normal_textnode = Inversion::Template::TextNode.new( ':the stuff after the attr' )
+			@rescue_textnode = Inversion::Template::TextNode.new( 'rescue stuff' )
+			@rescue_textnode2 = Inversion::Template::TextNode.new( 'alternative rescue stuff' )
+
+			@tag << @attrtag << @normal_textnode
+			@tag << Inversion::Template::RescueTag.new( '' )
+			@tag << @rescue_textnode
+			@tag << Inversion::Template::RescueTag.new( 'Errno::ENOENT, Errno::EWOULDBLOCK' )
+			@tag << @rescue_textnode2
+
+			@renderstate = Inversion::RenderState.new
+		end
+
+		it "contains a rescue tuple for each rescue tag" do
+			@tag.rescue_clauses.should == [
+				[[::RuntimeError], [@rescue_textnode]],
+				[[Errno::ENOENT, Errno::EWOULDBLOCK], [@rescue_textnode2]],
+			]
+		end
+
+		it "should render its subnodes as-is if none of them raise an exception"  do
+			renderstate = Inversion::RenderState.new( :foo => OpenStruct.new(:baz => 'the body') )
+			renderstate << @tag
+			renderstate.to_s.should == 'the body:the stuff after the attr'
+		end
+
+		it "should render the first rescue section if a subnode raises the exception it " +
+		   "specifies"  do
+			fooobj = Object.new
+			def fooobj.baz; raise "An exception"; end
+
+			renderstate = Inversion::RenderState.new( :foo => fooobj )
+			renderstate << @tag
+			renderstate.to_s.should == 'rescue stuff'
+		end
+
+		it "should render the second rescue section if a subnode raises the exception it " +
+		   "specifies"  do
+			fooobj = Object.new
+			def fooobj.baz; raise Errno::ENOENT, "no such file or directory"; end
+
+			renderstate = Inversion::RenderState.new( :foo => fooobj )
+			renderstate << @tag
+			renderstate.to_s.should == 'alternative rescue stuff'
+		end
+
+		it "should use the configured error behavior of the template if a subnode raises an " +
+		   "exception other than those specified by the rescue clauses" do
+			fooobj = Object.new
+			def fooobj.baz; raise Errno::ENOMEM, "All out!"; end
+
+			renderstate = Inversion::RenderState.new( :foo => fooobj )
+			renderstate << @tag
+			renderstate.to_s.should =~ /ENOMEM/i
+			renderstate.to_s.should_not =~ /rescue stuff/i
+			renderstate.to_s.should_not =~ /the stuff after the attr/i
+		end
+	end
+
+end

data/spec/inversion/template/defaulttag_spec.rb

@@ -0,0 +1,60 @@
+#!/usr/bin/env rspec -cfd -b
+# vim: set noet nosta sw=4 ts=4 :
+
+BEGIN {
+	require 'pathname'
+	basedir = Pathname( __FILE__ ).dirname.parent.parent.parent
+	libdir = basedir + 'lib'
+
+	$LOAD_PATH.unshift( basedir.to_s ) unless $LOAD_PATH.include?( basedir.to_s )
+	$LOAD_PATH.unshift( libdir.to_s ) unless $LOAD_PATH.include?( libdir.to_s )
+}
+
+require 'rspec'
+require 'spec/lib/helpers'
+require 'inversion/template/defaulttag'
+
+describe Inversion::Template::DefaultTag do
+
+	before( :all ) do
+		setup_logging( :fatal )
+	end
+
+	after( :all ) do
+		reset_logging()
+	end
+
+
+	it "sets a template attribute to a default value" do
+		tmpl = Inversion::Template.new( '<?default foo to 11883 ?><?attr foo ?>' )
+		tmpl.render.should == '11883'
+	end
+
+	it "doesn't override a value set on the template as an attribute" do
+		tmpl = Inversion::Template.new( '<?default foo to 11883 ?><?attr foo ?>' )
+		tmpl.foo = 'bar'
+		tmpl.render.should == 'bar'
+	end
+
+	it "can set a template attribute to the result of calling a methodchain" do
+		tmpl = Inversion::Template.
+			new( '<?default width to foo.length ?><?attr foo ?>:<?attr width ?>' )
+		tmpl.foo = 'bar'
+		tmpl.render.should == 'bar:3'
+	end
+
+	it "can format the default value" do
+		tmpl = Inversion::Template.
+			new( '<?default width to "[%02d]" % [ foo.length ] ?><?attr foo ?>:<?attr width ?>' )
+		tmpl.foo = 'bar'
+		tmpl.render.should == 'bar:[03]'
+	end
+
+	it "can render itself as a comment for template debugging" do
+		tag = Inversion::Template::DefaultTag.new( 'width to foo.length' )
+		tag.as_comment_body.should == "Default 'width': { template.foo.length }"
+	end
+
+end
+
+

data/spec/inversion/template/rescuetag_spec.rb

@@ -0,0 +1,109 @@
+#!/usr/bin/env rspec -cfd -b
+# vim: set noet nosta sw=4 ts=4 :
+
+BEGIN {
+	require 'pathname'
+	basedir = Pathname( __FILE__ ).dirname.parent.parent.parent
+	libdir = basedir + 'lib'
+
+	$LOAD_PATH.unshift( basedir.to_s ) unless $LOAD_PATH.include?( basedir.to_s )
+	$LOAD_PATH.unshift( libdir.to_s ) unless $LOAD_PATH.include?( libdir.to_s )
+}
+
+require 'rspec'
+require 'spec/lib/helpers'
+require 'inversion/template/begintag'
+require 'inversion/template/rescuetag'
+require 'inversion/template/commenttag'
+require 'inversion/template/fortag'
+require 'inversion/renderstate'
+
+describe Inversion::Template::RescueTag do
+
+	before( :all ) do
+		setup_logging( :fatal )
+	end
+
+	after( :all ) do
+		reset_logging()
+	end
+
+	it "handles a non-existant body" do
+		tag = Inversion::Template::RescueTag.new( nil )
+		tag.exception_types.should == [ ::RuntimeError ]
+	end
+
+	it "parses its body into classes" do
+		tag = Inversion::Template::RescueTag.new( 'ScriptError' )
+		tag.exception_types.should == [ ::ScriptError ]
+	end
+
+	it "handles fully-qualified class names" do
+		tag = Inversion::Template::RescueTag.new( '::ScriptError' )
+		tag.exception_types.should == [ ::ScriptError ]
+	end
+
+	it "can parse multiple exception class names" do
+		tag = Inversion::Template::RescueTag.new( '::ScriptError, Inversion::ParseError' )
+		tag.exception_types.should == [ ::ScriptError, Inversion::ParseError ]
+	end
+
+	it "can be appended to a 'begin' tag" do
+		template    = double( "template object" )
+		parserstate = Inversion::Template::Parser::State.new( template )
+		begintag    = Inversion::Template::BeginTag.new
+		rescuetag   = Inversion::Template::RescueTag.new
+		textnode    = Inversion::Template::TextNode.new( 'Yeah!' )
+		endtag      = Inversion::Template::EndTag.new
+
+		parserstate << begintag << rescuetag << textnode << endtag
+
+		parserstate.tree.should == [ begintag, endtag ]
+		begintag.rescue_clauses.should == [ [[::RuntimeError], [textnode]] ]
+	end
+
+	it "can be appended to a 'comment' tag" do
+		template    = double( "template object" )
+		parserstate = Inversion::Template::Parser::State.new( template )
+		commenttag  = Inversion::Template::CommentTag.new( 'rescue section for later' )
+		rescuetag   = Inversion::Template::RescueTag.new
+		endtag      = Inversion::Template::EndTag.new
+
+		parserstate << commenttag << rescuetag << endtag
+
+		parserstate.tree.should == [ commenttag, endtag ]
+		commenttag.subnodes.should include( rescuetag )
+	end
+
+	it "raises an error if it's about to be appended to anything other than a 'begin' or " +
+	   "'comment' tag" do
+		template    = double( "template object" )
+		parserstate = Inversion::Template::Parser::State.new( template )
+		parserstate << Inversion::Template::ForTag.new( 'foo in bar' )
+
+		expect {
+			parserstate << Inversion::Template::RescueTag.new
+		}.to raise_exception( Inversion::ParseError, /'for' tags can't have 'rescue' clauses/i )
+	end
+
+
+	it "raises an error if it's about to be appended without an opening 'begin'" do
+		template    = double( "template object" )
+		parserstate = Inversion::Template::Parser::State.new( template )
+
+		expect {
+			parserstate << Inversion::Template::RescueTag.new
+		}.to raise_exception( Inversion::ParseError, /orphaned 'rescue' tag/i )
+	end
+
+
+	it "doesn't render as anything by itself" do
+		renderstate = Inversion::RenderState.new
+		tag = Inversion::Template::RescueTag.new
+		tag.render( renderstate ).should be_nil()
+	end
+
+end
+
+
+