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

add_child(child) click to toggle source

@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
base_url=(url) click to toggle source

@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
children() click to toggle source

@private

# File lib/tlaw/namespace.rb, line 84
def children
  @children ||= {}
end
describe(definition = nil) click to toggle source

Detailed namespace documentation.

See {APIPath.describe} for explanations.

@return [Util::Description]

Calls superclass method TLAW::APIPath::describe
# File lib/tlaw/namespace.rb, line 93
def describe(definition = nil)
  super + describe_children
end
endpoints() click to toggle source

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
inspect() click to toggle source
# File lib/tlaw/namespace.rb, line 63
def inspect
  "#<#{name || '(unnamed namespace class)'}: " \
  "call-sequence: #{symbol}(#{param_set.to_code});" +
    inspect_docs
end
inspect_docs() click to toggle source

@private

# File lib/tlaw/namespace.rb, line 70
def inspect_docs
  inspect_namespaces + inspect_endpoints + ' docs: .describe>'
end
namespaces() click to toggle source

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
to_code() click to toggle source

@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

children_description(children) click to toggle source
# File lib/tlaw/namespace.rb, line 125
def children_description(children)
  children.values.map(&:describe_short)
          .map { |cd| cd.indent('  ') }.join("\n\n")
end
describe_children() click to toggle source
# File lib/tlaw/namespace.rb, line 109
def describe_children
  describe_namespaces + describe_endpoints
end
describe_endpoints() click to toggle source
# File lib/tlaw/namespace.rb, line 119
def describe_endpoints
  return '' if endpoints.empty?

  "\n\n  Endpoints:\n\n" + children_description(endpoints)
end
describe_namespaces() click to toggle source
# File lib/tlaw/namespace.rb, line 113
def describe_namespaces
  return '' if namespaces.empty?

  "\n\n  Namespaces:\n\n" + children_description(namespaces)
end
inspect_endpoints() click to toggle source
# File lib/tlaw/namespace.rb, line 104
def inspect_endpoints
  return '' if endpoints.empty?
  " endpoints: #{endpoints.keys.join(', ')};"
end
inspect_namespaces() click to toggle source
# File lib/tlaw/namespace.rb, line 99
def inspect_namespaces
  return '' if namespaces.empty?
  " namespaces: #{namespaces.keys.join(', ')};"
end

Public Instance Methods

describe() click to toggle source
# File lib/tlaw/namespace.rb, line 141
def describe
  self.class
      .describe("#{symbol}(#{param_set.to_hash_code(@parent_params)})")
end
inspect() click to toggle source
# 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

child(symbol, expected_class, **params) click to toggle source
# 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