mwmitchell-pepper 0.3.0

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2008 Matt Mitchell - goodieboy@gmail.com
+
+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/README

@@ -0,0 +1,103 @@
+Welcome to the pepper wiki!
+Pepper is a Ruby, DSL based framework for creating RESTful web applications. It adheres to the Ruby Rack specification.
+
+Pepper treats every fragment in a URL as a "context". Each context can be mapped to a block or another Pepper enabled module. For example, a URL of:
+
+<pre>/users/1/images/1</pre>
+
+could translate to a context block tree of:
+
+<pre>
+<code>
+map 'users' do
+  map :digit do
+    get{"The value of this user is #{value}"}
+    map 'images' do
+      map :digit do
+        get{"The ID of this image is #{value}"}
+      end
+    end
+  end
+end
+</code>
+</pre>
+
+Because each block maps to a single url fragment, "routing" is not needed. The value of a context's url fragment can be accessed by its :value attribute. You can also name the fragment and propagate to the request params like:
+
+<pre>
+<code>
+map :user_id=>/\d+/ do
+  puts params[:user_id]
+end
+</code>
+</pre>
+
+The :user_id param will then be available as a global request param to other contexts and "actions".
+
+The fragment value passed to :map can be a string, a regular expression or a symbol that matches one of the built-in rules; :digit, :word, etc.
+
+Standard HTTP methods (GET, POST, PUT, etc.) are used as the "actions". Each of the actions methods can accept a "rule" hash. The keys map to the REQUEST values (but down-cased and symbolized). So you could execute an action only if it matched the IP, or SERVER_NAME. The value of the rule can be a Regular Expression or a string.
+
+Here is an example:
+
+<pre>
+<code>
+require 'pepper'
+
+module SeriousApp
+  
+  class Contact # A delegate/sub-app
+    
+    include Pepper::Context::Delegate
+    
+    build do
+      before :post do
+        # a before :post block. Default is :all.
+      end
+      
+      get{'GET request'}
+      post{'POST request'}
+      
+      # request for /contact/:word
+      map :word do
+        get{"GET request for /contact/#{value}"}
+      end
+    end
+  end
+  
+  class Root
+    
+    include Pepper::App
+    
+    build do
+      get{'A simple GET to /'}
+      post{'A POST to /'}
+      
+      # /about/
+      map 'about' do
+        get{'GET request for /about'}
+      end
+      
+      # /notes
+      map 'notes' do
+        get(:server_name=>/^myspecialdomain\.com$/) do
+          'GET request for /notes, but only allowing a SERVER_NAME of "myspecialdomain.com"'}
+        end
+      end
+      
+      # forwarding /contact to the Contact class
+      map 'contact', {}, Contact
+    end
+    
+  end
+end
+</code>
+</pre>
+
+You then instantiate the Root class, and pass it to Rack's "run" method.
+
+<pre>
+<code>
+run SeriousApp::Root.new
+</code>
+</pre>

data/lib/pepper.rb

