inversion 0.0.1

data/lib/inversion/sinatra.rb

@@ -0,0 +1,35 @@
+#!/usr/bin/env ruby
+
+begin
+	require 'inversion/tilt'
+	require 'sinatra'
+	require 'sinatra/base'
+rescue LoadError => err
+	warn "Couldn't load Inversion Sinatra support: %s: %s" % [ err.class.name, err.message ]
+end
+
+# Add support for Tilt (https://github.com/rtomayko/tilt) if it's already been loaded.
+if defined?( ::Sinatra ) # :nodoc:
+
+	# A mixin to add Inversion support to Sinatra::Base
+	module Inversion::SinatraTemplateHelpers
+
+		### Add an 'inversion' helper method to Sinatra's template DSL:
+		###
+		###   get '/' do
+		###     inversion :company_directory, :locals => { :people => People.all }
+		###   end
+		def inversion( template, options={}, locals={} )
+			render :inversion, template, options, locals
+		end
+
+	end # Inversion::SinatraTemplateHelpers
+
+	# Inject Inversion helpers as a mixin
+	# :stopdoc:
+	class Sinatra::Base
+		include Inversion::SinatraTemplateHelpers
+	end
+
+end
+

data/lib/inversion/template.rb

@@ -0,0 +1,250 @@
+#!/usr/bin/env ruby
+# vim: set noet nosta sw=4 ts=4 :
+
+require 'pathname'
+require 'inversion' unless defined?( Inversion )
+
+# Load the Configurability library if it's installed
+begin
+	require 'configurability'
+	require 'configurability/config'
+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.
+class Inversion::Template
+	include Inversion::Loggable
+
+	# Configurability support -- load template configuration from the 'templates' section
+	# of the config.
+	if defined?( Configurability )
+		extend Configurability
+		config_key :templates if respond_to?( :config_key )
+	end
+
+
+	# Load subordinate classes
+	require 'inversion/template/parser'
+	require 'inversion/template/node'
+	require 'inversion/template/tag'
+	require 'inversion/renderstate'
+
+
+	# Valid actions for 'on_render_error'
+	VALID_ERROR_ACTIONS = [
+		:ignore,
+		:comment,
+		:propagate,
+	]
+
+	### Default config values
+	DEFAULT_CONFIG = {
+		:ignore_unknown_tags => true,
+		:on_render_error     => :comment,
+		:debugging_comments  => false,
+		:comment_start       => '<!-- ',
+		:comment_end         => ' -->',
+		:template_paths      => [],
+		:escape_format       => :html,
+		:strip_tag_lines     => true,
+	}
+
+
+	### Global config
+	@config = DEFAULT_CONFIG.dup
+	class << self; attr_accessor :config; end
+
+
+	### Configure the templating system.
+	def self::configure( config )
+		Inversion.log.debug "Merging config %p with current config %p" % [ config, self.config ]
+		self.config = self.config.merge( config )
+	end
+
+
+	### Read a template object from the specified +path+.
+	def self::load( path, parsestate=nil, opts={} )
+
+		# Shift the options hash over if there isn't a parse state
+		if parsestate.is_a?( Hash )
+			opts = parsestate
+			parsestate = nil
+		end
+
+		tmpl = nil
+		path = Pathname( path )
+		template_paths = self.config[:template_paths] + [ Dir.pwd ]
+
+		# Unrestricted template location.
+		if path.absolute?
+			tmpl = path
+
+		# Template files searched under paths specified in 'template_paths', then
+		# the current working directory. First match wins.
+		else
+			tmpl = template_paths.collect {|dir| Pathname(dir) + path }.find do |fullpath|
+				fullpath.exist?
+			end
+
+			raise RuntimeError, "Unable to find template %p within configured paths %p" %
+				[ path.to_s, template_paths ] if tmpl.nil?
+		end
+
+		# We trust files read from disk
+		source = tmpl.read
+		source.untaint
+
+		# Load the instance and set the path to the source
+		template = self.new( source, parsestate, opts )
+		template.source_file = tmpl.expand_path
+
+		return template
+	end
+
+
+	### Create a new Inversion:Template with the given +source+.
+	def initialize( source, parsestate=nil, opts={} )
+		if parsestate.is_a?( Hash )
+			self.log.debug "Shifting template options: %p" % [ parsestate ]
+			opts = parsestate
+			parsestate = nil
+		else
+			self.log.debug "Parse state is: %p" % [ parsestate ]
+		end
+
+		@source       = source
+		@parser       = Inversion::Template::Parser.new( self, opts )
+		@node_tree    = []
+		@options      = self.class.config.merge( opts )
+
+		@attributes   = {}
+		@source_file  = nil
+
+		# Now parse the template source into a tree of nodes and pre-generate accessors
+		# for any attributes defined by them
+		@node_tree = @parser.parse( source, parsestate )
+		self.define_attribute_accessors
+	end
+
+
+
+	######
+	public
+	######
+
+	attr_reader :source
+
+	attr_accessor :source_file
+
+	attr_reader :attributes
+
+	attr_reader :options
+
+	attr_reader :node_tree
+
+
+	### Render the template, optionally passing a render state (if, for example, the
+	### template is being rendered inside another template).
+	def render( parentstate=nil, &block )
+		self.log.info "rendering template 0x%08x" % [ self.object_id/2 ]
+		state = Inversion::RenderState.new( parentstate, self.attributes, self.options, &block )
+
+		# Pre-render hook
+		self.walk_tree {|node| node.before_rendering(state) }
+
+		self.log.debug "  rendering node tree: %p" % [ @node_tree ]
+		self.walk_tree {|node| state << node }
+
+		# Post-render hook
+		self.walk_tree {|node| node.after_rendering(state) }
+
+		self.log.info "  done rendering template 0x%08x" % [ self.object_id/2 ]
+		return state.to_s
+	end
+	alias_method :to_s, :render
+
+
+	### Return a human-readable representation of the template object suitable
+	### for debugging.
+	def inspect
+		return "#<%s:%08x (loaded from %s) attributes: %p, node_tree: %p, options: %p>" % [
+			self.class.name,
+			self.object_id / 2,
+			self.source_file ? self.source_file : "memory",
+			self.attributes,
+			self.node_tree.map(&:as_comment_body),
+			self.options,
+		]
+	end
+
+
+	#########
+	protected
+	#########
+
+	### Proxy method: handle attribute readers/writers for attributes that aren't yet
+	### defined.
+	def method_missing( sym, *args, &block )
+		return super unless sym.to_s =~ /^([a-z]\w+)=?$/i
+		attribute = $1
+		self.install_accessors( attribute )
+
+		# Call the new method via #method to avoid a method_missing loop.
+		return self.method( sym ).call( *args, &block )
+	end
+
+
+	### Walk the template's node tree, yielding each node in turn to the given block.
+	def walk_tree( nodes=@node_tree, &block )
+		nodes.each do |node|
+			yield( node )
+		end
+	end
+
+
+	### Search for identifiers in the template's node tree and declare an accessor
+	### for each one that's found.
+	def define_attribute_accessors
+		self.walk_tree do |node|
+			self.add_attributes_from_node( node )
+		end
+
+		self.attributes.each do |key, _|
+			self.install_accessors( key )
+		end
+	end
+
+
+	### Add attributes for the given +node+'s identifiers.
+	def add_attributes_from_node( node )
+		if node.respond_to?( :identifiers )
+			node.identifiers.each do |id|
+				next if @attributes.key?( id.to_sym )
+				@attributes[ id.to_sym ] = nil
+			end
+		end
+	end
+
+
+	### Install reader and writer methods for the attribute associated with the specified +key+.
+	def install_accessors( key )
+		reader, writer = self.make_attribute_accessors( key )
+
+		self.singleton_class.send( :define_method, key, &reader )
+		self.singleton_class.send( :define_method, "#{key}=", &writer )
+	end
+
+
+	### Make method bodies
+	def make_attribute_accessors( key )
+		key = key.to_sym
+		reader = lambda { self.attributes[key] }
+		writer = lambda {|newval| self.attributes[key] = newval }
+
+		return reader, writer
+	end
+end # class Inversion::Template
+

