inversion 0.0.1

data/History.md

@@ -0,0 +1,4 @@
+## 0.0.1 [2011-02-02] Michael Granger <ged@FaerieMUD.org>
+
+Initial release.
+

data/Manifest.txt

@@ -0,0 +1,74 @@
+ChangeLog
+History.md
+Manifest.txt
+README.rdoc
+Rakefile
+bin/inversion
+lib/inversion.rb
+lib/inversion/exceptions.rb
+lib/inversion/mixins.rb
+lib/inversion/monkeypatches.rb
+lib/inversion/renderstate.rb
+lib/inversion/sinatra.rb
+lib/inversion/template.rb
+lib/inversion/template/attrtag.rb
+lib/inversion/template/calltag.rb
+lib/inversion/template/codetag.rb
+lib/inversion/template/commenttag.rb
+lib/inversion/template/conditionaltag.rb
+lib/inversion/template/configtag.rb
+lib/inversion/template/containertag.rb
+lib/inversion/template/elsetag.rb
+lib/inversion/template/elsiftag.rb
+lib/inversion/template/endtag.rb
+lib/inversion/template/escapetag.rb
+lib/inversion/template/fortag.rb
+lib/inversion/template/iftag.rb
+lib/inversion/template/importtag.rb
+lib/inversion/template/includetag.rb
+lib/inversion/template/node.rb
+lib/inversion/template/parser.rb
+lib/inversion/template/pptag.rb
+lib/inversion/template/publishtag.rb
+lib/inversion/template/subscribetag.rb
+lib/inversion/template/tag.rb
+lib/inversion/template/textnode.rb
+lib/inversion/template/unlesstag.rb
+lib/inversion/template/uriencodetag.rb
+lib/inversion/template/yieldtag.rb
+lib/inversion/tilt.rb
+lib/inversion/utils.rb
+spec/data/sinatra/hello.inversion
+spec/inversion/mixins_spec.rb
+spec/inversion/monkeypatches_spec.rb
+spec/inversion/renderstate_spec.rb
+spec/inversion/sinatra_spec.rb
+spec/inversion/template/attrtag_spec.rb
+spec/inversion/template/calltag_spec.rb
+spec/inversion/template/codetag_spec.rb
+spec/inversion/template/commenttag_spec.rb
+spec/inversion/template/configtag_spec.rb
+spec/inversion/template/containertag_spec.rb
+spec/inversion/template/elsetag_spec.rb
+spec/inversion/template/elsiftag_spec.rb
+spec/inversion/template/endtag_spec.rb
+spec/inversion/template/escapetag_spec.rb
+spec/inversion/template/fortag_spec.rb
+spec/inversion/template/iftag_spec.rb
+spec/inversion/template/importtag_spec.rb
+spec/inversion/template/includetag_spec.rb
+spec/inversion/template/node_spec.rb
+spec/inversion/template/parser_spec.rb
+spec/inversion/template/pptag_spec.rb
+spec/inversion/template/publishtag_spec.rb
+spec/inversion/template/subscribetag_spec.rb
+spec/inversion/template/tag_spec.rb
+spec/inversion/template/textnode_spec.rb
+spec/inversion/template/unlesstag_spec.rb
+spec/inversion/template/uriencodetag_spec.rb
+spec/inversion/template/yieldtag_spec.rb
+spec/inversion/template_spec.rb
+spec/inversion/tilt_spec.rb
+spec/inversion_spec.rb
+spec/lib/constants.rb
+spec/lib/helpers.rb

data/README.rdoc

