roy 0.5.2 → 0.5.3

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    roy (0.5.2)
+    roy (0.5.3)
       rack
 
 GEM

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2009-2011 François "madx" Vaux <madx@yapok.org>
+Copyright (c) 2009-2012 François "madx" Vaux <madx@yapok.org>
 
 Permission is hereby granted, free of charge, to any person
 obtaining a copy of this software and associated documentation

data/lib/roy/after.rb

@@ -1,4 +1,30 @@
 module Roy
+  # This module allows you to modify the response before it is sent to the
+  # client. It does this by overriding the {Roy#call} method.
+  #
+  # == Configuration:
+  # roy.conf.after::
+  #   A proc object that will be called with the response as argument.
+  #   Defaults to identity if not set.
+  #
+  # @example Forcing a custom content-type
+  #
+  #   class SetContentType
+  #     include Roy
+  #
+  #     roy use: [:after],
+  #         after: ->(resp) { resp.headers['Content-Type'] = 'text/x-foo' }
+  #
+  #     def get(_)
+  #       "Hello, world\n"
+  #     end
+  #   end
+  #
+  # @example Demo
+  #
+  #   $ curl -i localhost:9292
+  #   HTTP/1.1 200 OK
+  #   Content-Type: text/x-foo
   module After
     def call(env)
       status, header, body = super

data/lib/roy/base.rb

@@ -9,17 +9,23 @@ require 'ostruct'
 require 'roy/version'
 require 'roy/context'
 
+# This is the main module that applications should include.
 module Roy
+
+  # Default options.
   Defaults = {allow: [:get], prefix: :'', use: [:halt]}
 
+  # Extend the class with the ClassMethods module.
   def self.included(base)
     base.send(:extend, ClassMethods)
   end
 
+  # Returns the application context or initialize it
   def roy
     @roy ||= Context.new(self)
   end
 
+  # A Rack-compliant #call method.
   def call(env)
     roy.prepare!(env)
 
@@ -41,6 +47,7 @@ module Roy
   module ClassMethods
     attr_reader :conf
 
+    # Setup default configuration for the application.
     def self.extended(base)
       base.instance_eval do
         @conf ||= OpenStruct.new
@@ -48,6 +55,7 @@ module Roy
       end
     end
 
+    # Set options for the application
     def roy(options={})
       options.each do |key,value|
         case key

data/lib/roy/basic_auth.rb

@@ -1,20 +1,76 @@
 module Roy
+  # This module provides helpers for using the HTTP basic authentication system.
+  #
+  # == Configuration:
+  # roy.conf.auth [:realm]::
+  #   The authentication realm to use.
+  # roy.conf.auth [:logic]::
+  #   A proc that checks if an user is authorized. See #authorized? in
+  #   InstanceMethods.
+  #
+  # @example Simple auth example
+  #
+  #   class AuthApp
+  #     include Roy
+  #     roy use: [:basic_auth],
+  #         auth: {
+  #           realm: "My Realm",
+  #           logic: ->(_, u, p) { %w(admin foobar) == [u, p] }
+  #         }
+  #
+  #     def get(_)
+  #       roy.protected!
+  #       "Protected zone"
+  #     end
+  #   end
+  #
+  # @example Using user data
+  #
+  #   class AuthUserDataApp
+  #     include Roy
+  #     roy use: [:basic_auth],
+  #         auth: {
+  #           realm: "My Realm",
+  #           logic: ->(override, u, p) {
+  #             override || (%w(admin foobar) == [u, p])
+  #           }
+  #         }
+  #
+  #     def get(path)
+  #       roy.protected!(path =~ /private/)
+  #       "Protected if path contains private"
+  #     end
+  #   end
   module BasicAuth
-    def protected!(data=nil)
-      unless authorized?(data)
-        realm = roy.conf.auth && roy.conf.auth[:realm] || 'Realm'
-        roy.response['WWW-Authenticate'] = %(Basic realm="#{realm}")
-        roy.halt 401
-      end
+    def self.setup(roy)
+      roy.send(:extend, InstanceMethods)
     end
 
-    def authorized?(data=nil)
-      auth = Rack::Auth::Basic::Request.new(roy.request.env)
+    module InstanceMethods
+
+      # Protect all subsequent code using HTTP Basic Authentication.
+      #
+      # @param data user data to pass to #authorized?
+      def protected!(data=nil)
+        unless authorized?(data)
+          realm = conf.auth && conf.auth[:realm] || 'Realm'
+          response['WWW-Authenticate'] = %(Basic realm="#{realm}")
+          halt 401
+        end
+      end
 
