inversion 0.0.1

data/lib/inversion.rb

@@ -0,0 +1,98 @@
+#!/usr/bin/env ruby
+# vim: set noet nosta sw=4 ts=4 :
+
+require 'logger'
+
+
+# The Inversion templating system. This module provides the namespace for all the other
+# classes and modules, and contains the logging subsystem. A good place to start for 
+# documentation would be to check out the examples in the README, and then 
+# Inversion::Template for a list of tags, configuration options, etc.
+#
+# == Authors
+#
+# * Michael Granger <ged@FaerieMUD.org>
+# * Mahlon E. Smith <mahlon@martini.nu>
+#
+# :main: README.rdoc
+#
+module Inversion
+
+	warn ">>> Inversion requires Ruby 1.9.2 or later. <<<" if RUBY_VERSION < '1.9.2'
+
+	require 'inversion/exceptions'
+	require 'inversion/mixins'
+	require 'inversion/utils'
+	require 'inversion/monkeypatches'
+
+	# Library version constant
+	VERSION = '0.0.1'
+
+	# Version-control revision constant
+	REVISION = %q$Revision: 73c3d8215868 $
+
+	#
+	# Logging
+	#
+
+	# Log levels
+	LOG_LEVELS = {
+		'debug' => Logger::DEBUG,
+		'info'  => Logger::INFO,
+		'warn'  => Logger::WARN,
+		'error' => Logger::ERROR,
+		'fatal' => Logger::FATAL,
+	}.freeze
+
+	# Log levels keyed by level
+	LOG_LEVEL_NAMES = LOG_LEVELS.invert.freeze
+
+	@default_logger = Logger.new( $stderr )
+	@default_logger.level = $DEBUG ? Logger::DEBUG : Logger::WARN
+
+	@default_log_formatter = Inversion::LogFormatter.new( @default_logger )
+	@default_logger.formatter = @default_log_formatter
+
+	@logger = @default_logger
+
+
+	class << self
+		# the log formatter that will be used when the logging subsystem is reset
+		attr_accessor :default_log_formatter
+
+		# the logger that will be used when the logging subsystem is reset
+		attr_accessor :default_logger
+
+		# the logger that's currently in effect
+		attr_accessor :logger
+		alias_method :log, :logger
+		alias_method :log=, :logger=
+	end
+
+
+	### Reset the global logger object to the default
+	def self::reset_logger
+		self.logger = self.default_logger
+		self.logger.level = Logger::WARN
+		self.logger.formatter = self.default_log_formatter
+	end
+
+
+	### Returns +true+ if the global logger has not been set to something other than
+	### the default one.
+	def self::using_default_logger?
+		return self.logger == self.default_logger
+	end
+
+
+	### Get the Inversion version.
+	def self::version_string( include_buildnum=false )
+		vstring = "%s %s" % [ self.name, VERSION ]
+		vstring << " (build %s)" % [ REVISION[/: ([[:xdigit:]]+)/, 1] || '0' ] if include_buildnum
+		return vstring
+	end
+
+	require 'inversion/template'
+
+end # module Inversion
+

data/lib/inversion/exceptions.rb

@@ -0,0 +1,21 @@
+#!/usr/bin/env ruby
+# vim: set noet nosta sw=4 ts=4 :
+
+#--
+module Inversion
+
+	# An exception class raised from the Inversion::Template::Parser when
+	# a problem is encountered while parsing a template.
+	class ParseError < ::RuntimeError; end
+
+	# An exception class raised when a problem is detected in a template
+	# configuration option.
+	class OptionsError < ::RuntimeError; end
+
+	# An exception class raised when a template includes itself, either
+	# directly or indirectly.
+	class StackError < ::RuntimeError; end
+
+end # module Inversion
+
+

data/lib/inversion/mixins.rb