@@ -0,0 +1,171 @@
+= inversion
+
+* http://deveiate.org/projects/Inversion
+
+
+== Description
+
+Inversion is a templating system for Ruby. It uses the "Inversion of Control" principle to decouple
+the contents and structure of the template from the code that uses it, making it easier to use,
+test-friendly, and clean.
+
+
+=== Details
+
+Inversion, like most other templating systems, works by giving you a way of defining the static
+parts of your output, and then letting you combine that at a later point with the dynamic parts:
+
+Create the template and use it to render an exciting message:
+
+	tmpl = Inversion::Template.new( "Hello, <?attr name ?>!" )
+	tmpl.name = "World"
+	puts tmpl.render
+
+The <tt><?attr name ?></tt> tag defines the _name_ accessor on the template object, the value of
+which is substituted for any occurrences of +name+ in the template:
+
+    Hello, World!
+
+This by itself isn't fantastically useful, but it does illustrate one of the ways in which Inversion
+is different: the program and the template share data through an API, instead of through a complex
+data structure, which establishes a clear delineation between what responsibility is the program's
+and which is the template's. The program doesn't have to know how the view uses the data it's given,
+and tests of the controller can substitute a Mock Object for the template to test the interaction
+between the two instead of having to match patterns in the eventual output like an integration test.
+
+You can also interact with the values set in the template:
+
+    Name: <?attr employee.full_name ?>
+
+This will call the +#full_name+ method on whatever is set as the +employee+ attribute when 
+rendered, and the result will take the place of the tag.
+
+Inversion also comes with a collection of other tags that provide flow control, exception-handling,
+etc.
+
+Here's a slightly more complex example: Say we have a layout template that contains all the
+boilerplate, navigation, etc. for the site, and then an `<?attr body ?>` somewhere in the content
+area for the content specific to each view:
+
+    layout = Inversion::Template.load( 'templates/layout.tmpl' )
+
+Then there's a view template that displays a bulleted list of article titles:
+ 
+    <!-- articlelist.tmpl -->
+    <section id="articles">
+      <ul>
+      <?for article in articles ?>
+        <li><?call article.title ?></li>
+      <?end for ?>
+      </ul>
+    </section>
+
+Loading this template results in a Ruby object whose API contains one method: `#articles`. To render
+the view, we just call that accessor with instances of an `Article` domain class we defined
+elsewhere, and then drop the 'alist' template into the layout and render them:
+
+    alist = Inversion::Template.load( 'templates/alist.tmpl' )
+    alist.articles = Articles.latest( 10 )
+    
+    layout.body = alist
+    puts layout.render
+
+The `for` tag in the alist will iterate over the enumerable Articles and generate an `<li>` for each
+one. The resulting template object will be set as the body of the layout template, and stringified
+when the enclosing template is rendered. Templates can be nested this way as deeply as you like.
+
+
+=== Tags To Implement
+
+* <?prettyprint «attr/methodchain» ?>
+
+* <?render «attr/methodchain» AS «identifier» IN «template path» ?>
+
+
+=== Tags Implemented
+
+* <?attr?>
+* <?call?>
+* <?comment?>…<?end?>
+* <?for obj, i in attr.each_with_index ?>
+  <?end?>
+* <?config
+	  escaping: 'html'
+	  ignore_unknown_tags: false
+  ?>
+* <?include other_template.tmpl ?>
+* <?escape obj.some_method ?>
+* <?urlencode obj.some_method ?>
+* <?pp obj ?>
+* <?if obj.some_method ?>…<?elsif otherobj.some_method ?>…<?else?>…<?end?>
+* <?unless obj.some_method ?>..<?end ?>
+* <?import attrname ?>
+* <?publish identifier ?>...<?end publish ?>
+* <?subscribe identifier ?>
+* <?timedelta obj.time_method ?>
+* <?yield ?>
+* <?default attribute to value ?>
+* <?begin ?>…<?rescue ?>…<?end?>
+
+
+== References
+
+* Inversion of Control: http://en.wikipedia.org/wiki/Inversion_of_control
+* Passive View: http://martinfowler.com/eaaDev/PassiveScreen.html
+* Supervising Controller: http://martinfowler.com/eaaDev/SupervisingPresenter.html
+
+
+== Installation
+
+    gem install inversion
+
+
+== Contributing
+
+You can check out the current development source
+{with Mercurial}[http://repo.deveiate.org/Inversion], or if you prefer Git, via the
+project's {Github mirror}[https://github.com/ged/Inversion].
+
+You can submit bug reports, suggestions, and read more about future plans at
+{the project page}[http://deveiate.org/projects/Inversion].
+
+After checking out the source, run:
+
+	$ rake newb
+
+This task will install any missing dependencies, run the tests/specs,
+and generate the API documentation.
+
+
+== License
+
+Copyright © 2011, Michael Granger and Mahlon E. Smith
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice,
+  this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the author/s, nor the names of the project's
+  contributors may be used to endorse or promote products derived from this
+  software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+
+

data/Rakefile

@@ -0,0 +1,55 @@
+#!/usr/bin/env rake
+
+begin
+	require 'hoe'
+rescue LoadError
+	abort "This Rakefile requires hoe (gem install hoe)"
+end
+
+Hoe.plugin :mercurial
+Hoe.plugin :signing
+Hoe.plugin :manualgen
+
+Hoe.plugins.delete :rubyforge
+
+hoespec = Hoe.spec 'inversion' do
+	self.readme_file = 'README.rdoc'
+	self.history_file = 'History.md'
+	self.extra_rdoc_files = ['README.rdoc']
+
+	self.developer 'Michael Granger', 'ged@FaerieMUD.org'
+	self.developer 'Mahlon E. Smith', 'mahlon@martini.nu'
+
+	self.dependency 'ripper',        '~> 1.0',    :development unless defined?( Encoding )
+	self.dependency 'rspec',         '~> 2.6.0',  :development
+	self.dependency 'tilt',          '~> 1.3.2',  :development
+	self.dependency 'sinatra',       '~> 1.2.6',  :development
+	self.dependency 'rack-test',     '~> 0.6.0',  :development
+	self.dependency 'simplecov',     '~> 0.4.2',  :development
+	self.dependency 'hoe-manualgen', '~> 0.2.0',  :development
+
+	# bin/inversion deps
+	self.dependency 'trollop',       '~> 0.16.2', :development
+	self.dependency 'highline',      '~> 1.6.2',  :development
+	self.dependency 'sysexits',      '~> 1.0.2',  :development
+
+	self.spec_extras[:licenses] = ["BSD"]
+	self.require_ruby_version( '>=1.9.2' )
+	self.hg_sign_tags = true if self.respond_to?( :hg_sign_tags= )
+	self.rdoc_locations << "deveiate:/usr/local/www/public/code/#{remote_rdoc_dir}"
+end
+
+ENV['VERSION'] ||= hoespec.spec.version.to_s
+
+# Ensure the specs pass before checking in
+task 'hg:precheckin' => :spec
+
+# Rebuild the ChangeLog immediately before release (hoe hook)
+task :prerelease => 'ChangeLog'
+
+desc "Build a coverage report"
+task :coverage do
+	ENV["COVERAGE"] = 'yes'
+	Rake::Task[:spec].invoke
+end
+

data/bin/inversion

@@ -0,0 +1,276 @@
+#!/usr/bin/env ruby
+
+require 'logger'
+require 'inversion'
+require 'trollop'
+require 'highline'
+require 'sysexits'
+require 'shellwords'
+
+# Command class for the 'inversion' command-line tool.
+class Inversion::Command
+	extend Sysexits
+
+	# The list of valid subcommands
+	SUBCOMMANDS = %w[api tagtokens tree]
+
+	# Class-instance variable for the HighLine prompt object
+	@prompt = nil
+
+
+	### Run the command
+	def self::run( args )
+		opts, args = self.parse_options( args )
+		subcommand = args.shift
+
+		command = self.new( opts )
+		command.run( subcommand, args )
+	rescue => err
+		$stderr.puts "%p: %s" % [ err.class, err.message ]
+		$stderr.puts( err.backtrace.join("\n  ") ) if opts && opts.debug
+	end
+
+
+	### Fetch the HighLine instance for the command, creating it if necessary.
+	def self::prompt
+		unless @prompt
+			@prompt = HighLine.new
+			@prompt.page_at = @prompt.output_rows - 5
+			@prompt.wrap_at = @prompt.output_cols - 2
+		end
+
+		@prompt
+	end
+
+
+	### Create an option parser for the command and return it
+	def self::create_option_parser
+		pr = self.prompt
+		progname = pr.color( File.basename($0), :bold, :yellow )
+
+		return Trollop::Parser.new do
+			version Inversion.version_string( true )
+
+			banner (<<-END_BANNER).gsub(/^\t+/, '')
+			#{progname} OPTIONS SUBCOMMAND ARGS
+	
+			Run the specified SUBCOMMAND with the given ARGS.
+			END_BANNER
+			text ''
+
+			stop_on( *SUBCOMMANDS )
+			text pr.color('Subcommands', :bold, :white)
+			text pr.list( SUBCOMMANDS, :columns_across )
+			text ''
+
+			text pr.color('Inversion Config', :bold, :white)
+			opt :ignore_unknown_tags, "Ignore unknown tags instead of displaying an error"
+			opt :path, "Add one or more directories to the template search path",
+				:type => :string, :multi => true
+			text ''
+
+
+			text pr.color('Other Options', :bold, :white)
+			opt :debug, "Enable debugging output"
+		end
+	end
+
+
+	### Parse the given command line +args+, returning a populated options struct
+	### and any remaining arguments.
+	def self::parse_options( args )
+		oparser = self.create_option_parser
+		opts = oparser.parse( args )
+
+		if oparser.leftovers.empty?
+			$stderr.puts "No subcommand given.\nUsage: "
+			oparser.educate( $stderr )
+			exit :usage
+		end
+		args.replace( oparser.leftovers )
+
+		return opts, args
+	rescue Trollop::HelpNeeded
+		oparser.educate( $stderr )
+		exit :ok
+	rescue Trollop::VersionNeeded
+		$stderr.puts( oparser.version )
+		exit :ok
+	end
+
+
+	### Create a new instance of the command that will use the specified +opts+
+	### to parse and dump info about the given +templates+.
+	def initialize( opts )
+		@opts      = opts
+		@prompt    = self.class.prompt
+
+		# Configure Inversion's strictness and logging
+		Inversion.log.level = opts.debug ? Logger::DEBUG : Logger::ERROR
+		Inversion.log.formatter = Inversion::ColorLogFormatter.new( Inversion.log )
+		Inversion::Template.configure(
+			:ignore_unknown_tags => opts.ignore_unknown_tags,
+			:template_paths      => opts.path,
+		)
+	end
+
+
+	######
+	public
+	######
+
+	# The command-line options
+	attr_reader :opts
+
+	# The command's prompt object (HighLine)
+	attr_reader :prompt
+
+
+	### Run the given +subcommand+ with the specified +args+.
+	def run( subcommand, args )
+		case subcommand.to_sym
+		when :tree
+			self.dump_node_trees( args )
+		when :api
+			self.describe_templates( args )
+		when :tagtokens
+			self.dump_tokens( args )
+		else
+			self.output_error( "No such command #{subcommand.dump}" )
+		end
+	end
+
+
+	### Load the Inversion::Template from the specified +tmplpath+ and return it. If there
+	### is an error loading the template, output the error and return +nil+.
+	def load_template( tmplpath )
+		template = Inversion::Template.load( tmplpath )
+		return template
+	rescue Errno => err
+		self.prompt.say "Failed to load %s: %s" % [ tmplpath, err.message ]
+	rescue Inversion::ParseError => err
+		self.prompt.say "%s: Invalid template: %p: %s" %
+			[ tmplpath, err.class, err.message ]
+		self.prompt.say( err.backtrace.join("\n  ") ) if self.opts.debug
+	end
+
+
+	### Dump the node tree of the given +templates+.
+	def dump_node_trees( templates )
+		templates.each do |path|
+			template = self.load_template( path )
+			self.output_blank_line
+			self.output_template_header( template )
+			self.output_template_nodes( template.node_tree )
+		end
+	end
+
+
+	### Output the given +tree+ of nodes at the specified +indent+ level.
+	def output_template_nodes( tree, indent=0 )
+		indenttxt = ' ' * indent
+		tree.each do |node|
+			self.prompt.say( indenttxt + node.as_comment_body )
+			self.output_template_nodes( node.subnodes, indent+4 ) if node.is_container?
+		end
+	end
+
+
+	### Output a description of the templates.
+	def describe_templates( templates )
+		templates.each do |path|
+			template = self.load_template( path )
+			self.output_blank_line
+			self.output_template_header( template )
+			self.describe_template_api( template )
+			self.describe_publications( template )
+			self.describe_subscriptions( template )
+		end
+	end
+
+
+	### Output a header between each template.
+	def output_template_header( template )
+		header_info = "%s (%0.2fK, %s)" %
+			[ template.source_file, template.source.bytesize/1024.0, template.source.encoding ]
+		header_line = "-- %s" % [ header_info ]
+		self.prompt.say( self.prompt.color(header_line, :bold, :white) )
+	end
+
+
+	### Output a description of the +template+'s attributes, subscriptions, etc.
+	def describe_template_api( template )
+		attrs = template.attributes.keys.map( &:to_s )
+		return if attrs.empty?
+
+		self.output_subheader "%d Attribute/s" % [ attrs.length ]
+		self.output_list( attrs.sort )
+		self.output_blank_line
+	end
+
+
+	### Output a list of sections the template publishes.
+	def describe_publications( template )
+		ptags = template.node_tree.find_all {|node| node.is_a?(Inversion::Template::PublishTag) }
+		return if ptags.empty?
+
+		pubnames = ptags.map( &:key ).map( &:to_s ).uniq.sort
+		self.output_subheader "%d Publication/s" % [ pubnames.length ]
+		self.output_list( pubnames )
+		self.output_blank_line
+	end
+
+
+	### Output a list of sections the template subscribes to.
+	def describe_subscriptions( template )
+		stags = template.node_tree.find_all {|node| node.is_a?(Inversion::Template::SubscribeTag) }
+		return if stags.empty?
+
+		subnames = stags.map( &:key ).map( &:to_s ).uniq.sort
+		self.output_subheader "%d Subscription/s" % [ subnames.length ]
+		self.output_list( subnames )
+		self.output_blank_line
+	end
+
+
+	### Attempt to parse the given +code+ and dump its tokens as a tagpattern.
+	def dump_tokens( args )
+		code = args.join(' ')
+
+		require 'ripper'
+		tokens = Ripper.lex( code ).collect do |(pos, tok, text)|
+			"%s<%p>" % [ tok.to_s.sub(/^on_/,''), text ]
+		end.join(' ')
+
+		self.prompt.say( tokens )
+	end
+
+
+	### Display a columnar list.
+	def output_list( columns )
+		self.prompt.say( self.prompt.list(columns, :columns_down) )
+	end
+
+
+	### Display an error message.
+	def output_error( message )
+		self.prompt.say( self.prompt.color(message, :red) )
+	end
+
+
+	### Output a subheader with the given +caption+.
+	def output_subheader( caption )
+		self.prompt.say( self.prompt.color(caption, :cyan) )
+	end
+
+
+	### Output a blank line
+	def output_blank_line
+		self.prompt.say( "\n" )
+	end
+
+end # class Inversion::Command
+
+Inversion::Command.run( ARGV )
+
+