watts 0.0.1

data/Rakefile

@@ -0,0 +1,53 @@
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+
+$: << "#{File.dirname(__FILE__)}/lib"
+
+spec = Gem::Specification.new { |s|
+	s.platform = Gem::Platform::RUBY
+
+	s.author = "Pete Elmore"
+	s.email = "pete@debu.gs"
+	s.files = Dir["{lib,doc,bin,ext}/**/*"].delete_if {|f| 
+		/\/rdoc(\/|$)/i.match f
+	} + %w(Rakefile)
+	s.require_path = 'lib'
+	s.has_rdoc = true
+	s.extra_rdoc_files = Dir['doc/*'].select(&File.method(:file?))
+	s.extensions << 'ext/extconf.rb' if File.exist? 'ext/extconf.rb'
+	Dir['bin/*'].map(&File.method(:basename)).map(&s.executables.method(:<<))
+
+	s.name = 'watts'
+	s.summary =
+		"Another Rack-based web framework.  Yes, another one.  Sorry, guys."
+	s.homepage = "http://debu.gs/#{s.name}"
+	%w(metaid).each &s.method(:add_dependency)
+	s.version = '0.0.1'
+}
+
+Rake::RDocTask.new(:doc) { |t|
+	t.main = 'doc/README'
+	t.rdoc_files.include 'lib/**/*.rb', 'doc/*', 'bin/*', 'ext/**/*.c', 
+		'ext/**/*.rb'
+	t.options << '-S' << '-N'
+	t.rdoc_dir = 'doc/rdoc'
+}
+
+Rake::GemPackageTask.new(spec) { |pkg|
+	pkg.need_tar_bz2 = true
+}
+desc "Cleans out the packaged files."
+task(:clean) {
+	FileUtils.rm_rf 'pkg'
+}
+
+desc "Builds and installs the gem for #{spec.name}"
+task(:install => :package) { 
+	g = "pkg/#{spec.name}-#{spec.version}.gem"
+	system "sudo gem install -l #{g}"
+}
+
+desc "Runs IRB, automatically require()ing #{spec.name}."
+task(:irb) {
+	exec "irb -Ilib -r#{spec.name}"
+}

data/doc/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2010 Peter Elmore (pete at debu.gs)
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the 
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in 
+all copies or substantial portions of the Software. 
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL 
+THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 
+DEALINGS IN THE SOFTWARE.

data/doc/examples/README

@@ -0,0 +1,10 @@
+All of the examples are standalone Watts applications, which you can run
+directly.  They could all be pretty easily turned into rackup files.
+
+hello_world.rb is the most basic demonstration.
+matching.rb shows how Watts's pattern-matching works.
+hoshi.rb is a demonstration of the view-wrapping resource.
+environment.rb shows what you have to work with in your request.
+
+Although they're all single-file applications, there's nothing that
+prevents you from splitting things up arbitrarily.  It's all just Ruby.

data/doc/examples/environment.rb

@@ -0,0 +1,38 @@
+#!/usr/bin/env ruby
+# This example gives you a feel for the environment in which Watts::Resources
+# run.  By "environment", of course, I really just mean that the 'env' value
+# Rack gives you on requests is accessible from inside your resources.  You can
+# request /, /foo, or whatever.  If you want to have a look at how query string
+# parsing works, try having a look at /query?asdf=jkl%3B .  This example just
+# uses the CGI library that comes with Ruby for parsing queries.
+
+require 'watts'
+require 'pp'
+require 'cgi'
+
+class WattsEnvironment < Watts::App
+	class EnvPrinter < Watts::Resource
+		get { |*a|
+			s = ''
+			PP.pp env, s
+			s
+		}
+	end
+
+	class Queries < Watts::Resource
+		get {
+			CGI.parse(env['QUERY_STRING']).inspect rescue 'Couldn\'t parse.'
+		}
+	end
+
+	resource('/', EnvPrinter) {
+		resource('foo', EnvPrinter)
+		resource([:yeah], EnvPrinter)
+		resource('query', Queries)
+	}
+end
+
+app = WattsEnvironment.new
+builder = Rack::Builder.new { run app }
+
+Rack::Handler::Mongrel.run builder, :Port => 8080

data/doc/examples/hello_world.rb

@@ -0,0 +1,18 @@
+#!/usr/bin/env ruby
+# This is, I think, the simplest possible Watts application.  It starts up Rack
+# on port 8080 and responds only to GET /.
+
+require 'watts'
+
+class Simple < Watts::App
+	class EZResource < Watts::Resource
+		get { "Hello, World!\n" }
+	end
+
+	resource('/', EZResource)
+end
+
+app = Simple.new
+builder = Rack::Builder.new { run app }
+
+Rack::Handler::Mongrel.run builder, :Port => 8080

