tlaw 0.0.1

data/lib/tlaw.rb

@@ -0,0 +1,67 @@
+require 'open-uri'
+require 'json'
+require 'addressable'
+
+# Let no one know! But they in Ruby committee just too long to add
+# something like this to the language.
+#
+# See also https://bugs.ruby-lang.org/issues/12760
+#
+# @private
+class Object
+  def derp
+    yield self
+  end
+end
+
+# TLAW is a framework for creating API wrappers for get-only APIs (like
+# weather, geonames and so on) or subsets of APIs (like getting data from
+# Twitter).
+#
+# Short example:
+#
+# ```ruby
+# # Definition:
+# class OpenWeatherMap < TLAW::API
+#   param :appid, required: true
+#
+#   namespace :current, '/weather' do
+#     endpoint :city, '?q={city}{,country_code}' do
+#       param :city, required: true
+#     end
+#   end
+# end
+#
+# # Usage:
+# api = OpenWeatherMap.new(appid: '<yourappid>')
+# api.current.weather('Kharkiv')
+# # => {"weather.main"=>"Clear",
+# #  "weather.description"=>"clear sky",
+# #  "main.temp"=>8,
+# #  "main.pressure"=>1016,
+# #  "main.humidity"=>81,
+# #  "dt"=>2016-09-19 08:30:00 +0300,
+# #  ...}
+#
+# ```
+#
+# Refer to [README](./file/README.md) for reasoning about why you need it and links to
+# more detailed demos, or start reading YARD docs from {API} and {DSL}
+# modules.
+module TLAW
+end
+
+require_relative 'tlaw/util'
+require_relative 'tlaw/data_table'
+
+require_relative 'tlaw/param'
+require_relative 'tlaw/param_set'
+
+require_relative 'tlaw/api_path'
+require_relative 'tlaw/endpoint'
+require_relative 'tlaw/namespace'
+require_relative 'tlaw/api'
+
+require_relative 'tlaw/response_processor'
+
+require_relative 'tlaw/dsl'

data/lib/tlaw/api.rb

@@ -0,0 +1,58 @@
+module TLAW
+  # API is just a top-level {Namespace}.
+  #
+  # Basically, you start creating your endpoint by descending from API
+  # and defining namespaces and endpoints through a {DSL} like this:
+  #
+  # ```ruby
+  # class MyCoolAPI < TLAW::API
+  #   define do
+  #     base 'http://api.mycool.com'
+  #
+  #     namespace :awesome do
+  #       # ...and so on
+  #     end
+  #   end
+  # end
+  # ```
+  #
+  # And then, you use it:
+  #
+  # ```ruby
+  # api = MyCoolAPI.new
+  # api.awesome.cool(param: 'value')
+  # ```
+  #
+  # See {DSL} for explanation of API definition, {Namespace} for explanation
+  # of possible usages and {Endpoint} for real calls performing.
+  #
+  class API < Namespace
+    # Thrown when there are an error during call. Contains real URL which
+    # was called at the time of an error.
+    class Error < RuntimeError
+    end
+
+    class << self
+      # Runs the {DSL} inside your API wrapper class.
+      def define(&block)
+        DSL::APIWrapper.new(self).define(&block)
+      end
+
+      # Returns detailed description of an API, like this:
+      #
+      # ```ruby
+      # MyCoolAPI.describe
+      # # MyCoolAPI.new()
+      # #   This is cool API.
+      # #
+      # #   Namespaces:
+      # #   .awesome()
+      # #     This is awesome.
+      # ```
+      #
+      def describe(*)
+        super.sub(/\A./, '')
+      end
+    end
+  end
+end

data/lib/tlaw/api_path.rb

