tlaw 0.0.2 → 0.1.0.pre

data/lib/tlaw/formatting.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module TLAW
+  # Just a bit of formatting utils.
+  module Formatting
+    # 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::Formatting::Description.new(str)
+    # # Description of endpoint:
+    # # It has params:...
+    # ```
+    #
+    # TLAW uses it when responds to {Namespace.describe}/{Endpoint.describe}.
+    #
+    class Description < String
+      alias inspect to_s
+
+      def initialize(str)
+        super(str.to_s.gsub(/ +\n/, "\n"))
+      end
+    end
+
+    module_function
+
+    # @private
+    def call_sequence(klass)
+      params = params_to_ruby(klass.param_defs)
+      name = klass < API ? "#{klass.name}.new" : klass.symbol.to_s
+      params.empty? ? name : "#{name}(#{params})"
+    end
+
+    # @private
+    def params_to_ruby(params) # rubocop:disable Metrics/AbcSize
+      key, arg = params.partition(&:keyword?)
+      req_arg, opt_arg = arg.partition(&:required?)
+      req_key, opt_key = key.partition(&:required?)
+
+      # FIXME: default.inspect will fail with, say, Time
+      [
+        *req_arg.map { |p| p.name.to_s },
+        *opt_arg.map { |p| "#{p.name}=#{p.default.inspect}" },
+        *req_key.map { |p| "#{p.name}:" },
+        *opt_key.map { |p| "#{p.name}: #{p.default.inspect}" }
+      ].join(', ')
+    end
+  end
+end
+
+require_relative 'formatting/inspect'
+require_relative 'formatting/describe'

data/lib/tlaw/formatting/describe.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module TLAW
+  module Formatting
+    # @private
+    module Describe
+      class << self
+        def endpoint_class(klass)
+          [
+            Formatting.call_sequence(klass),
+            klass.description&.yield_self { |desc| "\n" + indent(desc, '  ') },
+            klass.docs_link&.yield_self(&"\n  Docs: %s".method(:%)),
+            param_defs(klass.param_defs)
+          ].compact.join("\n").yield_self(&Description.method(:new))
+        end
+
+        def namespace_class(klass)
+          [
+            endpoint_class(klass),
+            nested(klass.namespaces, 'Namespaces'),
+            nested(klass.endpoints, 'Endpoints')
+          ].join.yield_self(&Description.method(:new))
+        end
+
+        private
+
+        def short(klass)
+          descr = klass.description&.yield_self { |d| "\n" + indent(first_para(d), '  ') }
+          ".#{Formatting.call_sequence(klass)}#{descr}"
+        end
+
+        def nested(klasses, title)
+          return '' if klasses.empty?
+
+          "\n\n  #{title}:\n\n" +
+            klasses.map(&method(:short))
+                   .map { |cd| indent(cd, '  ') }
+                   .join("\n\n")
+        end
+
+        def param_defs(defs)
+          return nil if defs.empty?
+
+          defs
+            .map(&method(:param_def))
+            .join("\n")
+            .yield_self { |s| "\n" + indent(s, '  ') }
+        end
+
+        def param_def(param)
+          [
+            '@param',
+            param.name,
+            doc_type(param.type)&.yield_self { |t| "[#{t}]" },
+            param.description,
+            possible_values(param.type),
+            param.default&.yield_self { |d| "(default = #{d.inspect})" }
+          ].compact.join(' ').gsub(/ +\n/, "\n")
+        end
+
+        def possible_values(type)
+          return unless type.respond_to?(:possible_values)
+
+          "\n  Possible values: #{type.possible_values}"
+        end
+
+        def doc_type(type)
+          case type
+          when Param::ClassType
+            type.type.name
+          when Param::DuckType
+            "##{type.type}"
+          end
+        end
+
+        def first_para(str)
+          str.split("\n\n").first
+        end
+
+        def indent(str, indentation = '  ')
+          str.gsub(/(\A|\n)/, '\1' + indentation)
+        end
+      end
+    end
+  end
+end

