class TLAW::Namespace
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 # => class SampleAPI::MyNS, subclass of namespace api.my_ns # => short-living instance of SampleAPI::MyNS api.my_ns.weather # => real call to API
“`
Public Class Methods
@private
# File lib/tlaw/namespace.rb, line 75 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
# File lib/tlaw/namespace.rb, line 34 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
@private
# File lib/tlaw/namespace.rb, line 84 def children @children ||= {} end
Detailed namespace documentation.
See {APIPath.describe} for explanations.
@return [Util::Description]
TLAW::APIPath::describe
# File lib/tlaw/namespace.rb, line 93 def describe(definition = nil) super + describe_children end
Lists all current namespace's endpoints as a hash.
@return [Hash{Symbol => Endpoint}]
# File lib/tlaw/namespace.rb, line 52 def endpoints children.select { |_k, v| v < Endpoint } end
# File lib/tlaw/namespace.rb, line 63 def inspect "#<#{name || '(unnamed namespace class)'}: " \ "call-sequence: #{symbol}(#{param_set.to_code});" + inspect_docs end
@private
# File lib/tlaw/namespace.rb, line 70 def inspect_docs inspect_namespaces + inspect_endpoints + ' docs: .describe>' end
Lists all current namespace's nested namespaces as a hash.
@return [Hash{Symbol => Namespace}]
# File lib/tlaw/namespace.rb, line 45 def namespaces children.select { |_k, v| v < Namespace } end
@private
# File lib/tlaw/namespace.rb, line 57 def to_code "def #{to_method_definition}\n" \ " child(:#{symbol}, Namespace, {#{param_set.to_hash_code}})\n" \ 'end' end
Private Class Methods
# File lib/tlaw/namespace.rb, line 125 def children_description(children) children.values.map(&:describe_short) .map { |cd| cd.indent(' ') }.join("\n\n") end
# File lib/tlaw/namespace.rb, line 109 def describe_children describe_namespaces + describe_endpoints end
# File lib/tlaw/namespace.rb, line 119 def describe_endpoints return '' if endpoints.empty? "\n\n Endpoints:\n\n" + children_description(endpoints) end
# File lib/tlaw/namespace.rb, line 113 def describe_namespaces return '' if namespaces.empty? "\n\n Namespaces:\n\n" + children_description(namespaces) end
# File lib/tlaw/namespace.rb, line 104 def inspect_endpoints return '' if endpoints.empty? " endpoints: #{endpoints.keys.join(', ')};" end
# File lib/tlaw/namespace.rb, line 99 def inspect_namespaces return '' if namespaces.empty? " namespaces: #{namespaces.keys.join(', ')};" end
Public Instance Methods
# File lib/tlaw/namespace.rb, line 141 def describe self.class .describe("#{symbol}(#{param_set.to_hash_code(@parent_params)})") end
# File lib/tlaw/namespace.rb, line 136 def inspect "#<#{symbol}(#{param_set.to_hash_code(@parent_params)})" + self.class.inspect_docs end
Private Instance Methods
# File lib/tlaw/namespace.rb, line 148 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