Class: Roda::RodaPlugins::TypecastParams::Params

Inherits:
Object
  • Object
show all
Defined in:
lib/roda/plugins/typecast_params.rb

Overview

Class handling conversion of submitted parameters to desired types.

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(obj) ⇒ Params

Set the object used for converting. Conversion methods will convert members of the passed object.



601
602
603
604
605
606
607
608
609
610
611
612
 
# File 'lib/roda/plugins/typecast_params.rb', line 601

def initialize(obj)
  case @obj = obj
  when Hash, Array
    # nothing
  else
    if @nesting
      handle_error(nil, (@obj.nil? ? :missing : :invalid_type), "value of #{param_name(nil)} parameter not an array or hash: #{obj.inspect}", true)
    else
      handle_error(nil, :invalid_type, "parameters given not an array or hash: #{obj.inspect}", true)
    end
  end
end

Class Method Details

.handle_type(type, opts = OPTS, &block) ⇒ Object

Handle conversions for the given type using the given block. For a type named foo, this will create the following methods:

  • foo(key, default=nil)
  • foo!(key)
  • convert_foo(value) # private
  • _convert_array_foo(value) # private
  • _invalid_value_message_for_foo # private
  • _max_input_bytesize_for_foo # private

This method is used to define all type conversions, even the built in ones. It can be called in subclasses to setup subclass-specific types.



459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
 
# File 'lib/roda/plugins/typecast_params.rb', line 459

def self.handle_type(type, opts=OPTS, &block)
  convert_meth = :"convert_#{type}"
  define_method(convert_meth, &block)

  convert_array_meth = :"_convert_array_#{type}"
  define_method(convert_array_meth) do |v|
    raise Error, "expected array but received #{v.inspect}" unless v.is_a?(Array)
    v.map! do |val|
      check_allowed_bytesize(val, _max_input_bytesize_for(type))
      check_null_byte(val)
      send(convert_meth, val)
    end
  end

  private convert_meth, convert_array_meth

  invalid_value_message(type, opts[:invalid_value_message])
  max_input_bytesize(type, opts[:max_input_bytesize])

  define_method(type) do |key, default=nil|
    process_arg(convert_meth, key, default, type) if require_hash!
  end

  define_method(:"#{type}!") do |key|
    send(type, key, CHECK_NIL)
  end
end

.invalid_value_message(type, message) ⇒ Object

Set the invalid message for the given type.



488
489
490
491
492
493
 
# File 'lib/roda/plugins/typecast_params.rb', line 488

def self.invalid_value_message(type, message)
  invalid_value_message_meth = :"_invalid_value_message_for_#{type}"
  define_method(invalid_value_message_meth){message}
  private invalid_value_message_meth
  alias_method invalid_value_message_meth, invalid_value_message_meth
end

.max_input_bytesize(type, bytesize) ⇒ Object

Set the maximum input bytesize for the given type.



496
497
498
499
500
501
 
# File 'lib/roda/plugins/typecast_params.rb', line 496

def self.max_input_bytesize(type, bytesize)
  max_input_bytesize_meth = :"_max_input_bytesize_for_#{type}"
  define_method(max_input_bytesize_meth){bytesize}
  private max_input_bytesize_meth
  alias_method max_input_bytesize_meth, max_input_bytesize_meth
end

.nest(obj, nesting) ⇒ Object

Create a new instance with the given object and nesting level. obj should be an array or hash, and nesting should be an array. Designed for internal use, should not be called by external code.



507
508
509
510
511
512
 
# File 'lib/roda/plugins/typecast_params.rb', line 507

def self.nest(obj, nesting)
  v = allocate
  v.instance_variable_set(:@nesting, nesting)
  v.send(:initialize, obj)
  v
end

Instance Method Details

#[](key) ⇒ Object

Return a new Params instance for the given key. The value of key should be an array if key is an integer, or hash otherwise.



631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
 
# File 'lib/roda/plugins/typecast_params.rb', line 631

def [](key)
  @subs ||= {}
  if sub = @subs[key]
    return sub
  end

  if @obj.is_a?(Array)
    unless key.is_a?(Integer)
      handle_error(key, :invalid_type, "invalid use of non-integer key for accessing array: #{key.inspect}", true)
    end
  else
    if key.is_a?(Integer)
      handle_error(key, :invalid_type, "invalid use of integer key for accessing hash: #{key}", true)
    end
  end

  v = @obj[key]
  v = yield if v.nil? && defined?(yield)

  begin
    sub = self.class.nest(v, Array(@nesting) + [key])
  rescue => e
    handle_error(key, :invalid_type, e, true)
  end

  @subs[key] = sub
  sub.sub_capture(@capture, @symbolize, @skip_missing)
  sub
end

#array(type, key, default = nil) ⇒ Object

Convert the value of key to an array of values of the given type. If default is given, any nil values in the array are replaced with default. If key is an array then this returns an array of arrays, one for each respective value of key. If there is no value for key, nil is returned instead of an array.

Raises:



768
769
770
771
772
 
# File 'lib/roda/plugins/typecast_params.rb', line 768

def array(type, key, default=nil)
  meth = :"_convert_array_#{type}"
  raise ProgrammerError, "no typecast_params type registered for #{type.inspect}" unless respond_to?(meth, true)
  process_arg(meth, key, default, type) if require_hash!