data/lib/inversion/template/attrtag.rb

@@ -0,0 +1,120 @@
+#!/usr/bin/env ruby
+# vim: set noet nosta sw=4 ts=4 :
+
+require 'inversion/template/codetag'
+
+# Inversion attribute tag.
+#
+# Attribute tags add an accessor to a template like 'attr_accessor' does for Ruby classes.
+#
+# == Syntax
+#
+#   <?attr foo ?>
+#   <?attr "%0.2f" % foo ?>
+#
+class Inversion::Template::AttrTag < Inversion::Template::CodeTag
+
+	# <?attr foo ?>
+	tag_pattern '$(ident)' do |tag, match|
+		tag.send( :log ).debug "  Identifier is: %p" % [ match.string(1) ]
+		tag.name = match.string( 1 ).untaint.to_sym
+	end
+
+	# <?attr "%s" % foo ?>
+	tag_pattern 'tstring_beg $(tstring_content) tstring_end sp* $(op) sp* $(ident)' do |tag, match|
+		op = match.string( 2 )
+		raise Inversion::ParseError, "expected '%%', got %p instead" % [ op ] unless op == '%'
+
+		tag.format = match.string( 1 )
+		tag.name   = match.string( 3 ).untaint.to_sym
+	end
+
+	# <?attr foo.methodchain ?>
+	tag_pattern '$(ident) $( .+ )' do |tag, match|
+		tag.name = match.string( 1 ).untaint.to_sym
+		tag.methodchain = match.string( 2 )
+	end
+
+	# <?attr "%s" % foo.methodchain ?>
+	tag_pattern 'tstring_beg $(tstring_content) tstring_end sp* $(op) sp* $(ident) $( .+ )' do |tag, match|
+		op = match.string( 2 )
+		raise Inversion::ParseError, "expected '%%', got %p instead" % [ op ] unless op == '%'
+
+		tag.format      = match.string( 1 )
+		tag.name        = match.string( 3 ).untaint.to_sym
+		tag.methodchain = match.string( 4 )
+	end
+
+
+
+	### Create a new AttrTag with the given +name+, which should be a valid
+	### Ruby identifier. The +linenum+ and +colnum+ should be the line and column of
+	### the tag in the template source, if available.
+	def initialize( body, linenum=nil, colnum=nil )
+		@name        = nil
+		@format      = nil
+		@methodchain = nil
+
+		super
+
+		# Add an identifier for the tag name
+		self.identifiers << self.name.untaint.to_sym
+	end
+
+
+	######
+	public
+	######
+
+	# the name of the attribute
+	attr_accessor :name
+
+	# the format string used to format the attribute in the template (if
+	# one was declared)
+	attr_accessor :format
+
+	# the chain of methods that should be called (if any).
+	attr_accessor :methodchain
+
+
+	### Render the tag attributes of the specified +render_state+ and return them.
+	def render( render_state )
+		self.log.debug "Rendering %p with state: %p" % [ self, render_state ]
+
+		value     = nil
+		attribute = render_state.attributes[ self.name.to_sym ]
+		self.log.debug "  initial attribute: %p" % [ attribute ]
+
+		# Evaluate the method chain (if there is one) against the attribute
+		if self.methodchain
+			methodchain = "self" + self.methodchain
+			self.log.debug "  evaling methodchain: %p on: %p" % [ methodchain, attribute ]
+			value = attribute.instance_eval( methodchain )
+		else
+			value = attribute
+		end
+		self.log.debug "  evaluated value: %p" % [ value ]
+
+		return value unless value
+
+		# Apply the format if there is one
+		if self.format
+			return self.format % value
+		else
+			return value
+		end
+	end
+
+
+	### Render the tag as the body of a comment, suitable for template debugging.
+	def as_comment_body
+		comment = "%s: { template.%s" % [ self.tagname, self.name ]
+		comment << self.methodchain if self.methodchain
+		comment << " }"
+		comment << " with format: %p" % [ self.format ] if self.format
+
+		return comment
+	end
+
+end # class Inversion::Template::AttrTag
+

