grape 0.1.0 → 0.1.1

data/.rspec

@@ -1,3 +1,2 @@
 --color
---format=nested
---fail-fast
+--format=nested

data/Gemfile

@@ -1,3 +1,5 @@
+source 'http://rubygems.org'
+
 gem 'rack'
 gem 'rack-mount', '~> 0.6.13'
 gem 'rack-jsonp'
@@ -9,6 +11,7 @@ gem 'multi_xml'
 group :development do
   gem 'rake'
   gem 'jeweler'
+  # gem 'yard'
 end
 
 group :test do

data/Gemfile.lock

@@ -1,4 +1,5 @@
 GEM
+  remote: http://rubygems.org/
   specs:
     builder (2.1.2)
     cucumber (0.8.5)

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2009 Michael Bleigh
+Copyright (c) 2010 Michael Bleigh and Intridea, Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.markdown

@@ -0,0 +1,75 @@
+# Grape
+
+Grape is a REST-like API micro-framework for Ruby. It is built to complement existing web application frameworks such as Rails and Sinatra by providing a simple DSL to easily provide APIs. It has built-in support for common conventions such as multiple formats, subdomain/prefix restriction, and versioning.
+
+## Installation
+
+Grape is available as a gem, to install it just install the gem:
+
+    gem install grape
+    
+## Basic Usage
+
+Grape APIs are Rack applications that are created by subclassing `Grape::API`. Below is a simple example showing some of the more common features of Grape in the context of recreating parts of the Twitter API.
+
+    class Twitter::API < Grape::Base
+      version '1'
+      
+      helpers do
+        def current_user
+          @current_user ||= User.authorize!(env)
+        end
+        
+        def authenticate!
+          error!('401 Unauthorized', 401) unless current_user
+        end
+      end
+      
+      resource :statuses do
+        get :public_timeline do
+          Tweet.limit(20)
+        end
+      
+        get :home_timeline do
+          authenticate!
+          current_user.home_timeline
+        end
+        
+        get '/show/:id' do
+          Tweet.find(params[:id])
+        end
+        
+        post :update do
+          authenticate!
+          Tweet.create(
+            :user => current_user,
+            :text => params[:status]
+          )
+        end
+      end
+    end
+    
+This would create a Rack application that could be used like so (in a Rackup file):
+
+    use Twitter::API
+    
+And would respond to the following routes:
+
+    GET  /1/statuses/public_timeline(.json)
+    GET  /1/statuses/home_timeline(.json)
+    GET  /1/statuses/show/:id(.json)
+    POST /1/statuses/update(.json)
+    
+Serialization takes place automatically. For more detailed usage information, please visit the [Grape Wiki](http://github.com/intridea/grape/wiki).
+    
+## Note on Patches/Pull Requests
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a future version unintentionally.
+* Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+## Copyright
+
+Copyright (c) 2010 Michael Bleigh and Intridea, Inc. See LICENSE for details.

data/Rakefile

@@ -3,6 +3,10 @@ require 'bundler'
 
 Bundler.setup :default, :test, :development
 
+def version
+  @version ||= open('VERSION').read.trim
+end
+
 begin
   require 'jeweler'
   Jeweler::Tasks.new do |gem|
@@ -33,12 +37,34 @@ end
 task :spec => :check_dependencies
 task :default => :spec
 
-require 'rake/rdoctask'
-Rake::RDocTask.new do |rdoc|
-  version = File.exist?('VERSION') ? File.read('VERSION') : ""
-
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "grape #{version}"
-  rdoc.rdoc_files.include('README*')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-end
+begin
+  require 'yard'
+  YARD_OPTS = ['-m', 'markdown', '-M', 'maruku']
+  DOC_FILES = ['lib/**/*.rb', 'README.markdown']
+  
+  YARD::Rake::YardocTask.new(:doc) do |t|
+    t.files   = DOC_FILES
+    t.options = YARD_OPTS
+  end
+  
+  namespace :doc do
+    YARD::Rake::YardocTask.new(:pages) do |t|
+      t.files   = DOC_FILES
+      t.options = YARD_OPTS + ['-o', '../grape.doc']
+    end
+    
+    namespace :pages do
+      desc 'Generate and publish YARD docs to GitHub pages.'
+      task :publish => ['doc:pages'] do
+        Dir.chdir(File.dirname(__FILE__) + '/../grape.doc') do
+          system("git add .")
+          system("git add -u")
+          system("git commit -m 'Generating docs for version #{version}.'")
+          system("git push origin gh-pages")
+        end
+      end
+    end
+  end
+rescue LoadError
+  puts "You need to install YARD."
+end

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.1.1

data/grape.gemspec

@@ -5,16 +5,16 @@
 
 Gem::Specification.new do |s|
   s.name = %q{grape}
-  s.version = "0.1.0"
+  s.version = "0.1.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Michael Bleigh"]
-  s.date = %q{2010-11-13}
+  s.date = %q{2010-11-14}
   s.description = %q{A Ruby framework for rapid API development with great conventions.}
   s.email = %q{michael@intridea.com}
   s.extra_rdoc_files = [
     "LICENSE",
-     "README.rdoc"
+     "README.markdown"
   ]
   s.files = [
     ".document",
@@ -24,7 +24,7 @@ Gem::Specification.new do |s|
      "Gemfile",
      "Gemfile.lock",
      "LICENSE",
-     "README.rdoc",
+     "README.markdown",
      "Rakefile",
      "VERSION",
      "autotest/discover.rb",

data/lib/grape/api.rb

@@ -1,13 +1,19 @@
 require 'rack/mount'
 require 'rack/auth/basic'
+require 'logger'
 
 module Grape
+  # The API class is the primary entry point for
+  # creating Grape APIs. Users should subclass this
+  # class in order to build an API.
   class API
-    module Helpers; end
-    
     class << self
       attr_reader :route_set
       
+      def logger
+        @logger ||= Logger.new($STDOUT)
+      end
+      
       def reset!
         @settings = [{}]
         @route_set = Rack::Mount::RouteSet.new
@@ -15,7 +21,7 @@ module Grape
       end
       
       def call(env)
-        puts "#{env['REQUEST_METHOD']} #{env['PATH_INFO']}"
+        logger.info "#{env['REQUEST_METHOD']} #{env['PATH_INFO']}"
         route_set.freeze.call(env)
       end
       
@@ -30,6 +36,11 @@ module Grape
         @settings
       end
       
+      # Set a configuration value for this
+      # namespace.
+      #
+      # @param key [Symbol] The key of the configuration variable.
+      # @param value [Object] The value to which to set the configuration variable.
       def set(key, value)
         @settings.last[key.to_sym] = value
       end
@@ -48,6 +59,9 @@ module Grape
         new_versions.any? ? nest(block){ set(:version, new_versions) } : settings[:version]
       end
       
+      # Specify the default format for the API's 
+      # serializers. Currently only `:json` is
+      # supported.
       def default_format(new_format = nil)
         new_format ? set(:default_format, new_format.to_sym) : settings[:default_format]
       end
@@ -76,6 +90,8 @@ module Grape
         end
       end
       
+      # Add an authentication type to the API. Currently
+      # only `:http_basic` is supported.
       def auth(type = nil, options = {}, &block)
         if type
           set(:auth, {:type => type.to_sym, :proc => block}.merge(options))
@@ -93,47 +109,34 @@ module Grape
         auth :http_basic, options, &block
       end
       
-      def route_set
-        @route_set ||= Rack::Mount::RouteSet.new
-      end
-      
-      def compile_path(path)
-        parts = []
-        parts << prefix if prefix
-        parts << ':version' if version
-        parts << namespace if namespace
-        parts << path
-        Rack::Mount::Utils.normalize_path(parts.join('/'))
-      end
-
-      def route(method, path_info, &block)
-        route_set.add_route(build_endpoint(&block), 
-          :path_info => Rack::Mount::Strexp.compile(compile_path(path_info)), 
-          :request_method => method
-        )
-      end
-      
-      def build_endpoint(&block)
-        
-        b = Rack::Builder.new
-        b.use Grape::Middleware::Error
-        b.use Rack::Auth::Basic, settings[:auth][:realm], &settings[:auth][:proc] if settings[:auth] && settings[:auth][:type] == :http_basic
-        b.use Grape::Middleware::Prefixer, :prefix => prefix if prefix        
-        b.use Grape::Middleware::Versioner, :versions => (version if version.is_a?(Array)) if version
-        b.use Grape::Middleware::Formatter, :default_format => default_format || :json
-        
-        endpoint = Grape::Endpoint.new(&block)
-        endpoint.send :extend, helpers
-        b.run endpoint
+      # Defines a route that will be recognized
+      # by the Grape API.
+      #
+      # @param methods [HTTP Verb(s)] One or more HTTP verbs that are accepted by this route. Set to `:any` if you want any verb to be accepted.
+      # @param paths [String(s)] One or more strings representing the URL segment(s) for this route.
+      # @param block [Proc] The code to be executed 
+      def route(methods, paths, &block)
+        methods = Array(methods)
+        paths = ['/'] if paths == []
+        paths = Array(paths)
+        endpoint = build_endpoint(&block)
         
-        b.to_app
+        methods.each do |method|
+          paths.each do |path|
+            path = Rack::Mount::Strexp.compile(compile_path(path))
+            route_set.add_route(endpoint, 
+              :path_info => path, 
+              :request_method => (method.to_s.upcase unless method == :any)
+            )
+          end
+        end
       end
       
-      def get(path_info = '', &block); route('GET', path_info, &block) end
-      def post(path_info = '', &block); route('POST', path_info, &block) end
-      def put(path_info = '', &block); route('PUT', path_info, &block) end
-      def head(path_info = '', &block); route('HEAD', path_info, &block) end
-      def delete(path_info = '', &block); route('DELETE', path_info, &block) end
+      def get(*paths, &block); route('GET', paths, &block) end
+      def post(*paths, &block); route('POST', paths, &block) end
+      def put(*paths, &block); route('PUT', paths, &block) end
+      def head(*paths, &block); route('HEAD', paths, &block) end
+      def delete(*paths, &block); route('DELETE', paths, &block) end
       
       def namespace(space = nil, &block)
         if space || block_given?
@@ -145,6 +148,19 @@ module Grape
         end
       end
       
+      alias_method :group, :namespace
+      alias_method :resource, :namespace
+      alias_method :resources, :namespace
+      
+      # Create a scope without affecting the URL.
+      # 
+      # @param name [Symbol] Purely placebo, just allows to to name the scope to make the code more readable.
+      def scope(name = nil, &block)
+        nest(block)
+      end
+      
+      protected
+      
       # Execute first the provided block, then each of the
       # block passed in. Allows for simple 'before' setups
       # of settings stack pushes.
@@ -152,7 +168,7 @@ module Grape
         blocks.reject!{|b| b.nil?}
         if blocks.any?
           settings_stack << {}
-          instance_eval &block
+          instance_eval &block if block_given?
           blocks.each{|b| instance_eval &b}
           settings_stack.pop
         else
@@ -160,13 +176,37 @@ module Grape
         end
       end
       
-      alias_method :group, :namespace
-      alias_method :resource, :namespace
-      alias_method :resources, :namespace
+      def build_endpoint(&block)
+        b = Rack::Builder.new
+        b.use Grape::Middleware::Error
+        b.use Rack::Auth::Basic, settings[:auth][:realm], &settings[:auth][:proc] if settings[:auth] && settings[:auth][:type] == :http_basic
+        b.use Grape::Middleware::Prefixer, :prefix => prefix if prefix        
+        b.use Grape::Middleware::Versioner, :versions => (version if version.is_a?(Array)) if version
+        b.use Grape::Middleware::Formatter, :default_format => default_format || :json
+        
+        endpoint = Grape::Endpoint.generate(&block)
+        endpoint.send :include, helpers
+        b.run endpoint
+        
+        b.to_app
+      end
       
       def inherited(subclass)
         subclass.reset!
       end
+      
+      def route_set
+        @route_set ||= Rack::Mount::RouteSet.new
+      end
+      
+      def compile_path(path)
+        parts = []
+        parts << prefix if prefix
+        parts << ':version' if version
+        parts << namespace if namespace
+        parts << path
+        Rack::Mount::Utils.normalize_path(parts.join('/'))
+      end
     end  
     
     reset! 

data/lib/grape/endpoint.rb

@@ -7,12 +7,26 @@ module Grape
   # on the instance level of this class may be called
   # from inside a `get`, `post`, etc. block.
   class Endpoint
-    def initialize(&block)
-      @block = block
+    def self.generate(&block)
+      c = Class.new(Grape::Endpoint)
+      c.class_eval do
+        @block = block
+      end
+      c
+    end
+    
+    class << self
+      attr_accessor :block
+    end
+    
+    def self.call(env)
+      new.call(env)
     end
     
     attr_reader :env, :request
     
+    # The parameters passed into the request as
+    # well as parsed from URL segments.
     def params
       @params ||= request.params.merge(env['rack.routing_args'] || {}).inject({}) do |h,(k,v)|
         h[k.to_s] = v
@@ -21,13 +35,21 @@ module Grape
       end
     end
     
+    # The API version as specified in the URL.
     def version; env['api.version'] end
     
+    # End the request and display an error to the
+    # end user with the specified message.
+    #
+    # @param message [String] The message to display.
+    # @param status [Integer] the HTTP Status Code. Defaults to 403.
     def error!(message, status=403)
       throw :error, :message => message, :status => status
     end
     
     # Set or retrieve the HTTP status code.
+    #
+    # @param status [Integer] The HTTP Status Code to return for this request.
     def status(status = nil)
       if status
         @status = status
@@ -54,10 +76,10 @@ module Grape
     
     def call(env)
       @env = env
-      @request = Rack::Request.new(@env)
       @header = {}
+      @request = Rack::Request.new(@env)
       
-      response_text = instance_eval &@block
+      response_text = instance_eval &self.class.block
       
       [status, header, [response_text]]
     end

data/lib/grape/middleware/formatter.rb

@@ -99,7 +99,7 @@ module Grape
       end
       
       def encode_txt(object)
-        body.respond_to?(:to_txt) ? body.to_txt : body.to_s
+        object.respond_to?(:to_txt) ? object.to_txt : object.to_s
       end
     end
   end

data/spec/grape/api_spec.rb

@@ -119,7 +119,7 @@ describe Grape::API do
         version 'v2'
         compile_path('hello').should == '/:version/hello'
       end
-      subject.compile_path('hello').should == '/hello'
+      subject.send(:compile_path, 'hello').should == '/hello'
     end
     
     %w(group resource resources).each do |als|
@@ -149,6 +149,39 @@ describe Grape::API do
       last_response.body.should == 'Created a Vote'
     end
     
+    it 'should allow for multiple paths' do
+      subject.get("/abc", "/def") do
+        "foo"
+      end
+      
+      get '/abc'
+      last_response.body.should == 'foo'
+      get '/def'
+      last_response.body.should == 'foo'
+    end
+    
+    it 'should allow for multiple verbs' do
+      subject.route([:get, :post], '/abc') do
+        "hiya"
+      end
+      
+      get '/abc'
+      last_response.body.should == 'hiya'
+      post '/abc'
+      last_response.body.should == 'hiya'
+    end
+    
+    it 'should allow for :any as a verb' do
+      subject.route(:any, '/abc') do
+        "lol"
+      end
+      
+      %w(get post put delete).each do |m|
+        send(m, '/abc')
+        last_response.body.should == 'lol'
+      end
+    end
+    
     verbs = %w(post get head delete put)
     verbs.each do |verb|
       it "should allow and properly constrain a #{verb.upcase} method" do
@@ -280,4 +313,31 @@ describe Grape::API do
       lambda{get '/howdy'}.should_not raise_error
     end
   end
+  
+  describe '.scope' do
+    it 'should scope the various settings' do
+      subject.version 'v2'
+      
+      subject.scope :legacy do
+        version 'v1'
+        
+        get '/abc' do
+          version
+        end
+      end
+      
+      subject.get '/def' do
+        version
+      end
+      
+      get '/v2/abc'
+      last_response.status.should == 404
+      get '/v1/abc'
+      last_response.status.should == 200
+      get '/v1/def'
+      last_response.status.should == 404
+      get '/v2/def'
+      last_response.status.should == 200
+    end
+  end
 end

data/spec/grape/endpoint_spec.rb

@@ -72,4 +72,33 @@ describe Grape::Endpoint do
       last_response.body.should == "Unauthorized."
     end
   end
+  
+  it 'should not persist params between calls' do
+    subject.post('/new') do
+      params[:text]
+    end
+    
+    post '/new', :text => 'abc'
+    last_response.body.should == 'abc'
+    
+    post '/new', :text => 'def'
+    last_response.body.should == 'def'
+  end
+  
+  it 'should reset all instance variables (except block) between calls' do
+    subject.helpers do
+      def memoized
+        @memoized ||= params[:howdy]
+      end
+    end
+    
+    subject.get('/hello') do
+      memoized
+    end
+    
+    get '/hello?howdy=hey'
+    last_response.body.should == 'hey'
+    get '/hello?howdy=yo'
+    last_response.body.should == 'yo'
+  end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: grape
 version: !ruby/object:Gem::Version 
-  hash: 27
+  hash: 25
   prerelease: false
   segments: 
   - 0
   - 1
-  - 0
-  version: 0.1.0
+  - 1
+  version: 0.1.1
 platform: ruby
 authors: 
 - Michael Bleigh
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-11-13 00:00:00 -06:00
+date: 2010-11-14 00:00:00 -06:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -140,7 +140,7 @@ extensions: []
 
 extra_rdoc_files: 
 - LICENSE
-- README.rdoc
+- README.markdown
 files: 
 - .document
 - .gitignore
@@ -149,7 +149,7 @@ files:
 - Gemfile
 - Gemfile.lock
 - LICENSE
-- README.rdoc
+- README.markdown
 - Rakefile
 - VERSION
 - autotest/discover.rb

data/README.rdoc

@@ -1,52 +0,0 @@
-= UNDER CONSTRUCTION. DO NOT USE
-
-= Grape
-
-Grape is a REST-like API micro-framework for Ruby. It is built to complement existing web application frameworks such as Rails and Sinatra by providing a simple DSL to easily provide APIs. It has built-in support for common conventions such as multiple formats, subdomain/prefix restriction, and versioning.
-
-    class Twitter::API < Grape::Base
-      subdomain 'api'
-      version '1'
-      formats :xml, :json
-      authorization :oauth, User
-      
-      resource :statuses do
-        group :timelines do
-          formats :rss, :atom
-          
-          get :public_timeline do
-            optional :trim_user, Boolean
-            optional :include_entities, Boolean
-          
-            Tweet.limit(20)
-          end
-        
-          get :home_timeline do
-            authorized
-          
-            user.home_timeline
-          end
-        end
-      end
-    end
-    
-    # Rack endpoint
-    Twitter::API.statuses.timelines.get(:public_timeline)
-    
-    class Twitter::API::User < Grape::Resource::ActiveRecord
-      represents ::User
-      
-      property :status, lambda{|u| u.latest_status}, Twitter::API::Status
-    end
-    
-== Note on Patches/Pull Requests
- 
-* Fork the project.
-* Make your feature addition or bug fix.
-* Add tests for it. This is important so I don't break it in a future version unintentionally.
-* Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
-* Send me a pull request. Bonus points for topic branches.
-
-== Copyright
-
-Copyright (c) 2010 Michael Bleigh and Intridea, Inc. See LICENSE for details.