data/doc/examples/hoshi.rb

@@ -0,0 +1,31 @@
+#!/usr/bin/env ruby
+# An example illustrating how to use the for_html_view method, with help from
+# Hoshi.  Try running this and opening http://localhost:8080/ in a browser.
+
+require 'watts'
+require 'hoshi'
+
+class HelloHTML < Watts::App
+	# First, a simple, traditional greeting, done in Hoshi:
+	class View < Hoshi::View :html4
+		def hello
+			doc {
+				head { title 'Hello, World!' }
+				body {
+					h1 'Here is your greeting:'
+					p 'Hello, World!'
+				}
+			}
+			render
+		end
+	end
+
+	Res = Watts::Resource.for_html_view(View, :hello)
+
+	resource('/', Res)
+end
+
+app = HelloHTML.new
+builder = Rack::Builder.new { run app }
+
+Rack::Handler::Mongrel.run builder, :Port => 8080

data/doc/examples/matching.rb

@@ -0,0 +1,61 @@
+#!/usr/bin/env ruby
+# An illustration of the pattern-matching capabilities of Watts.  Some URLs to
+# try if you start this one up:
+# 	http://localhost:8080/strlen/foo (Which should tell you '3'.)
+# 	http://localhost:8080/fib/15 (Which should give you 987.)
+# 	http://localhost:8080/fib/foo (Which is a 404.  'foo' isn't a number!)
+# 	http://localhost:8080/fib/f (Which should give you 0x3db.)
+# 	http://localhost:8080/fib/0x15 (Which should give you 0x452f.)
+
+require 'watts'
+
+class MatchingDemo < Watts::App
+	class Strlen < Watts::Resource
+		# Takes an argument, and just returns the length of the argument.
+		get { |str| str.length.to_s + "\n" }
+	end
+
+	class Fibonacci < Watts::Resource
+		# This resource takes an argument for GET.  It is filled in by Watts
+		# according to the argument pattern passed into resource below.
+		get { |n| fib(n.to_i).to_s + "\n" }
+
+		# A naive, recursive, slow, text-book implementation of Fibonacci.
+		def fib(n)
+			if n < 2
+				1
+			else
+				fib(n - 1) + fib(n - 2)
+			end
+		end
+	end
+
+	# As above, but with a base-16 number.
+	class HexFibonacci < Fibonacci
+		get { |n| "0x" + fib(n.to_i(16)).to_s(16) + "\n" }
+	end
+
+	resource('/') {
+		# A symbol can be used to indicate an 'argument' component of a path,
+		# which is in turn passed to the resource's method as paths.  It will
+		# match anything, making it almost equivalent to just using an empty
+		# regex (see below), except that it can serve as documentation.
+		resource(['strlen', :str], Strlen)
+
+		resource('fib') {
+			# You can match arguments based on a regex.  The path component for
+			# the regex is passed to the resource's method as part of the
+			# argument list.
+			resource([/^[0-9]+$/], Fibonacci)
+
+			# As above, but here we use hexadecimal.  If the pattern for
+			# Fibonacci doesn't match, then we'll end up hitting this one.
+			resource([/^(0x)?[0-9a-f]+$/i], HexFibonacci)
+		}
+	}
+end
+
+app = MatchingDemo.new
+builder = Rack::Builder.new { run app }
+
+Rack::Handler::Mongrel.run builder, :Port => 8080

data/lib/watts.rb

