sinatra-param 0.0.1

data/Gemfile

@@ -0,0 +1,5 @@
+source :rubygems
+
+gemspec
+
+gem 'sinatra', '~> 1.3'

data/Gemfile.lock

@@ -0,0 +1,28 @@
+PATH
+  remote: .
+  specs:
+    sinatra-param (0.0.1)
+      sinatra (~> 1.3)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    rack (1.4.1)
+    rack-protection (1.2.0)
+      rack
+    rake (0.9.2.2)
+    rspec (0.6.4)
+    sinatra (1.3.2)
+      rack (~> 1.3, >= 1.3.6)
+      rack-protection (~> 1.2)
+      tilt (~> 1.3, >= 1.3.3)
+    tilt (1.3.3)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  rake (~> 0.9.2)
+  rspec (~> 0.6.1)
+  sinatra (~> 1.3)
+  sinatra-param!

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2012 Mattt Thompson (http://mattt.me/)
+
+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.md

@@ -0,0 +1,80 @@
+# sinatra-param
+_Parameter Validation and Typecasting for Sinatra_
+
+REST conventions takes the guesswork out of designing and consuming web APIs. `GET` / `POST` / `PATCH` / `DELETE` resource endpoints and you get what you'd expect.
+
+But figuring out what parameters are expected... well, all bets are off. This Sinatra extension takes a first step to solving this problem on the developer side
+
+**`sinatra-param` allows you to declare, validate, and transform endpoint parameters as you would in frameworks like [DataMapper](http://datamapper.org/) or [ActiveModel](http://rubydoc.info/gems/activemodel/3.2.3/frames).**
+
+## Example
+
+``` ruby
+class App < Sinatra::Base
+  helpers Sinatra::Param
+
+  before do
+    content_type :json
+  end
+  
+  # GET /search?q=example
+  # GET /search?q=example&categories=news
+  # GET /search?q=example&sort=created_at&order=ASC
+  get '/search' do
+    param :q,           String, required: true
+    param :categories,  Array
+    param :sort,        String, default: "title"
+    param :order,       String, in: ["ASC", "DESC"], transform: :upcase, default: "ASC"
+    
+    {...}.to_json
+  end
+end
+```
+
+
+### Parameter Types
+
+By declaring parameter types, incoming parameters will automatically be transformed into an object of that type. For instance, if a param is `Boolean`, values of `'1'`, `'true'`, `'t'`, `'yes'`, and `'y'` will be automatically transformed into `true`.
+
+- String
+- Integer
+- Float
+- Boolean _("1/0", "true/false", "t/f", "yes/no", "y/n")_
+- Array _("1,2,3,4,5")_
+- Hash _(key1:value1,key2:value2)_
+
+### Validations
+
+Encapsulate business logic in a consistent way with validations. If a parameter does not satisfy a particular condition, a `406` error is returned with a message explaining the failure.
+
+- `required`
+- `blank`
+- `is`
+- `in`, `within`, `range`
+- `min` / `max`
+
+### Defaults and Transformations
+
+Passing a `default` option will provide a default value for a parameter if none is passed.
+
+Use the `transform` option to take even more of the business logic of parameter I/O out of your code. Anything that responds to `to_proc` (including Procs and symbols) will do.
+
+## Next Steps
+
+- [Design by contract](http://en.wikipedia.org/wiki/Design_by_contract) like this is great for developers, and with a little meta-programming, it could probably be exposed to users as well. The self-documenting dream of [Hypermedia folks](http://twitter.com/#!/steveklabnik) could well be within reach.
+
+- Another pain point is the awkward way parameters are passed as JSON in HTTP bodies. I'd love to see an elegant, unobtrusive way to do this automatically.
+
+- Testing. This will happen soon. 
+
+## Contact
+
+Mattt Thompson
+
+- http://github.com/mattt
+- http://twitter.com/mattt
+- m@mattt.me
+
+## License
+
+sinatra-param is available under the MIT license. See the LICENSE file for more info.

data/Rakefile

@@ -0,0 +1,11 @@
+require "bundler"
+Bundler.setup
+
+gemspec = eval(File.read("sinatra-param.gemspec"))
+
+task :build => "#{gemspec.full_name}.gem"
+
+file "#{gemspec.full_name}.gem" => gemspec.files + ["sinatra-param.gemspec"] do
+  system "gem build sinatra-param.gemspec"
+  system "gem install sinatra-param-#{Sinatra::Param::VERSION}.gem"
+end

data/example/Gemfile

@@ -0,0 +1,4 @@
+source :rubygems
+
+gem 'sinatra'
+gem 'thin'

data/example/Gemfile.lock

@@ -0,0 +1,24 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    daemons (1.1.8)
+    eventmachine (0.12.10)
+    rack (1.4.1)
+    rack-protection (1.2.0)
+      rack
+    sinatra (1.3.2)
+      rack (~> 1.3, >= 1.3.6)
+      rack-protection (~> 1.2)
+      tilt (~> 1.3, >= 1.3.3)
+    thin (1.3.1)
+      daemons (>= 1.0.9)
+      eventmachine (>= 0.12.6)
+      rack (>= 1.0.0)
+    tilt (1.3.3)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  sinatra
+  thin

data/example/Procfile

@@ -0,0 +1 @@
+web: bundle exec thin start -p $PORT

data/example/app.rb

@@ -0,0 +1,43 @@
+require 'sinatra/base'
+require 'json'
+
+require '../lib/sinatra/param'
+
+class App < Sinatra::Base
+  helpers Sinatra::Param
+
+  before do
+    content_type :json
+  end
+  
+  # GET /messages
+  # GET /messages?sort=name&order=ASC
+  get '/messages' do
+    param :sort,  String, default: "name"
+    param :order, String, in: ["ASC", "DESC"], transform: :upcase, default: "ASC"
+    
+    {
+      sort: params[:sort],
+      order: params[:order]
+    }.to_json
+  end
+  
+  # GET /messages/1,2,3,4,5
+  get '/messages/:ids' do
+    param :ids, Array, required: true
+    
+    {
+      ids: params[:ids]
+    }.to_json
+  end
+  
+  # POST /messages/1/response
+  post '/messages/:id/response' do
+    param :message, String, max: 1024, required: true
+    
+    {
+      message: params[:message]
+    }.to_json
+  end
+end
+

data/example/config.ru

@@ -0,0 +1,3 @@
+require './app'
+
+run App

data/lib/sinatra/param.rb

@@ -0,0 +1,70 @@
+require 'sinatra/base'
+
+module Sinatra
+  module Param
+    VERSION = "0.0.1"
+
+    class InvalidParameterError < StandardError; end
+
+    def param(name, type, options = {})
+      begin
+        params[name] = coerce(params[name], type, options) || options[:default]
+        params[name] = options[:transform].to_proc.call(params[name]) if options[:transform]
+        validate!(params[name], options)
+      rescue
+        error = "Invalid parameter, #{name}"
+        if content_type.match(mime_type(:json))
+          error = {message: error}.to_json
+        end
+
+        halt 406, error
+      end
+    end
+
+    private
+
+      def coerce(param, type, options = {})
+        return nil if param.nil?
+        return Integer(param) if type == Integer
+        return Float(param) if type == Float
+        return String(param) if type == String
+        return Array(param.split(options[:delimiter] || ",")) if type == Array
+        return Hash[param.split(options[:delimiter] || ",").map{|c| c.split(options[:separator] || ":")}] if type == Hash
+        return ((/(false|f|no|n|0)$/i === param) ? false : (/(true|t|yes|y|1)$/i === param) ? true : nil) if type == Boolean
+        return nil
+      end
+
+      def validate!(param, options)
+        options.each do |key, value|
+          case key
+            when :required
+              raise InvalidParameterError if value && param.nil?
+            when :blank
+              raise InvalidParameterError if !value && case param
+                  when String
+                    !(/\S/ === param)
+                  when Array, Hash
+                    param.empty?
+                  else
+                    param.nil?
+                end
+            when :is
+              raise InvalidParameterError unless value === param
+            when :in, :within, :range
+              raise InvalidParameterError unless case value
+                  when Range
+                    value.include?(param)
+                  else
+                    Array(value).include?(param)
+                  end
+            when :min
+              raise InvalidParameterError unless value <= param
+            when :max
+              raise InvalidParameterError unless value >= param
+          end
+        end
+      end
+    end
+
+  helpers Param
+end

data/sinatra-param.gemspec

@@ -0,0 +1,24 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "sinatra/param"
+
+Gem::Specification.new do |s|
+  s.name        = "sinatra-param"
+  s.authors     = ["Mattt Thompson"]
+  s.email       = "m@mattt.me"
+  s.homepage    = "http://github.com/mattt/sinatra-param"
+  s.version     = Sinatra::Param::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.summary     = "sinatra-param"
+  s.description = "Parameter Contracts for Sinatra"
+  
+  s.add_dependency "sinatra",   "~> 1.3"
+
+  s.add_development_dependency "rspec", "~> 0.6.1"
+  s.add_development_dependency "rake",  "~> 0.9.2"
+
+  s.files         = Dir["./**/*"].reject { |file| file =~ /\.\/(bin|log|pkg|script|spec|test|vendor)/ }
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end

metadata

@@ -0,0 +1,95 @@
+--- !ruby/object:Gem::Specification
+name: sinatra-param
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Mattt Thompson
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-04-30 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sinatra
+  requirement: &70189725114120 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70189725114120
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &70189725113620 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.6.1
+  type: :development
+  prerelease: false
+  version_requirements: *70189725113620
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: &70189725113160 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.9.2
+  type: :development
+  prerelease: false
+  version_requirements: *70189725113160
+description: Parameter Contracts for Sinatra
+email: m@mattt.me
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ./example/app.rb
+- ./example/config.ru
+- ./example/Gemfile
+- ./example/Gemfile.lock
+- ./example/Procfile
+- ./Gemfile
+- ./Gemfile.lock
+- ./lib/sinatra/param.rb
+- ./LICENSE
+- ./Rakefile
+- ./README.md
+- ./sinatra-param.gemspec
+homepage: http://github.com/mattt/sinatra-param
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 4481802987950945093
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 4481802987950945093
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.15
+signing_key: 
+specification_version: 3
+summary: sinatra-param
+test_files: []