tlaw 0.0.2 → 0.1.0.pre

data/lib/tlaw/dsl/api_builder.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative 'base_builder'
+require_relative 'endpoint_builder'
+require_relative 'namespace_builder'
+
+module TLAW
+  module DSL
+    # @private
+    class ApiBuilder < NamespaceBuilder
+      # @private
+      CLASS_NAMES = {
+        :[] => 'Element'
+      }.freeze
+
+      def initialize(api_class, &block)
+        @api_class = api_class
+        @definition = {}
+        # super(symbol: nil, children: api_class.children || [], &block)
+        super(symbol: nil, **api_class.definition, &block)
+      end
+
+      def finalize
+        @api_class.setup(**definition)
+        define_children_methods(@api_class)
+        constantize_children(@api_class)
+      end
+
+      def base(url)
+        @definition[:base_url] = url
+      end
+
+      private
+
+      def constantize_children(namespace)
+        return unless namespace.name&.match?(/^[A-Z]/) && namespace.respond_to?(:children)
+
+        namespace.children.each do |child|
+          class_name = CLASS_NAMES.fetch(child.symbol, Util.camelize(child.symbol.to_s))
+          # namespace.send(:remove_const, class_name) if namespace.const_defined?(class_name)
+          namespace.const_set(class_name, child) unless namespace.const_defined?(class_name)
+          constantize_children(child)
+        end
+      end
+    end
+  end
+end

data/lib/tlaw/dsl/base_builder.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module TLAW
+  module DSL
+    # @private
+    class BaseBuilder
+      attr_reader :params, :processors, :shared_definitions
+
+      def initialize(symbol:, path: nil, context: nil, xml: false, params: {}, **opts, &block)
+        path ||= "/#{symbol}" # Not default arg, because we need to process explicitly passed path: nil, too
+        @definition = opts.merge(symbol: symbol, path: path)
+        @params = params.merge(params_from_path(path))
+        @processors = (context&.processors || []).dup
+        @parser = parser(xml)
+        @shared_definitions = context&.shared_definitions || {}
+        instance_eval(&block) if block
+      end
+
+      def definition
+        @definition.merge(param_defs: params.map { |name, **opts| Param.new(name: name, **opts) })
+      end
+
+      def docs(link)
+        @definition[:docs_link] = link
+        self
+      end
+
+      def description(text)
+        @definition[:description] = Util.deindent(text)
+        self
+      end
+
+      alias desc description
+
+      def param(name, type = nil, enum: nil, desc: nil, description: desc, **opts)
+        opts = opts.merge(
+          type: type || enum&.yield_self(&method(:enum_type)),
+          description: description&.yield_self(&Util.method(:deindent))
+        ).compact
+        params.merge!(name => opts) { |_, o, n| o.merge(n) }
+        self
+      end
+
+      def shared_def(name, &block)
+        @shared_definitions[name] = block
+        self
+      end
+
+      def use_def(name)
+        shared_definitions
+          .fetch(name) { fail ArgumentError, "#{name.inspect} is not a shared definition" }
+          .tap { |block| instance_eval(&block) }
+        self
+      end
+
+      def finalize
+        fail NotImplementedError, "#{self.class} doesn't implement #finalize"
+      end
+
+      G = ResponseProcessors::Generators
+
+      def post_process(key_pattern = nil, &block)
+        @processors << (key_pattern ? G.transform_by_key(key_pattern, &block) : G.mutate(&block))
+      end
+
+      # @private
+      class PostProcessProxy
+        def initialize(owner, parent_key)
+          @owner = owner
+          @parent_key = parent_key
+        end
+
+        def post_process(key = nil, &block)
+          @owner.processors << G.transform_nested(@parent_key, key, &block)
+        end
+      end
+
+      def post_process_items(key_pattern, &block)
+        PostProcessProxy.new(self, key_pattern).instance_eval(&block)
+      end
+
+      def post_process_replace(&block)
+        @processors << block
+      end
+
+      private
+
+      def parser(xml)
+        xml ? Crack::XML.method(:parse) : JSON.method(:parse)
+      end
+
+      def enum_type(enum)
+        case enum
+        when Hash
+          enum
+        when Enumerable # well... in fact respond_to?(:each) probably will do
+          enum.map { |v| [v, v] }.to_h
+        else
+          fail ArgumentError, "Can't construct enum from #{enum.inspect}"
+        end
+      end
+
+      def params_from_path(path)
+        Addressable::Template.new(path).keys.map { |key| [key.to_sym, keyword: false] }.to_h
+      end
+    end
+  end
+end