@@ -0,0 +1,236 @@
+#!/usr/bin/env ruby
+# vim: set nosta noet ts=4 sw=4:
+
+require 'logger'
+
+
+module Inversion
+
+	# Add logging to a Inversion class. Including classes get #log and 
+	# #log_debug methods.
+	#
+	#   class MyClass
+	#       include Inversion::Loggable
+	#       
+	#       def a_method
+	#           self.log.debug "Doing a_method stuff..."
+	#       end
+	#   end
+	#
+	module Loggable
+
+		### A logging proxy class that wraps calls to the logger into calls that include
+		### the name of the calling class.
+		class ClassNameProxy # :nodoc:
+
+			### Create a new proxy for the given +klass+.
+			def initialize( klass, force_debug=false )
+				@classname   = klass.name
+				@force_debug = force_debug
+			end
+
+			### Delegate debug messages to the global logger with the appropriate class name.
+			def debug( msg=nil, &block )
+				Inversion.logger.add( Logger::DEBUG, msg, @classname, &block )
+			end
+
+			### Delegate info messages to the global logger with the appropriate class name.
+			def info( msg=nil, &block )
+				return self.debug( msg, &block ) if @force_debug
+				Inversion.logger.add( Logger::INFO, msg, @classname, &block )
+			end
+
+			### Delegate warn messages to the global logger with the appropriate class name.
+			def warn( msg=nil, &block )
+				return self.debug( msg, &block ) if @force_debug
+				Inversion.logger.add( Logger::WARN, msg, @classname, &block )
+			end
+
+			### Delegate error messages to the global logger with the appropriate class name.
+			def error( msg=nil, &block )
+				return self.debug( msg, &block ) if @force_debug
+				Inversion.logger.add( Logger::ERROR, msg, @classname, &block )
+			end
+
+			### Delegate fatal messages to the global logger with the appropriate class name.
+			def fatal( msg=nil, &block )
+				Inversion.logger.add( Logger::FATAL, msg, @classname, &block )
+			end
+
+		end # ClassNameProxy
+
+		#########
+		protected
+		#########
+
+		### Copy constructor -- clear the original's log proxy.
+		def initialize_copy( original )
+			@log_proxy = @log_debug_proxy = nil
+			super
+		end
+
+		### Return the proxied logger.
+		def log
+			@log_proxy ||= ClassNameProxy.new( self.class )
+		end
+
+		### Return a proxied "debug" logger that ignores other level specification.
+		def log_debug
+			@log_debug_proxy ||= ClassNameProxy.new( self.class, true )
+		end
+
+	end # module Loggable
+
+
+	# Hides your class's ::new method and adds a +pure_virtual+ method generator for
+	# defining API methods. If subclasses of your class don't provide implementations of
+	# "pure_virtual" methods, NotImplementedErrors will be raised if they are called.
+	#
+	#   # AbstractClass
+	#   class MyBaseClass
+	#       include Inversion::AbstractClass
+	#
+	#       # Define a method that will raise a NotImplementedError if called
+	#       pure_virtual :api_method
+	#   end
+	#
+	module AbstractClass
+
+		### Methods to be added to including classes
+		module ClassMethods
+
+			### Define one or more "virtual" methods which will raise
+			### NotImplementedErrors when called via a concrete subclass.
+			def pure_virtual( *syms )
+				syms.each do |sym|
+					define_method( sym ) do |*args|
+						raise ::NotImplementedError,
+							"%p does not provide an implementation of #%s" % [ self.class, sym ],
+							caller(1)
+					end
+				end
+			end
+
+
+			### Turn subclasses' new methods back to public.
+			def inherited( subclass )
+				subclass.module_eval { public_class_method :new }
+				super
+			end
+
+		end # module ClassMethods
+
+
+		extend ClassMethods
+
+		### Inclusion callback
+		def self::included( mod )
+			super
+			if mod.respond_to?( :new )
+				mod.extend( ClassMethods )
+				mod.module_eval { private_class_method :new }
+			end
+		end
+
+
+	end # module AbstractClass
+
+
+	# A collection of utilities for working with Hashes.
+	module HashUtilities
+
+		###############
+		module_function
+		###############
+
+		### Return a version of the given +hash+ with its keys transformed
+		### into Strings from whatever they were before.
+		###
+		###    stringhash = stringify_keys( symbolhash )
+		###
+		def stringify_keys( hash )
+			newhash = {}
+
+			hash.each do |key,val|
+				if val.is_a?( Hash )
+					newhash[ key.to_s ] = stringify_keys( val )
+				else
+					newhash[ key.to_s ] = val
+				end
+			end
+
+			return newhash
+		end
+
+
+		### Return a duplicate of the given +hash+ with its identifier-like keys
+		### untainted and transformed into symbols from whatever they were before.
+		###
+		###    symbolhash = symbolify_keys( stringhash )
+		###
+		def symbolify_keys( hash )
+			newhash = {}
+
+			hash.each do |key,val|
+				keysym = key.to_s.dup.untaint.to_sym
+
+				if val.is_a?( Hash )
+					newhash[ keysym ] = symbolify_keys( val )
+				else
+					newhash[ keysym ] = val
+				end
+			end
+
+			return newhash
+		end
+		alias_method :internify_keys, :symbolify_keys
+
+	end # module HashUtilities
+
+
+	# A mixin that adds configurable escaping to a tag class.
+	# 
+	#   class MyTag < Inversion::Template::Tag
+	#       include Inversion::Escaping
+	#   
+	#       def render( renderstate )
+	#           val = self.get_rendered_value
+	#           return self.escape( val.to_s, renderstate )
+	#       end
+	#   end
+	#
+	# To add a new kind of escaping to Inversion, add a #escape_<formatname> method to this
+	# module similar to #escape_html.
+	module Escaping
+
+		# The fallback escape format
+		DEFAULT_ESCAPE_FORMAT = :none
+
+
+		### Escape the +output+ using the format specified by the given +render_state+'s config.
+		def escape( output, render_state )
+			format = render_state.options[:escape_format] || DEFAULT_ESCAPE_FORMAT
+			return output if format == :none
+
+			unless self.respond_to?( "escape_#{format}" )
+				self.log.error "Format %p not supported. To add support, define a #escape_%s to %s" %
+					[ format, format, __FILE__ ]
+				raise Inversion::OptionsError, "No such escape format %p" % [ format ]
+			end
+
+			return self.__send__( "escape_#{format}", output )
+		end
+
+
+		### Escape the given +output+ using HTML entity-encoding.
+		def escape_html( output )
+			return output.
+				gsub( /&/, '&amp;' ).
+				gsub( /</, '&lt;' ).
+				gsub( />/, '&gt;' )
+		end
+
+	end # Escaping
+
+end # module Inversion
+