@@ -0,0 +1,270 @@
+%w(
+	forwardable
+	metaid
+	rack
+	watts/monkey_patching
+).each &method(:require)
+
+# Here's the main module, Watts.
+module Watts
+	# You are unlikely to need to interact with this.  It's mainly for covering
+	# up the path-matching logic for Resources.
+	class Path
+		extend Forwardable
+		include Enumerable
+
+		attr_accessor :resource
+		attr_new Hash, :sub_paths
+
+		def match path, args
+			if path.empty?
+				[resource, args]
+			elsif(sub = self[path[0]])
+				sub.match(path[1..-1], args)
+			else
+				each { |k,sub|
+					if k.kind_of?(Regexp) && k.match(path[0])
+						return sub.match(path[1..-1], args + [path[0]])
+					end
+				}
+				each { |k,sub|
+					if k.kind_of?(Symbol)
+						return sub.match(path[1..-1], args + [path[0]])
+					end
+				}
+				nil
+			end
+		end
+
+		def_delegators :sub_paths, :'[]', :'[]=', :each
+	end
+
+	# In order to have a Watts app, you'll want to subclass Watts::App.  For a
+	# good time, you'll also probably want to provide some resources to that
+	# class using the resource method, which maps paths to resources.
+	class App
+		Errors = {
+			400 =>
+				[400, {'Content-Type' => 'text/plain'}, "400 Bad Request.\n"],
+			404 =>
+				[404, {'Content-Type' => 'text/plain'}, "404 Not Found\n"],
+		}
+
+		class << self
+			attr_new Hash, :http_methods
+			attr_new Watts::Path, :path_map
+			attr_new Array, :path_stack
+			attr_writer :path_stack
+		end
+
+		def self.decypher_path p
+			return p if p.kind_of?(Array)
+			return [] if ['/', ''].include?(p)
+			p = p.split('/')
+			p.select { |sub| sub != '' }
+		end
+
+		to_instance :path_map, :decypher_path
+
+		# If you want your Watts application to do anything at all, you're very
+		# likely to want to call this method at least once.  The basic purpose
+		# of the method is to tell your app how to match a resource to a path.
+		# For example, if you create a resource (see Watts::Resource) Foo, and
+		# you want requests against '/foo' to match it, you could do this:
+		# 	resource('foo', Foo)
+		#
+		# The first argument is the path, and the second is the resource that
+		# path is to match.  (Please see the README for more detailed
+		# documentation of path-matching.)  You may also pass it a block, in
+		# which resources that are defined are 'namespaced'.  For example, if
+		# you also had a resource called Bar and wanted its path to be a
+		# sub-path of the Foo resource's (e.g., '/foo/bar'), then typing these
+		# lines is a pretty good plan:
+		# 	resource('foo', Foo) {
+		# 		resource('bar', Bar)
+		# 	}
+		#
+		# Lastly, the resource argument itself is optional, for when you want a
+		# set of resources to be namespaced under a given path, but don't
+		# have a resource in mind.  For example, if you suddenly needed your
+		# entire application to reside under '/api', you could do this:
+		# 	resource('api') {
+		#	 	resource('foo', Foo) {
+		# 			resource('bar', Bar)
+		#			resource('baz', Baz)
+		# 		}
+		#	}
+		#
+		# This is probably the most important method in Watts.  Have a look at
+		# the README and the example applications under doc/examples if you
+		# want to understand the pattern-matching, arguments to resources, etc.
+		def self.resource(path, res = nil, &b)
+			path = decypher_path(path)
+
+			last = (path_stack + path).inject(path_map) { |m,p|
+				m[p] ||= Path.new
+			}
+			last.resource = res
+
+			if b
+				old_stack = path_stack
+				self.path_stack = old_stack + path
+				b.call
+				self.path_stack = old_stack
+			end
+			res
+		end
+
+		# Given a path, returns the matching resource, if any.
+		def match req_path
+			req_path = decypher_path req_path
+			path_map.match req_path, []
+		end
+
+		# Our interaction with Rack.
+		def call env, req_path = nil
+			rm = env['REQUEST_METHOD'].downcase.to_sym
+			return(Errors[400]) unless Resource::HTTPMethods.include?(rm)
+
+			req_path ||= decypher_path env['REQUEST_PATH']
+			resource_class, args = match req_path
+
+			if resource_class
+				res = resource_class.new(env)
+				res.send(rm, *args)
+			else
+				Errors[404]
+			end
+		end
+	end
+
+	# HTTP is all about resources, and this class represents them.  You'll want
+	# to subclass it and then define some HTTP methods on it, then use
+	# your application's resource method to tell it where to find these
+	# resources.  (See Watts::App.resource().)  If you want your resource to
+	# respond to GET with a cheery, text/plain greeting, for example:
+	# 	class Foo < Watts::Resource
+	# 		get { || "Hello, world!" }
+	# 	end
+	# 
+	# Or you could do something odd like this:
+	# 	class RTime < Watts::Resource
+	#		class << self; attr_accessor :last_post_time; end
+	#
+	# 		get { || "The last POST was #{last_post_time}." }
+	# 		post { ||
+	# 			self.class.last_post_time = Time.now.strftime('%F %R')
+	#			[204, {}, []]
+	#		}
+	#
+	#		def last_post_time
+	#			self.class.last_post_time || "...never"
+	#		end
+	#	end
+	# 
+	# It is also possible to define methods in the usual way (e.g., 'def get
+	# ...'), although you'll need to add them to the list of allowed methods
+	# (for OPTIONS) manually.  Have a look at the README and doc/examples.
+	class Resource
+		HTTPMethods =
+			[:get, :post, :put, :delete, :head, :options, :trace, :connect]
+
+		class << self
+			attr_new Array, :http_methods
+		end
+
+		# For each method allowed by HTTP, we define a "Method not allowed"
+		# response, and a method for generating a method.  You may also just
+		# def methods, as seen below for the options method.
+		HTTPMethods.each { |http_method|
+			meta_def(http_method) { |&b|
+				http_methods << http_method.to_s.upcase
+				bmname = "__#{http_method}".to_sym
+				define_method(bmname, &b)
+				define_method(http_method) { |*args|
+					begin
+						resp = send bmname, *args
+					rescue ArgumentError => e
+						# TODO:  Arity/path args mismatch handler here.
+						raise e
+					end
+
+					# TODO:  Problems.
+					case resp
+					when nil
+						[response.status, response.headers, response.body]
+					when Array
+						resp
+					else
+						[200, {'Content-Type' => 'text/plain'}, resp.to_s]
+					end
+				}
+			}
+			define_method(http_method) { |*args| default_http_method(*args) }
+		}
+
+		# This method is for creating Resources that simply wrap first-class
+		# HTML views.  It was created with Hoshi in mind, although you can use
+		# any class that can be instantiated and render some HTML when the
+		# specified method is called.  It takes two arguments:  the view class,
+		# and the method to call to render the HTML.
+		def self.for_html_view klass, method
+			c = Class.new HTMLViewResource
+			c.view_class = klass
+			c.view_method = method
+			c
+		end
+
+		to_instance :http_methods
+		attr_new Rack::Response, :response
+		attr_accessor :env, :response
+
+		# Every resource, on being instantiated, is given the Rack env.
+		def initialize(env)
+			self.env = env
+			self.response = Rack::Response.new
+		end
+
+		# The default options method, to comply with RFC 2616, returns a list
+		# of allowed methods in the Allow header.  These are filled in when the
+		# method-defining methods (i.e., get() et al) are called.
+		def options(*args)
+			[
+				200,
+				{
+					'Content-Length' => '0', # cf. RFC 2616
+					'Allow' => http_methods.join(', ')
+				},
+				[]
+			]
+		end
+
+		# By default, we return "405 Method Not Allowed" and set the Allow:
+		# header appropriately.
+		def default_http_method(*args)
+			[405, { 'Allow' => http_methods.join(', ') }, 'Method not allowed.']
+		end
+	end
+
+	# See the documentation for Watts::Resource.for_html_view().
+	class HTMLViewResource < Resource
+		class << self
+			attr_writer :view_class, :view_method
+		end
+
+		def self.view_class
+			@view_class ||= (superclass.view_class rescue nil)
+		end
+
+		def self.view_method
+			@view_method ||= (superclass.view_method rescue nil)
+		end
+
+		to_instance :view_class, :view_method
+
+		def get *args
+			[200, {'Content-Type' => 'text/html'},
+				view_class.new.send(view_method, *args)]
+		end
+	end
+end