@@ -0,0 +1,137 @@
+require 'forwardable'
+
+module TLAW
+  # Base class for all API pathes: entire API, namespaces and endpoints.
+  # Allows to define params and post-processors on any level.
+  #
+  class APIPath
+    class << self
+      # @private
+      attr_accessor :base_url, :path, :xml, :docs_link
+
+      # @private
+      def symbol
+        # FIXME: the second part is necessary only for describes,
+        #   and probably should not be here.
+        @symbol || (name && "#{name}.new")
+      end
+
+      # @private
+      CLASS_NAMES = {
+        :[] => 'Element'
+      }.freeze
+
+      # @private
+      def class_name
+        # TODO:
+        # * validate if it is classifiable
+        # * provide additional option for non-default class name
+        CLASS_NAMES[symbol] || Util.camelize(symbol.to_s)
+      end
+
+      # @private
+      def description=(descr)
+        @description = Util::Description.new(descr)
+      end
+
+      # @private
+      def description
+        return unless @description || @docs_link
+
+        Util::Description.new(
+          [@description, ("Docs: #{@docs_link}" if @docs_link)]
+            .compact.join("\n\n")
+        )
+      end
+
+      # @private
+      def inherit(namespace, **attrs)
+        Class.new(self).tap do |subclass|
+          attrs.each { |a, v| subclass.send("#{a}=", v) }
+          namespace.const_set(subclass.class_name, subclass)
+        end
+      end
+
+      # @private
+      def params_from_path!
+        Addressable::Template.new(path).keys.each do |key|
+          param_set.add key.to_sym, keyword: false
+        end
+      end
+
+      # @private
+      def setup_parents(parent)
+        param_set.parent = parent.param_set
+        response_processor.parent = parent.response_processor
+      end
+
+      # @private
+      def symbol=(sym)
+        @symbol = sym
+        @path ||= "/#{sym}"
+      end
+
+      # @return [ParamSet]
+      def param_set
+        @param_set ||= ParamSet.new
+      end
+
+      # @private
+      def response_processor
+        @response_processor ||= ResponseProcessor.new
+      end
+
+      # @private
+      def to_method_definition
+        "#{symbol}(#{param_set.to_code})"
+      end
+
+      # Redefined on descendants, it just allows you to do `api.namespace.describe`
+      # or `api.namespace1.namespace2.endpoints[:my_endpoint].describe`
+      # and have reasonable useful description printed.
+      #
+      # @return [Util::Description] It is just description string but with
+      #   redefined `#inspect` to be pretty-printed in console.
+      def describe(definition = nil)
+        Util::Description.new(
+          ".#{definition || to_method_definition}" +
+            (description ? "\n" + description.indent('  ') + "\n" : '') +
+            (param_set.empty? ? '' : "\n" + param_set.describe.indent('  '))
+        )
+      end
+
+      # @private
+      def describe_short
+        Util::Description.new(
+          ".#{to_method_definition}" +
+            (description ? "\n" + description_first_para.indent('  ') : '')
+        )
+      end
+
+      # @private
+      def define_method_on(host)
+        file, line = method(:to_code).source_location
+        # line + 1 is where real definition, theoretically, starts
+        host.module_eval(to_code, file, line + 1)
+      end
+
+      private
+
+      def description_first_para
+        description.split("\n\n").first
+      end
+    end
+
+    extend Forwardable
+
+    def initialize(**parent_params)
+      @parent_params = parent_params
+    end
+
+    private
+
+    def object_class
+      self.class
+    end
+  end
+end

data/lib/tlaw/data_table.rb