-      auth.provided? && auth.basic? && auth.credentials &&
-        (roy.conf.auth[:logic] || ->(data, u, p) {
-          %w(admin password) == [u, p]
-         }).(data, *auth.credentials)
+      # Runs the authentication logic against the user and passord given in the
+      # request, using custom additional data.
+      #
+      # @param data user data to pass to the authentication logic
+      def authorized?(data=nil)
+        auth = Rack::Auth::Basic::Request.new(request.env)
+
+        auth.provided? && auth.basic? && auth.credentials &&
+          (conf.auth[:logic] || ->(data, u, p) {
+            %w(admin password) == [u, p]
+           }).(data, *auth.credentials)
+      end
     end
   end
 end

data/lib/roy/before.rb

@@ -1,4 +1,33 @@
 module Roy
+  # This module allows you to modify the environment before it is handled by the
+  # application. It does this by overriding the {Roy#call} method.
+  #
+  # == Configuration:
+  # roy.conf.before::
+  #   A proc object that will be called with the environment as argument.
+  #   Defaults to identity if not set.
+  #
+  # @example Forcing a method
+  #
+  #   class AlwaysGet
+  #     include Roy
+  #
+  #     roy allow: [:put, :post], use: [:before],
+  #         before: ->(env) { env['REQUEST_METHOD'] = 'GET' }
+  #
+  #     def get(_)
+  #       "Hello, world\n"
+  #     end
+  #   end
+  #
+  # @example Demo
+  #
+  #   $ curl -i localhost:9292
+  #   HTTP/1.1 200 OK
+  #   $ curl -X POST -i localhost:9292
+  #   HTTP/1.1 200 OK
+  #   $ curl -X PUT -i localhost:9292
+  #   HTTP/1.1 200 OK
   module Before
     def call(env)
       (roy.conf.before || lambda {|x| x }).(env)

data/lib/roy/context.rb

@@ -1,7 +1,33 @@
 module Roy
+  # Application context for Roy applications.
+  #
+  # Everything must be namespaced in this context to avoid any clashes and to
+  # make the code cleaner.
   class Context
-    attr_reader :app, :conf, :env, :request, :response, :headers, :params
+    # Returns the current application
+    attr_reader :app
 
+    # Returns the application's configuration
+    attr_reader :conf
+
+    # Returns the environment passed to #call
+    attr_reader :env
+
+    # Returns the current request
+    attr_reader :request
+
+    # Returns the current response
+    attr_reader :response
+
+    # Returns the current response's headers
+    attr_reader :headers
+
+    # Returns the current request's params
+    attr_reader :params
+
+    # Creates a new Context object.
+    #
+    # @param app the context's application
     def initialize(app)
       @app  = app
       @conf = app.class.conf
@@ -11,6 +37,9 @@ module Roy
       end
     end
 
+    # Initializes the attributes based on an environment.
+    #
+    # @param env the environment to use
     def prepare!(env)
       @env      = env
       @request  = Rack::Request.new(env)

data/lib/roy/halt.rb

@@ -1,11 +1,38 @@
 module Roy
+  # This module adds a +halt+ method to the application context that allows you
+  # to break during a handler and immediately return a status code and a body.
+  #
+  # Included by default.
+  #
+  # @example A Not Found application
+  #
+  #   class NotFoundApp
+  #     include Roy
+  #
+  #     def get(_)
+  #       halt 404
+  #     end
+  #   end
+  #
+  # @example Test
+  #
+  #   $ curl -i localhost:9292
+  #   HTTP/1.1 404 Not Found
   module Halt
 
     def self.setup(roy)
-      class << roy
-        def halt(code, message=nil)
-          throw :halt, [code, message || Rack::Utils::HTTP_STATUS_CODES[code]]
-        end
+      roy.send(:extend, InstanceMethods)
+    end
+
+    module InstanceMethods
+      # Break from the current +catch(:halt)+ block
+      #
+      # @param [Integer] code the response status code.
+      # @param [String] message the response body.
+      # @return [Integer, String] the status and the given message or a default
+      #   one.
+      def halt(code, message=nil)
+        throw :halt, [code, message || Rack::Utils::HTTP_STATUS_CODES[code]]
       end
     end
 

data/lib/roy/render.rb

@@ -1,24 +1,99 @@
 require 'tilt'
 
 module Roy
