simple_router 0.9.8.1

data/.gitignore

@@ -0,0 +1,3 @@
+pkg/
+doc/
+*.gem

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright © 2009 Martin Aumont (mynyml)
+
+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/Manifest

@@ -0,0 +1,17 @@
+.gitignore
+LICENSE
+Manifest
+README.md
+Rakefile
+TODO
+examples/rack_app.ru
+lib/simple_router.rb
+lib/simple_router/dsl.rb
+lib/simple_router/engines/simple_engine.rb
+lib/simple_router/routes.rb
+simple_router.gemspec
+test/engines/test_simple_engine.rb
+test/test_dsl.rb
+test/test_helper.rb
+test/test_routes.rb
+test/test_simple_router.rb

data/README.md

@@ -0,0 +1,81 @@
+
+Summary
+-------
+Small and simple standalone router, meant for use with Rack applications.
+
+Features
+--------
+* Familiar Sinatra-like DSL for defining actions
+* Modular architecture (see ROUTING ENGINES section)
+* No magic
+* Low level / Highly flexible
+* Simple code
+
+Examples
+--------
+
+  class App
+    include SimpleRouter::DSL
+
+    get '/' do
+      'home'
+    end
+
+    get '/archives/:year/:month/:day' do |year, month, day|
+      Article.archived.find_by_date(year, month, day)
+    end
+
+    def call(env)
+      verb, path  = ENV['REQUEST_METHOD'], ENV['PATH_INFO']
+      route = self.class.routes.match(verb, path)
+      route.nil? ?
+        [404, {'Content-Type' => 'text/html'}, '404 page not found'] :
+        [200, {'Content-Type' => 'text/html'}, route.action.call(*route.values)]
+    end
+  end
+
+The SimpleRouter::DSL mixin provides 5 class methods:
+
+  #get, #post, #put, #delete and #routes
+
+The four verb methods allow you to define actions that will match a request for
+the verb and route signature it defines.
+
+The #routes method responds to #match and will return the first matching route
+(in order they were defined), and the values of the variables defined in the
+route signature if any (:year, :month, ...).
+
+Finally, the route returned is a simple object: for the second route in the
+example above:
+
+  route.verb    #=> :get
+  route.path    #=> '/archives/:year/:month/:day'
+  route.action  #=> lambda {|year, month, day| Article.archived.find_by_date(year, month, day) }
+  route.values  #=> ['2008', '07', '01'] # after being matched with path '/archives/2008/07/01'
+
+See examples/ directory for executable code examples.
+
+Routing Engines
+---------------
+By design, the code is seperated in two main components:
+
+  o DSL for defining routes/actions and retrieving requested action block.
+  o Routing engine
+
+Different engines can be used by assigning them to the router:
+
+  SimpleRouter.engine = UltraFastEngine
+
+This allows, for instance, a new faster engine to be used by an app without
+changes in the top level DSL.
+
+Engines can also allow route definitions to include more (or less!) features.
+For example, the built-in SimpleEngine allows route variables and extension
+handling. Others could add variable conditions ( :id => Integer ), mime-type
+restrictions, etc.
+
+#### Engine Writers
+
+Engines only need to conform to a simple interface. See
+lib/simple_router/engines/simple_engine.rb for details.
+

data/Rakefile

@@ -0,0 +1,30 @@
+def gem_opt
+  defined?(Gem) ? "-rubygems" : ""
+end
+
+def ruby(path)
+  path = "-e'%w( #{path.join(' ')} ).each {|p| require p }'" if path.is_a?(Array)
+  system "ruby #{gem_opt} -I.:lib:test #{path}"
+end
+
+# --------------------------------------------------
+# Tests
+# --------------------------------------------------
+task(:default => :test)
+
+desc "Run tests"
+task(:test) do
+  exit ruby( Dir['test/**/test_*.rb'] - ['test/test_helper.rb'] )
+end
+
+# --------------------------------------------------
+# Docs
+# --------------------------------------------------
+desc "Generate YARD Documentation"
+task(:yardoc) do
+  require 'yard'
+  files   = %w( lib/**/*.rb )
+  options = %w( -o doc/yard --readme README.md --files LICENSE )
+  YARD::CLI::Yardoc.run *(options + files)
+end
+

data/TODO

@@ -0,0 +1 @@
+o improve docs

data/examples/rack_app.ru

