tlaw 0.0.2 → 0.1.0.pre

data/lib/tlaw/api_path.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'forwardable'
 
 module TLAW
@@ -7,130 +9,127 @@ module TLAW
   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
-
+      attr_reader :symbol, :parent, :path, :param_defs, :description, :docs_link
       # @private
-      CLASS_NAMES = {
-        :[] => 'Element'
-      }.freeze
+      attr_writer :parent
 
       # @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)
+      def define(**args)
+        Class.new(self).tap do |subclass|
+          subclass.setup(**args)
+        end
       end
 
       # @private
-      def description=(descr)
-        @description = Util::Description.new(descr)
+      def definition
+        {
+          symbol: symbol,
+          path: path,
+          description: description,
+          docs_link: docs_link,
+          params: param_defs&.map { |p| [p.name, p.to_h] }.to_h || {}
+        }
       end
 
       # @private
-      def description
-        return unless @description || @docs_link
-
-        Util::Description.new(
-          [@description, ("Docs: #{@docs_link}" if @docs_link)]
-            .compact.join("\n\n")
-        )
+      def is_defined? # rubocop:disable Naming/PredicateName
+        !symbol.nil?
       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
+      def full_param_defs
+        [*parent&.full_param_defs, *param_defs]
       end
 
       # @private
-      def params_from_path!
-        Addressable::Template.new(path).keys.each do |key|
-          param_set.add key.to_sym, keyword: false
-        end
+      def required_param_defs
+        param_defs.select(&:required?)
       end
 
       # @private
-      def setup_parents(parent)
-        param_set.parent = parent.param_set
-        response_processor.parent = parent.response_processor
+      def url_template
+        parent&.url_template or fail "Orphan path #{path}, can't determine full URL"
+        [parent.url_template, path].join
       end
 
-      # @private
-      def symbol=(sym)
-        @symbol = sym
-        @path ||= "/#{sym}"
+      # @return [Array<Class>]
+      def parents
+        Util.parents(self)
       end
 
-      # @return [ParamSet]
-      def param_set
-        @param_set ||= ParamSet.new
-      end
+      protected
 
-      # @private
-      def response_processor
-        @response_processor ||= ResponseProcessor.new
+      def setup(symbol:, path:, param_defs: [], description: nil, docs_link: nil)
+        self.symbol = symbol
+        self.path = path
+        self.param_defs = param_defs
+        self.description = description
+        self.param_defs = param_defs
+        self.docs_link = docs_link
       end
 
-      # @private
-      def to_method_definition
-        "#{symbol}(#{param_set.to_code})"
-      end
+      attr_writer :symbol, :param_defs, :path, :description, :xml, :docs_link
+    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
+    extend Forwardable
 
-      # @private
-      def describe_short
-        Util::Description.new(
-          ".#{to_method_definition}" +
-            (description ? "\n" + description_first_para.indent('  ') : '')
-        )
-      end
+    # @private
+    attr_reader :parent, :params
 
-      # @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
+    def initialize(parent, **params)
+      @parent = parent
+      @params = params
+    end
+
+    # @return [Array<APIPath>]
+    def parents
+      Util.parents(self)
+    end
 
-      private
+    def_delegators :self_class, :describe
 
-      def description_first_para
-        description.split("\n\n").first
-      end
+    # @private
+    # Could've been protected, but it hurts testability :shrug:
+    def prepared_params
+      (parent&.prepared_params || {}).merge(prepare_params(@params))
     end
 
-    extend Forwardable
+    protected
 
-    def initialize(**parent_params)
-      @parent_params = parent_params
+    def api
+      is_a?(API) ? self : parent&.api
     end
 
     private
 
