inversion 0.0.1

data/lib/inversion/template/iftag.rb

@@ -0,0 +1,69 @@
+#!/usr/bin/env ruby
+# vim: set noet nosta sw=4 ts=4 :
+
+require 'inversion/mixins'
+require 'inversion/template/attrtag'
+require 'inversion/template/containertag'
+require 'inversion/template/conditionaltag'
+require 'inversion/template/elsiftag'
+require 'inversion/template/elsetag'
+
+# Inversion 'if' tag.
+#
+# This tag causes a section of the template to be rendered only if its methodchain or attribute
+# is a true value.
+#
+# == Syntax
+#
+#   <?if attr ?>...<?end?>
+#   <?if obj.method ?>...<?end?>
+#
+class Inversion::Template::IfTag < Inversion::Template::AttrTag
+	include Inversion::Loggable,
+	        Inversion::Template::ContainerTag,
+	        Inversion::Template::ConditionalTag
+
+	# Inherits AttrTag's tag patterns
+
+	### Render the tag's contents if the condition is true, or any else or elsif sections
+	### if the condition isn't true.
+	def render( state )
+		self.enable_rendering if super
+		self.render_subnodes( state )
+		return nil
+	end
+
+
+	### Render the tag's subnodes according to the tag's logical state.
+	def render_subnodes( renderstate )
+		self.log.debug "Rendering subnodes. Rendering initially %s" %
+			[ self.rendering_enabled? ? "enabled" : "disabled" ]
+
+		# walk the subtree, modifying the logic flags for else and elsif tags,
+		# and rendering nodes if rendering is enabled
+		self.subnodes.each do |node|
+			case node
+			when Inversion::Template::ElsifTag
+				self.log.debug "  logic switch: %p..." % [ node ]
+				if !self.rendering_was_enabled? && node.render( renderstate )
+					self.enable_rendering
+				else
+					self.disable_rendering
+				end
+
+			when Inversion::Template::ElseTag
+				self.log.debug "  logic switch: %p..." % [ node ]
+				if !self.rendering_was_enabled?
+					self.enable_rendering
+				else
+					self.disable_rendering
+				end
+
+			else
+				renderstate << node if self.rendering_enabled?
+			end
+		end
+	end
+
+end # class Inversion::Template::IfTag
+

data/lib/inversion/template/importtag.rb

@@ -0,0 +1,70 @@
+#!/usr/bin/env ruby
+# vim: set noet nosta sw=4 ts=4 :
+
+require 'inversion/template/tag'
+
+# Inversion import tag.
+#
+# The import tag copies one or more attributes from an enclosing template so they
+# only need to be set once.
+#
+# == Syntax
+#
+#   <?import txn ?>
+#   <?import foo, bar ?>
+#
+class Inversion::Template::ImportTag < Inversion::Template::Tag
+
+	### Create a new ImportTag with the given +name+, which should be a valid
+	### Ruby identifier.
+	def initialize( body, linenum=nil, colnum=nil )
+		super
+		@attributes = body.split( /\s*,\s*/ ).collect {|name| name.untaint.strip.to_sym }
+	end
+
+
+	######
+	public
+	######
+
+	# the names of the attributes to import
+	attr_reader :attributes
+
+
+	### Merge the inherited renderstate into the current template's +renderstate+.
+	def render( renderstate )
+		if (( cstate = renderstate.containerstate ))
+			self.log.debug "Importing inherited attributes: %p from %p" % [ @attributes, cstate.attributes ]
+
+			# Pick out the attributes that are being imported
+			inherited_attrs = @attributes.inject( {} ) do |attrs, key|
+				attrs[ key ] = cstate.attributes[ key ]
+				attrs
+			end
+
+			# Merge, but overwrite unset values with inherited ones
+			renderstate.attributes.merge!( inherited_attrs ) do |key, oldval, newval|
+				if oldval.nil?
+					self.log.debug "Importing attribute %p: %p" % [ key, newval ]
+					newval
+				else
+					self.log.debug "Not importing attribute %p: already set to %p" % [ key, oldval ]
+					oldval
+				end
+			end
+
+		else
+			self.log.debug "No-op import: no parent attributes set."
+		end
+
+		return nil
+	end
+
+
+	### Render the tag as the body of a comment, suitable for template debugging.
+	def as_comment_body
+		return "Import %s" % [ self.attributes.join(', ') ]
+	end
+
+end # class Inversion::Template::ImportTag
+

data/lib/inversion/template/includetag.rb