data/lib/tlaw/formatting/inspect.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module TLAW
+  module Formatting
+    # @private
+    module Inspect
+      class << self
+        def endpoint(object)
+          _object(object)
+        end
+
+        def namespace(object)
+          _object(object, children_list(object.class))
+        end
+
+        def endpoint_class(klass)
+          _class(klass, 'endpoint')
+        end
+
+        def namespace_class(klass)
+          _class(klass, 'namespace', children_list(klass))
+        end
+
+        private
+
+        def children_list(namespace)
+          ns = " namespaces: #{namespace.namespaces.map(&:symbol).join(', ')};" \
+            unless namespace.namespaces.empty?
+          ep = " endpoints: #{namespace.endpoints.map(&:symbol).join(', ')};" \
+            unless namespace.endpoints.empty?
+
+          [ns, ep].compact.join
+        end
+
+        def _object(object, addition = '')
+          "#<#{object.class.name}(" +
+            object.params.map { |name, val| "#{name}: #{val.inspect}" }.join(', ') +
+            ');' +
+            addition +
+            ' docs: .describe>'
+        end
+
+        def _class(klass, type, addition = '')
+          (klass.name || "(unnamed #{type} class)") +
+            "(call-sequence: #{Formatting.call_sequence(klass)};" +
+            addition +
+            ' docs: .describe)'
+        end
+      end
+    end
+  end
+end

data/lib/tlaw/namespace.rb

@@ -1,159 +1,202 @@
+# frozen_string_literal: true
+
 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.
+  # Namespace is a grouping tool for API endpoints.
   #
-  # 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):
+  # Assuming we have this API definition:
   #
   # ```ruby
-  # class SampleAPI < TLAW::API
-  #   # namespace definition:
-  #   namespace :my_ns do
-  #     endpoint :weather
+  # class OpenWeatherMap < TLAW::API
+  #   define do
+  #     base 'http://api.openweathermap.org/data/2.5'
+  #
+  #     namespace :current, '/weather' do
+  #       endpoint :city, '?q={city}{,country_code}'
+  #     end
   #   end
   # end
+  # ```
+  #
+  # We can now use it this way:
   #
-  # # usage:
-  # api = SampleAPI.new
+  # ```ruby
+  # api = OpenWeatherMap.new
+  # api.namespaces
+  # # => [OpenWeatherMap::Current(call-sequence: current; endpoints: city; docs: .describe)]
+  # api.current
+  # # => #<OpenWeatherMap::Current(); endpoints: city; docs: .describe>
+  # #    OpenWeatherMap::Current is dynamically generated class, descendant from Namespace,
+  # #    it is inspectable and usable for future calls
   #
-  # 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
+  # api.current.describe
+  # # current
+  # #
+  # #   Endpoints:
+  # #
+  # #   .city(city=nil, country_code=nil)
+  #
+  # api.current.city('Kharkiv', 'UA')
+  # # => real API call at /weather?q=Kharkiv,UA
+  # ```
+  #
+  # Namespaces are useful for logical endpoint grouping and allow providing additional params to
+  # them. When params are defined for namespace by DSL, the call could look like this:
+  #
+  # ```ruby
+  # worldbank.countries('uk').population(2016)
+  # #         ^^^^^^^^^^^^^^            ^
+  # # namespace :countries have         |
+  # # defined country_code parameter    |
+  # #                               all namespace and endpoint params would be passed to endpoint call,
+  # #                               so real API call would probably look like ...?country=uk&year=2016
   # ```
   #
+  # See {DSL} for more details on namespaces, endpoints and params definitions.
+  #
   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
+      TRAVERSE_RESTRICTION = {
+        endpoints: Endpoint,
+        namespaces: Namespace,
+        nil => APIPath
+      }.freeze
+
+      # Traverses through all of the children (depth-first). Yields them into a block specified,
+      # or returns `Enumerator` if no block was passed.
+      #
+      # @yield [Namespace or Endpoint]
+      # @param restrict_to [Symbol] `:endpoints` or `:namespaces` to traverse only children of
+      #   specified class; if not passed, traverses all of them.
+      # @return [Enumerator, self] Enumerator is returned if no block passed.
+      def traverse(restrict_to = nil, &block)
+        return to_enum(:traverse, restrict_to) unless block_given?
+
+        klass = TRAVERSE_RESTRICTION.fetch(restrict_to)
+        children.each do |child|
+          yield child if child < klass
+          child.traverse(restrict_to, &block) if child.respond_to?(:traverse)
         end
+        self
+      end
+
+      # Returns the namespace's child of the requested name.
+      #
+      # @param name [Symbol]
+      # @param restrict_to [Class] `Namespace` or `Endpoint`
+      # @return [Array<APIPath>]
+      def child(name, restrict_to: APIPath)
+        child_index[name]
+          .tap { |child| validate_class(name, child, restrict_to) }
       end
 
-      # Lists all current namespace's nested namespaces as a hash.
+      # Lists all current namespace's nested namespaces.
       #
-      # @return [Hash{Symbol => Namespace}]
+      # @return [Array<Namespace>]
       def namespaces
-        children.select { |_k, v| v < Namespace }
+        children.grep(Namespace.singleton_class)
       end
 
