tlaw 0.0.1

data/lib/tlaw/endpoint.rb

@@ -0,0 +1,132 @@
+require 'faraday'
+require 'addressable/template'
+require 'crack'
+
+module TLAW
+  # This class does all the hard work: actually calling some HTTP API
+  # and processing responses.
+  #
+  # Each real API endpoint is this class descendant, defining its own
+  # params and response processors. On each call small instance of this
+  # class is created, {#call}-ed and dies as you don't need it anymore.
+  #
+  # Typically, you will neither create nor use endpoint descendants or
+  # instances directly:
+  #
+  # * endpoint class definition is performed through {DSL} helpers,
+  # * and then, containing namespace obtains `.<current_endpoint_name>()`
+  #   method, which is (almost) everything you need to know.
+  #
+  class Endpoint < APIPath
+    class << self
+      # Inspects endpoint class prettily.
+      #
+      # Example:
+      #
+      # ```ruby
+      # some_api.some_namespace.endpoints[:my_endpoint]
+      # # => <SomeApi::SomeNamespace::MyEndpoint call-sequence: my_endpoint(param1, param2: nil), docs: .describe>
+      # ```
+      def inspect
+        "#<#{name || '(unnamed endpoint class)'}:" \
+        " call-sequence: #{symbol}(#{param_set.to_code}); docs: .describe>"
+      end
+
+      # @private
+      def to_code
+        "def #{to_method_definition}\n" \
+        "  child(:#{symbol}, Endpoint).call({#{param_set.to_hash_code}})\n" \
+        'end'
+      end
+
+      # @private
+      def construct_template
+        tpl = if query_string_params.empty?
+                base_url
+              else
+                joiner = base_url.include?('?') ? '&' : '?'
+                "#{base_url}{#{joiner}#{query_string_params.join(',')}}"
+              end
+        Addressable::Template.new(tpl)
+      end
+
+      # @private
+      def parse(body)
+        if xml
+          Crack::XML.parse(body)
+        else
+          JSON.parse(body)
+        end.derp { |response| response_processor.process(response) }
+      end
+
+      private
+
+      def query_string_params
+        param_set.all_params.values.map(&:field).map(&:to_s) -
+          Addressable::Template.new(base_url).keys
+      end
+    end
+
+    attr_reader :url_template
+
+    # Creates endpoint class (or  descendant) instance. Typically, you
+    # never use it directly.
+    #
+    # Params defined in parent namespace are passed here.
+    #
+    def initialize(**parent_params)
+      super
+
+      @client = Faraday.new
+      @url_template = self.class.construct_template
+    end
+
+    # Does the real call to the API, with all params passed to this method
+    # and to parent namespace.
+    #
+    # Typically, you don't use it directly, that's what called when you
+    # do `some_namespace.endpoint_name(**params)`.
+    #
+    # @return [Hash,Array] Parsed, flattened and post-processed response
+    #   body.
+    def call(**params)
+      url = construct_url(**full_params(params))
+
+      @client.get(url)
+             .tap { |response| guard_errors!(response) }
+             .derp { |response| self.class.parse(response.body) }
+    rescue API::Error
+      raise # Not catching in the next block
+    rescue => e
+      raise unless url
+      raise API::Error, "#{e.class} at #{url}: #{e.message}"
+    end
+
+    def_delegators :object_class, :inspect, :describe
+
+    private
+
+    def full_params(**params)
+      @parent_params.merge(params.reject { |_, v| v.nil? })
+    end
+
+    def guard_errors!(response)
+      return response if (200...400).cover?(response.status)
+
+      body = JSON.parse(response.body) rescue nil
+      message = body && (body['message'] || body['error'])
+
+      fail API::Error,
+           "HTTP #{response.status} at #{response.env[:url]}" +
+           (message ? ': ' + message : '')
+    end
+
+    def construct_url(**params)
+      url_params = self.class.param_set.process(**params)
+      @url_template
+        .expand(url_params).normalize.to_s
+        .split('?', 2).derp { |url, param| [url.gsub('%2F', '/'), param] }
+        .compact.join('?')
+    end
+  end
+end

data/lib/tlaw/namespace.rb

