inversion 1.3.1 → 1.5.0

data/lib/inversion/template/publishtag.rb

@@ -1,5 +1,4 @@
 # -*- ruby -*-
-# frozen_string_literal: true
 # vim: set noet nosta sw=4 ts=4 :
 
 require 'inversion/template' unless defined?( Inversion::Template )
@@ -31,7 +30,7 @@ class Inversion::Template::PublishTag < Inversion::Template::Tag
 	include Inversion::Template::ContainerTag
 
 
-	### Create a new PublishTag with the given +body+.
+	### Create a new PublishTag with the given `body`.
 	def initialize( body, line=nil, column=nil )
 		super
 
@@ -50,7 +49,7 @@ class Inversion::Template::PublishTag < Inversion::Template::Tag
 	attr_reader :key
 
 
-	### Render the published subnodes in the context of the given +renderstate+, but
+	### Render the published subnodes in the context of the given `renderstate`, but
 	### save them for publication after the render is done.
 	def render( renderstate )
 		self.log.debug "Publishing %d nodes as %s" % [ self.subnodes.length, self.key ]

data/lib/inversion/template/rescuetag.rb

@@ -1,5 +1,4 @@
 # -*- ruby -*-
-# frozen_string_literal: true
 # vim: set noet nosta sw=4 ts=4 :
 
 require 'inversion/template' unless defined?( Inversion::Template )
@@ -72,7 +71,7 @@ class Inversion::Template::RescueTag < Inversion::Template::Tag
 	private
 	#######
 
-	### Parse one or more exception classes from the given +rescuespec+ and return them.
+	### Parse one or more exception classes from the given `rescuespec` and return them.
 	def parse_exception_types( rescuespec )
 		return [ ::RuntimeError ] if rescuespec.nil? || rescuespec == ''
 

data/lib/inversion/template/subscribetag.rb

@@ -1,5 +1,4 @@
 # -*- ruby -*-
-# frozen_string_literal: true
 # vim: set noet nosta sw=4 ts=4 :
 
 require 'inversion/template' unless defined?( Inversion::Template )
@@ -29,7 +28,7 @@ require 'inversion/template/tag'
 #
 class Inversion::Template::SubscribeTag < Inversion::Template::Tag
 
-	### Create a new SubscribeTag with the given +body+.
+	### Create a new SubscribeTag with the given `body`.
 	def initialize( body, line=nil, column=nil )
 		super
 
@@ -60,7 +59,7 @@ class Inversion::Template::SubscribeTag < Inversion::Template::Tag
 	attr_reader :content
 
 
-	### Tell the +renderstate+ that this tag is interested in nodes that are published with
+	### Tell the `renderstate` that this tag is interested in nodes that are published with
 	### its key.
 	def before_rendering( renderstate )
 		@content.clear
@@ -74,7 +73,7 @@ class Inversion::Template::SubscribeTag < Inversion::Template::Tag
 	end
 
 
-	### Pub/sub callback. Called from the RenderState when a PublishTag publishes +nodes+
+	### Pub/sub callback. Called from the RenderState when a PublishTag publishes `nodes`
 	### with the same key as the current tag.
 	def publish( *nodes )
 		self.log.debug "Adding published nodes %p to %p" % [ nodes, @content ]

data/lib/inversion/template/tag.rb

@@ -1,5 +1,4 @@
 # -*- ruby -*-
-# frozen_string_literal: true
 # vim: set noet nosta sw=4 ts=4 :
 
 require 'loggability'
@@ -105,7 +104,7 @@ class Inversion::Template::Tag < Inversion::Template::Node
 	end
 
 
-	### Safely load the specified +tagfile+.
+	### Safely load the specified `tagfile`.
 	def self::load( tagfile )
 		tagrequire = tagfile[ %r{inversion/template/\w+tag} ] or
 			raise "tag file %p doesn't look like a tag plugin" % [ tagfile ]
@@ -118,7 +117,7 @@ class Inversion::Template::Tag < Inversion::Template::Node
 	end
 
 
-	### Create a new Inversion::Template::Tag from the specified +tagname+ and +body+.
+	### Create a new Inversion::Template::Tag from the specified `tagname` and `body`.
 	def self::create( tagname, body, linenum=nil, colnum=nil )
 		tagname =~ /^(\w+)$/i or raise ArgumentError, "invalid tag name %p" % [ tagname ]
 		tagtype = $1.downcase
@@ -137,7 +136,7 @@ class Inversion::Template::Tag < Inversion::Template::Node
 	### I N S T A N C E   M E T H O D S
 	########################################################################
 