data/lib/tlaw/dsl/endpoint_builder.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative 'base_builder'
+
+module TLAW
+  module DSL
+    # @private
+    class EndpointBuilder < BaseBuilder
+      def definition
+        # TODO: Here we'll be more flexible in future, allowing to avoid flatten/datablize
+        all_processors = [
+          @parser,
+          ResponseProcessors.method(:flatten),
+          *processors,
+          ResponseProcessors.method(:datablize)
+        ]
+
+        super.merge(processors: all_processors)
+      end
+
+      def finalize
+        Endpoint.define(**definition)
+      end
+    end
+  end
+end

data/lib/tlaw/dsl/namespace_builder.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative 'base_builder'
+require_relative 'endpoint_builder'
+
+module TLAW
+  module DSL
+    # @private
+    class NamespaceBuilder < BaseBuilder
+      CHILD_CLASSES = {NamespaceBuilder => Namespace, EndpointBuilder => Endpoint}.freeze
+
+      attr_reader :children
+
+      ENDPOINT_METHOD = <<~CODE
+        def %{call_sequence}
+          child(:%{symbol}, Endpoint, %{params}).call
+        end
+      CODE
+
+      NAMESPACE_METHOD = <<~CODE
+        def %{call_sequence}
+          child(:%{symbol}, Namespace, %{params})
+        end
+      CODE
+
+      METHODS = {Endpoint => ENDPOINT_METHOD, Namespace => NAMESPACE_METHOD}.freeze
+
+      def initialize(children: [], **args, &block)
+        @children = children.map { |c| [c.symbol, c] }.to_h
+        super(**args, &block)
+      end
+
+      def definition
+        super.merge(children: children.values)
+      end
+
+      def endpoint(symbol, path = nil, **opts, &block)
+        child(EndpointBuilder, symbol, path, **opts, &block)
+      end
+
+      def namespace(symbol, path = nil, **opts, &block)
+        child(NamespaceBuilder, symbol, path, **opts, &block)
+      end
+
+      def finalize
+        Namespace.define(**definition).tap(&method(:define_children_methods))
+      end
+
+      private
+
+      def child(builder_class, symbol, path, **opts, &block)
+        symbol = symbol.to_sym
+        target_class = CHILD_CLASSES.fetch(builder_class)
+        existing = children[symbol]
+          &.tap { |c|
+            c < target_class or fail ArgumentError, "#{symbol} already defined as #{c.ansestors.first}"
+          }
+          &.definition || {}
+
+        builder_class.new(
+          symbol: symbol,
+          path: path,
+          context: self,
+          **opts,
+          **existing,
+          &block
+        ).finalize.tap { |child| children[symbol] = child }
+      end
+
+      def define_children_methods(namespace)
+        children.each_value do |child|
+          namespace.module_eval(child_method_code(child))
+        end
+      end
+
+      def child_method_code(child)
+        params = child.param_defs.map { |par| "#{par.name}: #{par.name}" }.join(', ')
+        METHODS.fetch(child.ancestors[1]) % {
+          call_sequence: Formatting.call_sequence(child),
+          symbol: child.symbol,
+          params: params
+        }
+      end
+    end
+  end
+end

data/lib/tlaw/endpoint.rb

@@ -1,137 +1,115 @@
+# frozen_string_literal: true
+
 require 'faraday'
 require 'faraday_middleware'
 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.
+  # Represents API endpoint.
   #
-  # Typically, you will neither create nor use endpoint descendants or
-  # instances directly:
+  # 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.
+  # * and then, containing namespace obtains `.<endpoint_name>()` method, which is (almost)
+  #   everything you need to know.
   #
   class Endpoint < APIPath
     class << self
+      # @private
+      attr_reader :processors
+
       # Inspects endpoint class prettily.
       #
       # Example:
       #
       # ```ruby
-      # some_api.some_namespace.endpoints[:my_endpoint]
+      # some_api.some_namespace.endpoint(:my_endpoint)
       # # => <SomeApi::SomeNamespace::MyEndpoint call-sequence: my_endpoint(param1, param2: nil), docs: .describe>
       # ```
