tlaw 0.0.2 → 0.1.0.pre

data/lib/tlaw/param.rb

@@ -1,155 +1,59 @@
-module TLAW
-  # Base parameter class for working with parameters validation and
-  # converting. You'll never instantiate it directly, just see {DSL#param}
-  # for parameters definition.
-  #
-  class Param
-    # This error is thrown when some value could not be converted to what
-    # this parameter inspects. For example:
-    #
-    # ```ruby
-    # # definition:
-    # param :timestamp, :to_time, format: :to_i
-    # # this means: parameter, when passed, will first be converted with
-    # # method #to_time, and then resulting time will be made into
-    # # unix timestamp with #to_i before passing to API
-    #
-    # # usage:
-    # my_endpoint(timestamp: Time.now) # ok
-    # my_endpoint(timestamp: Date.today) # ok
-    # my_endpoint(timestamp: '2016-06-01') # Nonconvertible! ...unless you've included ActiveSupport :)
-    # ```
-    #
-    Nonconvertible = Class.new(ArgumentError)
-
-    def self.make(name, **options)
-      # NB: Sic. :keyword is nil (not provided) should still
-      #     make a keyword argument.
-      if options[:keyword] != false
-        KeywordParam.new(name, **options)
-      else
-        ArgumentParam.new(name, **options)
-      end
-    end
+# frozen_string_literal: true
 
-    attr_reader :name, :type, :options
+require_relative 'param/type'
 
-    def initialize(name, **options)
+module TLAW
+  # @private
+  class Param
+    attr_reader :name, :field, :type, :description, :default, :format
+
+    def initialize(
+      name:,
+      field: name,
+      type: nil,
+      description: nil,
+      required: false,
+      keyword: true,
+      default: nil,
+      format: :itself
+    )
       @name = name