@@ -0,0 +1,45 @@
+require 'pathname'
+root  =  Pathname(__FILE__).dirname.parent.expand_path
+$:.unshift(root.join('lib'))
+
+# run me with:
+#   $rackup examples/rack_app.ru
+# --------------------------------------------------
+require 'rubygems'
+require 'simple_router'
+
+class App
+  include SimpleRouter::DSL
+
+  get '/' do |params|
+    <<-html
+    <pre>
+      params: #{params.inspect}
+    </pre>
+    html
+  end
+
+  get '/:foo.:type' do |foo, type, params|
+    <<-html
+    <pre>
+      foo: #{foo.inspect}
+      type: #{type.inspect}
+      params: #{params.inspect}
+    </pre>
+    html
+  end
+
+  def call(env)
+    request = Rack::Request.new(env)
+
+    verb = request.request_method.downcase.to_sym
+    path = Rack::Utils.unescape(request.path_info)
+
+    route = self.class.routes.match(verb, path)
+    route.nil? ?
+      [404, {'Content-Type' => 'text/html'}, '404 page not found'] :
+      [200, {'Content-Type' => 'text/html'}, [route.action.call(*route.values.push(request.params))]]
+  end
+end
+
+run App.new

data/lib/simple_router.rb

@@ -0,0 +1,13 @@
+module SimpleRouter
+  class << self
+    attr_accessor :engine
+    def engine() @engine || Engines::SimpleEngine end
+  end
+
+  autoload :DSL,    'simple_router/dsl'
+  autoload :Routes, 'simple_router/routes'
+
+  module Engines
+    autoload :SimpleEngine, 'simple_router/engines/simple_engine'
+  end
+end

data/lib/simple_router/dsl.rb

@@ -0,0 +1,57 @@
+module SimpleRouter
+
+  # Mixin that provides a Sinatra-line DSL frontend to the routing engine
+  # backend.
+  #
+  # Meant to be minimal, simple and as magic-free as possible.
+  # When mixed in, only adds 5 class methods (#get, #post, #put, #delete and #routes).
+  #
+  # ==== Examples
+  # # simple rack app
+  #
+  # class App
+  #   include SimpleRouter::DSL
+  #
+  #   get '/' do
+  #     'home'
+  #   end
+  #
+  #   get '/users/:id' do |id|
+  #   end
+  #
+  #   put '/:foo/:bar' do |foo, bar, *params|
+  #   end
+  #
+  #   def call(env)
+  #     request = Rack::Request.new(env)
+  #
+  #     verb = request.request_method
+  #     path = Rack::Utils.unescape(request.path_info)
+  #
+  #     action = self.class.routes.match(verb, path).action
+  #     action.nil? ? [404, {}, []] : [200, {}, [action.call]]
+  #   end
+  # end
+  #
+  # ==== Notes
+  # Because the DSL is a simple mixin, it can be used in any class (i.e. not
+  # necessarily a rack app).
+  #
+  module DSL
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.class_eval do
+        @routes = Routes.new
+      end
+    end
+
+    module ClassMethods
+      attr_reader :routes
+
+      def get(   path, opts={}, &block) routes.add(:get,    path, opts, &block) end
+      def post(  path, opts={}, &block) routes.add(:post,   path, opts, &block) end
+      def put(   path, opts={}, &block) routes.add(:put,    path, opts, &block) end
+      def delete(path, opts={}, &block) routes.add(:delete, path, opts, &block) end
+    end
+  end
+end

data/lib/simple_router/engines/simple_engine.rb

