sinatra-wanted 0.8

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2bb6e4a003636fbb934a4b36e249ac757ba1cd450e4d632ea2016b61095d3752
+  data.tar.gz: 6493f6270ae54b97c3df03df9b02146b3a40f43c9e8ca667cdd242033da8232a
+SHA512:
+  metadata.gz: f9d6e85a50bd7ac41da1160142ddb6932a00527dea08f57204683506a586792e30ac246c08f64e399e6201678a9e035202c7abaff6a1e1153253923bef6403fb
+  data.tar.gz: 5453e53c9250895bdf081bca06864a06c2fc06771a28a0a05fcf7457ab8eaaeedad933450d5586790246108050684ad6281febe9b498094bda3162c470a4de27

data/README.md

@@ -0,0 +1,94 @@
+sinatra-wanted
+==============
+
+Parameter processing for Sinatra framework
+
+Allow to easily expressing parameter requirements, such as:
+
+* required/optional
+* type checking/coercion (best done using dry-types)
+* object retrieval (using Sequel, LOM, or class instantiating)
+* further processing (such as conversion) using block
+
+Examples
+========
+
+Note that in URL query `?param` as no value but `?param=` as the
+empty string value (ie: "").
+
+
+~~~ruby
+# Retrieve a required VM model from Sequel
+vm       = want! :vm,       Types::VM::Name, VM
+
+# Retrieve a require public key (in rfc4716 or openssh format)
+# and ensure the final result is in openssh format:
+pubkey   = want! :pubkey,   Types::SSHPublicKey do |k|
+                                SSHPublicKey.to_openssh(k)
+                            end
+
+# Get an optional parameter called locked which is a boolean,
+# if the parameter is present but as no value use true
+locked   = want? :locked,   Types::Params::Bool.default(true)
+
+# Parameter is optional but in this case we require a default value
+# which will be processed
+type     = want  :type,     Types::VM::Stop, default: 'savestate'
+~~~
+
+Parameter processing
+====================
+Parameter value retrieval will be processed as follow, please
+read carefully:
+
+1. Retrieve parameter value
+   If `param` is a symbol, it's key will be looked up
+   in the sinatra parameter list and assign special value:
+   * nil      : key not found
+   * NO_VALUE : key found but no value (ie: nil) associated
+
+2. Check for missing parameter (ie: nil)
+   According to named-parameter `missing`:
+   * :raise     : raise exception WantedMissing
+   * :ignore    : use the `default` value and continue processing
+   * :return    : return the `default` value (all processing stops here)
+
+3. Check for missing value (ie: NO_VALUE)
+   * If value is missing use instead the value from the
+     named parameter `no_value` (default to NO_VALUE)
+   * If the type checking/coercion is one of dry-type, the NO_VALUE
+     is changed for the Dry::Types::Undefined so that DRY can
+     correctly processed undefined value.
+
+4. Perform the type checking / coercion
+   This is done by using the first available method: [], call.
+
+   The easiest (but not required) is to use the dry-types library
+
+5. Unless value is already nil, use a getter to retrieve the real
+   value object. Object retrieval will be considered as not found,
+   if the getter returns nil
+   This is done by using the first available method: [], get,
+   fetch, call, new.
+
+   Usually getter will be Sequel Model, LDAP Object Model,
+   Class, ...
+
+   If not found (ie: nil), according to named-parameter `not_found`:
+   
+   * :raise     : raise exception WantedNotFound
+   * :ignore    : keep the value as nil and continue processing
+   * :not_found : execute the sinatra #not_found action
+   * :pass      : execute the sinatra #pass action
+
+6. Apply block processing
+
+\#want, #want!, and #want? are the same methods with different default
+for the `missing` and `not_found` named parameter
+
+| method | missing | not_found  |
+|--------|---------|------------|
+| want   | :ignore | :ignore    |
+| want!  | :raise  | :raise     |
+| want?  | :return | :ignore    |
+

data/lib/sinatra/helpers/wanted.rb