-    def object_class
+    def_delegators :self_class, :param_defs, :required_param_defs
+
+    def prepare_params(arguments)
+      guard_missing!(arguments)
+      guard_unknown!(arguments)
+
+      param_defs
+        .map { |dfn| [dfn, arguments[dfn.name]] }
+        .reject { |_, v| v.nil? }
+        .map { |dfn, arg| dfn.(arg) }
+        .inject(&:merge)
+        &.transform_keys(&:to_sym) || {}
+    end
+
+    def guard_unknown!(arguments)
+      arguments.keys.-(param_defs.map(&:name)).yield_self { |unknown|
+        unknown.empty? or fail ArgumentError, "Unknown arguments: #{unknown.join(', ')}"
+      }
+    end
+
+    def guard_missing!(arguments)
+      required_param_defs.map(&:name).-(arguments.keys).yield_self { |missing|
+        missing.empty? or fail ArgumentError, "Missing arguments: #{missing.join(', ')}"
+      }
+    end
+
+    # For def_delegators
+    def self_class
       self.class
     end
   end

data/lib/tlaw/data_table.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 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.
@@ -40,15 +42,11 @@ module TLAW
     #
     # @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
-      }
+      hashes = hashes.each_with_index(&method(:enforce_hash!))
+                     .map { |h| h.transform_keys(&:to_s) }
       empty = hashes.map(&:keys).flatten.uniq.map { |k| [k, nil] }.to_h
-      hashes = hashes.map { |h| empty.merge(h) }
+      hashes = hashes.map(&empty.method(:merge))
+
       super(hashes)
     end
 
@@ -109,8 +107,15 @@ module TLAW
     end
 
     # @private
-    def pretty_print(pp)
-      pp.text("#<#{self.class.name}[#{keys.join(', ')}] x #{size}>")
+    def pretty_print(printer)
+      printer.text("#<#{self.class.name}[#{keys.join(', ')}] x #{size}>")
+    end
+
+    private
+
+    def enforce_hash!(val, idx)
+      val.is_a?(Hash) or fail ArgumentError,
+                              "All rows are expected to be hashes, row #{idx} is #{val.class}"
     end
   end
 end

data/lib/tlaw/dsl.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module TLAW
   # This module is core of a TLAW API definition. It works like this:
   #
@@ -21,17 +23,15 @@ module TLAW
   #
   module DSL
     # @!method base(url)
-    #   Allows to set entire API base URL, all endpoints and namespaces
-    #   pathes are calculated relative to it.
+    #   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:
+    #   Set description string for API object (namespace or endpoint). It can be multiline, and
+    #   TLAW will automatically un-indent excessive indentations:
     #
     #   ```ruby
     #       # ...several levels of indents while you create a definition
@@ -41,7 +41,7 @@ module TLAW
     #       }
     #
     #   # ...but when you are using it...
-    #   p my_api.endpoints[:endpoint].describe
+    #   p my_api.endpoint(:endpoint).describe
     #   # This is some endpoint.
     #   # And it works!
     #   # ....
@@ -52,8 +52,7 @@ module TLAW
     #   @param text [String]
 
     # @!method docs(link)
-    #   Allows to add link to documentation as a separate line to
-    #   object description. Just to be semantic :)
+    #   Add link to documentation as a separate line to object description. Just to be semantic :)
     #
     #   ```ruby
     #   # you do something like
@@ -62,7 +61,7 @@ module TLAW
     #   docs "http://docs.example.com/my/endpoint"
     #
     #   # ...and then somewhere...
-    #   p my_api.endpoints[:endpoint].describe
+    #   p my_api.endpoint(:endpoint).describe
     #   # That is my endpoint.
     #   #
     #   # Docs: http://docs.example.com/my/endpoint
@@ -78,19 +77,17 @@ module TLAW
     #
     #   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.
+    #   * 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:
+    #   * 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}'
@@ -110,8 +107,7 @@ module TLAW
     #   # call-sequence now is foo(bar, baz:)
     #   ```
     #
-    #   * param of outer namespace are passed to API on call from inner
-    #     namespaces and endpoints, for ex:
+    #   * param of outer namespace are passed to API on call to inner namespaces and endpoints, for ex:
     #
     #   ```ruby
     #   namespace :city do
@@ -130,39 +126,37 @@ module TLAW
     #   **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 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:
+    #   @option opts [Symbol] :field What the field would be called in API query string (it would be
+    #     param's 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 Params::Base 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
+    #     # Enumerable form
     #     param :units, enum: %i[us metric britain]
