inversion 0.12.3 → 0.14.0

data/lib/inversion.rb

@@ -26,10 +26,10 @@ module Inversion
 	warn ">>> Inversion requires Ruby 1.9.2 or later. <<<" if RUBY_VERSION < '1.9.2'
 
 	# Library version constant
-	VERSION = '0.12.3'
+	VERSION = '0.14.0'
 
 	# Version-control revision constant
-	REVISION = %q$Revision: 100ed23eb2ba $
+	REVISION = %q$Revision: 9bb165feaf57 $
 
 
 	### Get the Inversion version.

data/lib/inversion/renderstate.rb

@@ -21,8 +21,9 @@ class Inversion::RenderState
 
 		### Create a new RenderState::Scope with its initial tag locals set to
 		### +locals+.
-		def initialize( locals={} )
+		def initialize( locals={}, fragments={} )
 			@locals = locals
+			@fragments = fragments
 		end
 
 
@@ -41,7 +42,7 @@ class Inversion::RenderState
 		### Return a copy of the receiving Scope merged with the given +values+,
 		### which can be either another Scope or a Hash.
 		def +( values )
-			return Scope.new( @locals.merge(values) )
+			return Scope.new( self.__locals__.merge(values), self.__fragments__ )
 		end
 
 
@@ -52,6 +53,12 @@ class Inversion::RenderState
 		alias_method :to_hash, :__locals__
 
 
+		### Returns the Hash of rendered fragments that belong to this scope.
+		def __fragments__
+			return @fragments
+		end
+
+
 		#########
 		protected
 		#########
@@ -60,7 +67,7 @@ class Inversion::RenderState
 		### and map them into values from the Scope's locals.
 		def method_missing( sym, *args, &block )
 			return super unless sym =~ /^\w+$/
-			@locals[ sym ]
+			return @locals[ sym ].nil? ? @fragments[ sym ] : @locals[ sym ]
 		end
 
 	end # class Scope
@@ -104,6 +111,7 @@ class Inversion::RenderState
 		# as a Symbol
 		@subscriptions      = Hash.new {|hsh, k| hsh[k] = [] } # Auto-vivify to an Array
 		@published_nodes    = Hash.new {|hsh, k| hsh[k] = [] }
+		@fragments          = Hash.new {|hsh, k| hsh[k] = [] }
 
 	end
 
@@ -127,6 +135,9 @@ class Inversion::RenderState
 	# Published nodes, keyed by subscription
 	attr_reader :published_nodes
 
+	# Fragment nodes, keyed by fragment name
+	attr_reader :fragments
+
 	# The stack of rendered output destinations, most-recent last.
 	attr_reader :destinations
 
@@ -296,14 +307,7 @@ class Inversion::RenderState
 
 	### Turn the rendered node structure into the final rendered String.
 	def to_s
-		strings = @output.flatten.map( &:to_s )
-
-		if enc = self.options[ :encoding ]
-			self.log.debug "Encoding rendered template parts to %s" % [ enc ]
-			strings.map! {|str| str.encode(enc, invalid: :replace, undef: :replace) }
-		end
-
-		return strings.join
+		return self.stringify_nodes( @output )
 	end
 
 
@@ -337,6 +341,23 @@ class Inversion::RenderState
 	end
 
 
+	### Add one or more rendered +nodes+ to the state as a reusable fragment associated
+	### with the specified +name+.
+	def add_fragment( name, *nodes )
+		nodes.flatten!
+		self.fragments[ name.to_sym ] = nodes
+		self.scope.__fragments__[ name.to_sym ] = nodes
+	end
+
+
+	### Return the current fragments Hash rendered as Strings.
+	def rendered_fragments
+		return self.fragments.each_with_object( {} ) do |(key, nodes), accum|
+			accum[ key ] = self.stringify_nodes( nodes )
+		end
+	end
+
+
 	### Handle an +exception+ that was raised while appending a node by calling the
 	### #errhandler.
 	def handle_render_error( node, exception )
@@ -454,6 +475,20 @@ class Inversion::RenderState
 	end
 
 
+	### Return the given +nodes+ as a String in the configured encoding.
+	def stringify_nodes( nodes )
+		self.log.debug "Rendering nodes: %p" % [ nodes ]
+		strings = nodes.flatten.map( &:to_s )
+
+		if enc = self.options[ :encoding ]
+			self.log.debug "Encoding rendered template parts to %s" % [ enc ]
+			strings.map! {|str| str.encode(enc, invalid: :replace, undef: :replace) }
+		end
+
+		return strings.join
+	end
+
+
 	### Handle attribute methods.
 	def method_missing( sym, *args, &block )
 		return super unless sym.to_s =~ /^\w+$/

data/lib/inversion/template.rb

@@ -13,9 +13,76 @@ rescue LoadError
 end
 
 
