strelka 0.0.1.pre.309 → 0.0.1.pre.314

data/ChangeLog

@@ -1,9 +1,28 @@
+2012-09-26  Michael B. Hix  <mhix@laika.com>
+
+	* Deploying.rdoc:
+	Convert Deploying.rdoc.
+	[97e69307bb0c] [tip]
+
+	* Branch merge.
+	[06f595677069]
+
+	* Plugins.rdoc:
+	Plugins.rdoc corrections.
+	[2be9f81193f0]
+
+2012-09-25  Michael B. Hix  <mhix@laika.com>
+
+	* Plugins.rdoc:
+	Plugins.rdoc conversion.
+	[c5ee423330e3]
+
 2012-09-25  Michael Granger  <ged@FaerieMUD.org>
 
 	* lib/strelka/constants.rb, lib/strelka/cookie.rb,
 	lib/strelka/exceptions.rb, spec/strelka/cookie_spec.rb:
 	Updating Strelka::Cookie to adhere to rfc6265
-	[04568539aa83] [tip]
+	[04568539aa83]
 
 2012-09-21  Michael Granger  <ged@FaerieMUD.org>
 

data/Deploying.rdoc

@@ -1,80 +1,89 @@
----
-title: Deploying a Strelka App
-layout: default
-index: 4
-filters:
-  - erb
-  - links
-  - examples
-  - textile
----
+= Deploying
 
-h2. <%= page.config['title'] %>
+== Deploying a Strelka App
 
-<div id="auto-toc"></div>
+Strelka uses the Rubygems plugin system to find and load applications. You don't
+need to necessarily package them up this way if you've already got a deployment
+strategy in mind, but the rest of this manual assumes you will be.
 
-Strelka uses the Rubygems plugin system to find and load applications. You don't need to necessarily package them up this way if you've already got a deployment strategy in mind, but the rest of this manual assumes you will be.
+A Strelka app plugin:
 
-** Include their static content and the apps themselves in their data dir
-** Include any library code in lib/
-* These instructions use Hoe, but you don't need to necessarily use that
+* Includes its static content and the apps themselves in its datadir.
+* Includes library code under <tt>lib/</tt>.
 