data/lib/inversion/monkeypatches.rb

@@ -0,0 +1,20 @@
+#!/usr/bin/env ruby
+# vim: set nosta noet ts=4 sw=4:
+
+require 'inversion' unless defined?( Inversion )
+require 'ripper'
+
+# Monkeypatch mixin to expose the 'tokens' instance variable of 
+# Ripper::TokenPattern::MatchData. Included in Ripper::TokenPattern::MatchData.
+module Inversion::RipperAdditions
+
+	# the array of token tuples
+	attr_reader :tokens
+
+end
+
+# :stopdoc:
+class Ripper::TokenPattern::MatchData
+	include Inversion::RipperAdditions
+end
+

data/lib/inversion/renderstate.rb

@@ -0,0 +1,337 @@
+#!/usr/bin/env ruby
+# vim: set noet nosta sw=4 ts=4 :
+
+require 'inversion' unless defined?( Inversion )
+
+
+# An object that provides an encapsulation of the template's state while it is rendering.
+class Inversion::RenderState
+	include Inversion::Loggable
+
+	### Create a new RenderState. If the template is being rendered inside another one, the
+	### containing template's RenderState will be passed as the +containerstate+. The 
+	### +initial_attributes+ will be deep-copied, and the +options+ will be merged with
+	### Inversion::Template::DEFAULT_CONFIG. The +block+ is stored for use by
+	### template nodes.
+	def initialize( containerstate=nil, initial_attributes={}, options={}, &block )
+
+		# Shift hash arguments if created without a parent state
+		if containerstate.is_a?( Hash )
+			options = initial_attributes
+			initial_attributes = containerstate
+			containerstate = nil
+		end
+
+		self.log.debug "Creating a render state with attributes: %p" %
+			[ initial_attributes ]
+
+		@containerstate     = containerstate
+		@options            = Inversion::Template::DEFAULT_CONFIG.merge( options )
+		@attributes         = [ deep_copy(initial_attributes) ]
+		@block              = block
+		@default_errhandler = self.method( :default_error_handler )
+		@errhandler         = @default_errhandler
+
+		# The rendered output Array, and the stack of render destinations
+		@output             = []
+		@destinations       = [ @output ]
+
+		# Hash of subscribed Nodes, keyed by the subscription key as a Symbol
+		@subscriptions      = Hash.new {|hsh, k| hsh[k] = [] } # Auto-vivify
+
+	end
+
+
+	######
+	public
+	######
+
+	# The Inversion::RenderState of the containing template, if any
+	attr_reader :containerstate
+
+	# The config options passed in from the template
+	attr_reader :options
+
+	# The block passed to the template's #render method, if there was one
+	attr_reader :block
+
+	# Subscribe placeholders for publish/subscribe
+	attr_reader :subscriptions
+
+	# The stack of rendered output destinations, most-recent last.
+	attr_reader :destinations
+
+	# The callable object that handles exceptions raised when a node is appended
+	attr_reader :errhandler
+
+	# The default error handler
+	attr_reader :default_errhandler
+
+
+	### Return the hash of attributes that are currently in effect in the
+	### rendering state.
+	def attributes
+		return @attributes.last
+	end
+
+
+	### Evaluate the specified +code+ in the context of itself and
+	### return the result.
+	def eval( code )
+		self.log.debug "Evaling: %p" [ code ]
+		return self.instance_eval( code )
+	end
+
+
+	### Override the state's attributes with the given +overrides+, call the +block+, then
+	### restore the attributes to their original values.
+	def with_attributes( overrides )
+		raise LocalJumpError, "no block given" unless block_given?
+		self.log.debug "Overriding template attributes with: %p" % [ overrides ]
+
+		begin
+			@attributes.push( @attributes.last.merge(overrides) )
+			yield( self )
+		ensure
+			@attributes.pop
+		end
+	end
+
+
+	### Override the state's render destination, call the block, then restore the original
+	### destination when the block returns.
+	def with_destination( new_destination )
+		raise LocalJumpError, "no block given" unless block_given?
+		self.log.debug "Overriding render destination with: %p" % [ new_destination ]
+
+		begin
+			@destinations.push( new_destination )
+			yield
+		ensure
+			self.log.debug "  removing overridden render destination: %p" % [ @destinations.last ]
+			@destinations.pop
+		end
+
+		return new_destination
+	end
+
+
+	### Set the state's error handler to +handler+ for the duration of the block, restoring
+	### the previous handler after the block exits. +Handler+ must respond to #call, and will
+	### be called with two arguments: the node that raised the exception, and the exception object
+	### itself.
+	def with_error_handler( handler )
+		original_handler = self.errhandler
+		raise ArgumentError, "%p doesn't respond_to #call" unless handler.respond_to?( :call )
+		@errhandler = handler
+
+		yield
+
+	ensure
+		@errhandler = original_handler
+	end
+
+
+	### Return the current rendered output destination.
+	def destination
+		return self.destinations.last
+	end
+
+
+	### Returns a new RenderState containing the attributes and options of the receiver
+	### merged with those of the +otherstate+.
+	def merge( otherstate )
+		merged = self.dup
+		merged.merge!( otherstate )
+		return merged
+	end
+
+
+	### Merge the attributes and options of the +otherstate+ with those of the receiver,
+	### replacing any with the same keys.
+	def merge!( otherstate )
+		self.attributes.merge!( otherstate.attributes )
+		self.options.merge!( otherstate.options )
+		return self
+	end
+
+
+	### Append operator -- add an node to the final rendered output. If the +node+ renders 
+	### as an object that itself responds to the #render method, #render will be called and 
+	### the return value will be appended instead. This will continue until the returned
+	### object either doesn't respond to #render or #renders as itself.
+	def <<( node )
+		self.log.debug "Appending a %p to %p" % [ node.class, self ]
+		self.destination << self.make_node_comment( node ) if self.options[:debugging_comments]
+		original_node = node
+		previous_node = nil
+
+		begin
+			# Allow render to be delegated to subobjects
+			while node.respond_to?( :render ) && node != previous_node
+				self.log.debug "    delegated rendering to: %p" % [ node ]
+				previous_node = node
+				node = node.render( self )
+			end
+
+			self.log.debug "  adding a %p to the destination (%p)" %
+				[ node.class, self.destination.class ]
+			self.destination << node
+			self.log.debug "    just appended %p to %p" % [ node, self.destination ]
+		rescue ::StandardError => err
+			self.log.debug "  handling a %p while rendering: %s" % [ err.class, err.message ]
+			self.destination << self.handle_render_error( original_node, err )
+		end
+
+		return self
+	end
+
+
+	### Turn the rendered node structure into the final rendered String.
+	def to_s
+		return @output.flatten.map( &:to_s ).join
+	end
+
+
+	### Publish the given +nodes+ to all subscribers to the specified +key+.
+	def publish( key, *nodes )
+		key = key.to_sym
+
+		self.containerstate.publish( key, *nodes ) if self.containerstate
+		self.subscriptions[ key ].each do |subscriber|
+			subscriber.publish( *nodes )
+		end
+	end
+	alias_method :publish_nodes, :publish
+
+
+	### Subscribe the given +node+ to nodes published with the specified +key+.
+	def subscribe( key, node )
+		key = key.to_sym
+		self.subscriptions[ key ] << node
+	end
+
+
+	### Handle an +exception+ that was raised while appending a node by calling the
+	### #errhandler.
+	def handle_render_error( node, exception )
+		self.log.error "%s while rendering %p: %s" %
+			[ exception.class.name, node.as_comment_body, exception.message ]
+
+		handler = self.errhandler
+		raise ScriptError, "error handler %p isn't #call-able!" % [ handler ] unless
+			handler.respond_to?( :call )
+
+		self.log.debug "Handling %p with handler: %p" % [ exception.class, handler ]
+		return handler.call( self, node, exception )
+
+	rescue ::StandardError => err
+		# Handle exceptions from overridden error handlers (re-raised or errors in
+		# the handler itself) via the default handler.
+		if handler && handler != self.default_errhandler
+			self.log.error "%p (re)raised from custom error handler %p" % [ err.class, handler ]
+			self.default_errhandler.call( self, node, exception )
+		else
+			raise( err )
+		end
+	end
+
+
+	### Default exception handler: Handle an +exception+ while rendering +node+ according to the 
+	### behavior specified by the `on_render_error` option. Returns the string which should be
+	### appended to the output, if any.
+	def default_error_handler( state, node, exception )
+		case self.options[:on_render_error].to_s
+		when 'ignore'
+			self.log.debug "  not rendering anything for the error"
+			return ''
+
+		when 'comment'
+			self.log.debug "  rendering error as a comment"
+			msg = "%s: %s" % [ exception.class.name, exception.message ]
+			return self.make_comment( msg )
+
+		when 'propagate'
+			self.log.debug "  propagating error while rendering"
+			raise( exception )
+
+		else
+			raise Inversion::OptionsError,
+				"unknown exception-handling mode: %p" % [ self.options[:on_render_error] ]
+		end
+	end
+
+
+	### Return a human-readable representation of the object.
+	def inspect
+		return "#<%p:0x%08x containerstate: %s, attributes: %s, destination: %p>" % [
+			self.class,
+			self.object_id / 2,
+			self.containerstate ? "0x%08x" % [ self.containerstate.object_id ] : "nil",
+			self.attributes.keys.sort.join(', '),
+			self.destination.class,
+		]
+	end
+
+
+	#########
+	protected
+	#########
+
+	### Return the +node+ as a comment if debugging comments are enabled.
+	def make_node_comment( node )
+		comment_body = node.as_comment_body or return ''
+		return self.make_comment( comment_body )
+	end
+
+
+	### Return the specified +content+ inside of the configured comment characters.
+	def make_comment( content )
+		return [
+			self.options[:comment_start],
+			content,
+			self.options[:comment_end],
+		].join
+	end
+
+
+	### Handle attribute methods.
+	def method_missing( sym, *args, &block )
+		return super unless sym.to_s =~ /^[a-z]\w+[\?=!]?$/
+		self.log.debug "mapping missing method call to attribute: %p" % [ sym ]
+		return self.attributes[ sym ]
+	end
+
+
+	#######
+	private
+	#######
+
+	### Recursively copy the specified +obj+ and return the result.
+	def deep_copy( obj )
+		Inversion.log.debug "Deep copying: %p" % [ obj ]
+
+		# Handle mocks during testing
+		return obj if obj.class.name == 'RSpec::Mocks::Mock'
+
+		return case obj
+			when NilClass, Numeric, TrueClass, FalseClass, Symbol
+				obj
+
+			when Array
+				obj.map {|o| deep_copy(o) }
+
+			when Hash
+				newhash = {}
+				obj.each do |k,v|
+					newhash[ deep_copy(k) ] = deep_copy( v )
+				end
+				newhash
+
+			else
+				obj.clone
+			end
+	end
+
+end # class Inversion::RenderState
+