-# The main template class. Instances of this class are created by parsing template
-# source and combining the resulting node tree with a set of attributes that
-# can be used to populate it when rendered.
+# The main template class.
+#
+# Inversion templates are the primary objects you'll be interacting with. Templates
+# can be created from a string:
+#
+#   Inversion::Template.new( template_source )
+#
+# or from a file:
+#
+#   Inversion::Template.load( 'path/to/template.tmpl' )
+#
+#
+# == Template Options
+#
+# Inversion supports the {Configurability}[http://rubygems.org/gems/configurability]
+# API, and registers itself with the +templates+ key. This means you can either add
+# a +templates+ section to your Configurability config, or call
+# ::configure yourself with a config Hash (or something that quacks like one).
+#
+# To set options on a per-template basis, you can pass an options hash to either
+# Inversion::Template::load or Inversion::Template::new, or set them from within the template
+# itself using the {config tag}[rdoc-ref:Tags@config].
+#
+# The available options are:
+#
+# [:ignore_unknown_tags]
+#   Setting to false causes unknown tags used in templates to raise an
+#   Inversion::ParseError. Defaults to +true+.
+#
+# [:on_render_error]
+#   Dictates the behavior of exceptions during rendering. Defaults to +:comment+.
+#
+#   [:ignore]
+#     Exceptions are silently ignored.
+#   [:comment]
+#     Exceptions are rendered inline as comments.
+#   [:propagate]
+#     Exceptions bubble up to the caller of Inversion::Template#render.
+#
+#
+# [:debugging_comments]
+#   Insert various Inversion parse and render statements while rendering. Defaults to +false+.
+#
+# [:comment_start]
+#   When rendering debugging comments, the comment is started with these characters.
+#   Defaults to <code>"<!--"</code>.
+#
+# [:comment_end]
+#   When rendering debugging comments, the comment is finished with these characters.
+#   Defaults to <code>"-->"</code>.
+#
+# [:template_paths]
+#   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. Defaults to <code>[]</code>.
+#
+# [:escape_format]
+#   The escaping used by tags such as +escape+ and +pp+. Default: +:html+.
+#
+# [:strip_tag_lines]
+#   If a tag's presence introduces a blank line into the output, this option
+#   removes it. Defaults to +true+.
+#
+# [:stat_delay]
+#   Templates know when they've been altered on disk, and can dynamically
+#   reload themselves in long running applications.  Setting this option creates
+#   a purposeful delay between reloads for busy servers. Defaults to +0+
+#   (disabled).
+#
+#
 class Inversion::Template
 	extend Loggability
 	include Inversion::DataUtilities
@@ -65,13 +132,15 @@ class Inversion::Template
 	}.freeze
 
 
-	### Global config
-	@config = DEFAULT_CONFIG.dup
+	##
+	# Global config
 	class << self; attr_accessor :config; end
+	self.config = DEFAULT_CONFIG.dup
 
+	##
 	# Global template search path
-	@template_paths = []
 	class << self; attr_accessor :template_paths; end
+	self.template_paths = []
 
 
 	### Configure the templating system.
@@ -145,8 +214,9 @@ class Inversion::Template
 
 		@source       = source
 		@node_tree    = [] # Parser expects this to always be an Array
-		@options      = opts
+		@options      = self.class.config.merge( opts )
 		@attributes   = {}
+		@fragments    = {}
 		@source_file  = nil
 		@created_at   = Time.now
 		@last_checked = @created_at
@@ -159,6 +229,7 @@ class Inversion::Template
 	def initialize_copy( other )
 		@options    = deep_copy( other.options )
 		@attributes = deep_copy( other.attributes )
+		@fragments  = deep_copy( other.fragments )
 	end
 
 
@@ -175,6 +246,9 @@ class Inversion::Template
 	# The Hash of template attributes
 	attr_reader :attributes
 
+	# The Hash of rendered template fragments
+	attr_reader :fragments
+
 	# The Template's configuration options hash
 	attr_reader :options
 
@@ -216,6 +290,8 @@ class Inversion::Template
 		opts = self.options
 		opts.merge!( parentstate.options ) if parentstate
 
+		self.fragments.clear
+
 		state = Inversion::RenderState.new( parentstate, self.attributes, opts, &block )
 
 		# self.log.debug "  rendering node tree: %p" % [ @node_tree ]
@@ -223,6 +299,8 @@ class Inversion::Template
 		self.log.info "  done rendering template 0x%08x: %0.4fs" %
 			[ self.object_id/2, state.time_elapsed ]
 
+		self.fragments.replace( state.rendered_fragments )
+
 		return state.to_s
 	end
 	alias_method :to_s, :render

data/lib/inversion/template/attrtag.rb

@@ -82,7 +82,7 @@ class Inversion::Template::AttrTag < Inversion::Template::CodeTag
 		value = self.evaluate( renderstate ) # :FIXME: or return value # nil or false?
 
 		# Apply the format if there is one
-		if self.format
+		if self.format && value
 			return self.format % value
 		else
 			return value

data/lib/inversion/template/begintag.rb

@@ -20,15 +20,15 @@ require 'inversion/template/rescuetag'
 #   <?begin ?><?call employees.length ?><?end?>
 #
 #   <?begin ?>