-h3. Setting up the Project
+These instructions use Hoe[http://docs.seattlerb.org/hoe/], but you don't need
+to necessarily use it.
 
-First you'll need to create the project layout. It should look something like this:
 
-!images/project-layout.png(Example project layout screenshot)!
+== Setting up the Project
 
-The data directory should contain your apps, templates, and any static content your app requires in a directory with the same name as your gem. Strelka's runtime environment will look for them there, though most of them can be configured to look elsewhere. The presence of an @apps@ subdirectory is what Strelka looks for when searching for installed application gems.
+First you'll need to create the project layout. It should look something like
+this:
 
-The rest of the gem is "pretty standard":http://chneukirchen.github.com/rps/: Your applications' reusable code should be under @lib/@ and @ext/@ directories, and tests or specs under @test/@ and @spec/@, respectively. 
+https://bitbucket.org/ged/strelka/raw/97e69307bb0c/manual/resources/images/project-layout.png
 
-h4. Easy Setup with Hoe
+The data directory should contain your apps, templates, and any static content
+your app requires in a directory with the same name as your gem. Strelka's
+runtime environment will look for them there, though most of them can be
+configured to look elsewhere. The presence of an <tt>apps</tt> subdirectory is
+what Strelka looks for when searching for installed application gems.
 
-Hoe is a Rake helper that provides tasks for setting up and maintaining a project. It comes with a tool called 'sow' that generates a project based on a template directory. Strelka includes a Hoe project template in its @contrib/hoetemplate@ directory. If you copy that directory into @~/.hoe_template@:
+The rest of the gem is {pretty standard}[http://chneukirchen.github.com/rps/].
+Your applications' reusable code should be under <tt>lib/</tt> and <tt>ext/</tt>
+directories, and tests or specs under <tt>test/</tt> and <tt>spec/</tt>,
+respectively.
 
-bc. $ sow  #(run once to set up the template directory if you don't have one)
-$ cp -r contrib/hoetemplate ~/.hoe_template/strelka
+=== Easy Setup with Hoe
 
-you can generate a new project like so:
+Hoe is a Rake helper that provides tasks for setting up and maintaining a
+project. It comes with a tool called 'sow' that generates a project based on a
+template directory. Strelka includes a Hoe project template in its
+<tt>contrib/hoetemplate</tt> directory. If you copy that directory into
+<tt>~/.hoe_template</tt>:
 
-bc.. $ sow -s strelka GoodDoggie
-erb: .autotest.erb
-erb: History.rdoc.erb
-erb: Manifest.txt.erb
-erb: README.rdoc.erb
-erb: Rakefile.erb
-erb: data/good_doggie/apps/file_name_app
-erb: data/good_doggie/templates/layout.tmpl.erb
-erb: data/good_doggie/templates/top.tmpl.erb
-erb: lib/file_name.rb.erb
-erb: spec/file_name_spec.rb.erb
+  $ sow  #(run once to set up the template directory if you don't have one)
+  $ cp -r contrib/hoetemplate ~/.hoe_template/strelka
 
-... done, now go fix all occurrences of 'FIX':
+You can generate a new project like so:
 
-  GoodDoggie/data/good_doggie/apps/good_doggie_app:10:	ID = 'FIX' # (set the app id of the main application)
-  GoodDoggie/data/good_doggie/templates/layout.tmpl:5:			FIX (application title)
-  GoodDoggie/data/good_doggie/templates/layout.tmpl:9:		<!-- FIX (set up the main layout template) -->
-  GoodDoggie/data/good_doggie/templates/top.tmpl:1:<!-- FIX (set up the main content template) -->
-  GoodDoggie/lib/good_doggie.rb:3:# FIX (top-level documentation)
-  GoodDoggie/Rakefile:17:	self.developer 'FIX', 'FIX' # (name, email)
-  GoodDoggie/README.rdoc:3:* FIX (url)
-  GoodDoggie/README.rdoc:7:FIX (describe your package)
-  GoodDoggie/README.rdoc:15:Copyright (c) 2011, FIX
+  $ sow -s strelka GoodDoggie
+  erb: .autotest.erb
+  erb: History.rdoc.erb
+  erb: Manifest.txt.erb
+  erb: README.rdoc.erb
+  erb: Rakefile.erb
+  erb: data/good_doggie/apps/file_name_app
+  erb: data/good_doggie/templates/layout.tmpl.erb
+  erb: data/good_doggie/templates/top.tmpl.erb
+  erb: lib/file_name.rb.erb
+  erb: spec/file_name_spec.rb.erb
 
-p. Now just fix all the "FIX" items.
+  ... done, now go fix all occurrences of 'FIX':
 
-Strelka looks for handler apps in the 'apps' subdirectory of your gem's datadir, so in our example, the app is @GoodDoggie/data/good_doggie/apps/good_doggie_app@:
+    GoodDoggie/data/good_doggie/apps/good_doggie_app:10:	ID = 'FIX' # (set the app id of the main application)
+    GoodDoggie/data/good_doggie/templates/layout.tmpl:5:			FIX (application title)
+    GoodDoggie/data/good_doggie/templates/layout.tmpl:9:		<!-- FIX (set up the main layout template) -->
+    GoodDoggie/data/good_doggie/templates/top.tmpl:1:<!-- FIX (set up the main content template) -->
+    GoodDoggie/lib/good_doggie.rb:3:# FIX (top-level documentation)
+    GoodDoggie/Rakefile:17:	self.developer 'FIX', 'FIX' # (name, email)
+    GoodDoggie/README.rdoc:3:* FIX (url)
+    GoodDoggie/README.rdoc:7:FIX (describe your package)
+    GoodDoggie/README.rdoc:15:Copyright (c) 2011, FIX
 
-bc.. # The main GoodDoggie application
-class GoodDoggie::Application < Strelka::App
+Now just fix all the <tt>'FIX'</tt> items.
 
-	# Uncomment this if you need an appid other than 
-	# 'gooddoggie-application'.
-	#ID = 'FIX' # (set the app id of the main application)
+Strelka looks for handler apps in the 'apps' subdirectory of your gem's datadir.
 
+For example, in <tt>GoodDoggie/data/good_doggie/apps/good_doggie_app</tt>:
 
-p. The End
+  # The main GoodDoggie application
+  class GoodDoggie::Application < Strelka::App
+
+  	# Uncomment this if you need an appid other than 
+  	# 'gooddoggie-application'.
+  	#ID = 'FIX' # (set the app id of the main application)
+
+The End
 
 
 

data/Plugins.rdoc

@@ -1,201 +1,176 @@
----
-title: Write Your Own Strelka Plugin
-layout: default
-index: 5
-filters:
-  - erb
-  - api
-  - links
-  - examples
-  - textile
----
-
-h2. <%= page.config['title'] %>
-
-<div id="auto-toc"></div>
-
-h3. Overview
-
-Because Mongrel2 makes it easy to have discrete handler processes
-managing different URI routes, you'll quickly find benefit from
+= Write Your Own Strelka Plugin
+
+== Overview
+
+Because Mongrel2[http://mongrel2.org/] makes it easy to have discrete handler
+processes managing different URI routes, you'll quickly find benefit from
 refactoring common code into reusable components.
 
-As mentioned in the <?link "tutorial":Strelka Tutorial ?> section,
-Strelka breaks out functionality into a set of core plugins that allow
-you to cherry pick the capabilities you need.  It's easy to create your
-own plugins for optional loading of shared behavior into any number of
-handlers.
+As mentioned in the {Strelka Tutorial}[rdoc-ref:Tutorial] section, Strelka
+breaks out functionality into a set of core plugins that allow you to cherry
+pick the capabilities you need. It's easy to create your own plugins for
+optional loading of shared behavior into any number of handlers.
 
-This page is a walkthrough for creating an example Strelka plugin that
-logs all HTTP accesses to a "SQLite":http://www.sqlite.org/ database.
+This page is a walkthrough for creating an example Strelka plugin that logs all
+HTTP accesses to a SQLite[http://www.sqlite.org/] database.
 
-h3. The Basics
 
-A Strelka plugin is just a module under the <?api Strelka::App ?>
-namespace that is extended by the <?api Strelka::Plugin ?> class.
-Once extended, the plugin participates in the @request@ -> @response@
-lifecycle, and is able to alter it via hooks.  The plugin only
-participates for handlers that load it via the @plugin@ declarative.
+== The Basics
+
+A Strelka plugin is just a module under the Strelka::App namespace that is
+extended by the Strelka::Plugin class. Once extended, the plugin participates in
+the <tt>request</tt> -> <tt>response</tt> lifecycle, and is able to alter it via
+hooks.  The plugin only participates for handlers that load it via the
+<tt>plugin</tt> declarative.
 
 Lets start by creating and naming an empty plugin.  We'll call it
-@dblogger@.
+<tt>dblogger</tt>.
 
-<?example { lang: Ruby, caption: "A no-op plugin" } ?>
-require 'strelka'
-require 'strelka/app'
+    require 'strelka'
+    require 'strelka/app'
 
-module Strelka::App::DBLogger
-	extend Strelka::Plugin
-end
-<?end example ?>
+    module Strelka::App::DBLogger
+        extend Strelka::Plugin
+    end
 
-It's important to save the plugin under a path that Strelka can
-locate it.  It can go anywhere in your @$LOAD_PATH@, but should be under a
-@lib/strelka/app@ subdirectory, and the filename should match the class.
+It's important to save the plugin under a path that Strelka can locate it.  It
+can go anywhere in your <tt>$LOAD_PATH</tt>, but should be under a
+<tt>lib/strelka/app</tt> subdirectory, and the filename should match the class.
 
-We'll save this to @lib/strelka/app/dblogger.rb@, and Strelka
+We'll save this to <tt>lib/strelka/app/dblogger.rb</tt>, and Strelka
 applications can use it like so:
 
-<?example { lang: Ruby, caption: "Using the dblogger plugin" } ?>
-require 'strelka'
-
-class ExampleApplication < Strelka::App
-	plugins :routing, :dblogger
-
-	get do |req|
-		res = req.response
-		res.content_type = 'text/plain'
-		return res.body << "Hi!  I'll be logged!"
-	end
-end
-
-ExampleApplication.run
-<?end example ?>
-
-
-h3. Load Order
-
-The request is passed through plugins sequentually.  You can control
-where in the chain your plugin belongs, by using the @run_before@ and
-@run_after@ methods.  Both methods accept a comma separated list of
-other plugin names.
-
-In this example case, we want the logger to log the request before the
-other core plugins run, so any errors still make it out to the log.
-
-<?example { lang: Ruby, caption: "Adding load order" } ?>
-require 'strelka'
-require 'strelka/app'
-
-module Strelka::App::DBLogger
-	extend Strelka::Plugin
-
-	run_before \
-		:auth,
-		:filters,
-		:negotiation,
-		:parameters,
-		:routing,
-		:sessions,
-		:templating
-
-end
-<?end example ?>
-
-h3. Hooks
-
-There are three primary extension points you can override in your
-plugin.  All hooks absolutely require you to @super@ at some point, so
-the request/response chain passes through your plugin.
-
-<dl>
-<dt>fixup_request</dt>
-<dd>
-	Make any changes to the @request@ that are necessary before handling it and
-	return it. This is an alternate extension-point for plugins that
-	wish to modify or replace the request before the request cycle is
-	started.
-</dd>
-<dt>handle_request</dt>
-<dd>
-	Handle the request and return a @response@. This is the main extension-point
-	for the plugin system. Without being overridden or extended by plugins, this
-	method just returns the default Mongrel2 response.
-</dd>
-<dt>fixup_response</dt>
-<dd>
-	Make any changes to the @response@ that are necessary before handing it to
-	Mongrel and return it. This is an alternate extension-point for plugins that
-	wish to modify or replace the response after the whole request cycle is
-	completed.
-</dd>
-</dl>
-
-For our logging purposes, we want to hook the @fixup_response@ method.
-We won't be altering the response itself, but just reading attributes
-from it and squirreling them away.  (Most notably, the @response@ has
-access to the @request@ object, and visa versa.)  You can find more detail
-for these hooks in the API documentation for <?api Strelka::App ?>.
+    require 'strelka'
 
-Here's the complete plugin.
+    class ExampleApplication < Strelka::App
+        plugins :routing, :dblogger
+
+        get do |req|
+            res = req.response
+            res.content_type = 'text/plain'
+            return res.body << "Hi!  I'll be logged!"
+        end
+    end
+
+    ExampleApplication.run
+
+
+== Load Order
+
+The request is passed through plugins sequentually.  You can control where in
+the chain your plugin belongs, by using the <tt>run_before</tt> and
+<tt>run_after</tt> methods.  Both methods accept a comma separated list of other
+plugin names.
+
+In this example case, we want the logger to log the request before the other
+core plugins run, so any errors still make it out to the log.
+
+    require 'strelka'
+    require 'strelka/app'
+
+    module Strelka::App::DBLogger
+        extend Strelka::Plugin
+
+        run_before :auth,
+            :filters,
+            :negotiation,
+            :parameters,
+            :routing,
+            :sessions,
+            :templating
+
+    end
 
-<?example { lang: Ruby, caption: "A basic DBLogger plugin" } ?>
-require 'strelka'
-require 'strelka/app'
-require 'sequel'
-
-module Strelka::App::DBLogger
-	extend Strelka::Plugin
-
-	run_before \
-		:auth,
-		:filters,
-		:negotiation,
-		:parameters,
-		:routing,
-		:sessions,
-		:templating
-
-	def initialize( * )
-		super
-
-		@db = Sequel.sqlite( '////tmp/strelka_access.db' )
-		@db.create_table( :log ) do
-			timestamptz :date,      :null => false
-			varchar     :agent,     :size => 255
-			varchar     :remote_ip, :null => false
-			smallint    :status
-			varchar     :method,    :size => 8, :null => false
-			varchar     :path,      :size => 255
-			varchar     :query,     :size => 255
-			varchar     :referer,   :size => 255
-		end unless @db.table_exists?( :log )
-	end
-
-	attr_reader :db
-
-	def fixup_response( response )
-		request = response.request
-
-		self.log.debug self.db[ :log ].insert(
-			:date      => Time.now.to_s,
-			:agent     => request.headers.user_agent,
-			:remote_ip => request.remote_ip.to_s,
-			:status    => response.status,
-			:method    => request.verb.to_s,
-			:path      => request.uri.path,
-			:query     => request.uri.query,
-			:referer   => request.headers.referer
-		)
-
-		super
-	end
-end
-<?end example ?>
-
-Handler startup creates the database and the logging schema, and
-every request performs an @insert@ with the data we're after.  There's
-plenty of room for improvement here (configurable db location, prepared
-statements), but hopefully that gives you a first-round idea of how easy
-it is to add pluggable functionality to Strelka.
 
+== Hooks
+
+There are three primary extension points you can override in your plugin.  All
+hooks absolutely require you to <tt>super</tt> at some point, so the
+request/response chain passes through your plugin.
+
+[\fixup_request]
+
+	Make any changes to the <tt>request</tt> that are necessary before handling
+	it and return it. This is an alternate extension-point for plugins that wish
+	to modify or replace the request before the request cycle is started.
+
+[\handle_request]
+
+	Handle the <tt>request</tt> and return a <tt>response</tt>. This is the main
+	extension-point for the plugin system. Without being overridden or extended
+	by plugins, this method just returns the default Mongrel2 response.
+
+[\fixup_response]
+
+	Make any changes to the <tt>response</tt> that are necessary before handing
+	it to Mongrel and return it. This is an alternate extension- point for
+	plugins that wish to modify or replace the response after the whole request
+	cycle is completed.
+
+
+== Completing the Example
+
+For our logging purposes, we want to hook the <tt>fixup_response</tt> method. We
+won't be altering the response itself, but just reading attributes from it and
+squirreling them away. Most notably, the <tt>response</tt> has access to the
+<tt>response</tt> object, and visa versa. You can find more detail for these
+hooks in the API documentation for Strelka::App.
+
+Here's the complete plugin.
+
+    require 'strelka'
+    require 'strelka/app'
+    require 'sequel'
+
+    module Strelka::App::DBLogger
+        extend Strelka::Plugin
+
+        run_before :auth,
+            :filters,
+            :negotiation,
+            :parameters,
+            :routing,
+            :sessions,
+            :templating
+
+        def initialize( * )
+            super
+
+            @db = Sequel.sqlite( '////tmp/strelka_access.db' )
+            @db.create_table( :log ) do
+                timestamptz :date,      :null => false
+                varchar     :agent,     :size => 255
+                varchar     :remote_ip, :null => false
+                smallint    :status
+                varchar     :method,    :size => 8, :null => false
+                varchar     :path,      :size => 255
+                varchar     :query,     :size => 255
+                varchar     :referer,   :size => 255
+            end unless @db.table_exists?( :log )
+        end
+
+        attr_reader :db
+
+        def fixup_response( response )
+            request = response.request
+
+            self.log.debug self.db[ :log ].insert(
+                :date      => Time.now.to_s,
+                :agent     => request.headers.user_agent,
+                :remote_ip => request.remote_ip.to_s,
+                :status    => response.status,
+                :method    => request.verb.to_s,
+                :path      => request.uri.path,
+                :query     => request.uri.query,
+                :referer   => request.headers.referer
+            )
+
+            super
+        end
+    end
+
+Handler startup creates the database and the logging schema, and every request
+performs an <tt>insert</tt> with the data we're after. There's plenty of room
+for improvement here (configurable db location, prepared statements), but
+hopefully that gives you a first-round idea of how easy it is to add pluggable
+functionality to Strelka.

data/README.rdoc

@@ -9,10 +9,10 @@ docs :: http://deveiate.org/code/strelka
 == Description
 
 Strelka is a framework for creating and deploying
-"Mongrel2":http://mongrel2.org/ web applications in Ruby.
+Mongrel2[http://mongrel2.org/] web applications in Ruby.
 
-It's named after a lesser known "Russian
-cosmonaut":http://en.wikipedia.org/wiki/Strelka_(dog)#Belka_and_Strelka who was
+It's named after a lesser known {Russian
+cosmonaut}[http://en.wikipedia.org/wiki/Strelka_(dog)#Belka_and_Strelka] who was
 one of the first canine space travelers to orbit the Earth and return alive.
 Her name means "little arrow".
 

data/Rakefile

@@ -39,7 +39,11 @@ hoespec = Hoe.spec 'strelka' do
 	self.dependency 'simplecov',       '~> 0.6', :developer
 
 	self.spec_extras[:licenses] = ["BSD"]
-	self.spec_extras[:rdoc_options] = ['-f', 'fivefish', '-t', 'Strelka Web Application Toolkit']
+	self.spec_extras[:rdoc_options] = [
+		'-f', 'fivefish',
+		'-t', 'Strelka Web Application Toolkit',
+		'-w', '4',
+	]
 	self.require_ruby_version( '>=1.9.2' )
 	self.hg_sign_tags = true if self.respond_to?( :hg_sign_tags= )
 	self.check_history_on_release = true if self.respond_to?( :check_history_on_release= )

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: strelka
 version: !ruby/object:Gem::Version
-  version: 0.0.1.pre.309
+  version: 0.0.1.pre.314
   prerelease: 
 platform: ruby
 authors:
@@ -328,12 +328,12 @@ dependencies:
         version: '3.0'
 description: ! 'Strelka is a framework for creating and deploying
 
-  "Mongrel2":http://mongrel2.org/ web applications in Ruby.
+  Mongrel2[http://mongrel2.org/] web applications in Ruby.
 
 
-  It''s named after a lesser known "Russian
+  It''s named after a lesser known {Russian
 
-  cosmonaut":http://en.wikipedia.org/wiki/Strelka_(dog)#Belka_and_Strelka who was
+  cosmonaut}[http://en.wikipedia.org/wiki/Strelka_(dog)#Belka_and_Strelka] who was
 
   one of the first canine space travelers to orbit the Earth and return alive.
 
@@ -486,6 +486,8 @@ rdoc_options:
 - fivefish
 - -t
 - Strelka Web Application Toolkit
+- -w
+- '4'
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
@@ -505,6 +507,6 @@ rubyforge_project: strelka
 rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
-summary: Strelka is a framework for creating and deploying "Mongrel2":http://mongrel2.org/
+summary: Strelka is a framework for creating and deploying Mongrel2[http://mongrel2.org/]
   web applications in Ruby
 test_files: []