-      # Lists all current namespace's endpoints as a hash.
+      # Returns the namespace's nested namespaces of the requested name.
       #
-      # @return [Hash{Symbol => Endpoint}]
+      # @param name [Symbol]
+      # @return [Namespace]
+      def namespace(name)
+        child(name, restrict_to: Namespace)
+      end
+
+      # Lists all current namespace's endpoints.
+      #
+      # @return [Array<Endpoint>]
       def endpoints
-        children.select { |_k, v| v < Endpoint }
+        children.grep(Endpoint.singleton_class)
       end
 
-      # @private
-      def to_code
-        "def #{to_method_definition}\n" \
-        "  child(:#{symbol}, Namespace, {#{param_set.to_hash_code}})\n" \
-        'end'
+      # Returns the namespace's endpoint of the requested name.
+      #
+      # @param name [Symbol]
+      # @return [Endpoint]
+      def endpoint(name)
+        child(name, restrict_to: Endpoint)
       end
 
+      # @return [String]
       def inspect
-        "#<#{name || '(unnamed namespace class)'}: " \
-        "call-sequence: #{symbol}(#{param_set.to_code});" +
-          inspect_docs
-      end
+        return super unless is_defined? || self < API
 
-      # @private
-      def inspect_docs
-        inspect_namespaces + inspect_endpoints + ' docs: .describe>'
+        Formatting::Inspect.namespace_class(self)
       end
 
-      # @private
-      def add_child(child)
-        children[child.symbol] = child
-
-        child.base_url = base_url + child.path if !child.base_url && base_url
+      # Detailed namespace documentation.
+      #
+      # @return [Formatting::Description]
+      def describe
+        return '' unless is_defined?
 
-        child.define_method_on(self)
+        Formatting::Describe.namespace_class(self)
       end
 
       # @private
-      def children
-        @children ||= {}
+      def definition
+        super.merge(children: children)
       end
 
-      # Detailed namespace documentation.
-      #
-      # See {APIPath.describe} for explanations.
-      #
-      # @return [Util::Description]
-      def describe(definition = nil)
-        super + describe_children
+      # @private
+      def children
+        child_index.values
       end
 
-      private
-
-      def inspect_namespaces
-        return '' if namespaces.empty?
-        " namespaces: #{namespaces.keys.join(', ')};"
+      # @private
+      def child_index
+        @child_index ||= {}
       end
 
-      def inspect_endpoints
-        return '' if endpoints.empty?
-        " endpoints: #{endpoints.keys.join(', ')};"
-      end
+      protected
 
-      def describe_children
-        describe_namespaces + describe_endpoints
+      def setup(children: [], **args)
+        super(**args)
+        self.children = children.dup.each { |c| c.parent = self }
       end
 
-      def describe_namespaces
-        return '' if namespaces.empty?
-
-        "\n\n  Namespaces:\n\n" + children_description(namespaces)
+      def children=(children)
+        children.each do |child|
+          child_index[child.symbol] = child
+        end
       end
 
-      def describe_endpoints
-        return '' if endpoints.empty?
+      private
 
-        "\n\n  Endpoints:\n\n" + children_description(endpoints)
-      end
+      def validate_class(sym, child_class, expected_class)
+        return if child_class&.<(expected_class)
 
-      def children_description(children)
-        children.values.map(&:describe_short)
-                .map { |cd| cd.indent('  ') }.join("\n\n")
+        kind = expected_class.name.split('::').last.downcase.sub('apipath', 'path')
+        fail ArgumentError,
+             "Unregistered #{kind}: #{sym}"
       end
     end
 
-    def_delegators :object_class,
-                   :symbol,
-                   :children, :namespaces, :endpoints,
-                   :param_set, :describe_short
+    def_delegators :self_class, :symbol,
+                   :namespaces, :endpoints,
+                   :namespace, :endpoint
 
+    # @return [String]
     def inspect
-      "#<#{symbol}(#{param_set.to_hash_code(@parent_params)})" +
-        self.class.inspect_docs
+      Formatting::Inspect.namespace(self)
     end
 
-    def describe
-      self.class
-          .describe("#{symbol}(#{param_set.to_hash_code(@parent_params)})")
+    # Returns `curl` string to call specified endpoit with specified params from command line.
+    #
+    # @param endpoint [Symbol] Endpoint's name
+    # @param params [Hash] Endpoint's argument
+    # @return [String]
+    def curl(endpoint, **params)
+      child(endpoint, Endpoint, **params).to_curl
     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))
-        }
+    def child(sym, expected_class, **params)
+      self.class.child(sym, restrict_to: expected_class).new(self, **params)
     end
   end
 end