@@ -0,0 +1,176 @@
+require_relative 'wanted/version'
+
+# {include:file:README.md}
+
+module Sinatra::Helpers::Wanted
+    # Define a "No Value" object.
+    # It is used to signal that a parameter exists but as no associated value.
+    NO_VALUE = Object.new.then {|o|
+                   def o.insect
+                       "No_Value"
+                   end
+               }.freeze
+
+    # Generic exception.
+    # Only the inherited exceptions are raised.
+    class WantedError < StandardError
+        def initialize(msg=nil, value: nil, id: nil)
+            super(msg)
+            @value = value
+            @id    = id
+        end
+    end
+
+    # Exception to notify of syntax error
+    class WantedSyntaxError < WantedError
+    end
+
+    # Exception to notify of missing parameter
+    class WantedMissing < WantedError
+    end
+
+    # Exception to notify of object not found
+    class WantedNotFound < WantedError
+    end
+
+    
+    # Retrieve value/object associated with a parameter.
+    #
+    # @param param [Symbol, Object, nil, NO_VALUE]  parameter key or parameter value
+    # @param type      [#[], #call]                     type checking / coercion
+    # @param getter    [#[], #get, #fetch, #call, #new] object getter
+    # @param id        [Symbol] name of the parameter being processed
+    # @param default   [Object] default value to use if parameter is missing
+    # @param no_value  [Obejct] default value to use if object is not found
+    # @param missing   [:raise, :ignore, :return]       how to deal with missing parameter
+    # @param not_found [:false, :ignore, :not_found, :pass]   how to deal with object not found
+    #
+    # @yieldparam  obj [Object]  retrieve parameter value/object
+    # @yieldreturn [Object]      modified value/object
+    #
+    # @return [Object]           parameter value/object
+    # @return [nil]              parameter is missing or it's value is nil
+    # @return [NO_VALUE]         parameter has no associated value
+    #
+    # @raise [WantedMissing]     parameter is missing
+    # @raise [WantedNotFound]    object not found
+    # @raise [WantedSyntaxError] syntax error
+    #
+    def want(param, type=nil, getter=nil, id: nil,
+             default: nil, no_value: NO_VALUE,
+             missing: :ignore, not_found: :ignore, &block)
+        error_handler do
+            _want(param, type, getter, id: id,
+                  default: default, no_value: no_value,
+                  missing: missing, not_found: not_found, &block)
+        end
+    end
+    
+    # (see #want)
+    def want!(param, type=nil, getter=nil, id: nil,
+              default: nil, no_value: NO_VALUE,
+              missing: :raise, not_found: :raise, &block)
+        want(param, type, getter, id: id,
+             default: default, no_value: no_value,
+             missing: missing, not_found: not_found, &block)
+    end
+              
+    # (see #want)
+    def want?(param, type=nil, getter=nil, id: nil,
+              default: nil, no_value: NO_VALUE,
+              missing: :return, not_found: :ignore, &block)
+        want(param, type, getter,
+             default: default, id: id, no_value: no_value,
+             missing: missing, not_found: not_found, &block)
+    end
+
+
+    private
+    
+    def _want(param, type, getter, id:,
+              default:, no_value:, missing:, not_found:)
+        type_method = if type
+                          [ :[], :call ]
+                              .find {|m| type.respond_to?(m)   } ||
+                              raise(ArgumentError)
+                       end
+        get_method  = if getter
+                          [ :[], :get, :fetch, :call, :new ]
+                              .find {|m| getter.respond_to?(m) } ||
+                              raise(ArgumentError)
+                      end
+        value, id   = if param.kind_of?(Symbol)
+                          if params.include?(param)
+                          then [ params[param] || NO_VALUE, param ]
+                          else [ nil,                       param ]
+                          end
+                      else
+                          [ param, nil ]
+                      end
+
+        # Check for missing param
+        # Note: we consider the case where `param` is nil to be
+        #       a missing parameter, otherwise the user should
+        #       have explicitly passed NO_VALUE
+        if value.nil?
+            case missing
+            when :raise  then raise WantedMissing, id: id
+            when :return then return default
+            when :ignore then value = default
+            else raise ArgumentError
+            end
+        end
+
+        # If the parameter has no value, replace it with the
+        # user-supplied no_value
+        # Note: if type is a dry-type, NO_VALUE will be replaced
+        #       with Dry::Types::Undefined
+        if value == NO_VALUE
+            value = no_value
+            if value == NO_VALUE &&
+               defined?(Dry::Types) && type.kind_of?(Dry::Types::Type)
+                value = Dry::Types::Undefined
+            end
+        end
+        
+        # Build value from various check/conversion
+        if type_method
+            value = type.public_send(type_method, value) 
+        end
+        if !value.nil? && get_method
+            value = getter.public_send(get_method, value)
+            # Check if we consider it as not found
+            if value.nil?
+                case not_found
+                when :raise     then raise WantedNotFound, id: id
+                when :not_found then self.not_found
+                when :pass      then self.pass
+                when :ignore
+                else raise ArgumentError
+                end
+            end
+        end
+        if block_given?
+            value = yield(value)
+        end
+
+        # Return value
+        value
+    rescue Dry::Types::CoercionError, Dry::Types::ConstraintError
+        raise WantedSyntaxError, value: value, id: id
+    end
+
+    def error_handler
+        if defined?(Dry::Types)
+            begin
+                yield
+            rescue Dry::Types::CoercionError, Dry::Types::ConstraintError
+                raise WantedSyntaxError, value: value, id: id
+            end
+        else
+            yield
+        end
+    end
+   
+end
+