-#		<?for employee in employees.all ?>
-#			<?attr employee.name ?> --> <?attr employee.title ?>
-#		<?end for?>
+#       <?for employee in employees.all ?>
+#           <?attr employee.name ?> --> <?attr employee.title ?>
+#       <?end for?>
 #   <?rescue DatabaseError => err ?>
-#		Oh no!! I can't talk to the database for some reason.  The
-#		error was as follows:
-#		<pre>
-#			<?attr err.message ?>
-#		</pre>
+#       Oh no!! I can't talk to the database for some reason.  The
+#       error was as follows:
+#       <pre>
+#           <?attr err.message ?>
+#       </pre>
 #   <?end?>
 #
 class Inversion::Template::BeginTag < Inversion::Template::Tag

data/lib/inversion/template/fragmenttag.rb

@@ -0,0 +1,60 @@
+#!/usr/bin/env ruby
+# vim: set noet nosta sw=4 ts=4 :
+
+require 'inversion/template/tag'
+require 'inversion/template/containertag'
+
+
+# Inversion 'fragment' tag.
+#
+# This tag provides a way to generate a fragment of content once in a template
+# as an attribute, and then reuse it later either in the same template or even
+# outside of it.
+#
+# == Syntax
+#
+#   <?fragment subject ?>Receipt for Order #<?call order.number ?><?end subject ?>
+#
+class Inversion::Template::FragmentTag < Inversion::Template::Tag
+	include Inversion::Template::ContainerTag
+
+
+	### Create a new FragmentTag with the given +body+.
+	def initialize( body, line=nil, column=nil )
+		super
+
+		key = self.body[ /^([a-z]\w+)$/ ] or
+			raise Inversion::ParseError,
+				"malformed key: expected simple identifier, got %p" % [ self.body ]
+		@key = key.to_sym
+	end
+
+
+	######
+	public
+	######
+
+	# The fragment key; corresponds to the name of the attribute that will be set
+	# by the rendered contents of the fragment.
+	attr_reader :key
+
+
+	### Render the fragment and store it as an attribute.
+	def render( renderstate )
+		self.log.debug "Publishing %d nodes as %s" % [ self.subnodes.length, self.key ]
+		rendered_nodes = []
+		renderstate.with_destination( rendered_nodes ) do
+			sn = self.render_subnodes( renderstate )
+			self.log.debug "  subnodes are: %p" % [ sn ]
+			sn
+		end
+
+		self.log.debug "  rendered nodes are: %p" % [ rendered_nodes ]
+		renderstate.add_fragment( self.key, rendered_nodes )
+
+		return nil
+	end
+
+
+end # class Inversion::Template::FragmentTag
+

data/lib/inversion/template/rescuetag.rb

@@ -42,7 +42,7 @@ class Inversion::Template::RescueTag < Inversion::Template::Tag
 
 
 	### Parsing callback -- check to be sure the node tree can have the
-	### 'else' tag appended to it.
+	### 'rescue' tag appended to it.
 	def before_appending( parsestate )
 		condtag = parsestate.node_stack.reverse.find do |node|
 			case node

data/spec/{lib/helpers.rb → helpers.rb}

@@ -1,40 +1,18 @@
 #!/usr/bin/ruby
 # coding: utf-8
 
-BEGIN {
-	require 'pathname'
-	basedir = Pathname.new( __FILE__ ).dirname.parent
-
-	libdir = basedir + "lib"
-
-	$LOAD_PATH.unshift( libdir.to_s ) unless $LOAD_PATH.include?( libdir.to_s )
-}
-
 # SimpleCov test coverage reporting; enable this using the :coverage rake task
-if ENV['COVERAGE']
-	require 'simplecov'
-	SimpleCov.start do
-		add_filter 'spec'
-		add_group "Tags" do |file|
-			file.filename =~ /tag.rb$/
-		end
-		add_group "Needing tests" do |file|
-			file.covered_percent < 90
-		end
-	end
-end
+require 'simplecov' if ENV['COVERAGE']
 
 require 'rspec'
 require 'loggability'
 require 'loggability/spechelpers'
 
 require 'inversion'
-require 'spec/lib/constants'
 
 
 ### RSpec helper functions.
 module Inversion::SpecHelpers
-	include Inversion::TestConstants
 
 	###############
 	module_function
@@ -52,22 +30,21 @@ module Inversion::SpecHelpers
 		return "<?#{name} #{data} ?>"
 	end
 
-
 end
 
 
 ### Mock with RSpec
 RSpec.configure do |c|
-	include Inversion::TestConstants
-	include Loggability::SpecHelpers
 
-	c.mock_with :rspec
+	c.run_all_when_everything_filtered = true
+	c.filter_run :focus
+	c.order = 'random'
+	c.mock_with( :rspec ) do |mock|
+		mock.syntax = :expect
+	end
 
 	c.include( Inversion::SpecHelpers )
 	c.include( Loggability::SpecHelpers )
-
-	c.filter_run_excluding( :ruby_1_9_only => true ) if
-		Inversion::SpecHelpers.vvec( RUBY_VERSION ) < Inversion::SpecHelpers.vvec('1.9.0')
 end
 
 # vim: set nosta noet ts=4 sw=4: