strelka-cms 0.0.1.pre.15

data/lib/strelka/cms/pagecatalog.rb

@@ -0,0 +1,121 @@
+#!/usr/bin/env ruby
+
+require 'pathname'
+require 'configurability'
+require 'strelka'
+
+require 'strelka/cms' unless defined?( Strelka::CMS )
+require 'strelka/cms/page' unless defined?( Strelka::CMS::Page )
+
+# A catalog of Strelka::CMS::Page objects. It provides a collection interface
+# over a group of pages, suitable for searching for, or iterating over
+# pages matching one or more criteria.
+class Strelka::CMS::PageCatalog
+	extend Loggability
+	include Enumerable
+
+	# Loggability API -- log to the deveiate logger
+	log_to :strelka_cms
+
+
+	# The default glob pattern to match pages.
+	DEFAULT_GLOB_PATTERN = '**/*.page'
+
+
+	#################################################################
+	###	I N S T A N C E   M E T H O D S
+	#################################################################
+
+	### Create a new PageCatalog that will find and read pages from the configured
+	### directory.
+	def initialize( basedir=Pathname.pwd, pattern=DEFAULT_GLOB_PATTERN )
+		pattern.slice!( 0, 1 ) if pattern.start_with?( '/' )
+		self.log.debug "New catalog for pages matching: %s in: %s" % [ pattern, basedir ]
+		@basedir  = Pathname( basedir )
+		@pageglob = pattern
+	end
+
+
+	######
+	public
+	######
+
+	# The base directory of the catalog
+	attr_reader :basedir
+
+	# The glob pattern that will match a collection of one or more pages
+	attr_reader :pageglob
+
+
+	### Return the glob pattern for pages in this catalog.
+	def glob
+		return (self.basedir + self.pageglob).to_s
+	end
+
+
+	### Enumerable interface -- if called with a block, load and yield each page matching the
+	### #pageglob. If called without a block, return an Enumerator.
+	def each
+		iter = self.page_enumerator
+		if block_given?
+			block = Proc.new
+			iter.each( &block )
+		else
+			return iter
+		end
+	end
+
+
+	### Return a clone of the directory that will limit the pages in the catalog to those
+	### under the given +dir+.
+	def relative_to( dir )
+		dir = dir.to_s
+		dir.slice!( 0, 1 ) if dir.start_with?( '/' )
+		self.log.debug "Build new catalog for %p relative to %s" % [ dir, self.basedir ]
+		self.class.new( self.basedir + dir, self.pageglob )
+	end
+
+
+	### Return a clone of the directory that will use the specified +pattern+ to find pages
+	### instead of the original.
+	def matching_pattern( pattern )
+		self.class.new( self.basedir, pattern )
+	end
+
+
+	### Return the catalog object as a human-readable string.
+	def inspect
+		"#<%s:0x%0x %s, %d documents>" % [
+			self.class.name,
+			self.object_id / 2,
+			self.glob,
+			self.page_path_enumerator.count,
+		]
+	end
+
+
+	#########
+	protected
+	#########
+
+	### Return an Enumerator that will yield a Pathname for each page matching the #pageglob
+	def page_path_enumerator
+		self.log.debug "Fetching an enumerator for %s" % [ self.glob ]
+		Pathname.glob( self.glob ).each
+	end
+
+
+	### Return an Enumerator that will yield a Strelka::CMS::Page object for each page matching
+	### the #pageglob.
+	def page_enumerator
+		Enumerator.new do |yielder|
+			self.page_path_enumerator.each do |path|
+				page = Strelka::CMS::Page.load( path, self )
+				yielder.yield( page )
+			end
+		end
+	end
+
+
+end # class Strelka::CMS::PageCatalog
+

data/lib/strelka/cms/pagefilter.rb

