sinatra-browse 0.5 → 0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1faa38c99f34fe11336ea7e4beb14b9c6c8c5d44
-  data.tar.gz: 2d1cc86c5d25a45f8c557202f095f74a9e145325
+  metadata.gz: 5bdedea1f30918fa4b4e9e40329b5d36d376e26a
+  data.tar.gz: a3f543ea671453b43857a83971491ebc70469aef
 SHA512:
-  metadata.gz: 6a68e861b2d04655faa2a459d9246754b526829c1ca4ebfae6ef0c7c2502a7a39583981cdb22b5ec08819aa311f9d460136b96d90f904db964d586d0b0d448b1
-  data.tar.gz: 740fbf66e097ea5d34c5998ba248df93a09db40948312b9af0659f5f0b47186ad1f314904419ceee38e4434ebe1a4a8418fe35e8f02a237b4b8a0f2fa168fcdc
+  metadata.gz: 5d9ca106f1fc4d51484e5985cfa8f6e66ff18a2fd5deedb325010decb99e1d76dbb86925a436fb1b47e4c1f2cedc0c8f1190d75d92dbba9d39db92c7db378ad9
+  data.tar.gz: 792cb9ccd3f3103046644bc72eb23aa71de835cb7b1b2af7cc0cd5313a8fa9b4a63c0f3cf4fe56ab8af5f63222548fe833b4684dcffce8095a986c80bce3e66e

data/README.md