-	### Create a new Inversion::Template::Tag with the specified +body+.
+	### Create a new Inversion::Template::Tag with the specified `body`.
 	def initialize( body, linenum=nil, colnum=nil )
 		super
 		@body = body.to_s.strip

data/lib/inversion/template/textnode.rb

@@ -1,5 +1,4 @@
 # -*- ruby -*-
-# frozen_string_literal: true
 # vim: set noet nosta sw=4 ts=4 :
 
 require 'inversion/template' unless defined?( Inversion::Template )
@@ -8,7 +7,7 @@ require 'inversion/template/node'
 # Inversion text node class -- container for static content in templates between tags.
 class Inversion::Template::TextNode < Inversion::Template::Node
 
-	### Create a new TextNode with the specified +source+.
+	### Create a new TextNode with the specified `source`.
 	def initialize( body, linenum=nil, colnum=nil )
 		@body = body
 		super

data/lib/inversion/template/timedeltatag.rb

@@ -1,5 +1,4 @@
 # -*- ruby -*-
-# frozen_string_literal: true
 # vim: set noet nosta sw=4 ts=4 :
 
 require 'uri'
@@ -74,7 +73,7 @@ class Inversion::Template::TimeDeltaTag < Inversion::Template::AttrTag
 	private
 	#######
 
-	### Return a string describing +seconds+ as an approximate interval of time.
+	### Return a string describing `seconds` as an approximate interval of time.
 	def timeperiod( seconds )
 		return case
 			when seconds < MINUTES - 5

data/lib/inversion/template/unlesstag.rb

@@ -1,5 +1,4 @@
 # -*- ruby -*-
-# frozen_string_literal: true
 # vim: set noet nosta sw=4 ts=4 :
 
 require 'inversion/mixins'

data/lib/inversion/template/uriencodetag.rb

@@ -1,5 +1,4 @@
 # -*- ruby -*-
-# frozen_string_literal: true
 # vim: set noet nosta sw=4 ts=4 :
 
 require 'uri'
@@ -19,7 +18,7 @@ class Inversion::Template::UriencodeTag < Inversion::Template::AttrTag
 	include Inversion::Escaping
 
 
-	### Render the method chains against the attributes of the specified +render_state+
+	### Render the method chains against the attributes of the specified `render_state`
 	### and return them.
 	def render( render_state )
 		raw = super

data/lib/inversion/template/yieldtag.rb

@@ -1,5 +1,4 @@
 # -*- ruby -*-
-# frozen_string_literal: true
 # vim: set noet nosta sw=4 ts=4 :
 
 require 'pathname'

data/lib/inversion/template.rb

@@ -1,5 +1,4 @@
 # -*- ruby -*-
-# frozen_string_literal: true
 # vim: set noet nosta sw=4 ts=4 :
 
 require 'loggability'
@@ -28,23 +27,23 @@ end
 #
 # == 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
+# 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].
+# 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+.
+#   Inversion::ParseError. Defaults to `true`.
 #
 # [:on_render_error]
-#   Dictates the behavior of exceptions during rendering. Defaults to +:comment+.
+#   Dictates the behavior of exceptions during rendering. Defaults to `:comment`.
 #
 #   [:ignore]
 #     Exceptions are silently ignored.
@@ -55,7 +54,7 @@ end
 #
 #
 # [:debugging_comments]
-#   Insert various Inversion parse and render statements while rendering. Defaults to +false+.
+#   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.
@@ -71,16 +70,16 @@ end
 #   last checked member of this. Defaults to <code>[]</code>.
 #
 # [:escape_format]
-#   The escaping used by tags such as +escape+ and +pp+. Default: +:html+.
+#   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+.
+#   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+
+#   a purposeful delay between reloads for busy servers. Defaults to `0`
 #   (disabled).
 #
 # [:strict_attributes]
@@ -111,9 +110,6 @@ class Inversion::Template
 	require 'inversion/template/tag'
 	require 'inversion/renderstate'
 