@@ -0,0 +1,76 @@
+#!/usr/bin/env ruby
+
+require 'pluginfactory'
+require 'strelka/mixins'
+
+require 'strelka/cms' unless defined?( Strelka::CMS )
+require 'strelka/cms/page' unless defined?( Strelka::CMS::Page )
+
+
+# An abstract base class for page filters in the Strelka CMS.
+#
+# A page filter replaces one or more placeholders with generated or altered
+# content.
+#
+class Strelka::CMS::PageFilter
+	extend Loggability,
+	       PluginFactory
+
+
+	# Loggability API -- log to the deveiate logger
+	log_to :strelka_cms
+
+
+	### PluginFactory API -- list the directories to search for derivatives.
+	def self::derivative_dirs
+		[ 'strelka/cms/pagefilter' ]
+	end
+
+
+	### Search for plugins in the $LOAD_PATH and load each of them that's found.
+	def self::load_all
+		loaded = []
+		glob_pat = '{' + self.derivative_dirs.join(',') + '}/*.rb'
+		$LOAD_PATH.uniq.collect {|path| path.untaint; Pathname(path) }.each do |base|
+			self.log.debug "  searching for %s" % [ base + glob_pat ]
+			Pathname.glob( base + glob_pat ).each do |plugin|
+				# Don't load this file twice
+				next if Pathname(__FILE__).expand_path == plugin.expand_path
+
+				begin
+					path = plugin.to_s.untaint
+					require( path )
+					loaded << plugin
+				rescue LoadError, SecurityError => err
+					self.log.error "  %s while loading %s: %s" %
+						[ err.class.name, plugin.to_s, err.message ]
+					err.backtrace.each do |frame|
+						self.log.debug "  #{frame}"
+					end
+				end
+			end
+		end
+
+		return loaded
+	end
+
+
+	#################################################################
+	###	I N S T A N C E   M E T H O D S
+	#################################################################
+
+	### Export any static resources required by this filter to the given +output_dir+.
+	def export_resources( output_dir )
+		# No-op by default
+	end
+
+
+	### Process the +page+'s source with the filter and return the altered content.
+	def process( source, page, index )
+		raise NotImplementedError,
+			"%s does not implement the #process method" % [ self.class.name ]
+	end
+
+end # class Strelka::CMS::PageFilter
+
+

data/lib/strelka/cms/pagefilter/autoindex.rb

@@ -0,0 +1,140 @@
+#!/usr/bin/env ruby
+
+require 'ostruct'
+require 'configurability'
+
+require 'strelka/cms/pagecatalog'
+require 'strelka/cms/page'
+require 'strelka/cms/pagefilter' unless defined?( Strelka::CMS::PageFilter )
+
+require 'inversion'
+
+# Generate an index for any pages matching the specified <tt>pattern</tt> with one or
+# more +option+s.
+#
+#   <?autoindex «pattern» [option]+ ?>
+#
+# Styles are implemented with templates placed in the data/templates/autoindex/ directory.
+#
+# Examples:
+#
+#   <?autoindex *.page ?>
+#   <?autoindex *.page with default ?>
+#   <?autoindex *.page with dl, sort by date ?>
+#   <?autoindex blog/*.page limit 10 ?>
+#   <?autoindex /*.page ?>
+#   <?autoindex /it/is/*.page ?>
+#   <?autoindex /it/is/*.page with filetree ?>
+#   <?autoindex /it/**/*.page ?>
+#
+class Strelka::CMS::PageFilter::AutoIndex < Strelka::CMS::PageFilter
+
+	# PI	   ::= '<?' PITarget (S (Char* - (Char* '?>' Char*)))? '?>'
+	PI = %r{
+		<\?
+			autoindex           # Instruction Target
+			\s+
+			(\S+)              # glob for pages to link [$1]
+			(.*?)				# options [$2]
+			\s*
+		\?>
+	  }xm
+
+	# Default style template
+	DEFAULT_STYLE = 'default'
+
+	# Autoindex templates subdirectory
+	DEFAULT_TEMPLATE_DIR = Pathname( 'autoindex' )
+
+	# The comment that's inserted if the target page doesn't know what catalog
+	# it belongs to.
+	NO_CATALOG_COMMENT = %Q{<!-- AutoIndex skipped: page doesn't have a catalog -->}
+
+
+
+	######
+	public
+	######
+
+	### Process the given +source+ for <?autoindex ... ?> processing-instructions
+	def process( source, page )
+		if catalog = page.catalog
+			self.log.debug "Processing autoindex directives."
+			source.gsub!( PI ) do |match|
+				self.log.debug "  got: %p" % [ match ]
+				# Grab the tag values
+				pattern = $1
+				options = $2
+
+				self.log.debug "Generating an index for %p relative to %p." % [ pattern, page.path ]
+				self.generate_index( pattern, page, catalog, options )
+			end
+			return source
+		else
+			self.log.debug "Not generating autoindex sections: no catalog"
+			return source.gsub( PI, NO_CATALOG_COMMENT )
+		end
+	end
+
+
+	### Create an HTML fragment.
+	def generate_index( pattern, page, catalog, options )
+		options = self.parse_options( options )
+		style   = options.style || DEFAULT_STYLE
+
+		pages = if pattern.start_with?( '/' )
+				self.log.debug "  absolute pattern; matching relative to catalog basedir %p" %
+					[ catalog.basedir.to_s ]
+				catalog.matching_pattern( pattern ).to_a
+			else
+				self.log.debug "  relative pattern; matching relative to page directory %p" %
+					[ page.path.dirname.to_s ]
+				catalog.relative_to( page.path.dirname ).matching_pattern( pattern ).to_a
+			end
+		pages = self.sort_pages( pages, options ) if options.sortkey
+
+		style = style + '.tmpl' unless style =~ /\.tmpl$/
+		style = DEFAULT_TEMPLATE_DIR + style
+
+		self.log.debug "  generating an HTML index fragment for %d pages under %s" %
+			[ pages.length, pattern ]
+		template = Inversion::Template.load( style )
+
+		template.pages        = pages
+		template.source_page  = page
+		template.catalog      = catalog
+		template.list_options = options
+
+		return template.to_s
+	end
+
+
+	#########
+	protected
+	#########
+
+	### Parse the options to the PI, returning the results as an OpenStruct.
+	def parse_options( optstring )
+		opts = OpenStruct.new
+
+		opts.limit   = Integer($1) if optstring =~ /\blimit\s+(\d+)/i
+		opts.style   = $1.untaint  if optstring =~ /\bwith\s+([a-zA-Z0-9.\/\-]+)/i
+		opts.sortkey = $1.untaint  if optstring =~ /\bsort\s+by\s+(\w+)/i
+
+		return opts
+	end
+
+
+	### Return the given +pages+ sorted according to the specified +options+.
+	def sort_pages( pages, options )
+		case options.sortkey
+		when 'date'
+			return pages.sort_by {|page| page.path.mtime }.reverse
+		when 'title'
+			return pages.sort_by {|page| page.title }
+		else
+			self.log.error "Don't know how to sort the index by %p" % [ options.sortkey ]
+		end
+	end
+
+end # class Strelka::CMS::Page::AutoIndexFilter

data/lib/strelka/cms/pagefilter/cleanup.rb

@@ -0,0 +1,40 @@
+#!/usr/bin/env ruby
+
+require 'rbconfig'
+require 'tidy'
+require 'nokogiri'
+
+require 'strelka/cms/pagefilter' unless defined?( Strelka::CMS::PageFilter )
+
+# A filter that cleans up broken HTML using libtidy.
+class Strelka::CMS::PageFilter::Cleanup < Strelka::CMS::PageFilter
+
+	# Options to pass to libtidy
+	TIDY_OPTIONS = {
+		:show_warnings     => true,
+		:indent            => true,
+		:indent_attributes => false,
+		:indent_spaces     => 4,
+		:vertical_space    => true,
+		:tab_size          => 4,
+		:wrap_attributes   => true,
+		:wrap              => 100,
+		:output_xhtml      => true,
+		:char_encoding     => 'utf8'
+	  }
+
+
+	### Process the +page+'s source with the filter and return the altered content.
+	def process( source, page )
+		Tidy.open( TIDY_OPTIONS ) do |tidy|
+			xml = tidy.clean( source )
+
+			errors = tidy.errors
+			self.log.error( errors.join('; ') ) unless errors.empty?
+
+			return xml
+		end
+	end
+
+end # class Strelka::CMS::Page::CleanupFilter
+

data/lib/strelka/cms/pagefilter/editorial.rb

@@ -0,0 +1,55 @@
+#!/usr/bin/env ruby
+
+require 'digest/md5'
+
+require 'strelka/cms/pagefilter' unless defined?( Strelka::CMS::PageFilter )
+
+# A class for embedding editorial remarks in a page.
+class Strelka::CMS::PageFilter::Editorial < Strelka::CMS::PageFilter
+
+	# PI	   ::= '<?' PITarget (S (Char* - (Char* '?>' Char*)))? '?>'
+	LinkPI = %r{
+		<\?
+			ed					# Instruction Target
+			\s+
+			(\w+?)				# type of editorial mark [$1]
+			:?					# optional colon
+			"
+				(.*?)           # content that should be edited [$2]
+			"
+			\s*
+		\?>
+	  }x
+
+	# Tooltip template
+	TOOLTIP_TEMPLATE = %{<div class="tooltip ed %s-ed"><h3>%s</h3><p>%s</p></div>}
+
+
+	######
+	public
+	######
+
+	### Process the given +source+ for <?ed ... ?> processing-instructions
+	def process( source, page )
+		return source.gsub( LinkPI ) do |match|
+			# Grab the tag values
+			mark_type = $1
+			content   = $2
+
+			self.generate_mark( page, mark_type, content )
+		end
+	end
+
+
+	### Create an HTML fragment from the parsed LinkPI.
+	def generate_mark( current_page, mark_type, content )
+		id = Digest::MD5.hexdigest( content )
+
+		edmark = %{<span class="edmark %s-edmark">(ed.)</span>} % [ mark_type ]
+		tooltip = TOOLTIP_TEMPLATE % [ mark_type, mark_type.upcase, content ]
+
+		return edmark + "\n" + tooltip + "\n"
+	end
+
+
+end # class Strelka::CMS::Page::EditorialFilter

data/lib/strelka/cms/pagefilter/example.rb

@@ -0,0 +1,232 @@
+#!/usr/bin/env ruby
+
+require 'pathname'
+require 'strscan'
+require 'yaml'
+require 'rcodetools/xmpfilter'
+require 'tmpdir'
+require 'erb'
+
+require 'strelka/cms/page'
+require 'strelka/cms/pagefilter' unless defined?( Strelka::CMS::PageFilter )
+
+### A filter for inline example code or command-line sessions -- does
+### syntax-highlighting (via CodeRay), syntax-checking for some languages, and
+### captioning.
+###
+### Examples are enclosed in XML processing instructions like so:
+###
+###   <?example {language: ruby, testable: true, caption: "A fine example"} ?>
+###      a = 1
+###      puts a
+###   <?end example ?>
+###
+### This will be pulled out into a preformatted section in the HTML,
+### highlighted as Ruby source, checked for valid syntax, and annotated with
+### the specified caption. Valid keys in the example PI are:
+###
+### language::
+###   Specifies which (machine) language the example is in.
+### testable::
+###	  If set and there is a testing function for the given language, run it and append
+###	  any errors to the output.
+### caption::
+###   A small blurb to put below the pulled-out example in the HTML.
+class Strelka::CMS::PageFilter::Example < Strelka::CMS::PageFilter
+
+	DEFAULTS = {
+		:language     => :shell,
+		:line_numbers => :inline,
+		:tab_width    => 4,
+		:hint         => :debug,
+		:testable     => false,
+	}
+
+	# PI	   ::= '<?' PITarget (S (Char* - (Char* '?>' Char*)))? '?>'
+	EXAMPLE_PI = %r{
+		<\?
+			example				# Instruction Target
+			(?:					# Optional instruction body
+			\s+
+			((?:				# [$1]
+				[^?]*			# Run of anything but a question mark
+				|				# -or-
+				\?(?!>)			# question mark not followed by a closing angle bracket
+			)*)
+			)?
+		\?>
+	  }x
+
+	END_PI = %r{ <\? end (?: \s+ example )? \s* \?> }x
+
+
+	######
+	public
+	######
+
+	### Process the given +source+ for <?example ... ?> processing-instructions, calling out
+	def process( source, page )
+		scanner = StringScanner.new( source )
+
+		buffer = ''
+		until scanner.eos?
+			startpos = scanner.pos
+
+			# If we find an example
+			if scanner.skip_until( EXAMPLE_PI )
+				contents = ''
+
+				# Append the interstitial content to the buffer
+				if ( scanner.pos - startpos > scanner.matched.length )
+					offset = scanner.pos - scanner.matched.length - 1
+					buffer << scanner.string[ startpos..offset ]
+				end
+
+				# Append everything up to it to the buffer and save the contents of
+				# the tag
+				params = scanner[1]
+
+				# Now find the end of the example or complain
+				contentpos = scanner.pos
+				scanner.skip_until( END_PI ) or
+					raise "Unterminated example at line %d" % 
+						[ scanner.string[0..scanner.pos].count("\n") ]
+
+				# Now build the example and append to the buffer
+				if ( scanner.pos - contentpos > scanner.matched.length )
+					offset = scanner.pos - scanner.matched.length - 1
+					contents = scanner.string[ contentpos..offset ]
+				end
+
+				self.log.debug "Processing with params: %p, contents: %p" % [ params, contents ]
+				buffer << self.process_example( params, contents, page )
+			else
+				break
+			end
+
+		end
+		buffer << scanner.rest
+		scanner.terminate
+
+		return buffer
+	end
+
+
+	### Filter out 'example' macros, doing syntax highlighting, and running
+	### 'testable' examples through a validation process appropriate to the
+	### language the example is in.
+	def process_example( params, body, page )
+		options = self.parse_options( params )
+		caption = options.delete( :caption )
+		content = ''
+		lang = options.delete( :language ).to_s
+		self.log.debug "Processing a %p example..." % [ lang ]
+
+		# Test it if it's testable
+		if options[:testable]
+			content = test_content( body, lang, page )
+		else
+			content = body
+		end
+
+		# If the language is something that can itself include PIs, look for the 
+		# special '<??end ?>' token and strip the extra '?'
+		if %w[xml html textile xhtml].include?( lang )
+			content.gsub!( /<\?\?(.*?)\?>/ ) do
+				tag_content = $1
+				self.log.debug "Unescaping escaped PI %p in example." % [ tag_content ]
+				"<?#{tag_content}?>"
+			end
+
+			self.log.debug "  example is now: %p" % [ content ]
+		end
+
+		# Strip trailing blank lines and syntax-highlight
+		content = highlight( content.strip, lang )
+		caption = %{<div class="caption">} + caption.to_s + %{</div>} if caption
+
+		return %{<notextile><div class="example %s-example">%s%s</div></notextile>} %
+		 	[lang, content, caption || '']
+	end
+
+
+	### Parse an options hash for filtering from the given +args+, which can either 
+	### be a plain String, in which case it is assumed to be the name of the language the example 
+	### is in, or a Hash of configuration options.
+	def parse_options( args )
+		args = "{ #{args} }" unless args && args.strip[0] == ?{
+		args = YAML.load( args )
+
+		# Convert to Symbol keys and value
+		args.keys.each do |k|
+			newval = args.delete( k )
+			next if newval.nil? || (newval.respond_to?(:size) && newval.size == 0)
+			args[ k.to_sym ] = newval.respond_to?( :to_sym ) ? newval.to_sym : newval
+		end
+		return DEFAULTS.merge( args )
+	end
+
+
+	### Test the given +content+ with a rule specific to the given +language+.
+	def test_content( body, language, page )
+		self.log.debug "Running a testable %p example..." % [ language ]
+		case language.to_sym
+		when :ruby
+			return self.test_ruby_content( body, page )
+
+		when :yaml
+			return self.test_yaml_content( body, page )
+
+		else
+			self.log.error "...oops, I don't know how to test %p examples." % [ language ]
+			return body
+		end
+	end
+
+
+	### Test the specified Ruby content for valid syntax
+	def test_ruby_content( source, page )
+		# $stderr.puts "Testing ruby content..."
+		libdir = Pathname.new( __FILE__ ).dirname.parent.parent.parent + 'lib'
+		extdir = Pathname.new( __FILE__ ).dirname.parent.parent.parent + 'ext'
+
+		options = Rcodetools::XMPFilter::INITIALIZE_OPTS.dup
+		options[:include_paths] |= [ libdir.to_s, extdir.to_s ]
+		options[:width] = 80
+
+		if page.config['example_prelude']
+			prelude = page.config['example_prelude']
+			self.log.debug "  prepending prelude:\n#{prelude}"
+			source = prelude.strip + "\n\n" + source.strip
+		else
+			self.log.debug "  no prelude; page config is: %p" % [ page.config ]
+		end
+
+		rval = Rcodetools::XMPFilter.run( source, options )
+
+		self.log.debug "test output: %p" % [ rval ]
+		return rval.join
+	rescue Exception => err
+		return "%s while testing: %s\n  %s" %
+			[ err.class.name, err.message, err.backtrace.join("\n  ") ]
+	end
+
+
+	### Test the specified YAML content for valid syntax
+	def test_yaml_content( source, metadata )
+		YAML.load( source )
+	rescue YAML::Error => err
+		return "# Invalid YAML: " + err.message + "\n" + source
+	else
+		return source
+	end
+
+
+	### Highlights the given +content+ in language +lang+.
+	def highlight( content, lang )
+		source = ERB::Util.html_escape( content )
+		return %Q{\n\n<pre class="brush: #{lang}">#{source}</pre>\n\n}
+	end
+
+end # class Strelka::CMS::PageFilter::Example
+