+  # A simple template rendering mechanism based on Tilt.
+  #
+  # == Configuration:
+  # roy.conf.render::
+  #   A hash of options to pass to Tilt.
+  # roy.conf.views::
+  #   The directory where views are kept. Defaults to +views/+
+  #
+  # @example Using <tt>roy.render</tt>
+  #
+  #   class ErbApp
+  #     include Roy
+  #
+  #     roy use: [:render]
+  #
+  #     def get(path)
+  #       case path
+  #       when /\/hello/
+  #         roy.render :erb, "Hello, <%= roy.params[:p] || \"world\" %>!\n"
+  #       else
+  #         roy.render :erb, :index
+  #       end
+  #     end
+  #   end
+  #
+  # @example Test
+  #
+  #   $ cat views/index.erb
+  #   Let me <a href="/hello">greet</a> you.
+  #   $ curl -i localhost:9292
+  #   Let me <a href="/hello">greet</a> you.
+  #   $ curl -i localhost:9292/hello?p=blah
+  #   Hello, blah!
+  #
+  # @example Haml renderer with partials support
+  #
+  #   module HamlRenderWithPartial
+  #     def self.setup(roy)
+  #       roy.send(:extend, InstanceMethods)
+  #     end
+  #
+  #     module InstanceMethods
+  #       def render(tpl_or_string, params={})
+  #         case layout = params.delete(:layout)
+  #         when false
+  #           super(:haml, tpl_or_string, params)
+  #         else
+  #           super(:haml, :layout, params do
+  #             super(:haml, tpl_or_string, params)
+  #           end
+  #         end
+  #       end
+  #     end
+  #   end
   module Render
 
     def self.setup(roy)
-      class << roy
-        def render(engine, view_or_string, params={}, &block)
-          options = conf.render || {}
-          template = case view_or_string
-            when Symbol
-              file = [view_or_string.to_s, engine].map(&:to_s).join('.')
-              dir = conf.views || 'views'
-              Tilt.new(File.join(dir, file), nil, options)
-            else
-              Tilt[engine].new(nil, nil, options) { view_or_string.to_s }
-            end
+      roy.send(:extend, InstanceMethods)
+    end
+
+    module InstanceMethods
 
-          template.render(app, params, &block)
-        end
+      # Render the given template or string with the selected engine.
+      #
+      # Views are looked for inside the +roy.conf.views+ directory.
+      # Files should have an extension matching the selected engine.
+      # If you want to use sub-directories, you have to use the
+      # +:"subdir/file.ext"+ syntax.
+      #
+      # @see https://github.com/rtomayko/tilt/blob/master/README.md
+      # @see https://github.com/rtomayko/tilt/blob/master/TEMPLATES.md
+      #
+      # @param [Symbol] engine the name of the rendering engine. Must be
+      #   supported by Tilt.
+      # @param [Symbol] view_or_string a template file.
+      # @param [String] view_or_string a template string.
+      # @param [Hash] params locals for Tilt::Template#render.
+      # @param [Proc] block a block to execute when using +yield+ in the
+      #   template.
+      def render(engine, view_or_string, params={}, &block)
+        options = conf.render || {}
+        template = case view_or_string
+          when Symbol
+            file = [view_or_string.to_s, engine].map(&:to_s).join('.')
+            dir = conf.views || 'views'
+            Tilt.new(File.join(dir, file), nil, options)
+          else
+            Tilt[engine].new(nil, nil, options) { view_or_string.to_s }
+          end
+
+        template.render(app, params, &block)
       end
+
     end
 
   end

data/lib/roy/version.rb

@@ -1,6 +1,8 @@
 module Roy
-  VERSION = [0, 5, 2]
+  # Roy version
+  VERSION = [0, 5, 3]
 
+  # Return the version as a String.
   def self.version
     VERSION.join('.')
   end

data/test/plugins/basic_auth_test.rb

@@ -10,7 +10,7 @@ class BasicAuthTestObject
       }
 
   def get(path)
-    protected!
+    roy.protected!
     'success'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: roy
 version: !ruby/object:Gem::Version
-  version: 0.5.2
+  version: 0.5.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-01-17 00:00:00.000000000 Z
+date: 2012-02-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
-  requirement: &19255820 !ruby/object:Gem::Requirement
+  requirement: &13775240 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *19255820
+  version_requirements: *13775240
 - !ruby/object:Gem::Dependency
   name: minitest
-  requirement: &19255280 !ruby/object:Gem::Requirement
+  requirement: &13774520 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *19255280
+  version_requirements: *13774520
 - !ruby/object:Gem::Dependency
   name: rack-test
-  requirement: &19254660 !ruby/object:Gem::Requirement
+  requirement: &13792140 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,10 +43,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *19254660
+  version_requirements: *13792140
 - !ruby/object:Gem::Dependency
   name: tilt
-  requirement: &19254220 !ruby/object:Gem::Requirement
+  requirement: &13791400 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,7 +54,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *19254220
+  version_requirements: *13791400
 description: ! 'roy is a small library which allows every Ruby object to be used
 
   as a Rack application.'
@@ -111,7 +111,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: roy
-rubygems_version: 1.8.5
+rubygems_version: 1.8.15
 signing_key: 
 specification_version: 3
 summary: make your objects REST-friendly