data/lib/sinatra/helpers/wanted/version.rb

@@ -0,0 +1,8 @@
+module Sinatra
+module Helpers
+module Wanted
+    # Version
+    VERSION = 0.8
+end
+end
+end

data/sinatra-wanted.gemspec

@@ -0,0 +1,30 @@
+# -*- encoding: utf-8 -*-
+
+require_relative 'lib/sinatra/helpers/wanted/version'
+
+Gem::Specification.new do |s|
+    s.name        = 'sinatra-wanted'
+    s.version     = Sinatra::Helpers::Wanted::VERSION
+    s.summary     = "Parameters processing for Sinatra framework"
+    s.description =  <<~EOF
+      Ease processing of parameters in Sinatra framework.
+      Integrates well with dry-types, sequel, ...
+
+      Example:
+        want! :user,    Dry::Types::String, User
+        want? :expired, Dry::Types::Params::Bool.default(true)
+      EOF
+
+    s.homepage    = 'https://gitlab.com/sdalu/sinatra-wanted'
+    s.license     = 'MIT'
+
+    s.authors     = [ "Stéphane D'Alu" ]
+    s.email       = [ 'stephane.dalu@insa-lyon.fr' ]
+
+    s.files       = %w[ README.md sinatra-wanted.gemspec ] +
+                    Dir['lib/**/*.rb']
+
+    s.add_dependency 'sinatra'
+    s.add_development_dependency 'yard', '~>0'
+    s.add_development_dependency 'rake', '~>13'
+end

metadata

@@ -0,0 +1,95 @@
+--- !ruby/object:Gem::Specification
+name: sinatra-wanted
+version: !ruby/object:Gem::Version
+  version: '0.8'
+platform: ruby
+authors:
+- Stéphane D'Alu
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2021-05-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sinatra
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13'
+description: |
+  Ease processing of parameters in Sinatra framework.
+  Integrates well with dry-types, sequel, ...
+
+  Example:
+    want! :user,    Dry::Types::String, User
+    want? :expired, Dry::Types::Params::Bool.default(true)
+email:
+- stephane.dalu@insa-lyon.fr
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/sinatra/helpers/wanted.rb
+- lib/sinatra/helpers/wanted/version.rb
+- sinatra-wanted.gemspec
+homepage: https://gitlab.com/sdalu/sinatra-wanted
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.8
+signing_key:
+specification_version: 4
+summary: Parameters processing for Sinatra framework
+test_files: []