data/lib/inversion/template/calltag.rb

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+# vim: set noet nosta sw=4 ts=4 :
+
+require 'inversion/template/attrtag'
+
+# Inversion call tag.
+#
+# This just exists to make 'call' an alias  for 'attr'.
+#
+# == Syntax
+#
+#   <?call foo.bar ?>
+#   <?call "%0.2f" % foo.bar ?>
+
+class Inversion::Template::CallTag < Inversion::Template::AttrTag; end
+

data/lib/inversion/template/codetag.rb

@@ -0,0 +1,164 @@
+#!/usr/bin/env ruby
+# vim: set noet nosta sw=4 ts=4 :
+
+require 'ripper'
+require 'inversion/template/tag'
+
+# The base class for Inversion tags that parse the body section of the tag using
+# a Ruby parser.
+#
+# It provides a +tag_pattern+ declarative method that is used to specify a pattern of
+# tokens to match, and a block for handling tag instances that match the pattern.
+#
+#    class Inversion::Template::MyTag < Inversion::Template::CodeTag
+#    
+#        # Match a tag that looks like: <?my "string of stuff" ?>
+#        tag_pattern 'tstring_beg $(tstring_content) tstring_end' do |tag, match|
+#            tag.string = match.string( 1 )
+#        end
+#    
+#    end
+#
+# The tokens in the +tag_pattern+ are Ruby token names used by the parser. If you're creating
+# your own tag, you can dump the tokens for a particular snippet using the 'inversion'
+# command-line tool that comes with the gem:
+#
+#   $ inversion tagtokens 'attr.dump! {|thing| thing.length }'
+#   ident<"attr"> period<"."> ident<"dump!"> sp<" "> lbrace<"{"> op<"|"> \
+#     ident<"thing"> op<"|"> sp<" "> ident<"thing"> period<".">          \
+#     ident<"length"> sp<" "> rbrace<"}">
+#
+# :TODO: Finish the tag_pattern docs: placeholders, regex limitations, etc.
+#
+class Inversion::Template::CodeTag < Inversion::Template::Tag
+	include Inversion::Loggable,
+	        Inversion::AbstractClass
+
+
+	### A subclass of Ripper::TokenPattern that binds matches to the beginning and
+	### end of the matched string.
+	class TokenPattern < Ripper::TokenPattern
+
+		# the token pattern's source string
+		attr_reader :source
+
+		#########
+		protected
+		#########
+
+		### Compile the token pattern into a Regexp
+		def compile( pattern )
+			if m = /[^\w\s$()\[\]{}?*+\.]/.match( pattern )
+				raise Ripper::TokenPattern::CompileError,
+					"invalid char in pattern: #{m[0].inspect}"
+			end
+
+			buf = '^'
+			pattern.scan( /(?:\w+|\$\(|[()\[\]\{\}?*+\.]+)/ ) do |tok|
+				case tok
+				when /\w/
+					buf << map_token( tok )
+				when '$('
+					buf << '('
+				when '('
+					buf << '(?:'
+				when /[?*\[\])\.]/
+					buf << tok
+				else
+					raise ScriptError, "invalid token in pattern: %p" % [ tok ]
+				end
+			end
+			buf << '$'
+
+			Regexp.compile( buf )
+		rescue RegexpError => err
+			raise Ripper::TokenPattern::CompileError, err.message
+		end
+
+	end # class TokenPattern
+
+
+	#################################################################
+	###	C L A S S   M E T H O D S
+	#################################################################
+
+	### Return the tag patterns for this class, or those of its superclass
+	### if it doesn't override them.
+	def self::tag_patterns
+		return @tag_patterns if defined?( @tag_patterns )
+		return self.superclass.tag_patterns
+	end
+
+
+	### Declare a +token_pattern+ for tag bodies along with a +callback+ that will
+	### be called when a tag matching the pattern is instantiated.
+	def self::tag_pattern( token_pattern, &callback ) #:yield: 
+		pattern = TokenPattern.compile( token_pattern )
+		@tag_patterns = [] unless defined?( @tag_patterns )
+		@tag_patterns << [ pattern, callback ]
+	end
+
+
+	#################################################################
+	###	I N S T A N C E   M E T H O D S
+	#################################################################
+
+	### Initialize a new tag that expects Ruby code in its +body+. Calls the
+	### tag's #parse_pi_body method with the specified +body+.
+	def initialize( body, linenum=nil, colnum=nil ) # :notnew:
+		super
+
+		@body = body.strip
+		@identifiers = []
+		@matched_pattern = self.match_tag_pattern( body )
+	end
+
+
+	######
+	public
+	######
+
+	# the body of the tag
+	attr_reader :body
+
+	# the identifiers in the code contained in the tag
+	attr_reader :identifiers
+
+
+	### Render the node as text.
+	pure_virtual :render
+
+
+
+	#########
+	protected
+	#########
+
+	### Match the given +body+ against one of the tag's tag patterns, calling the
+	### block associated with the first one that matches and returning the matching
+	### pattern.
+	def match_tag_pattern( body )
+
+		self.class.tag_patterns.each do |tp, callback|
+			if match = tp.match( body.strip )
+				self.log.debug "Matched tag pattern: %p, match is: %p" % [ tp, match ]
+				callback.call( self, match )
+				return tp
+			end
+		end
+
+		self.log.error "Failed to match %p with %d patterns." %
+			[ body, self.class.tag_patterns.length ]
+
+		valid_patterns = self.class.tag_patterns.map( &:first ).map( &:source ).join( "\n  ")
+		tokenized_src = Ripper.lex( body ).collect do |tok|
+			self.log.debug "  lexed token: #{tok.inspect}"
+			"%s<%s>" % [ tok[1].to_s[3..-1], tok[2] ]
+		end.join(' ')
+
+		raise Inversion::ParseError, "malformed %s: expected one of:\n  %s\ngot:\n  %s" %
+			[ self.tagname, valid_patterns, tokenized_src ]
+	end
+
+end # class Inversion::Template::CodeTag
+