@@ -0,0 +1,102 @@
+require 'pathname'
+
+module SimpleRouter
+  module Engines
+    module SimpleEngine #:nodoc:
+
+      def self.match(*args)
+        Base.match(*args)
+      end
+
+      class Base
+        # Finds a route definition that matches a path
+        #
+        # ===== Arguments
+        # * path: actual path to match (e.g. ENV['PATH_INFO'])
+        # * routes: array of 'routes', where each route is composed of [pattern, options]. If route isn't an array, an empty options hash is assumed
+        #
+        # Currently, this engine implementation ignores route options.
+        #
+        # ===== Returns
+        # Array of two elements:
+        #
+        # * index 0: first matching route
+        # * index 1: array of values for the matched route's variables (in the order they were specified in the route)
+        #
+        # ===== Examples
+        #
+        #   SimpleEngine.match('/foo', ['/', '/foo', '/bar/baz'])   #=> ['/foo', []]
+        #   SimpleEngine.match('/80/07/01', ['/:year/:month/:day']) #=> ['/foo', ['80', '07', '01']]
+        #
+        def self.match(path, routes)
+          path     = Path.new(path)
+          patterns = routes.map {|route| Pattern.new(Array(route).first) }
+
+          patterns.each do |pattern|
+            return [pattern.to_s, pattern.vars] if pattern == path
+          end
+
+          [nil, []]
+        end
+      end
+
+      class Path #:nodoc:
+        attr_accessor :parts, :ext
+
+        def initialize(path)
+          self.parts, self.ext = split_path(path)
+        end
+
+        def to_s
+          '/' + self.parts.join('/') + self.ext
+        end
+
+        private
+          def split_path(path)
+            path  = path.to_s
+            ext   = Pathname(path).extname
+            path  = path.sub(/#{ext}$/,'')
+            parts = path.split('/').reject {|part| part.empty? }
+            [parts, ext]
+          end
+      end
+
+      class Pattern < Path #:nodoc:
+
+        def variables
+          return [] unless @match
+
+          a = []
+          self.parts.each_with_index do |part,i|
+            a << @match.parts[i] if part[0] == ?:
+          end
+          a << @match.ext[1..-1] if self.ext[1] == ?:
+          a
+        end
+        alias :vars :variables
+
+        def ==(path)
+          is_match = size_match?(path) && ext_match?(path) && static_match?(path)
+          @match = path if is_match
+          is_match
+        end
+
+        private
+          def size_match?(path)
+            self.parts.size == path.parts.size
+          end
+
+          def ext_match?(path)
+            (self.ext == path.ext) || (self.ext[1] == ?: && !path.ext.empty?)
+          end
+
+          def static_match?(path)
+            self.parts.each_with_index do |part,i|
+              return false unless part[0] == ?: || path.parts[i] == part
+            end
+            true
+          end
+      end
+    end
+  end
+end

data/lib/simple_router/routes.rb

@@ -0,0 +1,36 @@
+module SimpleRouter
+  class Routes < Array
+
+    def add(*args, &action)
+      self << Route.new(*args, &action)
+    end
+
+    def match(verb, path)
+      return nil if self.empty?
+
+      verb = verb.to_s.downcase.strip.to_sym
+
+      routes = self.select {|route| route.verb == verb }
+      paths  = routes.map  {|route| route.path }
+
+      path, values = SimpleRouter.engine.match(path, paths)
+      return nil if path.nil?
+
+      route = routes.detect {|route| route.path == path }
+      route.values = values
+      route
+    end
+
+    class Route
+      attr_accessor :verb,:path,:options,:action, :values
+
+      def initialize(verb, path, options, &action)
+        self.verb    = verb
+        self.path    = path
+        self.options = options
+        self.action  = action
+        self.values  = nil
+      end
+    end
+  end
+end

data/simple_router.gemspec

@@ -0,0 +1,17 @@
+Gem::Specification.new do |s|
+  s.name                = 'simple_router'
+  s.version             = "0.9.8.1"
+  s.summary             = "Simple, minimalistic, standalone router meant to be used with pure rack applications"
+  s.description         = "Simple, minimalistic, standalone router meant to be used with pure rack applications."
+  s.author              = "mynyml"
+  s.email               = "mynyml@gmail.com"
+  s.homepage            = "http://github.com/mynyml/simple_router"
+  s.rubyforge_project   = "simple_router"
+  s.has_rdoc            =  true
+  s.require_path        = "lib"
+  s.files               =  File.read("Manifest").strip.split("\n")
+
+  s.add_development_dependency 'rack'
+  s.add_development_dependency 'nanotest'
+  s.add_development_dependency 'nanotest_extensions'
+end

data/test/engines/test_simple_engine.rb

@@ -0,0 +1,145 @@
+require 'test/test_helper'
+
+## SimpleEngine
+context do
+  include SimpleRouter::Engines::SimpleEngine
+
+  # matches static paths 
+  test do
+    Base.match('/',    ['/', '/foo']).first.must == '/'
+    Base.match('/foo', ['/', '/foo']).first.must == '/foo'
+    Base.match('/bar', ['/', '/foo']).first.must == nil
+  end
+
+  # matches variable paths 
+  test do
+    path, vars = Base.match('/80/07', ['/foo', '/:year/:month'])
+    path.must == '/:year/:month'
+    vars.must == ['80','07']
+  end
+
+  # matches hybrid paths 
+  test do
+    path, vars = Base.match('/archives/80/07', ['/foo', '/archives/:year/:month'])
+    path.must == '/archives/:year/:month'
+    vars.must == ['80','07']
+  end
+
+  # ignores leading slash in path 
+  test do
+    path, vars = Base.match('archives/80/07', ['/foo', '/archives/:year/:month'])
+    path.must == '/archives/:year/:month'
+    vars.must == ['80','07']
+  end
+
+  # no matches 
+  test do
+    path, vars = Base.match('/80/07/01', ['/foo', '/:year/:month'])
+    path.must == nil
+    vars.must == []
+  end
+
+  # treats extension as pattern part 
+  test do
+    path, vars = Base.match('/a/b.xml', ['/:foo/:bar', '/:foo/:bar.:type'])
+    path.must == '/:foo/:bar.:type'
+    vars.must == ['a','b','xml']
+  end
+end
+
+## Pattern
+context do
+  include SimpleRouter::Engines::SimpleEngine
+
+  # static pattern matches a path 
+  test do
+    path    = Path.new('/foo/bar')
+    pattern = Pattern.new('/foo/bar')
+
+    assert { pattern == path }
+  end
+
+  # variable pattern matches a path 
+  test do
+    path    = Path.new('/foo/bar')
+    pattern = Pattern.new('/:foo/:bar')
+
+    assert { pattern == path }
+  end
+
+  # pattern variables 
+  test do
+    path    = Path.new('/foo/bar/baz')
+    pattern = Pattern.new('/:a/:b/:c')
+
+    assert { pattern == path }
+    pattern.vars.must == %w( foo bar baz )
+  end
+
+  # pattern variables with extension 
+  test do
+    path    = Path.new('/foo/bar/baz.xml')
+    pattern = Pattern.new('/:a/:b/:c.:type')
+
+    assert { pattern == path }
+    pattern.vars.must == %w( foo bar baz xml )
+  end
+
+  # variable pattern matches a path with static extension 
+  test do
+    path    = Path.new('/foo/bar.xml')
+    pattern = Pattern.new('/:foo/:bar.xml')
+
+    assert { pattern == path }
+  end
+
+  # variable pattern matches a path with variable extension 
+  test do
+    path    = Path.new('/foo/bar.xml')
+    pattern = Pattern.new('/:foo/:bar.:type')
+
+    assert { pattern == path }
+  end
+
+  # pattern without extension doesn't match path with extension 
+  test do
+    path    = Path.new('/foo/bar.xml')
+    pattern = Pattern.new('/:foo/:bar')
+
+    assert { pattern != path }
+  end
+
+  # pattern with static extension doesn't match path without extension 
+  test do
+    path    = Path.new('/foo/bar')
+    pattern = Pattern.new('/:foo/:bar.xml')
+
+    assert { pattern != path }
+  end
+
+  # pattern with variable extension doesn't match path without extension 
+  test do
+    path    = Path.new('/foo/bar')
+    pattern = Pattern.new('/:foo/:bar.:type')
+
+    assert { pattern != path }
+  end
+
+  # doesn't ignore dots in path parts 
+  test do
+    path    = Path.new('/foo/bar.baz/abc')
+    pattern = Pattern.new('/:a/:b/:c')
+
+    assert { pattern == path }
+    pattern.variables.must == %w( foo bar.baz abc )
+  end
+
+  # doesn't get confused with extension when path contains other dots 
+  test do
+    path    = Path.new('/foo/bar.baz/abc.xml')
+    pattern = Pattern.new('/:a/:b/:c.:type')
+
+    assert { pattern == path }
+    pattern.variables.must == %w( foo bar.baz abc xml )
+  end
+end

data/test/test_dsl.rb

@@ -0,0 +1,45 @@
+require 'test/test_helper'
+
+class App
+  include SimpleRouter::DSL
+end
+
+context do
+
+  setup do
+    SimpleRouter.engine = SimpleRouter::Engines::SimpleEngine
+  end
+
+  teardown do
+    App.routes.clear
+  end
+
+  ## API
+
+  # provides action verb methods 
+  test do
+    App.get(   '/foo') {}
+    App.post(  '/foo') {}
+    App.put(   '/foo') {}
+    App.delete('/foo') {}
+
+    App.routes.size.must == 4
+  end
+
+  # provides routes object 
+  test do
+    App.respond_to?(:routes).must == true
+    App.routes.must.kind_of?(SimpleRouter::Routes)
+  end
+
+  ## matching
+
+  # matching routes 
+  test do
+    App.get('/foo') { 'foo' }
+    App.get('/bar') { 'bar' }
+
+    App.routes.match(:get, '/foo').wont == nil
+    App.routes.match(:get, '/foo').action.call.must == 'foo'
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,17 @@
+require 'pathname'
+require 'nanotest'
+require 'nanotest/spec'
+require 'nanotest/contexts'
+begin
+  require 'ruby-debug'
+  require 'redgreen'        # gem install mynyml-redgreen
+  require 'nanotest/stats'
+  require 'nanotest/focus'
+rescue LoadError, RuntimeError
+end
+
+$:.unshift Pathname(__FILE__).dirname.parent + 'lib' 
+require 'simple_router'
+
+include Nanotest
+include Nanotest::Contexts

data/test/test_routes.rb

@@ -0,0 +1,63 @@
+require 'test/test_helper'
+
+## Routes
+context do
+  Routes = SimpleRouter::Routes
+
+  setup do
+    @routes = Routes.new
+    @action = lambda {}
+  end
+
+  # stores route definitions 
+  test do
+    @routes.add(:get, '/foo', {}, &@action)
+    @routes.first.path.must == '/foo'
+  end
+
+  ## matching
+
+  # matches a path 
+  test do
+    @routes.add(:get, '/foo', {}, &@action)
+    @routes.add(:get, '/bar', {}, &@action)
+
+    @routes.match(:get, '/bar').wont == nil
+    @routes.match(:get, '/bar').path.must == '/bar'
+  end
+
+  # returns nil when no route matches 
+  test do
+    @routes.add(:get, '/foo', {}, &@action)
+    @routes.add(:get, '/bar', {}, &@action)
+
+    @routes.match('/baz', :get).must == nil
+  end
+
+  # normalizes passed in verb string 
+  test do
+    @routes.add(:get, '/foo', {}, &@action)
+    @routes.add(:get, '/bar', {}, &@action)
+
+    @routes.match('get',  '/bar').path.must == '/bar'
+    @routes.match('GET',  '/bar').path.must == '/bar'
+    @routes.match(' GET ','/bar').path.must == '/bar'
+  end
+end
+
+## Route
+context do
+
+  # internal API 
+  test do
+    verb, path, options, action = :get, '/foo', {}, lambda {}
+
+    route = SimpleRouter::Routes::Route.new(verb, path, options, &action)
+    route.verb    .must == verb
+    route.path    .must == path
+    route.options .must == options
+    route.action  .must == action
+    route.values  .must == nil
+  end
+end
+

data/test/test_simple_router.rb

@@ -0,0 +1,25 @@
+require 'test/test_helper'
+
+class App
+  include SimpleRouter::DSL
+end
+
+context do
+
+  setup do
+    SimpleRouter.engine = nil
+  end
+
+  ## engine
+
+  # default engine
+  test do
+    SimpleRouter.engine.name.split('::').last.must == 'SimpleEngine'
+  end
+
+  # custom engine
+  test do
+    SimpleRouter.engine = ::Object
+    SimpleRouter.engine.name.must == 'Object'
+  end
+end

metadata

@@ -0,0 +1,100 @@
+--- !ruby/object:Gem::Specification 
+name: simple_router
+version: !ruby/object:Gem::Version 
+  version: 0.9.8.1
+platform: ruby
+authors: 
+- mynyml
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-01-06 00:00:00 -05:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rack
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: nanotest
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: nanotest_extensions
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: Simple, minimalistic, standalone router meant to be used with pure rack applications.
+email: mynyml@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- LICENSE
+- Manifest
+- README.md
+- Rakefile
+- TODO
+- examples/rack_app.ru
+- lib/simple_router.rb
+- lib/simple_router/dsl.rb
+- lib/simple_router/engines/simple_engine.rb
+- lib/simple_router/routes.rb
+- simple_router.gemspec
+- test/engines/test_simple_engine.rb
+- test/test_dsl.rb
+- test/test_helper.rb
+- test/test_routes.rb
+- test/test_simple_router.rb
+has_rdoc: true
+homepage: http://github.com/mynyml/simple_router
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: simple_router
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Simple, minimalistic, standalone router meant to be used with pure rack applications
+test_files: []
+