sinatra-browse 0.4 → 0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9e596c2c094f363eec398cd2dc1c74d3d6cccbd9
-  data.tar.gz: 90b5732c3167897bb1cd6c6dcbed15d02b69e197
+  metadata.gz: 1faa38c99f34fe11336ea7e4beb14b9c6c8c5d44
+  data.tar.gz: 2d1cc86c5d25a45f8c557202f095f74a9e145325
 SHA512:
-  metadata.gz: 33205cac78eadc505f7c947ec7d79a23efdc7b592d6e0feed4a324f62b8374ad202947ce38cad9cf2ca251dd8c210fbfd088b74ddddc8c1f145c22f785b89950
-  data.tar.gz: 59ff1e796da21200d2b8f163f5a45611dbd2c0fd588b018978a787686fea630c07e56a1e023db7dd39563a4c989cb68d55b38f44a3c6c91973b81e81d972684b
+  metadata.gz: 6a68e861b2d04655faa2a459d9246754b526829c1ca4ebfae6ef0c7c2502a7a39583981cdb22b5ec08819aa311f9d460136b96d90f904db964d586d0b0d448b1
+  data.tar.gz: 740fbf66e097ea5d34c5998ba248df93a09db40948312b9af0659f5f0b47186ad1f314904419ceee38e4434ebe1a4a8418fe35e8f02a237b4b8a0f2fa168fcdc

data/README.md

@@ -94,7 +94,7 @@ param :order, :String, in: ["ascending", "descending"]
 
 The following parameter validators can only be used for parameters of type `:String`.
 