@@ -0,0 +1,159 @@
+module TLAW
+  # Namespace is basically a container for {Endpoint}s. It allows to
+  # nest Ruby calls (like `api.namespace1.namespace2.real_call(params)`),
+  # optionally providing some parameters while nesting, like
+  # `worldbank.countries('uk').population(2016)`.
+  #
+  # By default, namespaces nesting also means URL nesting (e.g.
+  # `base_url/namespace1/namespace2/endpoint`), but that could be altered
+  # on namespace definition, see {DSL} module for details.
+  #
+  # Typically, as with {Endpoint}, you never create namespace instances
+  # or subclasses by yourself: you use {DSL} for their definition and
+  # then call `.<namespace_name>` method on parent namespace (or API instance):
+  #
+  # ```ruby
+  # class SampleAPI < TLAW::API
+  #   # namespace definition:
+  #   namespace :my_ns do
+  #     endpoint :weather
+  #   end
+  # end
+  #
+  # # usage:
+  # api = SampleAPI.new
+  #
+  # api.namespaces[:my_ns] # => class SampleAPI::MyNS, subclass of namespace
+  # api.my_ns # => short-living instance of SampleAPI::MyNS
+  # api.my_ns.weather # => real call to API
+  # ```
+  #
+  class Namespace < APIPath
+    class << self
+      # @private
+      def base_url=(url)
+        @base_url = url
+
+        children.values.each do |c|
+          c.base_url = base_url + c.path if c.path && !c.base_url
+        end
+      end
+
+      # Lists all current namespace's nested namespaces as a hash.
+      #
+      # @return [Hash{Symbol => Namespace}]
+      def namespaces
+        children.select { |_k, v| v < Namespace }
+      end
+
+      # Lists all current namespace's endpoints as a hash.
+      #
+      # @return [Hash{Symbol => Endpoint}]
+      def endpoints
+        children.select { |_k, v| v < Endpoint }
+      end
+
+      # @private
+      def to_code
+        "def #{to_method_definition}\n" \
+        "  child(:#{symbol}, Namespace, {#{param_set.to_hash_code}})\n" \
+        'end'
+      end
+
+      def inspect
+        "#<#{name || '(unnamed namespace class)'}: " \
+        "call-sequence: #{symbol}(#{param_set.to_code});" +
+          inspect_docs
+      end
+
+      # @private
+      def inspect_docs
+        inspect_namespaces + inspect_endpoints + ' docs: .describe>'
+      end
+
+      # @private
+      def add_child(child)
+        children[child.symbol] = child
+
+        child.base_url = base_url + child.path if !child.base_url && base_url
+
+        child.define_method_on(self)
+      end
+
+      # @private
+      def children
+        @children ||= {}
+      end
+
+      # Detailed namespace documentation.
+      #
+      # See {APIPath.describe} for explanations.
+      #
+      # @return [Util::Description]
+      def describe(definition = nil)
+        super + describe_children
+      end
+
+      private
+
+      def inspect_namespaces
+        return '' if namespaces.empty?
+        " namespaces: #{namespaces.keys.join(', ')};"
+      end
+
+      def inspect_endpoints
+        return '' if endpoints.empty?
+        " endpoints: #{endpoints.keys.join(', ')};"
+      end
+
+      def describe_children
+        describe_namespaces + describe_endpoints
+      end
+
+      def describe_namespaces
+        return '' if namespaces.empty?
+
+        "\n\n  Namespaces:\n\n" + children_description(namespaces)
+      end
+
+      def describe_endpoints
+        return '' if endpoints.empty?
+
+        "\n\n  Endpoints:\n\n" + children_description(endpoints)
+      end
+
+      def children_description(children)
+        children.values.map(&:describe_short)
+                .map { |cd| cd.indent('  ') }.join("\n\n")
+      end
+    end
+
+    def_delegators :object_class,
+                   :symbol,
+                   :children, :namespaces, :endpoints,
+                   :param_set, :describe_short
+
+    def inspect
+      "#<#{symbol}(#{param_set.to_hash_code(@parent_params)})" +
+        self.class.inspect_docs
+    end
+
+    def describe
+      self.class
+          .describe("#{symbol}(#{param_set.to_hash_code(@parent_params)})")
+    end
+
+    private
+
+    def child(symbol, expected_class, **params)
+      children[symbol]
+        .tap { |child_class|
+          child_class && child_class < expected_class or
+            fail ArgumentError,
+                 "Unregistered #{expected_class.name.downcase}: #{symbol}"
+        }.derp { |child_class|
+          child_class.new(@parent_params.merge(params))
+        }
+    end
+  end
+end

data/lib/tlaw/param.rb

@@ -0,0 +1,155 @@
+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
+
+    attr_reader :name, :type, :options
+
+    def initialize(name, **options)
+      @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}"
+      }
+    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
+    end
+  end
+
+  # @private
+  class KeywordParam < Param
+    def keyword?
+      true
+    end
+
+    def to_code
+      if required?
+        "#{name}:"
+      else
+        "#{name}: #{default_to_code}"
+      end
+    end
+  end
+end
+
+require_relative 'param/type'

data/lib/tlaw/param/type.rb

@@ -0,0 +1,113 @@
+module TLAW
+  class Param
+    # @private
+    class Type
+      attr_reader :type
+
+      def self.parse(options)
+        type = options[:type]
+
+        case type
+        when nil
+          options[:enum] ? EnumType.new(options[:enum]) : Type.new(nil)
+        when Class
+          ClassType.new(type)
+        when Symbol
+          DuckType.new(type)
+        when Hash
+          EnumType.new(type)
+        else
+          fail ArgumenError, "Undefined type #{type}"
+        end
+      end
+
+      def initialize(type)
+        @type = type
+      end
+
+      def to_doc_type
+        nil
+      end
+
+      def convert(value)
+        validate(value) && _convert(value)
+      end
+
+      def validate(_value)
+        true
+      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}")
+      end
+
+      def _convert(value)
+        value
+      end
+
+      def to_doc_type
+        type.name
+      end
+    end
+
+    # @private
+    class DuckType < Type
+      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}"
+      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
+      end
+
+      def values
+        type.keys
+      end
+
+      def validate(value)
+        type.key?(value) or
+          nonconvertible!(
+            value,
+            "is not one of #{type.keys.map(&:inspect).join(', ')}"
+          )
+      end
+
+      def _convert(value)
+        type[value]
+      end
+    end
+  end
+end