-	# Alias to maintain backward compatibility with <0.2.0 code
-	Parser = Inversion::Parser
-
 	# Valid actions for 'on_render_error'
 	VALID_ERROR_ACTIONS = [
 		:ignore,
@@ -165,7 +161,7 @@ class Inversion::Template
 	end
 
 
-	### Read a template object from the specified +path+.
+	### 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
@@ -210,10 +206,10 @@ class Inversion::Template
 	end
 
 
-	### Add one or more extension +modules+ to Inversion::Template. This allows tags to decorate
+	### Add one or more extension `modules` to Inversion::Template. This allows tags to decorate
 	### the template class with new functionality.
 	###
-	### Each one of the given +modules+ will be included as a mixin, and if it also
+	### Each one of the given `modules` will be included as a mixin, and if it also
 	### contains a constant called ClassMethods and/or PrependedMethods, it will
 	### also be extended/prepended (respectively) with it.
 	###
@@ -260,7 +256,7 @@ class Inversion::Template
 	end
 
 
-	### Create a new Inversion:Template with the given +source+.
+	### 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 ]
@@ -325,7 +321,7 @@ class Inversion::Template
 	end
 
 
-	### Returns +true+ if the template was loaded from a file and the file's mtime
+	### Returns `true` if the template was loaded from a file and the file's mtime
 	### is after the time the template was created.
 	def changed?
 		return false unless file = self.source_file
@@ -408,7 +404,7 @@ class Inversion::Template
 	end
 
 
-	### Parse the given +source+ into the template node tree.
+	### Parse the given `source` into the template node tree.
 	def parse( source, parsestate=nil )
 		opts = self.class.config.merge( self.options )
 		parser = Inversion::Parser.new( self, opts )
@@ -442,7 +438,7 @@ class Inversion::Template
 	end
 
 
-	### Add attributes for the given +node+'s identifiers.
+	### Add attributes for the given `node`'s identifiers.
 	def add_attributes_from_node( node )
 		if node.respond_to?( :identifiers )
 			node.identifiers.each do |id|
@@ -453,7 +449,7 @@ class Inversion::Template
 	end
 
 
-	### Install reader and writer methods for the attribute associated with the specified +key+.
+	### Install reader and writer methods for the attribute associated with the specified `key`.
 	def install_accessors( key )
 		reader, writer = self.make_attribute_accessors( key )
 

data/lib/inversion/tilt.rb

@@ -1,5 +1,4 @@
 # -*- ruby -*-
-# frozen_string_literal: true
 # vim: set noet nosta sw=4 ts=4 :
 
 require 'tilt'
@@ -36,7 +35,7 @@ if defined?( ::Tilt )
 			self.evaluate( *args )
 		end
 
-		### Tilt::Template API: render the template with the given +scope+, +locals+, and +block+.
+		### Tilt::Template API: render the template with the given `scope`, `locals`, and `block`.
 		def evaluate( scope, locals, &block )
 			@template.attributes.merge!( scope.to_h ) if scope.respond_to?( :to_h )
 			@template.attributes.merge!( locals )

data/lib/inversion.rb

@@ -1,5 +1,4 @@
 # -*- ruby -*-
-# frozen_string_literal: true
 # vim: set noet nosta sw=4 ts=4 :
 
 require 'loggability'
@@ -26,7 +25,7 @@ module Inversion
 	warn ">>> Inversion requires Ruby 2.4.0 or later. <<<" if RUBY_VERSION < '2.4.0'
 
 	# Library version constant
-	VERSION = '1.3.1'
+	VERSION = '1.5.0'
 
 	# Version-control revision constant
 	REVISION = %q$Revision$
@@ -40,8 +39,8 @@ module Inversion
 	end
 
 	require 'inversion/exceptions'
+	require 'inversion/refinements'
 	require 'inversion/mixins'
-	require 'inversion/monkeypatches'
 	require 'inversion/template'
 
 end # module Inversion

data/lib/roda/plugins/inversion.rb

@@ -0,0 +1,225 @@
+# -*- ruby -*-
+# vim: set nosta noet ts=4 sw=4 ft=ruby:
+
+require 'inversion'
+require 'loggability'
+
+class Roda
+	module RodaPlugins
+
+		# A templated content-generation plugin for Roda Apps. It uses the
+		# Inversion[http://deveiate.org/projects/Inversion] templating system.
+		#
+		# It adds:
+		#
+		# * a preloaded/cached template table
+		# * a mechanism for fetching templates from the table
+		# * a global layout template which is automatically wrapped around responses
+		#
+		# Note: This is based almost entirely off the Strelka plugin of identical
+		# function.
+		#
+		# == Usage
+		#
+		# To use it, just load the <tt>:inversion</tt> plugin in your app:
+		#
+		#   plugin :inversion, '/path/to/templates/directory'
+		#
+		# You can specify more than one templates directory; they'll be searched in the order
+		# you specify for the named template and the first match wins:
+		#
+		#   plugin :inversion '/more/specific/templates', '/generic/app/templates'
+		#
+		# Then declare one or more templates that your application will use:
+		#
+		#   templates console:   'views/console.tmpl',
+		#             proctable: 'partials/proctable.tmpl'
+		#
+		# Then, inside your app, you can fetch a copy of one or more of the templates and
+		# return it as the response:
+		#
+		#   r.root do
+		#       tmpl = template( :console )
+		#       tmpl.message = "Everything's up."
+		#       tmpl.proctable = proctable
+		#       return tmpl
+		#   end
+		#
+		#
+		# You can also just return the template if you don't need to do anything else to the
+		# response.
+		#
+		# When returning a template, either in the body of the response or directly, it will
+		# automatically set a few attributes for commonly-used objects:
+		#
+		# request ::          The current Roda::Request
+		# response ::         The current Roda::Response
+		# app ::              The application object (Roda::App instance).
+		#
+		# If your app will *only* be loading and returning a template without doing anything
+		# with it, you can return just its name:
+		#
+		#   r.root do
+		#       return :console
+		#   end
+		#
+		# It will be loaded, set as the response body, and the above common objects added to it.
+		#
+		#
+		# === Layouts
+		#
+		# Very often, you'll want all or most of the views in your app to share a common page
+		# layout. To accomplish this, you can declare a layout template:
+		#
+		#   layout 'layout.tmpl'
+		#
+		# Any template that you return will be set as the 'body' attribute of this layout
+		# template (which you'd place into the layout with <tt><?attr body ?></tt>) and the
+		# layout rendered as the body of the response.
+		#
+		# Note that if you want any of the "common objects" from above with a layout template,
+		# they'll be set on it since it's the top-level template, but you can still access them
+		# using the <tt><?import ?></tt> directive:
+		#
+		#   <?import request, app ?>
+		#
+		#
+		# == Template Locations
+		#
+		# Inversion looks for templates in a load path much like Ruby does for libraries that
+		# you 'require'. It contains just the current working directory by default. You can add
+		# your own template directories via the config file (under +template_paths+ in
+		# the +templates+ section), or programmatically from your application.
+		#
+		module Inversion
+
+			### Add the specified +template_paths+ to Inversion.
+			def self::configure( app, *template_paths )
+				::Inversion::Template.template_paths.concat( template_paths )
+			end
+
+
+			module ClassMethods
+
+				### Add this Gem's template location to the Inversion search path.
+				def self::extended( subclass )
+					subclass.instance_variable_set( :@template_map, {} )
+					subclass.instance_variable_set( :@layout_template, nil )
+
+					super
+				end
+
+
+				# The map of template names to template file paths.
+				attr_reader :template_map
+
+				# An optional layout/wrap template.
+				attr_accessor :layout_template
+
+
+				### Load instances for all the template paths specified in the App's class
+				### and return them in a hash keyed by name (Symbol).
+				def templates( hash )
+					@template_map = hash.each_with_object( {} ) do |(name, path), map|
+						enc = Encoding.default_internal || Encoding::UTF_8
+						map[ name ] = ::Inversion::Template.load( path, encoding: enc )
+						map
+					end
+
+					return self.template_map
+				end
+
+
+				### Load an Inversion::Template for the layout template.
+				def layout( tmpl )
+					enc = Encoding.default_internal || Encoding::UTF_8
+					self.layout_template = ::Inversion::Template.load( tmpl, encoding: enc )
+					return self.layout_template
+				end
+			end
+
+
+			module InstanceMethods
+
+				### Return a previously declared template object.
+				def template( tmpl )
+					template = self.class.template_map[ tmpl ] or
+						raise ArgumentError, "no %p template registered!" % [ tmpl ]
+					template.reload if template.changed?
+					return template.dup
+				end
+			end
+
+
+			module RequestMethods
+
+				### Hook block results for template rendering.
+				def block_result_body( result )
+					if ( template = self.extract_template_from_result( result ) )
+
+						# Wrap the template in a layout if there is one
+						template = self.wrap_in_layout( template )
+
+						# Set some default stuff on the top-level template
+						self.set_common_attributes( template )
+
+						return template.render
+					else
+						super
+					end
+				end
+
+
+				#########
+				protected
+				#########
+
+				### Fetch the template from the +result+ (if there is one) and return it.
+				def extract_template_from_result( result )
+					templates = self.scope.class.template_map
+
+					# Result is a template name.
+					if result.is_a?( Symbol ) && templates.key?( result )
+						return scope.template( result )
+
+						# Result is a template object.
+					elsif result.respond_to?( :render )
+						return result
+					end
+
+					# Not templated; returned as-is
+					return nil
+				end
+
+
+				### Wrap the specified +content+ template in the layout template and
+				### return it. If there isn't a layout declared, just return +content+ as-is.
+				def wrap_in_layout( content )
+					layout = self.scope.class.layout_template or return content
+
+					layout.reload if layout.changed?
+					l_template = layout.dup
+					l_template.body = content
+
+					return l_template
+				end
+
+
+				### Set some default values from the request in the given top-level +template+.
+				def set_common_attributes( template )
+					template.request  = self
+					template.response = self.scope.response
+					template.app      = self.scope
+				end
+
+			end
+
+		end # module Inversion
+
+
+		# Hook: Inform Roda that we exist.
+		register_plugin :inversion, Inversion
+
+	end # module RodaPlugins
+end # class Roda
+

data/spec/helpers.rb

@@ -11,7 +11,7 @@ require 'loggability/spechelpers'
 
 require 'inversion'
 
-Inversion::Template::Tag.load_all
+# Inversion::Template::Tag.load_all
 
 
 ### RSpec helper functions.
@@ -21,14 +21,14 @@ module Inversion::SpecHelpers
 	module_function
 	###############
 
-	### Make an easily-comparable version vector out of +ver+ and return it.
+	### Make an easily-comparable version vector out of `ver` and return it.
 	def vvec( ver )
 		return ver.split('.').collect {|char| char.to_i }.pack('N*')
 	end
 
 
-	### Create a string containing an XML Processing Instruction with the given +name+
-	### and +data+.
+	### Create a string containing an XML Processing Instruction with the given `name`
+	### and `data`.
 	def create_pi( name, data )
 		return "<?#{name} #{data} ?>"
 	end
@@ -37,19 +37,25 @@ end
 
 
 ### Mock with RSpec
-RSpec.configure do |c|
+RSpec.configure do |config|
 
-	c.run_all_when_everything_filtered = true
-	c.filter_run :focus
-	c.order = 'random'
-	c.mock_with( :rspec ) do |mock|
+	config.mock_with( :rspec ) do |mock|
 		mock.syntax = :expect
 	end
-	c.wait_timeout = 3
-	c.example_status_persistence_file_path = 'spec/.state'
 
-	c.include( Inversion::SpecHelpers )
-	c.include( Loggability::SpecHelpers )
+	config.disable_monkey_patching!
+	config.example_status_persistence_file_path = "spec/.status"
+	config.filter_run :focus
+	config.filter_run_when_matching :focus
+	config.order = :random
+	config.profile_examples = 5
+	config.run_all_when_everything_filtered = true
+	config.shared_context_metadata_behavior = :apply_to_host_groups
+	config.wait_timeout = 3
+	# config.warnings = true
+
+	config.include( Inversion::SpecHelpers )
+	config.include( Loggability::SpecHelpers )
 end
 
 # vim: set nosta noet ts=4 sw=4:

data/spec/inversion/mixins_spec.rb

@@ -7,7 +7,7 @@ require 'set'
 require 'inversion/mixins'
 
 
-describe Inversion, "mixins" do
+RSpec.describe Inversion, "mixins" do
 
 	describe Inversion::HashUtilities do
 		it "includes a function for stringifying Hash keys" do

data/spec/inversion/parser_spec.rb

@@ -5,7 +5,7 @@ require_relative '../helpers'
 
 require 'inversion/parser'
 
-describe Inversion::Parser do
+RSpec.describe Inversion::Parser do
 
 	before( :all ) do
 		Inversion::Template::Tag.load_all

data/spec/inversion/refinements_spec.rb

@@ -0,0 +1,22 @@
+#!/usr/bin/env rspec -cfd -b
+# vim: set noet nosta sw=4 ts=4 :
+
+
+require_relative '../helpers'
+
+require 'ripper'
+require 'inversion/refinements'
+
+
+RSpec.describe Inversion, "refinements" do
+
+	using Inversion::Refinements
+
+	it "exposes the Ripper::TokenPattern::MatchData's #tokens array" do
+		tagpattern = Ripper::TokenPattern.compile( '$(ident) $(sp) $(ident)' )
+		matchdata = tagpattern.match( "foo bar" )
+		expect( matchdata.tokens.map {|tok| tok[1]} ).to eq([ :on_ident, :on_sp, :on_ident ])
+	end
+
+end
+

data/spec/inversion/renderstate_spec.rb

@@ -11,7 +11,7 @@ require 'inversion/template/fragmenttag'
 require 'inversion/template/subscribetag'
 require 'inversion/template/publishtag'
 
-describe Inversion::RenderState do
+RSpec.describe Inversion::RenderState do
 
 
 	it "provides access to the block it was constructed with if there was one" do