@@ -0,0 +1,377 @@
+require 'rubygems'
+require 'rack'
+
+$:.unshift File.dirname(__FILE__) unless $:.include? File.dirname(__FILE__)
+
+module Pepper
+  
+  VERSION='0.3.1'
+  
+  class Request < Rack::Request
+    def method_sym
+      request_method.to_s.downcase.to_sym
+    end
+    def path_info_slices
+      ['/'] + path_info.to_s.gsub(/\/+/, '/').sub(/^\/|\/$/, '').split('/')
+    end
+  end
+  
+  module Context
+
+    class Action
+      
+      #
+      # The main context class needs to be able to resfresh this when reloading this action instance
+      #
+      attr_accessor :app
+      
+      attr :method
+      attr :options
+      attr :block
+
+      def initialize(method, app, options={}, &block)
+        @app=app
+        @method=method
+        @options=options
+        @block=block
+      end
+      
+      def app; @app end
+      def request; app.request end
+      def params; request.params end
+      
+      def method_missing(m,*args,&block)
+        @app.send(m, *args, &block) if [:header, :headers].include?(m)
+      end
+      
+      def execute!; instance_eval(&@block) end
+
+    end
+
+    #
+    #
+    #
+    module InstanceMethods
+
+      #
+      # The main app class needs to be able to set this
+      #
+      attr_accessor :app
+
+      #
+      # attributes that are set by the "initialize" method
+      #
+      # can be a string, regexp, hash or symbol
+      #  * string - the current path slice will be compared using ==
+      #  * regexp - the current path slice will be compared using =~
+      #  * hash - if the value matches, the current slice is assigned to the request.params using the key
+      #    * the value can in-turn be any string, regexp, hash or symbol
+      #  * symbol - can be used to match preset rules found in the +PATTERNS+ hash
+      #    if the symbol is not found in +PATTERNS+, it's converted to a string and uses ==
+      #
+      attr :pattern
+      # The parent context
+      attr :parent
+      # the options passed into +map+ method calls
+      attr :options
+      # optional module name to delegate logic for a given sub-path
+      attr :delegate
+      # the block that holds the executable context code
+      attr :block
+      
+      def method_missing(m,*args,&block)
+        @app.send(m, *args, &block) if [:header, :headers].include?(m)
+      end
+      
+      #
+      # Create the HTTP action methods...
+      #
+      HTTP_METHODS=%W(get post put delete)
+      HTTP_METHODS.each do |m|
+        class_eval <<-EOF
+          def #{m}(options={}, &block)
+            if a=actions.detect {|a|a.method==:#{m}.to_sym and a.options==options}
+              # refresh the app - this is needed because the root context is a "static" instance
+              a.app=@app
+              return
+            end
+            actions << Action.new(:#{m}, @app, options, &block)
+          end
+        EOF
+      end
+      
+      #
+      # "attributes" that are set after initialization
+      #
+
+      # returns the child contexts
+      def children; @children||=[]; end
+      # returns the value from the path slices that this context matched
+      def value; @value||=nil; end
+      # the base application instance
+      def app; @app; end
+      # returns instance of Rack::Request
+      def request; app.request; end
+      # shortcut for request.params
+      def params; request.params; end
+      # 
+      def actions; @actions||=[] end
+      #
+      def before_blocks; @before_blocks||={} end
+      #
+      def after_blocks; @after_blocks||={} end
+
+      def before(action=:all, &block)
+        before_blocks[action]=block
+      end
+
+      def after(action=:all, &block)
+        after_blocks[action]=block
+      end
+
+      #
+      # Finds the action (get, post, put etc.) base on:
+      # * the method
+      # * the env/hash values
+      #
+      def find_action(method, env={})
+        actions.each do |a|
+          next if a.method != method
+          return a if a.options.nil? or a.options.size==0
+          a.options.each_pair do |k,v|
+            k=k.to_s.upcase
+            return a if env[k]==v or env[k]=~v
+          end
+        end
+        nil
+      end
+
+      PATTERNS={
+        :digit=>/^\d+$/,
+        :word=>/^\w+$/
+      }
+
+      #
+      #
+      #
+      def match?(pattern, value)
+        ok = simple_match?(pattern, value)
+        return ok if ok
+        # if hash, use the value as the pattern and set the request param[key] to the value argument
+        return (params[pattern.keys.first] = match?(pattern[pattern.keys.first], value)) if pattern.is_a?(Hash)
+        # if symbol
+        if pattern.is_a?(Symbol)
+          # lookup the symbol in the PATTERNS hash
+          return value if PATTERNS[pattern] and match?(PATTERNS[pattern], value)
+          # There was no match, convert to string
+          simple_match?(pattern.to_s, value)
+        end
+      end
+
+      #
+      #
+      #
+      def simple_match?(pattern, value)
+        # if string, simple comparison
+        return value if (pattern.is_a?(String) and value == pattern)
+        # if regexp, regx comparison
+        return value if (pattern.is_a?(Regexp) and value =~ pattern)
+      end
+
+      #
+      # Recursively looks for matching context instances returning the last one that matches.
+      #
+      def resolve(slices)
+        return unless match?(pattern, slices.first)
+        @value=slices.shift
+        catch :delegate do
+          instance_eval(&@block) if @block
+        end
+        if delegate
+          raise 'Only module based delegates are allowed' unless delegate.class==Module
+          return delegate.delegate!(self, [@value]+slices)
+        end
+        return self if slices.size==0
+        children.each do |child|
+          if found=child.resolve(slices)
+            return found
+          end
+        end
+        nil
+      end
+
+      #
+      # Shortcut assigning a delegate
+      #
+      def delegate_to(handler)
+        @delegate=handler
+        throw :delegate
+      end
+
+      def child_exists?(pattern, options)
+        children.detect{|child|child.pattern==pattern and child.options==options}
+      end
+
+      #
+      # The main method for creating child contexts
+      #
+      def map(pattern, options={}, delegate=nil, &block)
+        if child=child_exists?(pattern, options)
+          # refresh the app
+          child.app=@app
+          return child
+        else
+          children << Context::Base.new(pattern, options, delegate, self, &block)
+          children.last.app=app
+        end
+      end
+
+    end # end InstanceMethods
+
+    #
+    #
+    #
+
+    #
+    # Used for handling areas of your application, within the context of some path.
+    # For example, if you had a blog area of your site, you could off-load the logic
+    # from the main app to a "delegate" and keep the main app clear of too much clutter.
+    # It would actually be possible for your main app to do nothing but delegate.
+    #
+    module Delegate
+
+      #
+      # Shortcut for:
+      #   extend Pepper::Context::Delegate::ClassMethods
+      #
+      def self.included(base)
+        base.extend ClassMethods
+      end
+
+      #
+      # Pepper::Context::Delegate::ClassMethods
+      #
+      module ClassMethods
+
+        #
+        # Bring in the standard context methods
+        #
+        include Context::InstanceMethods
+
+        #
+        # define the standard build method so the delegate can start creating the context tree
+        #
+        def build(options={}, &block)
+          @options=options
+          @block=block
+        end
+
+        #
+        # Sets up this module as a delegate handler
+        # delegating_for - Pepper::Context::Base instance
+        # slices - array of path fragments
+        #
+        def delegate!(delegating_for, slices)
+          @app=delegating_for.app
+          @parent=delegating_for.parent
+          # Set the @pattern to the delegating_for's value so that when resolve is called, there will be a match
+          @pattern=delegating_for.value
+          # add this delegate to the delegating_for.parent.children
+          delegating_for.parent.children.unshift self
+          # find the matching context based on the slices
+          return resolve(slices)
+        end
+      end
+
+    end
+
+    #
+    # The base context class that gets instantiated for each "map" call
+    #
+    class Base
+
+      include Context::InstanceMethods
+
+      #
+      #
+      #
+      def initialize(pattern, options={}, delegate=nil, parent=nil, &block)
+        @pattern=pattern
+        @options=options
+        @delegate=delegate
+        @block=block
+        @parent=parent
+      end
+
+    end
+
+  end
+
+  #########
+
+  module App
+
+    #
+    # Shortcut for:
+    #   include Pepper::App::InstanceMethods
+    #   extend Pepper::App::ClassMethods
+    #
+    def self.included(base)
+      base.extend ClassMethods
+      base.send :include, InstanceMethods
+    end
+
+    #
+    # The class methods; provides the main "build" method
+    #
+    module ClassMethods
+
+      attr :root
+
+      #
+      # The initial build, class method
+      #
+      def build(options={}, &block)
+        @root=Context::Base.new('/', options, nil, nil, &block)
+      end
+
+    end
+
+    #
+    # The interface for Rack to connect to using the +call+ method
+    #
+    module InstanceMethods
+      
+      class Error404 < RuntimeError; end
+      class ErrorMethodNotSupported < RuntimeError; end
+      class ErrorRootContextNotFound < RuntimeError; end
+      
+      def root; self.class.root end
+      def request; @request end
+      
+      def response; @response; end
+      
+      def header(name, value)
+        response[name]=value
+      end
+      
+      def headers(hash)
+        hash.each_pair {|k,v|header(k,v)}
+      end
+      
+      def call(rack_env)
+        @response=Rack::Response.new
+        @request=Request.new(rack_env)
+        raise ErrorRootContextNotFound if root.nil?
+        root.app=self
+        context = root.resolve(request.path_info_slices)
+        raise Error404 if context.nil?
+        action = context.find_action(request.method_sym, request.env)
+        raise ErrorMethodNotSupported if action.nil?
+        response.write action.execute!
+        response.finish
+      end
+    end
+  end
+  
+end

data/lib/pepper/demo.rb

@@ -0,0 +1,54 @@
+module Pepper::Demo
+  
+  module Canning
+    include Pepper::Context::Delegate
+    build do
+      get do
+        'CANNING PEPPERS: Small peppers may be left whole; large peppers may be quartered. Remove cores and seeds; blister and peel peppers; flatten whole peppers. Add ½ teaspoon of salt to each pint jar, if desired. Fill jars loosely with peppers and add fresh boiled water, leaving 1-inch headspace. Adjust lids and process half-pints or pints for 35 minutes at 11 pounds pressure in a dial gauge canner or at 10 pounds pressure in a weighted gauge canner.'
+      end
+    end
+  end
+  
+  class Pickled
+    
+    include Pepper::App
+    
+    build do
+      
+      header 'Content-Type', 'text/html'
+      
+      get do
+        header 'Content-Type', 'text/plain'
+        'CAUTION: When working with hot peppers, wear plastic gloves while handling them, or wash hands thoroughly with soap and water before touching your face.'
+      end
+      
+      post{'We are creating a pickled pepper just for you. You will learn to love her.'}
+      put{'Adding a little more vinegar... removing some fuzz here and there.'}
+      delete{'Bad! Bad! Bad pickled pepper!'}
+      
+      map :peter do
+        get{"I am Peter, the pickled-pepper-packer, I want to tell you my story."}
+        map :piper do
+          map :packed do
+            map :a do
+              map :pack do
+                map :of do
+                  map :pickled do
+                    map :peppers do
+                      get{'zwiggle'}
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+      
+      map(:how_to_can) {delegate_to Canning}
+      
+    end
+    
+  end
+  
+end

data/spec/common.rb

@@ -0,0 +1,7 @@
+$:.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'pepper'
+require 'spec'
+
+def new_rack_env(path='/', attrs={})
+  Rack::MockRequest.env_for(path, attrs)
+end

data/spec/demo.spec.rb

@@ -0,0 +1,69 @@
+require File.join(File.dirname(__FILE__), 'common.rb')
+require 'pepper/demo'
+
+#
+#
+#
+describe Pepper::Demo::Pickled do
+  
+  before :each do
+    @app_class = Pepper::Demo::Pickled
+    @app=@app_class.new
+  end
+  
+  it '(class) should respond to build' do
+    @app_class.should respond_to(:build)
+  end
+  
+  it "should respond to :call" do
+    @app.should respond_to(:call)
+  end
+  
+  it "should have a nil :request attribute until :call is executed" do
+    @app.request.should == nil
+  end
+  
+  it "should have a :request attribute after calling the call method" do
+    @app.call(new_rack_env)
+    @app.should respond_to(:request)
+    @app.request.class.should == Pepper::Request
+  end
+  
+  it "should not fail when requesting a POST, GET, PUT or DELETE to /" do
+    r=@app.call(new_rack_env)
+    r[0].should == 200
+    r[1].should == {'Content-Type'=>'text/plain'}
+    r[2].body.should == ['CAUTION: When working with hot peppers, wear plastic gloves while handling them, or wash hands thoroughly with soap and water before touching your face.']
+    #
+    r=@app.call(new_rack_env('/', {'REQUEST_METHOD'=>'POST'}))
+    r[0].should == 200
+    r[1].should == {'Content-Type'=>'text/html'}
+    r[2].body.should == ['We are creating a pickled pepper just for you. You will learn to love her.']
+    #
+    r=@app.call(new_rack_env('/', {'REQUEST_METHOD'=>'PUT'}))
+    r[0].should == 200
+    r[1].should == {'Content-Type'=>'text/html'}
+    r[2].body.should == ['Adding a little more vinegar... removing some fuzz here and there.']
+    #
+    r=@app.call(new_rack_env('/', {'REQUEST_METHOD'=>'DELETE'}))
+    r[0].should == 200
+    r[1].should == {'Content-Type'=>'text/html'}
+    r[2].body.should == ['Bad! Bad! Bad pickled pepper!']
+  end
+  
+  it "should raise Error404 when requesting an invalid path" do
+    lambda {@app.call(new_rack_env('/blah'))}.should raise_error(@app.class::Error404)
+  end
+  
+  it "should raise ErrorMethodNotSupported when requesting a valid path, but no matching request method action" do
+    lambda {@app.call(new_rack_env('/peter', {'REQUEST_METHOD'=>'DELETE'}))}.should raise_error(@app.class::ErrorMethodNotSupported)
+  end
+  
+  it 'should support unlimited nesting depth' do
+    @app.call(new_rack_env('/peter/piper/packed/a/pack/of/pickled/peppers'))[2].body.should == ['zwiggle']
+  end
+  
+  it 'should support delegating from one context block to another' do
+    @app.call(new_rack_env('/how_to_can'))[2].body.should == ['CANNING PEPPERS: Small peppers may be left whole; large peppers may be quartered. Remove cores and seeds; blister and peel peppers; flatten whole peppers. Add ½ teaspoon of salt to each pint jar, if desired. Fill jars loosely with peppers and add fresh boiled water, leaving 1-inch headspace. Adjust lids and process half-pints or pints for 35 minutes at 11 pounds pressure in a dial gauge canner or at 10 pounds pressure in a weighted gauge canner.']
+  end
+end

data/spec/request.spec.rb

@@ -0,0 +1,23 @@
+require File.join(File.dirname(__FILE__), 'common.rb')
+
+#
+#
+#
+describe Pepper::Request do
+  it '(path_info_fragments return) should return an array' do
+    r=Pepper::Request.new(new_rack_env('/'))
+    r.path_info_slices.class.should == Array
+  end
+  
+  it '(path_info_fragments return) should always start with a /' do
+    r=Pepper::Request.new(new_rack_env('a/test//to/a/path/'))
+    r.path_info_slices[0].should == '/'
+    r=Pepper::Request.new(new_rack_env('/a/test//to/a/path/'))
+    r.path_info_slices[0].should == '/'
+  end
+  
+  it 'should remove duplicate slashes when responding to path_info_fragments' do
+    r=Pepper::Request.new(new_rack_env('a/test//to/a/path/'))
+    r.path_info_slices.should == ['/', 'a', 'test', 'to', 'a', 'path']
+  end
+end

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification 
+name: mwmitchell-pepper
+version: !ruby/object:Gem::Version 
+  version: 0.3.0
+platform: ruby
+authors: 
+- Matt Mitchell
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-06-11 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rack
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - "="
+      - !ruby/object:Gem::Version 
+        version: 0.3.0
+    version: 
+description: Pepper is a Ruby, DSL based framework for creating RESTful web applications. It adheres to the Ruby Rack specification.
+email: goodieboy@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+- LICENSE
+files: 
+- lib/pepper.rb
+- lib/pepper/demo.rb
+- README
+- LICENSE
+has_rdoc: true
+homepage: http://github.com/mwmitchell/pepper
+post_install_message: 
+rdoc_options: 
+- --main
+- README
+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: 
+rubygems_version: 1.0.1
+signing_key: 
+specification_version: 2
+summary: Pepper is a Ruby, DSL based framework for creating RESTful web applications. It adheres to the Ruby Rack specification.
+test_files: 
+- spec/common.rb
+- spec/demo.spec.rb
+- spec/request.spec.rb