-    #     # parameter accepts only :us, :metric, :britain values, and
-    #     # passes them to target API as is
+    #     # parameter accepts only :us, :metric, :britain values, and passes them to target API as is
+    #     # any Enumerable is OK:
+    #     param :count, enum: 1..5
+    #     # ^ note that means [1, 2, 3, 4, 5], not "any Numeric between 1 and 5"
     #
     #     # 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.
+    #     # parameter accepts true or false, on true passes "compact=gzip", on false passes nothing.
     #     ```
 
     # @!method namespace(name, path = nil, &block)
@@ -170,23 +164,20 @@ module TLAW
     #
     #   {Namespace} has two roles:
     #
-    #   * on Ruby API, defines how you access to the final endpoint,
-    #     like `api.namespace1.namespace2(some_param).endpoint(...)`
+    #   * 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).
+    #   **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 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)
+    #     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:
@@ -208,10 +199,9 @@ module TLAW
     #     # 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.
+    #   @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:
     #
@@ -231,42 +221,35 @@ module TLAW
     #     # call-sequence: foo(bar, baz:)
     #     ```
     #
-    #     ...and so on. See also {#param} for understanding what you
-    #     can change here.
-    #
+    #     ...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.
+    #   {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).
+    #   **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 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)
+    #     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.
+    #   @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:
     #
@@ -286,47 +269,42 @@ module TLAW
     #     # call-sequence: foo(bar, baz:)
     #     ```
     #
-    #     ...and so on. See also {#param} for understanding what you
-    #     can change here.
+    #     ...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).
+    #   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}`.
+    #   * 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. But only post-processors defined BEFORE the nested object
+    #     definition would be taken into account.
+    #   * 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}`. TODO: Probably it is subject to change.
     #
     #   @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:
+    #     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}
+    #     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.
+    #     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.
     #
@@ -341,13 +319,11 @@ module TLAW
     #     @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).
+    #   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).
+    #   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:
     #
@@ -377,11 +353,9 @@ module TLAW
     #   @param key [String]
 
     # @!method post_process_replace(&block)
-    #   Just like {#post_process} for entire response, but _replaces_
-    #   it with what block returns.
+    #   Just like {#post_process} for entire response, but _replaces_ it with what block returns.
     #
-    #   Real-life usage: WorldBank API typically returns responses this
-    #   way:
+    #   Real-life usage: WorldBank API typically returns responses this way:
     #
     #   ```json
     #   [
@@ -389,8 +363,8 @@ module TLAW
     #      {"some_data_variable": [{}, {}, {}]}
     #   ]
     #   ```
-    #   ...e.g. metadata and real response as two items in array, not
-    #   two keys in hash. We can easily fix this:
+    #   ...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|
@@ -400,112 +374,40 @@ module TLAW
     #
     #   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
+    # @!method shared_def(name, &block)
+    #   Define reusable parts of definition, which can be utilized with {#use_def}. Common example
+    #   is pagination (for one API, pagination logic for all paginated endpoints is typically the
+    #   same):
+    #
+    #   ```ruby
+    #   # at "whole API definition" level:
+    #   shared_def :pagination do
+    #     param :page, Integer, field: :pg, desc: "Page number, starts from 0"
+    #     param :per_page, enum: (5..50), field: :per, desc: "Number of items per page"
+    #   end
+    #
+    #   # at each particulare endpoint definition, just
+    #   use_def :pagination
+    #   # ...instead of repeating the param description above.
+    #   ```
+    #
+    #   Shared definition block may contain any DSL elements.
+    #
+    #   **Works for:** API, namespace, endpoint
 
-      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
+    # @!method use_def(name)
+    #   Use shared definition defined earlier. See {#shared_def} for explanation and examples.
+    #
+    #   **Works for:** API, namespace, endpoint
 
     # @private
-    class APIWrapper < NamespaceWrapper
-      def base(url)
-        @object.base_url = url
-      end
-    end
+    # If there is no content in class, YARD got mad with directives.
+    # See: https://github.com/lsegal/yard/issues/1207
+    DUMMY = nil
   end
 end
+
+require_relative 'dsl/api_builder'
+require_relative 'dsl/base_builder'
+require_relative 'dsl/endpoint_builder'
+require_relative 'dsl/namespace_builder'