@@ -0,0 +1,116 @@
+module TLAW
+  # Basically, just a 2-d array with column names. Or you can think of
+  # it as an array of hashes. Or loose DataFrame implementation.
+  #
+  # Just like this:
+  #
+  # ```ruby
+  # tbl = DataTable.new([
+  #   {id: 1, name: 'Mike', salary: 1000},
+  #   {id: 2, name: 'Doris', salary: 900},
+  #   {id: 3, name: 'Angie', salary: 1200}
+  # ])
+  # # => #<TLAW::DataTable[id, name, salary] x 3>
+  # tbl.count
+  # # => 3
+  # tbl.keys
+  # # => ["id", "name", "salary"]
+  # tbl[0]
+  # # => {"id"=>1, "name"=>"Mike", "salary"=>1000}
+  # tbl['salary']
+  # # => [1000, 900, 1200]
+  # ```
+  #
+  # Basically, that's it. Every array of hashes in TLAW response will be
+  # converted into corresponding `DataTable`.
+  #
+  class DataTable < Array
+    def self.from_columns(column_names, columns)
+      from_rows(column_names, columns.transpose)
+    end
+
+    def self.from_rows(column_names, rows)
+      new rows.map { |r| column_names.zip(r).to_h }
+    end
+
+    # Creates DataTable from array of hashes.
+    #
+    # Note, that all hash keys are stringified, and all hashes are expanded
+    # to have same set of keys.
+    #
+    # @param hashes [Array<Hash>]
+    def initialize(hashes)
+      hashes = hashes.each_with_index.map { |h, i|
+        h.is_a?(Hash) or
+          fail ArgumentError,
+               "All rows are expected to be hashes, row #{i} is #{h.class}"
+
+        h.map { |k, v| [k.to_s, v] }.to_h
+      }
+      empty = hashes.map(&:keys).flatten.uniq.map { |k| [k, nil] }.to_h
+      hashes = hashes.map { |h| empty.merge(h) }
+      super(hashes)
+    end
+
+    # All column names.
+    #
+    # @return [Array<String>]
+    def keys
+      empty? ? [] : first.keys
+    end
+
+    # Allows access to one column or row.
+    #
+    # @overload [](index)
+    #   Returns one row from a DataTable.
+    #
+    #   @param index [Integer] Row number
+    #   @return [Hash] Row as a hash
+    #
+    # @overload [](column_name)
+    #   Returns one column from a DataTable.
+    #
+    #   @param column_name [String] Name of column
+    #   @return [Array] Column as an array of all values in it
+    #
+    def [](index_or_column)
+      case index_or_column
+      when Integer
+        super
+      when String, Symbol
+        map { |h| h[index_or_column.to_s] }
+      else
+        fail ArgumentError,
+             'Expected integer or string/symbol index' \
+             ", got #{index_or_column.class}"
+      end
+    end
+
+    # Slice of a DataTable with only specified columns left.
+    #
+    # @param names [Array<String>] What columns to leave in a DataTable
+    # @return [DataTable]
+    def columns(*names)
+      names.map!(&:to_s)
+      DataTable.new(map { |h| names.map { |n| [n, h[n]] }.to_h })
+    end
+
+    # Represents DataTable as a `column name => all values in columns`
+    # hash.
+    #
+    # @return [Hash{String => Array}]
+    def to_h
+      keys.map { |k| [k, map { |h| h[k] }] }.to_h
+    end
+
+    # @private
+    def inspect
+      "#<#{self.class.name}[#{keys.join(', ')}] x #{size}>"
+    end
+
+    # @private
+    def pretty_print(pp)
+      pp.text("#<#{self.class.name}[#{keys.join(', ')}] x #{size}>")
+    end
+  end
+end

data/lib/tlaw/dsl.rb