-`format` You can pass a regular expression that the string provided must match to.
+`format` The string must match this regular expression.
 
 ```ruby
 param :alphanumeric, :String, format: /^[0-9A-Za-z]*$/

data/lib/sinatra/browse.rb

@@ -3,18 +3,36 @@
 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
+  #
+  # Main DSL methods
+  #
   def param(name, type, options = {})
     temp_browse_params[name] = options.merge({ type: type })
   end
 
   def parameter_options(parameter, options)
-    #TODO: Raise error when the parameter overridden doesn't exist
+    if temp_browse_params[parameter].nil?
+      msg = "Tried to override undeclared parameter #{parameter}"
+      raise Errors::UnknownParameterError, msg
+    end
+
     temp_browse_params[parameter].merge! options
   end
   alias :param_options :parameter_options
 
+  def describe(description)
+    @_browse_description = description
+  end
+  alias :desc :describe
+
+  #
+  # Internal stuff
+  #
   def temp_browse_params
     @_temp_browse_params ||= reset_temp_params
   end
@@ -31,18 +49,20 @@ module Sinatra::Browse
     @_browse_description ||= ""
   end
 
-  def describe(description)
-    @_browse_description = description
-  end
-  alias :desc :describe
-
   def browse_routes_for(request_method, path_info)
     browse_routes.values.find { |v| v.matches?(request_method, path_info) }
   end
 
-  #TODO: Rename method... It doesn't sound like we'd be creating a new route object here
-  def set_browse_routes_for(request_method, path_info, description = browse_description, new_params = temp_browse_params)
-    new_route = Route.new(request_method, path_info, browse_description, new_params)
+  def create_browse_route(request_method,
+                          path_info,
+                          description = browse_description,
+                          new_params = temp_browse_params)
+
+    new_route = Route.new(request_method,
+                          path_info,
+                          browse_description,
+                          new_params)
+
     browse_routes[new_route.name] = new_route
   end
 
@@ -76,29 +96,26 @@ module Sinatra::Browse
       browse_route = app.browse_routes_for(request.request_method, request.path_info)
 
       if browse_route
-        #TODO: Optionally throw error for undefined params
-
         if settings.remove_undefined_parameters
           browse_route.delete_undefined(params, settings.allowed_undefined_parameters)
         end
 
-        browse_route.coerce_type(params)
-        browse_route.set_defaults(params)
-        validation_result = browse_route.validate(params)
-        unless validation_result[:success]
-          if validation_result[:on_error].respond_to?(:to_proc)
-            error_proc = validation_result.delete(:on_error).to_proc
-            instance_exec validation_result, &error_proc
+        validation_successful, error_hash = browse_route.process(params)
+
+        unless validation_successful
+          if error_hash[:on_error].respond_to?(:to_proc)
+            error_proc = error_hash.delete(:on_error).to_proc
+            instance_exec error_hash, &error_proc
           else
-            instance_exec validation_result, &app.default_on_error
+            instance_exec error_hash, &app.default_on_error
           end
         end
-        browse_route.transform(params)
+
       end
     end
 
-    # Create the (future) browsable api
-    app.param :format, :String, in: ["kusohtml", "json", "yaml"], default: "kusohtml"
+    app.describe "Displays this browsable API."
+    app.param :format, :String, in: ["html", "json", "yaml", "yml"], default: "html"
     app.get '/browse' do
       Sinatra::Browse.format(params["format"], app.browse_routes).generate
     end
@@ -106,7 +123,7 @@ module Sinatra::Browse
 
   def self.route_added(verb, path, block)
     return if verb == "HEAD" && !@app.settings.show_head_routes
-    @app.set_browse_routes_for(verb, path)
+    @app.create_browse_route(verb, path)
     @app.reset_temp_params
     @app.desc ""
   end

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

@@ -0,0 +1,35 @@
+<!DOCTYPE html>
+<html>
+  <body>
+    <% @browse_routes.each do |name, route| %>
+      <h1><%= name %></h1>
+
+      <p><%= route.description %></p>
+
+      <% unless route.param_declarations.empty? %>
+        <h2>Parameters</h2>
+
+        <dl>
+        <% route.param_declarations.each do |name, param| %>
+          <dt><%= param.name %></dt>
+
+          <% if param.required? %>
+            <dd>Required</dd>
+          <% end %>
+
+          <dd>Type: <%= param.type %></dd>
+
+          <% if param.default %>
+            <dd>Default: <%= param.default %></dd>
+          <% end %>
+
+          <% param.validators.each do |v| %>
+            <dd><%= v.name %>: <%= h v.criteria %></dd>
+          <% end %>
+
+        <% end %>
+        </dl>
+      <% end %>
+    <% end %>
+  </body>
+</html>

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

@@ -0,0 +1,7 @@
+<% @browse_routes.each do |name, route| %>
+  # <%= name %>
+
+  <% route.param_declarations.each do |name, param| %>
+  * <%= param.name %>
+  <% end %>
+<% end %>

data/lib/sinatra/browse/errors.rb

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

data/lib/sinatra/browse/format.rb

@@ -1,16 +1,19 @@
 # -*- coding: utf-8 -*-
 
 require 'yaml'
+require 'erb'
 
 module Sinatra::Browse
   def self.format(f, browse_routes)
     case f
-    when "kusohtml"
-      KusoHtml.new(browse_routes)
+    when "html"
+      ErbTemplate.new(browse_routes, "html.erb")
     when "json"
       JSON.new(browse_routes)
-    when "yaml"
+    when "yaml", "yml"
       YAML.new(browse_routes)
+    when "markdown"
+      ErbTemplate.new(browse_routes, "markdown.erb")
     end
   end
 
@@ -20,30 +23,28 @@ module Sinatra::Browse
     end
   end
 
-  class KusoHtml < BrowseFormat
+  class ErbTemplate < BrowseFormat
+    include ERB::Util
+
+    def initialize(browse_routes, filename)
+      super(browse_routes)
+      @template = File.read(File.dirname(__FILE__) + "/erb_templates/" + filename)
+    end
+
     def generate
-      output = ""
-      @browse_routes.each { |name, route|
-        output += "<h3>#{name}</h3>"
-        output += "<p>#{route.description}</p><ul>"
-        route.parameters.each { |param_key, param_value|
-          output += "<li>#{param_key} #{param_value.to_s}</li>"
-        }
-        output += "</ul>"
-      }
-      output
+      ERB.new(@template).result(binding)
     end
   end
 
   class JSON < BrowseFormat
     def generate
-      @browse_routes.values.map { |br| br.to_hash }.to_json
+      @browse_routes.values.map { |br| br.to_hash(noprocs: true) }.to_json
     end
   end
 
   class YAML < BrowseFormat
     def generate
-      @browse_routes.values.map { |br| br.to_hash }.to_yaml
+      @browse_routes.values.map { |br| br.to_hash(noprocs: true) }.to_yaml
     end
   end
 end

data/lib/sinatra/browse/parameter_type.rb

@@ -0,0 +1,117 @@
+# -*- 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
+
+    def initialize(name, map)
+      @name = name
+      @default = map.delete(:default)
+
+      @transform = map.delete(:transform)
+      @transform = @transform.to_proc if @transform
+
+      @required = !! map[:required]
+      @on_error = map.delete(:on_error)
+
+      @validators = []
+      map.each do |key, value|
+        if val_blk = @@validator_declarations[key]
+          @validators << Validator.new(
+            name: key,
+            criteria: map[key],
+            validation_blk: val_blk
+          )
+        end
+      end
+
+    end
+
+    def default
+      @default.is_a?(Proc) ? @default.call : @default
+    end
+
+    def required?
+      @required
+    end
+
+    def validate(params)
+      @validators.each do |v|
+        return false, build_error_hash(v.name, v.value) unless v.validate(self.name, params)
+      end
+
+      true
+    end
+
+    def transform(value)
+      @transform ? @transform.call(value) : value
+    end
+
+    def coerce(value)
+      raise NotImplementedError
+    end
+
+    def build_error_hash(reason, value)
+      {
+        reason: reason,
+        parameter: self.name,
+        value: value,
+        on_error: @on_error
+      }
+    end
+
+    def type
+      type_string = self.class.to_s.split("::").last
+      type_string[0, type_string.size - 4].to_sym
+    end
+
+    def to_hash(options = {})
+      h = {
+        name: @name,
+        type: type,
+        required: required?,
+      }
+
+      if @default
+        h[:default] = if @default.is_a?(Proc) && options[:noprocs]
+          "dynamically generated"
+        else
+          @default
+        end
+      end
+
+      @validators.each { |v| h[v.name.to_sym] = v.criteria }
+
+      h
+    end
+
+    #
+    # 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
+
+    #
+    # Validators
+    #
+
+    # 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

@@ -0,0 +1,18 @@
+# -*- 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
+      end
+    end
+  end
+
+end

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

@@ -0,0 +1,7 @@
+# -*- coding: utf-8 -*-
+
+module Sinatra::Browse
+  parameter_type(:Float) do
+    coerce { |value| Float(value) }
+  end
+end

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

@@ -0,0 +1,7 @@
+# -*- coding: utf-8 -*-
+
+module Sinatra::Browse
+  parameter_type(:Integer) do
+    coerce { |value| Integer(value) }
+  end
+end

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

@@ -0,0 +1,13 @@
+# -*- coding: utf-8 -*-
+
+module Sinatra::Browse
+
+  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 }
+  end
+
+end

data/lib/sinatra/browse/route.rb

@@ -1,100 +1,69 @@
 # -*- coding: utf-8 -*-
 
- module Sinatra::Browse
+module Sinatra::Browse
   class Route
-    attr_reader :parameters
+    attr_reader :param_declarations
     attr_reader :name
     attr_reader :match
     attr_reader :description
 
-    class ValidationError < Exception; end
-
     # This is here because we're using the name as the keys for the
     # _browse_routes hash. We want to build it outside of this class for that.
     def self.build_name(request_method, path_info)
       "#{request_method}  #{path_info}"
     end
 
-    def initialize(request_method, path_info, description, parameters = nil)
+    def initialize(request_method, path_info, description, declaration_maps = nil)
       @name = build_name(request_method, path_info)
       @match = build_match(request_method, path_info)
       @description = description
-      @parameters = parameters || {}
+      build_declarations(declaration_maps || {})
     end
 
-    def to_hash
-      {name: @name, description: @description}.merge @parameters
+    def to_hash(options = {})
+      {
+        route: @name,
+        description: @description,
+        parameters: @param_declarations.map { |name, pd| pd.to_hash(options) }
+      }
     end
 
     def matches?(request_method, path_info)
       !! (build_name(request_method,path_info) =~ @match)
     end
 
-    def has_parameter?(parameter)
-      @parameters.has_key?(parameter.to_sym)
+    def has_parameter?(name)
+      @param_declarations.has_key?(name.to_sym)
     end
 
-    def coerce_type(params)
-      @parameters.each { |k,v|
-        params[k] &&= case v[:type]
-        when :Boolean
-          cast_to_boolean(params[k])
-        else
-          send(v[:type], params[k])
-        end
-      }
-    end
+    def process(params)
+      @param_declarations.each do |name, pd|
+        name = name.to_s # The params hash uses strings but declarations use symbols
 
-    def set_defaults(params)
-      @parameters.each { |k,v|
-        unless params[k] || v[:default].nil?
-          params[k] = v[:default].is_a?(Proc) ? v[:default].call(params[k]) : v[:default]
-        end
-      }
-    end
-
-    def delete_undefined(params, allowed)
-      params.delete_if { |i| !(self.has_parameter?(i) || allowed.member?(i)) }
-    end
+        params[name] ||= pd.default
 
-    def validate(params)
-      @parameters.each { |k,v|
-        return fail_validation k, params[k], v, :required if !params[k] && v[:required]
-        if params[k]
-          return fail_validation k, params[k], v, :depends_on if v[:depends_on] && !params[v[:depends_on]]
-          return fail_validation k, params[k], v, :in if v[:in] && !v[:in].member?(params[k])
-
-          if v[:type] == :String
-            return fail_validation k, params[k], v, :format if v[:format] && !(params[k] =~ v[:format])
-            return fail_validation k, params[k], v, :min_length if v[:min_length] && params[k].length < v[:min_length]
-            return fail_validation k, params[k], v, :max_length if v[:max_length] && params[k].length > v[:max_length]
-          end
+        # We specifically check for nil here since a boolean's default can be false
+        if params[name].nil?
+          return false, pd.build_error_hash(:required, nil) if pd.required?
+          next
         end
-      }
 
-      {success: true}
-    end
+        params[name] = pd.coerce(params[name])
 
-    def transform(params)
-      @parameters.each { |k,v|
-        params[k] = v[:transform].to_proc.call(params[k]) if params[k] && v[:transform]
-      }
-    end
+        success, error_hash = pd.validate(params)
+        return false, error_hash unless success
 
-    private
-    def cast_to_boolean(param)
-      case param
-      when "y", "yes", "t", "true", "1"
-        true
-      when "n", "no", "f", "false", "0"
-        false
+        params[name] = pd.transform(params[name])
       end
+
+      true
     end
 
-    def fail_validation(parameter, value, options, reason)
-      {success: false, reason: reason , parameter: parameter, value: value}.merge(options)
+    def delete_undefined(params, allowed)
+      params.delete_if { |i| !(self.has_parameter?(i) || allowed.member?(i)) }
     end
 
+    private
     def build_name(request_method, path_info)
       self.class.build_name(request_method, path_info)
     end
@@ -102,5 +71,15 @@
     def build_match(request_method, path_info)
       /^#{request_method}\s\s#{path_info.gsub(/:[^\/]*/, '[^\/]*')}$/
     end
+
+    def build_declarations(declaration_maps)
+      @param_declarations = {}
+
+      declaration_maps.each do |name, map|
+        type = map.delete(:type)
+
+        @param_declarations[name] = Sinatra::Browse.const_get("#{type}Type").new(name, map)
+      end
+    end
   end
 end

data/lib/sinatra/browse/validator.rb

@@ -0,0 +1,22 @@
+# -*- coding: utf-8 -*-
+
+module Sinatra::Browse
+  class Validator
+    attr_reader :criteria
+    attr_reader :value
+    attr_reader :name
+
+    def initialize(map)
+      @name = map[:name]
+      @criteria = map[:criteria]
+      @validation_blk = map[:validation_blk]
+    end
+
+    def validate(param_name, params)
+      @value = params[param_name]
+      @params = params
+
+      instance_exec @criteria, &@validation_blk
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sinatra-browse
 version: !ruby/object:Gem::Version
-  version: '0.4'
+  version: '0.5'
 platform: ruby
 authors:
 - Axsh Co. LTD
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-05-14 00:00:00.000000000 Z
+date: 2014-07-28 00:00:00.000000000 Z
 dependencies: []
 description: Parameter declaration framework and browsable API for Sinatra
 email: dev@axsh.net
@@ -17,8 +17,17 @@ extensions: []
 extra_rdoc_files: []
 files:
 - lib/sinatra/browse.rb
-- lib/sinatra/browse/format.rb
 - lib/sinatra/browse/route.rb
+- lib/sinatra/browse/errors.rb
+- lib/sinatra/browse/erb_templates/html.erb
+- lib/sinatra/browse/erb_templates/markdown.erb
+- lib/sinatra/browse/parameter_type.rb
+- lib/sinatra/browse/parameter_types/boolean.rb
+- lib/sinatra/browse/parameter_types/float.rb
+- lib/sinatra/browse/parameter_types/string.rb
+- lib/sinatra/browse/parameter_types/integer.rb
+- lib/sinatra/browse/format.rb
+- lib/sinatra/browse/validator.rb
 - LICENSE
 - README.md
 homepage: https://github.com/axsh/sinatra-browse