@@ -0,0 +1,51 @@
+#!/usr/bin/env ruby
+# vim: set noet nosta sw=4 ts=4 :
+
+require 'pathname'
+require 'inversion/mixins'
+require 'inversion/template/tag'
+
+
+# Inversion 'include' tag.
+#
+# A tag that inserts other template files into the current template.
+#
+# == Example
+#
+#   <?include /an/absolute/path/to/a/different/template.tmpl ?>
+#   <?include a/relative/path/to/a/different/template.tmpl ?>
+#
+#
+class Inversion::Template::IncludeTag < Inversion::Template::Tag
+	include Inversion::Loggable
+
+
+	### Create a new IncludeTag with the specified +path+.
+	def initialize( path, linenum=nil, colnum=nil )
+		super
+		self.log.debug "Body is: %p" % [ @body ]
+		@path = @body
+		@included_template = nil
+	end
+
+
+	######
+	public
+	######
+
+	# The path of the included template
+	attr_reader :path
+
+
+	### Parser callback -- Load the included template and check for recursive includes.
+	def before_appending( parsestate )
+		@included_template = parsestate.load_subtemplate( self.path )
+	end
+
+
+	def after_appending( parsestate )
+		parsestate.append_tree( @included_template.node_tree )
+	end
+
+end # class Inversion::Template::IncludeTag
+

data/lib/inversion/template/node.rb

@@ -0,0 +1,102 @@
+#!/usr/bin/env ruby
+# vim: set noet nosta sw=4 ts=4 :
+
+require 'inversion/mixins'
+require 'inversion/template' unless defined?( Inversion::Template )
+
+# Inversion template node base class. Template text is parsed by the
+# Inversion::Template::Parser into nodes, and appended to a tree
+# that is later walked when the template is rendered.
+# 
+# This class is abstract; it just defines the API that other nodes
+# are expected to implement.
+class Inversion::Template::Node
+	include Inversion::AbstractClass
+
+
+	### Create a new TextNode with the specified +source+.
+	def initialize( body, linenum=nil, colnum=nil )
+		@body    = body
+		@linenum = linenum
+		@colnum  = colnum
+	end
+
+
+	######
+	public
+	######
+
+	# The line number the node was parsed from in the template source (if known)
+	attr_reader :linenum
+
+	# The column number the node was parsed from in the template source (if known)
+	attr_reader :colnum
+
+
+	### Render the node using the given +render_state+. By default, rendering a node
+	### returns +nil+.
+	def render( render_state )
+		return nil
+	end
+
+
+	### Render the node as a comment
+	def as_comment_body
+		return self.inspect
+	end
+
+
+	### Returns +true+ if the node introduces a new parsing/rendering scope.
+	def is_container?
+		return false
+	end
+	alias_method :container?, :is_container?
+
+
+	### Return the location of the tag in the template, if it was parsed from one (i.e.,
+	### if it was created with a StringScanner)
+	def location
+		return "line %s, column %s" % [
+			self.linenum || '??',
+			self.colnum  || '??',
+		]
+	end
+
+
+	### Default (no-op) implementation of the before_appending callback. This exists so defining
+	### the append callbacks are optional for Node's subclasses.
+	def before_appending( state )
+		# Nothing to do
+		return nil
+	end
+	alias_method :before_append, :before_appending
+
+
+	### Default (no-op) implementation of the after_appending callback. This exists so defining
+	### the append callbacks are optional for Node's subclasses.
+	def after_appending( state )
+		# Nothing to do
+		return nil
+	end
+	alias_method :after_append, :after_appending
+
+
+	### Default (no-op) implementation of the before_rendering callback. This exists so defining
+	### the rendering callbacks are optional for Node's subclasses.
+	def before_rendering( state=nil )
+		# Nothing to do
+		return nil
+	end
+	alias_method :before_render, :before_rendering
+
+
+	### Default (no-op) implementation of the after_rendering callback. This exists so defining
+	### the rendering callbacks are optional for Node's subclasses.
+	def after_rendering( state=nil )
+		# Nothing to do
+		return nil
+	end
+	alias_method :after_render, :after_rendering
+
+end # class Inversion::Template::Node
+

data/lib/inversion/template/parser.rb

@@ -0,0 +1,297 @@
+#!/usr/bin/env ruby
+# encoding: utf-8
+# vim: set noet nosta sw=4 ts=4 :
+
+require 'inversion/template' unless defined?( Inversion::Template )
+require 'inversion/mixins'
+require 'inversion/template/textnode'
+require 'inversion/template/tag'
+require 'inversion/template/endtag'
+
+# This is the parser for Inversion templates. It takes template source and
+# returns a tree of Inversion::Template::Node objects (if parsing is successful).
+class Inversion::Template::Parser
+	include Inversion::Loggable
+
+	# The pattern for matching a tag opening
+	TAG_OPEN = /[\[<]\?/
+
+	# The pattern for matching a tag.
+	TAG_PATTERN = %r{
+		(?<tagstart>#{TAG_OPEN})    # Tag opening: either <? or [?
+		(?<tagname>[a-z]\w*)        # The name of the tag
+		(?:\s+                      # At least once whitespace character between the tagname and body
+		    (?<body>.+?)            # The body of the tag
+		)?
+		\s*
+		(?<tagend>\?[\]>])          # Tag closing: either ?] or ?>
+	}x
+
+	# Valid tagends by tagstart
+	MATCHING_BRACKETS = {
+		'<?' => '?>',
+		'[?' => '?]',
+	}
+
+	# Default values for parser configuration options.
+	DEFAULT_OPTIONS = {
+		:ignore_unknown_tags => true,
+	}
+
+
+	### Create a new Inversion::Template::Parser with the specified config +options+.
+	def initialize( template, options={} )
+		@template = template
+		@options  = DEFAULT_OPTIONS.merge( options )
+	end
+
+
+	######
+	public
+	######
+
+	# The parser's config options
+	attr_reader :options
+
+
+	### Parse the given +source+ into one or more Inversion::Template::Nodes and return
+	### it as an Array.
+	def parse( source, inherited_state=nil )
+		state = nil
+
+		if inherited_state
+			inherited_state.template = @template
+			state = inherited_state
+		else
+			state = Inversion::Template::Parser::State.new( @template, self.options )
+		end
+
+		self.log.debug "Starting parse of template source (%0.2fK, %s)" %
+			[ source.bytesize/1024.0, source.encoding ]
+
+		last_pos = last_linenum = last_colnum = 0
+		source.scan( TAG_PATTERN ) do |*|
+			match = Regexp.last_match
+			start_pos, end_pos = match.offset( 0 )
+			linenum            = match.pre_match.count( "\n" ) + 1
+			colnum             = match.pre_match.length - (match.pre_match.rindex("\n") || -1)
+
+			# Error on <?...?] and vice-versa.
+			unless match[:tagend] == MATCHING_BRACKETS[match[:tagstart]]
+				raise Inversion::ParseError,
+					"malformed tag %p: mismatched start and end brackets at line %d, column %d" %
+					[ match[0], linenum, colnum ]
+			end
+
+			# Check for nested tags
+			if match[0].index( TAG_OPEN, 2 ) 
+				raise Inversion::ParseError, "unclosed or nested tag %p at line %d, column %d" %
+					[ match[0], linenum, colnum ]
+			end
+
+			self.log.debug "  found a tag at offset: %d (%p) (line %d, col %d)" %
+				[ start_pos, abbrevstring(match[0]), linenum, colnum ]
+
+			# If there were characters between the end of the last match and
+			# the beginning of the tag, create a text node with them
+			unless last_pos == start_pos
+				text = match.pre_match[ last_pos..-1 ]
+				self.log.debug "  adding literal text node: %p" % [ abbrevstring(text) ]
+				state << Inversion::Template::TextNode.new( text, last_linenum, last_colnum )
+			end
+
+			self.log.debug "  creating tag with tagname: %p, body: %p" %
+				[ match[:tagname], match[:body] ]
+
+			tag = Inversion::Template::Tag.create( match[:tagname], match[:body], linenum, colnum )
+			if tag.nil?
+				unless state.options[ :ignore_unknown_tags ]
+					raise Inversion::ParseError, "Unknown tag %p at line %d, column %d" %
+						[ match[:tagname], linenum, colnum ]
+				end
+
+			    tag = Inversion::Template::TextNode.new( match[0], linenum, colnum )
+			end
+
+			self.log.debug "  created tag: %p" % [ tag ]
+			state << tag
+
+			# Keep offsets for the next match
+			last_pos     = end_pos
+			last_linenum = linenum + match[0].count( "\n" )
+			last_colnum  = match[0].length - ( match[0].rindex("\n") || -1 )
+		end
+
+		# If there are any characters left over after the last tag
+		remainder = source[ last_pos..-1 ]
+		if remainder && !remainder.empty?
+			self.log.debug "Remainder after last tag: %p" % [ abbrevstring(remainder) ]
+
+			# Detect unclosed tags
+			if remainder.index( "<?" ) || remainder.index( "[?" )
+				raise Inversion::ParseError,
+					"unclosed tag after line %d, column %d" % [ last_linenum, last_colnum ]
+			end
+
+			# Add any remaining text as a text node
+			state << Inversion::Template::TextNode.new( remainder, last_linenum, last_colnum )
+		end
+
+		return state.tree
+	end
+
+
+	#######
+	private
+	#######
+
+	### Return at most +length+ characters long from the given +string+, appending +ellipsis+
+	### at the end if it was truncated.
+	def abbrevstring( string, length=30, ellipsis='…' )
+		return string if string.length < length
+		length -= ellipsis.length
+		return string[ 0, length ] + ellipsis
+	end
+
+
+	# Parse state object class. State objects keep track of where in the parse tree
+	# new nodes should be appended, and manages inclusion.
+	class State
+		include Inversion::Loggable
+
+		### Create a new State object
+		def initialize( template, options={} )
+			@template      = template
+			@options       = options.dup
+			@tree          = []
+			@node_stack    = [ @tree ]
+			@include_stack = []
+		end
+
+
+		### Copy constructor -- duplicate inner structures.
+		def initialize_copy( original )
+			@template      = original.template
+			@options       = original.options.dup
+			@tree          = @tree.map( &:dup )
+			@node_stack    = [ @tree ]
+			@include_stack = original.include_stack.dup
+		end
+
+
+		######
+		public
+		######
+
+		# The parse options in effect for this parse state
+		attr_reader :options
+
+		# The template object for this parser state
+		attr_accessor :template
+
+		# The stack of templates that have been loaded for this state; for loop detection.
+		attr_reader :include_stack
+
+		# The stack of containers
+		attr_reader :node_stack
+
+
+		### Append operator: add nodes to the correct part of the parse tree.
+		def <<( node )
+			self.log.debug "Appending %p" % [ node ]
+
+			node.before_appending( self )
+			self.node_stack.last << node
+
+			if node.is_container?
+				# Containers get pushed onto the stack so they get appended to
+				self.node_stack.push( node )
+			else
+				# Container nodes' #after_appending gets called in #pop
+				node.after_appending( self )
+			end
+
+			return self
+		rescue Inversion::ParseError => err
+			raise err, "%s at %s" % [ err.message, node.location ]
+		end
+
+
+		### Append another Array of nodes onto this state's node tree.
+		def append_tree( newtree )
+			newtree.each do |node|
+				self.node_stack.last << node
+			end
+		end
+
+
+		### Returns the tree if it's well formed.
+		def tree
+			unless self.is_well_formed?
+				raise Inversion::ParseError, "Unclosed container tag: %s, from %s" %
+					[ self.node_stack.last.tagname, self.node_stack.last.location ]
+			end
+			return @tree
+		end
+
+
+		### Check to see if all open tags have been closed.
+		def is_well_formed?
+			return self.node_stack.length == 1
+		end
+		alias_method :well_formed?, :is_well_formed?
+
+
+		### Pop one level off of the node stack and return it.
+		def pop
+			closed_node = self.node_stack.pop
+
+			# If there's nothing on the node stack, we've popped the top-level
+			# Array, which means there wasn't an opening container.
+			raise Inversion::ParseError, "unbalanced end: no open tag" if
+				self.node_stack.empty?
+
+			closed_node.after_appending( self )
+
+			return closed_node
+		end
+
+
+		### Return the node that is currently being appended to, or +nil+ if there aren't any
+		### opened container nodes.
+		def current_node
+			return self.node_stack.last
+		end
+
+
+		### Clear any parsed nodes from the state, leaving the options and include_stack intact.
+		def clear_nodes
+			@tree       = []
+			@node_stack = [ @tree ]
+		end
+
+
+		### Load a subtemplate from the specified +path+, checking for recursive-dependency.
+		def load_subtemplate( path )
+			if self.include_stack.include?( path )
+				stack_desc = ( self.include_stack + [path] ).join( ' --> ' )
+				msg = "Recursive load of %p detected: from %s" % [ path, stack_desc ]
+
+				self.log.error( msg )
+				raise Inversion::StackError, msg
+			end
+
+			self.log.debug "Include stack is: %p" % [ self.include_stack ]
+
+			substate = self.dup
+			substate.clear_nodes
+			substate.include_stack.push( path )
+
+			return Inversion::Template.load( path, substate, self.options )
+		end
+
+	end # class Inversion::Template::Parser::State
+
+end # class Inversion::Template::Parser
+
+