+      #
+      # @return [String]
       def inspect
-        "#<#{name || '(unnamed endpoint class)'}:" \
-        " call-sequence: #{symbol}(#{param_set.to_code}); docs: .describe>"
-      end
+        return super unless is_defined?
 
-      # @private
-      def to_code
-        "def #{to_method_definition}\n" \
-        "  child(:#{symbol}, Endpoint).call({#{param_set.to_hash_code}})\n" \
-        'end'
+        Formatting::Inspect.endpoint_class(self)
       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
+      # @return [Formatting::Description]
+      def describe
+        return '' unless is_defined?
 
-      # @private
-      def parse(body)
-        if xml
-          Crack::XML.parse(body)
-        else
-          JSON.parse(body)
-        end.derp { |response| response_processor.process(response) }
+        Formatting::Describe.endpoint_class(self)
       end
 
-      private
+      protected
 
-      def query_string_params
-        param_set.all_params.values.map(&:field).map(&:to_s) -
-          Addressable::Template.new(base_url).keys
+      def setup(processors: [], **args)
+        super(**args)
+        self.processors = processors.dup
       end
+
+      attr_writer :processors
     end
 
-    attr_reader :url_template
+    # @private
+    attr_reader :url, :request_params
 
-    # Creates endpoint class (or  descendant) instance. Typically, you
-    # never use it directly.
+    # Creates endpoint class (or  descendant) instance. Typically, you never use it directly.
     #
     # Params defined in parent namespace are passed here.
     #
-    def initialize(**parent_params)
+    def initialize(parent, **params)
       super
 
-      @client = Faraday.new do |faraday|
-        faraday.use FaradayMiddleware::FollowRedirects
-        faraday.adapter Faraday.default_adapter
-      end
-      @url_template = self.class.construct_template
+      template = Addressable::Template.new(url_template)
+
+      # .normalize fixes ../ in path
+      @url = template.expand(**prepared_params).normalize.to_s.yield_self(&method(:fix_slash))
+      url_keys = template.keys.map(&:to_sym)
+      @request_params = prepared_params.reject { |k,| url_keys.include?(k) }
     end
 
-    # Does the real call to the API, with all params passed to this method
-    # and to parent namespace.
+    # 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)`.
+    # 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}"
+    # @return [Hash,Array] Parsed, flattened and post-processed response body.
+    def call
+      # TODO: we have a whole response here, so we can potentially have processors that
+      # extract some useful information (pagination, rate-limiting) from _headers_.
+      api.request(url, **request_params).body.yield_self(&method(:parse))
     end
 
-    def_delegators :object_class, :inspect, :describe
-
-    private
+    # @return [String]
+    def inspect
+      Formatting::Inspect.endpoint(self)
+    end
 
-    def full_params(**params)
-      @parent_params.merge(params.reject { |_, v| v.nil? })
+    # @private
+    def to_curl
+      separator = url.include?('?') ? '&' : '?'
+      full_url = url + separator + request_params.map(&'%s=%s'.method(:%)).join('&')
+      # FIXME: Probably unreliable (escaping), but Shellwords.escape do the wrong thing.
+      %{curl "#{full_url}"}
     end
 
-    def guard_errors!(response)
-      # TODO: follow redirects
-      return response if (200...400).cover?(response.status)
+    private
 
-      body = JSON.parse(response.body) rescue nil
-      message = body && (body['message'] || body['error'])
+    def_delegators :self_class, :url_template, :processors
 
-      fail API::Error,
-           "HTTP #{response.status} at #{response.env[:url]}" +
-           (message ? ': ' + message : '')
+    # Fix params substitution: if it was in path part, we shouldn't have escaped "/"
+    # E.g. for template `http://google.com/{foo}/bar`, and foo="some/path", Addressable would
+    # produce "http://google.com/some%2fpath/bar", but we want "http://google.com/some/path/bar"
+    def fix_slash(url)
+      url, query = url.split('?', 2)
+      url.gsub!('%2F', '/')
+      [url, query].compact.join('?')
     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('?')
+    def parse(body)
+      processors.inject(body) { |res, proc| proc.(res) }
     end
   end
 end