-      @options = options
-      @type = Type.parse(options)
-      @options[:desc] ||= @options[:description]
-      @options[:desc].gsub!(/\n( *)/, "\n  ") if @options[:desc]
-      @formatter = make_formatter
-    end
-
-    def required?
-      options[:required]
-    end
-
-    def default
-      options[:default]
-    end
-
-    def merge(**new_options)
-      Param.make(name, @options.merge(new_options))
-    end
-
-    def field
-      options[:field] || name
-    end
-
-    def convert(value)
-      type.convert(value)
-    end
-
-    def format(value)
-      to_url_part(formatter.call(value))
-    end
-
-    def convert_and_format(value)
-      format(convert(value))
-    end
-
-    alias_method :to_h, :options
-
-    def description
-      options[:desc]
-    end
-
-    def describe
-      [
-        '@param', name,
-        ("[#{doc_type}]" if doc_type),
-        description,
-        if @options[:enum]
-          "\n  Possible values: #{type.values.map(&:inspect).join(', ')}"
-        end,
-        ("(default = #{default.inspect})" if default)
-      ].compact.join(' ')
-        .derp(&Util::Description.method(:new))
-    end
-
-    private
-
-    attr_reader :formatter
-
-    def doc_type
-      type.to_doc_type
-    end
-
-    def to_url_part(value)
-      case value
-      when Array
-        value.join(',')
-      else
-        value.to_s
-      end
-    end
-
-    def make_formatter
-      options[:format].derp { |f|
-        return ->(v) { v } unless f
-        return f.to_proc if f.respond_to?(:to_proc)
-        fail ArgumentError, "#{self}: unsupporter formatter #{f}"
+      @field = field
+      @type = Type.coerce(type)
+      @description = description
+      @required = required
+      @keyword = keyword
+      @default = default
+      @format = format
+    end
+
+    def to_h
+      {
+        name: name,
+        field: field,
+        type: type,
+        description: description,
+        required: required?,
+        keyword: keyword?,
+        default: default,
+        format: format
       }
     end
 
-    def default_to_code
-      # FIXME: this `inspect` will fail with, say, Time
-      default.inspect
-    end
-  end
-
-  # @private
-  class ArgumentParam < Param
-    def keyword?
-      false
-    end
-
-    def to_code
-      if required?
-        name.to_s
-      else
-        "#{name}=#{default_to_code}"
-      end
+    def required?
+      @required
     end
-  end
 
-  # @private
-  class KeywordParam < Param
     def keyword?
-      true
+      @keyword
     end
 
-    def to_code
-      if required?
-        "#{name}:"
-      else
-        "#{name}: #{default_to_code}"
-      end
+    def call(value)
+      type.(value)
+        .yield_self(&format)
+        .yield_self { |val| {field => Array(val).join(',')} }
+    rescue TypeError => e
+      raise TypeError, "#{name}: #{e.message}"
     end
   end
 end
-
-require_relative 'param/type'

data/lib/tlaw/param/type.rb

@@ -1,15 +1,21 @@
+# frozen_string_literal: true
+
 module TLAW
   class Param
     # @private
     class Type
       attr_reader :type
 
-      def self.parse(options)
-        type = options[:type]
+      def self.default_type
+        @default_type ||= Type.new(nil)
+      end
 
+      def self.coerce(type = nil)
         case type
         when nil
-          options[:enum] ? EnumType.new(options[:enum]) : Type.new(nil)
+          default_type
+        when Type
+          type
         when Class
           ClassType.new(type)
         when Symbol
@@ -17,7 +23,7 @@ module TLAW
         when Hash
           EnumType.new(type)
         else
-          fail ArgumenError, "Undefined type #{type}"
+          fail ArgumentError, "Undefined type #{type}"
         end
       end
 
@@ -25,88 +31,69 @@ module TLAW
         @type = type
       end
 
-      def to_doc_type
-        nil
+      def ==(other)
+        other.is_a?(self.class) && other.type == type
       end
 
-      def convert(value)
-        validate(value) && _convert(value)
+      def call(value)
+        validation_error(value)
+          &.yield_self { |msg|
+            fail TypeError, "expected #{msg}, got #{value.inspect}"
+          }
+        _convert(value)
       end
 
-      def validate(_value)
-        true
+      private
+
+      def validation_error(_value)
+        nil
       end
 
       def _convert(value)
         value
       end
-
-      def nonconvertible!(value, reason)
-        fail Nonconvertible,
-             "#{self} can't convert  #{value.inspect}: #{reason}"
-      end
     end
 
     # @private
     class ClassType < Type
-      def validate(value)
-        value.is_a?(type) or
-          nonconvertible!(value, "not an instance of #{type}")
+      private
+
+      def validation_error(value)
+        "instance of #{type}" unless value.is_a?(type)
       end
 
       def _convert(value)
         value
       end
-
-      def to_doc_type
-        type.name
-      end
     end
 
     # @private
     class DuckType < Type
+      private
+
       def _convert(value)
         value.send(type)
       end
 
-      def validate(value)
-        value.respond_to?(type) or
-          nonconvertible!(value, "not responding to #{type}")
-      end
-
-      def to_doc_type
-        "##{type}"
+      def validation_error(value)
+        "object responding to ##{type}" unless value.respond_to?(type)
       end
     end
 
     # @private
     class EnumType < Type
-      def initialize(enum)
-        @type =
-          case enum
-          when Hash
-            enum
-          when ->(e) { e.respond_to?(:map) }
-            enum.map { |n| [n, n] }.to_h
-          else
-            fail ArgumentError, "Unparseable enum: #{enum.inspect}"
-          end
+      def possible_values
+        type.keys.map(&:inspect).join(', ')
       end
 
-      def values
-        type.keys
-      end
+      private
 
-      def validate(value)
-        type.key?(value) or
-          nonconvertible!(
-            value,
-            "is not one of #{type.keys.map(&:inspect).join(', ')}"
-          )
+      def validation_error(value)
+        "one of #{possible_values}" unless type.key?(value)
       end
 
       def _convert(value)
-        type[value]
+        type.fetch(value)
       end
     end
   end

data/lib/tlaw/response_processors.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module TLAW
+  # @private
+  module ResponseProcessors
+    # @private
+    module Generators
+      module_function
+
+      def mutate(&block)
+        proc { |hash| hash.tap(&block) }
+      end
+
+      def transform_by_key(key_pattern, &block)
+        proc { |hash| ResponseProcessors.transform_by_key(hash, key_pattern, &block) }
+      end
+
+      def transform_nested(key_pattern, nested_key_pattern = nil, &block)
+        transformer = if nested_key_pattern
+                        transform_by_key(nested_key_pattern, &block)
+                      else
+                        mutate(&block)
+                      end
+        proc { |hash| ResponseProcessors.transform_nested(hash, key_pattern, &transformer) }
+      end
+    end
+
+    class << self
+      def transform_by_key(value, key_pattern)
+        return value unless value.is_a?(Hash)
+
+        value
+          .map { |k, v| key_pattern === k ? [k, yield(v)] : [k, v] } # rubocop:disable Style/CaseEquality
+          .to_h
+      end
+
+      def transform_nested(value, key_pattern, &block)
+        transform_by_key(value, key_pattern) { |v| v.is_a?(Array) ? v.map(&block) : v }
+      end
+
+      def flatten(value)
+        case value
+        when Hash
+          flatten_hash(value)
+        when Array
+          value.map(&method(:flatten))
+        else
+          value
+        end
+      end
+
+      def datablize(value)
+        case value
+        when Hash
+          value.transform_values(&method(:datablize))
+        when Array
+          if !value.empty? && value.all?(Hash)
+            DataTable.new(value)
+          else
+            value
+          end
+        else
+          value
+        end
+      end
+
+      private
+
+      def flatten_hash(hash)
+        hash.flat_map do |k, v|
+          v = flatten(v)
+          if v.is_a?(Hash)
+            v.map { |k1, v1| ["#{k}.#{k1}", v1] }
+          else
+            [[k, v]]
+          end
+        end.reject { |_, v| v.nil? }.to_h
+      end
+    end
+  end
+end

data/lib/tlaw/util.rb

@@ -1,45 +1,28 @@
+# frozen_string_literal: true
+
 module TLAW
+  # @private
   module Util
     module_function
 
     def camelize(string)
-      string
-        .sub(/^[a-z\d]*/, &:capitalize)
-        .gsub(%r{(?:_|(/))([a-z\d]*)}i) {
-          "#{$1}#{$2.capitalize}" # rubocop:disable Style/PerlBackrefs
-        }
+      string.sub(/^[a-z\d]*/, &:capitalize)
     end
 
-    # Description is just a String subclass with rewritten `inspect`
-    # implementation (useful in `irb`/`pry`):
-    #
-    # ```ruby
-    # str = "Description of endpoint:\nIt has params:..."
-    # # "Description of endpoint:\nIt has params:..."
-    #
-    # TLAW::Util::Description.new(str)
-    # # Description of endpoint:
-    # # It has params:...
-    # ```
-    #
-    # TLAW uses it when responds to {APIPath.describe}.
-    #
-    class Description < String
-      alias_method :inspect, :to_s
-
-      def initialize(str)
-        super(str.to_s.gsub(/ +\n/, "\n"))
-      end
-
-      # @private
-      def indent(indentation = '  ')
-        gsub(/(\A|\n)/, '\1' + indentation)
-      end
+    def deindent(string)
+      string
+        .gsub(/^[ \t]+/, '')      # first, remove spaces at a beginning of each line
+        .gsub(/\A\n|\n\s*\Z/, '') # then, remove empty lines before and after docs block
+    end
 
-      # @private
-      def +(other)
-        self.class.new(super)
+    # Returns [parent, parent.parent, ...]
+    def parents(obj)
+      result = []
+      cursor = obj
+      while (cursor = cursor.parent)
+        result << cursor
       end
+      result
     end
   end
 end