@@ -0,0 +1,511 @@
+module TLAW
+  # This module is core of a TLAW API definition. It works like this:
+  #
+  # ```ruby
+  # class MyAPI < TLAW::API
+  #   define do # here starts what DSL does
+  #     namespace :ns do
+  #
+  #       endpoint :es do
+  #         param :param1, Integer, default: 1
+  #       end
+  #     end
+  #   end
+  # end
+  # ```
+  #
+  # Methods of current namespace documentation describe everything you
+  # can use inside `define` blocks. Actual structure of things is a bit
+  # more complicated (relate to lib/tlaw/dsl.rb if you wish), but current
+  # documentation structure considered to be most informative.
+  #
+  module DSL
+    # @!method base(url)
+    #   Allows to set entire API base URL, all endpoints and namespaces
+    #   pathes are calculated relative to it.
+    #
+    #   **Works for:** API
+    #
+    #   @param url [String]
+
+    # @!method desc(text)
+    #   Allows to set description string for your API object. It can
+    #   be multiline, and TLAW will automatically un-indent excessive
+    #   indentations:
+    #
+    #   ```ruby
+    #       # ...several levels of indents while you create a definition
+    #       desc %Q{
+    #         This is some endpoint.
+    #         And it works!
+    #       }
+    #
+    #   # ...but when you are using it...
+    #   p my_api.endpoints[:endpoint].describe
+    #   # This is some endpoint.
+    #   # And it works!
+    #   # ....
+    #   ```
+    #
+    #   **Works for:** API, namespace, endpoint
+    #
+    #   @param text [String]
+
+    # @!method docs(link)
+    #   Allows to add link to documentation as a separate line to
+    #   object description. Just to be semantic :)
+    #
+    #   ```ruby
+    #   # you do something like
+    #   desc "That's my endpoint"
+    #
+    #   docs "http://docs.example.com/my/endpoint"
+    #
+    #   # ...and then somewhere...
+    #   p my_api.endpoints[:endpoint].describe
+    #   # That is my endpoint.
+    #   #
+    #   # Docs: http://docs.example.com/my/endpoint
+    #   # ....
+    #   ```
+    #
+    #   **Works for:** API, namespace, endpoint
+    #
+    #   @param link [String]
+
+    # @!method param(name, type = nil, keyword: true, required: false, **opts)
+    #   Defines parameter for current API (global), namespace or endpoint.
+    #
+    #   Param defnition defines several things:
+    #
+    #   * how method definition to call this namespace/endpoint would
+    #     look like: whether the parameter is keyword or regular argument,
+    #     whether it is required and what is default value otherwise;
+    #   * how parameter is processed: converted and validated from passed
+    #     value;
+    #   * how param is sent to target API: how it will be called in
+    #     the query string and formatted on call.
+    #
+    #   Note also those things about params:
+    #
+    #   * as described in {#namespace} and {#endpoint}, setting path template
+    #     will implicitly set params. You can rewrite this on implicit
+    #     param call, for ex:
+    #
+    #   ```ruby
+    #   endpoint :foo, '/foo/{bar}'
+    #   # call-sequence would be foo(bar = nil)
+    #
+    #   # But you can make it back keyword:
+    #   endpoint :foo, '/foo/{bar}' do
+    #     param :bar, keyword: true, default: 'test'
+    #   end
+    #   # call-sequence now is foo(bar: 'test')
+    #
+    #   # Or make it strictly required
+    #   endpoint :foo, '/foo/{bar}/{baz}' do
+    #     param :bar, required: true
+    #     param :baz, keyword: true, required: true
+    #   end
+    #   # call-sequence now is foo(bar, baz:)
+    #   ```
+    #
+    #   * param of outer namespace are passed to API on call from inner
+    #     namespaces and endpoints, for ex:
+    #
+    #   ```ruby
+    #   namespace :city do
+    #     param :city_name
+    #
+    #     namespace :population do
+    #       endpoint :by_year, '/year/{year}'
+    #     end
+    #   end
+    #
+    #   # real call:
+    #   api.city('London').population.by_year(2015)
+    #   # Will get http://api.example.com/city/year/2015?city_name=London
+    #   ```
+    #
+    #   **Works for:** API, namespace, endpoint
+    #
+    #   @param name [Symbol] Parameter name
+    #   @param type [Class, Symbol] Expected parameter type. Could by
+    #     some class (then parameter would be checked for being instance
+    #     of this class or it would be `ArgumentError`), or duck type
+    #     (method name that parameter value should respond to).
+    #   @param keyword [true, false] Whether the param will go as a
+    #     keyword param to method definition.
+    #   @param required [true, false] Whether this param is required.
+    #     It will be considered on method definition.
+    #   @param opts [Hash] Options
+    #   @option opts [Symbol] :field What the field would be called in
+    #     API query string (it would be `name` by default).
+    #   @option opts [#to_proc] :format How to format this option before
+    #     including into URL. By default, it is just `.to_s`.
+    #   @option opts [String] :desc Param description. You could do it
+    #     multiline and with indents, like {#desc}.
+    #   @option opts :default Default value for this param. Would be
+    #     rendered in method definition and then passed to target API
+    #     _(TODO: in future, there also would be "invisible" params,
+    #     that are just passed to target, always the same, as well as
+    #     params that aren't passed at all if user gave default value.)_
+    #   @option opts [Hash, Array] :enum Whether parameter only accepts
+    #     enumerated values. Two forms are accepted:
+    #
+    #     ```ruby
+    #     # array form
+    #     param :units, enum: %i[us metric britain]
+    #     # parameter accepts only :us, :metric, :britain values, and
+    #     # passes them to target API as is
+    #
+    #     # hash "accepted => passed" form
+    #     param :compact, enum: {true => 'gzip', false => nil}
+    #     # parameter accepts true or false, on true passes "compact=gzip",
+    #     # on false passes nothing.
+    #     ```
+
+    # @!method namespace(name, path = nil, &block)
+    #   Defines new namespace or updates existing one.
+    #
+    #   {Namespace} has two roles:
+    #
+    #   * on Ruby API, defines how you access to the final endpoint,
+    #     like `api.namespace1.namespace2(some_param).endpoint(...)`
+    #   * on calling API, it adds its path to entire URL.
+    #
+    #   **NB:** If you call `namespace(:something)` and it was already defined,
+    #   current definition will be added to existing one (but it can't
+    #   change path of existing one, which is reasonable).
+    #
+    #   **Works for:** API, namespace
+    #
+    #   @param name [Symbol] Name of the method by which namespace would
+    #     be accessible.
+    #   @param path [String] Path to add to API inside this namespace.
+    #     When not provided, considered to be `/<name>`. When provided,
+    #     taken literally (no slashes or other symbols added). Note, that
+    #     you can use `/../` in path, redesigning someone else's APIs on
+    #     the fly. Also, you can use [RFC 6570](https://www.rfc-editor.org/rfc/rfc6570.txt)
+    #     URL templates to mark params going straightly into URI.
+    #
+    #     Some examples:
+    #
+    #     ```ruby
+    #     # assuming API base url is http://api.example.com
+    #
+    #     namespace :foo
+    #     # method would be foo(), API URL would be http://api.example.com/foo
+    #
+    #     namespace :bar, '/foo/bar'
+    #     # metod would be bar(), API URL http://api.example.com/foo/bar
+    #
+    #     namespace :baz, ''
+    #     # method baz(), API URL same as base: useful for gathering into
+    #     # quazi-namespace from several unrelated endpoints.
+    #
+    #     namespace :quux, '/foo/quux/{id}'
+    #     # method quux(id = nil), API URL http://api.example.com/foo/quux/123
+    #     # ...where 123 is what you've passed as id
+    #     ```
+    #   @param block Definition of current namespace params, and
+    #     namespaces and endpoints inside current.
+    #     Note that by defining params inside this block, you can change
+    #     namespace's method call sequence.
+    #
+    #     For example:
+    #
+    #     ```ruby
+    #     namespace :foo
+    #     # call-sequence: foo()
+    #
+    #     namespace :foo do
+    #       param :bar
+    #     end
+    #     # call-sequence: foo(bar: nil)
+    #
+    #     namespace :foo do
+    #       param :bar, required: true, keyword: false
+    #       param :baz, required: true
+    #     end
+    #     # call-sequence: foo(bar, baz:)
+    #     ```
+    #
+    #     ...and so on. See also {#param} for understanding what you
+    #     can change here.
+    #
+
+    # @!method endpoint(name, path = nil, **opts, &block)
+    #   Defines new endpoint or updates existing one.
+    #
+    #   {Endpoint} is the thing doing the real work: providing Ruby API
+    #   method to really call target API.
+    #
+    #   **NB:** If you call `endpoint(:something)` and it was already defined,
+    #   current definition will be added to existing one (but it can't
+    #   change path of existing one, which is reasonable).
+    #
+    #   **Works for:** API, namespace
+    #
+    #   @param name [Symbol] Name of the method by which endpoint would
+    #     be accessible.
+    #   @param path [String] Path to call API from this endpoint.
+    #     When not provided, considered to be `/<name>`. When provided,
+    #     taken literally (no slashes or other symbols added). Note, that
+    #     you can use `/../` in path, redesigning someone else's APIs on
+    #     the fly. Also, you can use [RFC 6570](https://www.rfc-editor.org/rfc/rfc6570.txt)
+    #     URL templates to mark params going straightly into URI.
+    #
+    #     Look at {#namespace} for examples, idea is the same.
+    #
+    #   @param opts [Hash] Some options, currently only `:xml`.
+    #   @option opts [true, false] :xml Whether endpoint's response should
+    #     be parsed as XML (JSON otherwise & by default). Parsing in this
+    #     case is performed with [crack](https://github.com/jnunemaker/crack),
+    #     producing the hash, to which all other rules of post-processing
+    #     are applied.
+    #   @param block Definition of endpoint's params and docs.
+    #     Note that by defining params inside this block, you can change
+    #     endpoints's method call sequence.
+    #
+    #     For example:
+    #
+    #     ```ruby
+    #     endpoint :foo
+    #     # call-sequence: foo()
+    #
+    #     endpoint :foo do
+    #       param :bar
+    #     end
+    #     # call-sequence: foo(bar: nil)
+    #
+    #     endpoint :foo do
+    #       param :bar, required: true, keyword: false
+    #       param :baz, required: true
+    #     end
+    #     # call-sequence: foo(bar, baz:)
+    #     ```
+    #
+    #     ...and so on. See also {#param} for understanding what you
+    #     can change here.
+
+    # @!method post_process(key = nil, &block)
+    #   Sets post-processors for response.
+    #
+    #   There are also {#post_process_replace} (for replacing entire
+    #   response with something else) and {#post_process_items} (for
+    #   post-processing each item of sub-array).
+    #
+    #   Notes:
+    #
+    #   * you can set any number of post-processors of any kind, and they
+    #     will be applied in exactly the same order they are set;
+    #   * you can set post-processors in parent namespace (or for entire
+    #     API), in this case post-processors of _outer_ namespace are
+    #     always applied before inner ones. That allow you to define some
+    #     generic parsing/rewriting on API level, then more specific
+    #     key postprocessors on endpoints;
+    #   * hashes are flattened again after _each_ post-processor, so if
+    #     for some `key` you'll return `{count: 1, continue: false}`,
+    #     response hash will immediately have
+    #     `{"key.count" => 1, "key.continue" => false}`.
+    #
+    #   @overload post_process(&block)
+    #     Sets post-processor for whole response. Note, that in this case
+    #     _return_ value of block is ignored, it is expected that your
+    #     block will receive response and modify it inplace, like this:
+    #
+    #     ```ruby
+    #     post_process do |response|
+    #       response['coord'] = Geo::Coord.new(response['lat'], response['lng'])
+    #     end
+    #     ```
+    #     If you need to replace entire response with something else,
+    #     see {#post_process_replace}
+    #
+    #   @overload post_process(key, &block)
+    #     Sets post-processor for one response key. Post-processor is
+    #     called only if key exists in the response, and value by this
+    #     key is replaced with post-processor's response.
+    #
+    #     Note, that if `block` returns `nil`, key will be removed completely.
+    #
+    #     Usage:
+    #
+    #     ```ruby
+    #     post_process('date') { |val| Date.parse(val) }
+    #     # or, btw, just
+    #     post_process('date', &Date.method(:parse))
+    #     ```
+    #
+    #     @param key [String]
+
+    # @!method post_process_items(key, &block)
+    #   Sets post-processors for each items of array, being at `key` (if
+    #   the key is present in response, and if its value is array of
+    #   hashes).
+    #
+    #   Inside `block` you can use {#post_process} method as described
+    #   above (but all of its actions will be related only to current
+    #   item of array).
+    #
+    #   Example:
+    #
+    #   Considering API response like:
+    #
+    #   ```json
+    #   {
+    #     "meta": {"count": 100},
+    #     "data": [
+    #       {"timestamp": "2016-05-01", "value": "10", "dummy": "foo"},
+    #       {"timestamp": "2016-05-02", "value": "13", "dummy": "bar"}
+    #     ]
+    #   }
+    #   ```
+    #   ...you can define postprocessing like this:
+    #
+    #   ```ruby
+    #   post_process_items 'data' do
+    #     post_process 'timestamp', &Date.method(:parse)
+    #     post_process 'value', &:to_i
+    #     post_process('dummy'){nil} # will be removed
+    #   end
+    #   ```
+    #
+    #   See also {#post_process} for some generic explanation of post-processing.
+    #
+    #   @param key [String]
+
+    # @!method post_process_replace(&block)
+    #   Just like {#post_process} for entire response, but _replaces_
+    #   it with what block returns.
+    #
+    #   Real-life usage: WorldBank API typically returns responses this
+    #   way:
+    #
+    #   ```json
+    #   [
+    #      {"count": 100, "page": 1},
+    #      {"some_data_variable": [{}, {}, {}]}
+    #   ]
+    #   ```
+    #   ...e.g. metadata and real response as two items in array, not
+    #   two keys in hash. We can easily fix this:
+    #
+    #   ```ruby
+    #   post_process_replace do |response|
+    #     {meta: response.first, data: response.last}
+    #   end
+    #   ```
+    #
+    #   See also {#post_process} for some generic explanation of post-processing.
+
+    # @private
+    class BaseWrapper
+      def initialize(object)
+        @object = object
+      end
+
+      def define(&block)
+        instance_eval(&block)
+      end
+
+      def description(text)
+        # first, remove spaces at a beginning of each line
+        # then, remove empty lines before and after docs block
+        @object.description =
+          text
+          .gsub(/^[ \t]+/, '')
+          .gsub(/\A\n|\n\s*\Z/, '')
+      end
+
+      alias_method :desc, :description
+
+      def docs(link)
+        @object.docs_link = link
+      end
+
+      def param(name, type = nil, **opts)
+        @object.param_set.add(name, **opts.merge(type: type))
+      end
+
+      def post_process(key = nil, &block)
+        @object.response_processor.add_post_processor(key, &block)
+      end
+
+      def post_process_replace(&block)
+        @object.response_processor.add_replacer(&block)
+      end
+
+      class PostProcessProxy
+        def initialize(parent_key, parent)
+          @parent_key = parent_key
+          @parent = parent
+        end
+
+        def post_process(key = nil, &block)
+          @parent.add_item_post_processor(@parent_key, key, &block)
+        end
+      end
+
+      def post_process_items(key, &block)
+        PostProcessProxy
+          .new(key, @object.response_processor)
+          .instance_eval(&block)
+      end
+    end
+
+    # @private
+    class EndpointWrapper < BaseWrapper
+    end
+
+    # @private
+    class NamespaceWrapper < BaseWrapper
+      def endpoint(name, path = nil, **opts, &block)
+        update_existing(Endpoint, name, path, **opts, &block) ||
+          add_child(Endpoint, name, path: path || "/#{name}", **opts, &block)
+      end
+
+      def namespace(name, path = nil, &block)
+        update_existing(Namespace, name, path, &block) ||
+          add_child(Namespace, name, path: path || "/#{name}", &block)
+      end
+
+      private
+
+      WRAPPERS = {
+        Endpoint => EndpointWrapper,
+        Namespace => NamespaceWrapper
+      }.freeze
+
+      def update_existing(child_class, name, path, **opts, &block)
+        existing = @object.children[name] or return nil
+        existing < child_class or
+          fail ArgumentError, "#{name} is already defined as #{child_class == Endpoint ? 'namespace' : 'endpoint'}, you can't redefine it as #{child_class}"
+
+        !path && opts.empty? or
+          fail ArgumentError, "#{child_class} is already defined, you can't change its path or options"
+
+        WRAPPERS[child_class].new(existing).define(&block) if block
+      end
+
+      def add_child(child_class, name, **opts, &block)
+        @object.add_child(
+          child_class.inherit(@object, symbol: name, **opts)
+          .tap { |c| c.setup_parents(@object) }
+          .tap(&:params_from_path!)
+          .tap { |c|
+            WRAPPERS[child_class].new(c).define(&block) if block
+          }
+        )
+      end
+    end
+
+    # @private
+    class APIWrapper < NamespaceWrapper
+      def base(url)
+        @object.base_url = url
+      end
+    end
+  end
+end