end

#array!(type, key, default = nil) ⇒ Object

Call array with the type, key, and default, but if the return value is nil or any value in the returned array is nil, raise an Error.



776
777
778
779
780
781
782
783
784
785
786
787
788
 
# File 'lib/roda/plugins/typecast_params.rb', line 776

def array!(type, key, default=nil)
  v = array(type, key, default)

  if key.is_a?(Array)
    key.zip(v).each do |k, arr|
      check_array!(k, arr)
    end
  else
    check_array!(key, v)
  end

  v
end

#convert!(keys = nil, opts = OPTS) ⇒ Object

Captures conversions inside the given block, and returns a hash of all conversions, including conversions of subkeys. keys should be an array of subkeys to access, or nil to convert the current object. If keys is given as a hash, it is used as the options hash. Options:

:raise :: If set to false, do not raise errors for missing keys :skip_missing :: If set to true, does not store values if the key is not present in the params. :symbolize :: Convert any string keys in the resulting hash and for any conversions below



677
678
679
680
681
682
683
684
685
686
687
688
 
# File 'lib/roda/plugins/typecast_params.rb', line 677

def convert!(keys=nil, opts=OPTS)
  if keys.is_a?(Hash)
    opts = keys
    keys = nil
  end

  _capture!(:nested_params, opts) do
    if sub = subkey(Array(keys).dup, opts.fetch(:raise, true))
      yield sub
    end
  end
end

#convert_each!(opts = OPTS, &block) ⇒ Object

Runs conversions similar to convert! for each key specified by the :keys option. If :keys option is not given and the object is an array, runs conversions for all entries in the array. If the :keys option is not given and the object is a Hash with string keys '0', '1', ..., 'N' (with no skipped keys), runs conversions for all entries in the hash. If :keys option is a Proc or a Method, calls the proc/method with the current object, which should return an array of keys to use. Supports options given to #convert!, and this additional option:

:keys :: The keys to extract from the object. If a proc or method, calls the value with the current object, which should return the array of keys to use.



701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
 
# File 'lib/roda/plugins/typecast_params.rb', line 701

def convert_each!(opts=OPTS, &block)
  np = !@capture

  _capture!(nil, opts) do
    case keys = opts[:keys]
    when nil
      keys = (0...@obj.length)

      valid = if @obj.is_a?(Array)
        true
      else
        keys = keys.map(&:to_s)
        keys.all?{|k| @obj.has_key?(k)}
      end

      unless valid
        handle_error(nil, :invalid_type, "convert_each! called on object not an array or hash with keys '0'..'N'")
        next 
      end
    when Array
      # nothing to do
    when Proc, Method
      keys = keys.call(@obj)
    else
      raise ProgrammerError, "unsupported convert_each! :keys option: #{keys.inspect}"
    end

    keys.map do |i|
      begin
        if v = subkey([i], opts.fetch(:raise, true))
          yield v
          v.nested_params if np 
        end
      rescue => e
        handle_error(i, :invalid_type, e)
      end
    end
  end
end

#dig(type, *nest, key) ⇒ Object

Convert values nested under the current obj. Traverses the current object using nest, then converts key on that object using type:

tp.dig(:pos_int, 'foo')               # tp.pos_int('foo')
tp.dig(:pos_int, 'foo', 'bar')        # tp['foo'].pos_int('bar')
tp.dig(:pos_int, 'foo', 'bar', 'baz') # tp['foo']['bar'].pos_int('baz')

Returns nil if any of the values are not present or not the expected type. If the nest path results in an object that is not an array or hash, then raises an Error.

You can use dig to get access to nested arrays by using :array or :array! as the first argument and providing the type in the second argument:

tp.dig(:array, :pos_int, 'foo', 'bar', 'baz')  # tp['foo']['bar'].array(:pos_int, 'baz')


755
756
757
 
# File 'lib/roda/plugins/typecast_params.rb', line 755

def dig(type, *nest, key)
  _dig(false, type, nest, key)
end

#dig!(type, *nest, key) ⇒ Object

Similar to dig, but raises an Error instead of returning nil if no value is found.



760
761
762
 
# File 'lib/roda/plugins/typecast_params.rb', line 760

def dig!(type, *nest, key)
  _dig(true, type, nest, key)
end

#fetch(key) ⇒ Object

Return the nested value for key. If there is no nested_value for key, calls the block to return the value, or returns nil if there is no block given.



663
664
665
 
# File 'lib/roda/plugins/typecast_params.rb', line 663

def fetch(key)
  send(:[], key){return(yield if defined?(yield))}
end

#present?(key) ⇒ Boolean

If key is a String Return whether the key is present in the object,

Returns:

  • (Boolean) 


615
616
617
618
619
620
621
622
623
624
625
626
627
 
# File 'lib/roda/plugins/typecast_params.rb', line 615

def present?(key)
  case key
  when String
    !any(key).nil?
  when Array
    key.all? do |k|
      raise ProgrammerError, "non-String element in array argument passed to present?: #{k.inspect}" unless k.is_a?(String)
      !any(k).nil?
    end
  else
    raise ProgrammerError, "unexpected argument passed to present?: #{key.inspect}"
  end
end