data/lib/watts/monkey_patching.rb

@@ -0,0 +1,26 @@
+# This is the place to stuff all of the monkey-patches.
+
+require 'metaid'
+
+class Class
+	# Has instances delegate methods to the class.
+	def to_instance *ms
+		ms.each { |m|
+			define_method(m) { |*a|
+				self.class.send(m, *a)
+			}
+		}
+	end
+
+	# A replacement for def x; @x ||= Y.new; end
+	def attr_new klass, *attrs
+		attrs.each { |attr|
+			ivname = "@#{attr}"
+			define_method(attr) {
+				ivval = instance_variable_get(ivname)
+				return ivval if ivval
+				instance_variable_set(ivname, klass.new)
+			}
+		}
+	end
+end

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification 
+name: watts
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Pete Elmore
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-06-01 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: metaid
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+description: 
+email: pete@debu.gs
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- doc/TODO
+- doc/LICENSE
+files: 
+- lib/watts.rb
+- lib/watts/monkey_patching.rb
+- doc/TODO
+- doc/examples/hello_world.rb
+- doc/examples/environment.rb
+- doc/examples/README
+- doc/examples/matching.rb
+- doc/examples/hoshi.rb
+- doc/LICENSE
+- Rakefile
+has_rdoc: true
+homepage: http://debu.gs/watts
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: Another Rack-based web framework.  Yes, another one.  Sorry, guys.
+test_files: []
+