@@ -40,12 +40,10 @@ The syntax is inspired by the [sinatra-param](https://github.com/mattt/sinatra-p
 
 **Browsable API**
 
-Sinatra-browse allows you to surf to your API. This works as documentation and allows you to send requests and see their responses directly in your browser.
+Sinatra-browse automatically adds another route simply called `browse`. Surfing to it will display documentation generated from the parameter definitions.
 
     http://<api_ip_address>:<api_port>/browse
 
-*Remark:* This is still work in progress. Right now the page only shows some simple documentation.
-
 ## Parameter types
 
 At the time of writing four parameter types are available.
@@ -53,17 +51,43 @@ At the time of writing four parameter types are available.
 * `:String`
 * `:Integer`
 * `:Float`
-* `:Boolean` ["1/0", "true/false", "t/f", "yes/no", "y/n"]
+* `:Boolean`
+* `:DateTime`
+
+**Remarks:**
+
+A `Boolean` parameter will be true for values: `"1"`, `"true"`, `"t"`, `"yes"`, `"y"` and false for values: `"0"`, `"false"`, `"f"`, `"no"`, `"n"`
+
+A `DateTime` parameter relies on Ruby's [DateTime#parse](http://www.ruby-doc.org/stdlib-2.2.2/libdoc/date/rdoc/DateTime.html#method-c-parse) method and can thus handle all formats this method can.
+
+Examples:
+
+    'Sat, 03 Feb 2001 04:05:06 GMT'
+    'Sat, 3 Feb 2001 04:05:06 +0700'
+    '2001-02-03T04:05:06+07:00'
+    'H13.02.03T04:05:06+07:00'
+    '2014/02/05'
+    'march 2nd'
 
 ## Default values
 
-You can set default values in your declarations. These will be used when the parameter in question wasn't provided in the request. You can either set the default value or provide a proc to generate it.
+You can set default values in your declarations. These will be used when the parameter in question wasn't provided in the request. You can either set the default value or provide a proc/lambda to generate it.
 
 ```ruby
 param :media_type, :String, default: "book"
 param :year, :Integer, default: lambda { Time.now.year }
 ```
 
+## Describing parameters
+
+Parameters declarations can have an optional arbitrary discription to be included in the generated documentation.
+
+```ruby
+# Both of these syntaxes will work.
+param :name, :Name, description: "What your mother calls you."
+param :age, :Integer, desc: "The amount of years you've spent on this planet."
+```
+
 ## Parameter validation
 
 You can write some quick validation logic directly in the parameter declaration. If the validation fails, either a standard 400 error will be returned or a custom error block will execute if provided.
@@ -90,6 +114,30 @@ param :small_prime_number, :Integer, in: Prime.take(10)
 param :order, :String, in: ["ascending", "descending"]
 ```
 
+### Minimum and maximum validation
+
+In the case of numeric values like `:Integer`, `:Float` and `:DateTime`, you can specify a minimum and/or maximum value.
+
+`min` The parameter must be greater than or equal to this.
+
+```ruby
+param :min_example, :Integer, min: 128
+```
+
+`max` The parameter must be lesser than or equal to this.
+
+```ruby
+param :max_example, :Float, max: 66.666
+```
+
+In the case of `:DateTime`, min/max validators van be defined as either ruby's DateTime class or a String representation that Ruby's [DateTime#parse](http://www.ruby-doc.org/stdlib-2.1.1/libdoc/date/rdoc/DateTime.html#method-c-parse) method can handle.
+
+```ruby
+param :string_min, :DateTime, min: '2014/02/05'
+param :date_max, :DateTime, max: DateTime.ordinal(2005,34,4,5,6,'+7')
+```
+
+
 ### String validation
 
 The following parameter validators can only be used for parameters of type `:String`.

data/lib/sinatra/browse.rb

@@ -2,18 +2,38 @@
 
 require 'sinatra/base'
 
-Dir["#{File.dirname(__FILE__)}/browse/*.rb"].each {|f| require f }
-Dir["#{File.dirname(__FILE__)}/browse/parameter_types/*.rb"].each do |f|
-  require f
-end
-
 module Sinatra::Browse
+  #
+  # Load other files
+  #
+  require_relative 'browse/format'
+  require_relative 'browse/parameter_type'
+  require_relative 'browse/route'
+  require_relative 'browse/validator'
+
+  module Errors
+    require_relative 'browse/errors'
+  end
+
+  module ParameterTypes
+    module MinMax
+      require_relative 'browse/parameter_types/min_max'
+    end
+
+    require_relative 'browse/parameter_types/boolean'
+    require_relative 'browse/parameter_types/date_time'
+    require_relative 'browse/parameter_types/float'
+    require_relative 'browse/parameter_types/integer'
+    require_relative 'browse/parameter_types/string'
+  end
+
   #
   # Main DSL methods
   #
-  def param(name, type, options = {})
+  def parameter(name, type, options = {})
     temp_browse_params[name] = options.merge({ type: type })
   end
+  alias :param :parameter
 
   def parameter_options(parameter, options)
     if temp_browse_params[parameter].nil?

data/lib/sinatra/browse/erb_templates/html.erb

@@ -13,6 +13,10 @@
         <% route.param_declarations.each do |name, param| %>
           <dt><%= param.name %></dt>
 
+          <% if param.description %>
+            <dd><%= param.description %><dd>
+          <% end %>
+
           <% if param.required? %>
             <dd>Required</dd>
           <% end %>

data/lib/sinatra/browse/errors.rb

@@ -1,7 +1,6 @@
 # -*- coding: utf-8 -*-
 
-module Sinatra::Browse
-  module Errors
-    class UnknownParameterError < Exception; end
-  end
+module Sinatra::Browse::Errors
+  class UnknownParameterError < Exception; end
+  class UnknownParameterTypeError < Exception; end
 end

data/lib/sinatra/browse/parameter_type.rb

@@ -1,19 +1,34 @@
 # -*- coding: utf-8 -*-
 
 module Sinatra::Browse
-  def self.parameter_type(name, &blk)
-    const_set "#{name}Type", Class.new(ParameterType, &blk)
-  end
-
   class ParameterType
     attr_reader :name
     attr_reader :default
     attr_reader :validators
+    attr_reader :description
+
+    def self.inherited(subclass)
+      subclass.class_eval do
+        # Initialize the validator hash
+        @validator_declarations ||= {}
+
+        #
+        # Global validators
+        #
+        validator(:in) { |possible_values| possible_values.member?(@value) }
+
+        # We need a to_s here because the user should be allowed to define dependencies
+        # using symbols while the actual keys of the params hash are strings
+        validator(:depends_on) { |dep| @params.has_key?(dep.to_s) }
+      end
+    end
 
     def initialize(name, map)
       @name = name
       @default = map.delete(:default)
 
+      @description = map.delete(:description) || map.delete(:desc)
+
       @transform = map.delete(:transform)
       @transform = @transform.to_proc if @transform
 
@@ -21,8 +36,9 @@ module Sinatra::Browse
       @on_error = map.delete(:on_error)
 
       @validators = []
+
       map.each do |key, value|
-        if val_blk = @@validator_declarations[key]
+        if val_blk = validator_declarations[key]
           @validators << Validator.new(
             name: key,
             criteria: map[key],
@@ -68,7 +84,7 @@ module Sinatra::Browse
 
     def type
       type_string = self.class.to_s.split("::").last
-      type_string[0, type_string.size - 4].to_sym
+      type_string.to_sym
     end
 
     def to_hash(options = {})
@@ -95,23 +111,17 @@ module Sinatra::Browse
     # DSL
     #
 
-    def self.coerce(&blk)
-      define_method(:coerce) { |value| blk.call(value) }
-    end
-
     def self.validator(name, &blk)
-      @@validator_declarations ||= {}
+      @validator_declarations[name] = blk
+    end
 
-      @@validator_declarations[name] = blk
+    def self.validator_declarations
+      @validator_declarations
     end
 
-    #
-    # Validators
-    #
+    def validator_declarations
+      self.class.validator_declarations
+    end
 
-    # We need a to_s here because the user should be allowed to define dependencies
-    # using symbols while the actual keys of the params hash are strings
-    validator(:depends_on) { |dep| @params.has_key?(dep.to_s) }
-    validator(:in) { |possible_values| possible_values.member?(@value) }
   end
 end

data/lib/sinatra/browse/parameter_types/boolean.rb

@@ -1,18 +1,21 @@
 # -*- coding: utf-8 -*-
 
 module Sinatra::Browse
-  parameter_type(:Boolean) do
-    coerce do |value|
-      #TODO: Raise error if it's something else
-      # true and false are included here because they can be set as default
-      # values even though only strings will come through http requests
-      case value
-      when "y", "yes", "t", "true", "1", true
-        true
-      when "n", "no", "f", "false", "0", false
-        false
+  module ParameterTypes
+
+    class Boolean < ParameterType
+      def coerce(value)
+        #TODO: Raise error if it's something else
+        # true and false are included here because they can be set as default
+        # values even though only strings will come through http requests
+        case value
+        when "y", "yes", "t", "true", "1", true
+          true
+        when "n", "no", "f", "false", "0", false
+          false
+        end
       end
     end
-  end
 
+  end
 end

data/lib/sinatra/browse/parameter_types/date_time.rb

@@ -0,0 +1,28 @@
+# -*- coding: utf-8 -*-
+
+require "date"
+
+module Sinatra::Browse
+  module ParameterTypes
+
+    class DateTime < ParameterType
+      extend MinMax
+
+      def initialize(name, map)
+        # Allow strings for min and max values
+        map[:min] = coerce(map[:min]) if map[:min].is_a?(::String)
+        map[:max] = coerce(map[:max]) if map[:max].is_a?(::String)
+
+        super(name, map)
+      end
+
+      def coerce(value)
+        # We add this line because default values also get coerced.
+        return value if value.is_a?(::DateTime)
+
+        ::DateTime.parse(value)
+      end
+    end
+
+  end
+end

data/lib/sinatra/browse/parameter_types/float.rb

@@ -1,7 +1,15 @@
 # -*- coding: utf-8 -*-
 
 module Sinatra::Browse
-  parameter_type(:Float) do
-    coerce { |value| Float(value) }
+  module ParameterTypes
+
+    class Float < ParameterType
+      extend MinMax
+
+      def coerce(value)
+        Float(value)
+      end
+    end
+
   end
 end

data/lib/sinatra/browse/parameter_types/integer.rb

@@ -1,7 +1,15 @@
 # -*- coding: utf-8 -*-
 
 module Sinatra::Browse
-  parameter_type(:Integer) do
-    coerce { |value| Integer(value) }
+  module ParameterTypes
+
+    class Integer < ParameterType
+      extend MinMax
+
+      def coerce(value)
+        Integer(value)
+      end
+    end
+
   end
 end

data/lib/sinatra/browse/parameter_types/min_max.rb

@@ -0,0 +1,14 @@
+# -*- coding: utf-8 -*-
+
+module Sinatra::Browse
+  module ParameterTypes
+    # This is a module for parameter types to extend. It will give them the
+    # validators defined here.
+    module MinMax
+      def self.extended(parameter_type)
+        parameter_type.validator(:min) { |min| @value >= min }
+        parameter_type.validator(:max) { |max| @value <= max }
+      end
+    end
+  end
+end

data/lib/sinatra/browse/parameter_types/string.rb

@@ -1,13 +1,16 @@
 # -*- coding: utf-8 -*-
 
 module Sinatra::Browse
+  module ParameterTypes
+    class String < ParameterType
+      def coerce(value)
+        String(value)
+      end
 
-  parameter_type(:String) do
-    coerce { |value| String(value) }
-
-    validator(:format) { |regex| !! (@value =~ regex) }
-    validator(:min_length) { |min_len| @value.length >= min_len }
-    validator(:max_length) { |max_len| @value.length <= max_len }
+      #TODO: raise error when declaring a validator that doesn't exist
+      validator(:format) { |regex| !! (@value =~ regex) }
+      validator(:min_length) { |min_len| @value.length >= min_len }
+      validator(:max_length) { |max_len| @value.length <= max_len }
+    end
   end
-
 end

data/lib/sinatra/browse/route.rb

@@ -77,8 +77,14 @@ module Sinatra::Browse
 
       declaration_maps.each do |name, map|
         type = map.delete(:type)
+        type_class = Sinatra::Browse::ParameterTypes.const_get(type)
 
-        @param_declarations[name] = Sinatra::Browse.const_get("#{type}Type").new(name, map)
+        #TODO: Unit test this error
+        unless type_class.is_a?(Class) && type_class.ancestors.member?(ParameterType)
+          raise Errors::UnknownParameterTypeError, type_class
+        end
+
+        @param_declarations[name] = type_class.new(name, map)
       end
     end
   end

data/lib/sinatra/browse/validators/in.rb

@@ -0,0 +1,25 @@
+# -*- coding: utf-8 -*-
+
+module Sinatra::Browse
+  module Validators
+    class In < Validator
+      class InvalidFormat < Exception; end
+      class UnableToCoerce < Exception; end
+
+      def intialize(parameter_type, criteria)
+        if ! criteria.respond_to?(:each)
+          raise InvalidFormat, "#{criteria} does not have an .each method. " +
+                               "Can't be used for 'in'."
+        end
+
+        criteria.map!
+
+        super(parameter_type, criteria)
+      end
+
+      def _validate
+        @criteria.member?(@value)
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sinatra-browse
 version: !ruby/object:Gem::Version
-  version: '0.5'
+  version: '0.6'
 platform: ruby
 authors:
 - Axsh Co. LTD
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-07-28 00:00:00.000000000 Z
+date: 2015-06-24 00:00:00.000000000 Z
 dependencies: []
 description: Parameter declaration framework and browsable API for Sinatra
 email: dev@axsh.net
@@ -17,16 +17,19 @@ extensions: []
 extra_rdoc_files: []
 files:
 - lib/sinatra/browse.rb
-- lib/sinatra/browse/route.rb
-- lib/sinatra/browse/errors.rb
-- lib/sinatra/browse/erb_templates/html.erb
+- lib/sinatra/browse/format.rb
 - lib/sinatra/browse/erb_templates/markdown.erb
+- lib/sinatra/browse/erb_templates/html.erb
 - lib/sinatra/browse/parameter_type.rb
-- lib/sinatra/browse/parameter_types/boolean.rb
+- lib/sinatra/browse/errors.rb
+- lib/sinatra/browse/validators/in.rb
+- lib/sinatra/browse/route.rb
+- lib/sinatra/browse/parameter_types/min_max.rb
 - lib/sinatra/browse/parameter_types/float.rb
 - lib/sinatra/browse/parameter_types/string.rb
+- lib/sinatra/browse/parameter_types/date_time.rb
 - lib/sinatra/browse/parameter_types/integer.rb
-- lib/sinatra/browse/format.rb
+- lib/sinatra/browse/parameter_types/boolean.rb
 - lib/sinatra/browse/validator.rb
 - LICENSE
 - README.md
@@ -42,7 +45,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - '>='
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.9.3
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - '>='
@@ -55,3 +58,4 @@ signing_key:
 specification_version: 4
 summary: Parameter declaration framework and browsable API for Sinatra
 test_files: []
+has_rdoc: