Module: Hanami::Slice::ClassMethods

Defined in:
lib/hanami/slice.rb

Overview

rubocop:disable Metrics/ModuleLength

Since:

  • 2.0.0

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#autoloader ⇒ Zeitwerk::Loader (readonly)

Returns the slice’s autoloader.

Each slice has its own ‘Zeitwerk::Loader` autoloader instance, which is setup when the slice is prepared.

Returns:

  • (Zeitwerk::Loader)

See Also:

Since:

  • 2.0.0



76
77
78
 
# File 'lib/hanami/slice.rb', line 76

def autoloader
  @autoloader
end

#container ⇒ Object (readonly)

Returns the slice’s container.

This is a ‘Dry::System::Container` that is already configured for the slice.

In ordinary usage, you shouldn’t need direct access the container at all, since the slice provides its own methods for interacting with the container (such as #[], #keys, #key? #register, #register_provider, #prepare, #start, #stop).

If you need to configure the container directly, use #prepare_container.

See Also:

Since:

  • 2.0.0



92
93
94
 
# File 'lib/hanami/slice.rb', line 92

def container
  @container
end

#parent ⇒ Hanami::Slice (readonly)

Returns the slice’s parent.

For top-level slices defined in ‘slices/` or `config/slices/`, this will be the Hanami app itself (`Hanami.app`). For nested slices, this will be the slice in which they were registered.

Returns:

See Also:

Since:

  • 2.0.0



63
64
65
 
# File 'lib/hanami/slice.rb', line 63

def parent
  @parent
end

Instance Method Details

#[](key) ⇒ Object

Resolves the component with the given key from the container.

For a prepared slice, this will attempt to load and register the matching component if it is not loaded already. For a booted slice, this will return from already registered components only.

Returns:

  • (Object) —

    the resolved component’s object

Raises:

  • Dry::Container::KeyError if the component could not be found or loaded

See Also:

Since:

  • 2.0.0

Since:

  • 2.0.0



590
591
592
 
# File 'lib/hanami/slice.rb', line 590

def [](...)
  container.[](...)
end

#app ⇒ Hanami::App

Returns the Hanami app.

Returns:

Since:

  • 2.0.0



100
101
102
 
# File 'lib/hanami/slice.rb', line 100

def app
  Hanami.app
end

#boot ⇒ self

Boots the slice.

This will prepare the slice (if not already prepared), start each of its providers, register all the slice’s components from its Ruby source files, and import components from any other slices. It will also boot any of the slice’s own registered nested slices. It will then freeze its container so no further components can be registered.

Call ‘boot` if you want to fully load a slice and incur all load time up front, such as when preparing an app to serve web requests. Booting slices is the approach taken when running Hanami’s standard Puma setup (see ‘config.ru`).

Returns:

  • (self)

See Also:

Since:

  • 2.0.0



305
306
307
308
309
310
311
312
313
314
315
316
 
# File 'lib/hanami/slice.rb', line 305

def boot
  return self if booted?

  prepare

  container.finalize!
  slices.each(&:boot)

  @booted = true

  self
end

#booted? ⇒ Boolean

Returns true if the slice has been booted.

Returns:

  • (Boolean)

See Also:

Since:

  • 2.0.0



350
351
352
 
# File 'lib/hanami/slice.rb', line 350

def booted?
  !!@booted
end

#call(rack_env) ⇒ Array

Calls the slice’s [Rack] app and returns a Rack-compatible response object

[rack]: github.com/rack/rack

Parameters:

  • rack_env (Hash) —

    the Rack environment for the request

Returns:

  • (Array) —

    the three-element Rack response array

See Also:

Since:

  • 2.0.0

Since:

  • 2.0.0



757
758
759
 
# File 'lib/hanami/slice.rb', line 757

def call(...)
  rack_app.call(...)
end

#config ⇒ Hanami::Config

Returns the slice’s config.

A slice’s config is copied from the app config at time of first access.

Returns:

See Also:

  • App::ClassMethods.config

Since:

  • 2.0.0



114
115
116
117
118
119
 
# File 'lib/hanami/slice.rb', line 114

def config
  @config ||= app.config.dup.tap do |slice_config|
    # Unset config from app that does not apply to ordinary slices
    slice_config.root = nil
  end
end

#environment(env_name) ⇒ self #environment(env_name) {|slice| ... } ⇒ self

Evaluates the block for a given app environment only.

If the given ‘env_name` matches Hanami.env, then the block will be evaluated in the context of `self` (the slice) via `instance_eval`. The slice is also passed as the block’s optional argument.

If the env does not match, then the block is not evaluated at all.

Examples:

module MySlice
  class Slice < Hanami::Slice
    environment(:test) do
      config.logger.level = :info
    end
  end
end

Overloads:

  • #environment(env_name) ⇒ self

    Parameters:

    • env_name (Symbol) —

      the environment name

  • #environment(env_name) {|slice| ... } ⇒ self

    Parameters:

    • env_name (Symbol) —

      the environment name

    Yield Parameters:

    • slice (self) —

      the slice

Returns:

  • (self)

See Also:

Since:

  • 2.0.0



151
152
153
154
 
# File 'lib/hanami/slice.rb', line 151

def environment(env_name, &block)
  instance_eval(&block) if env_name == config.env
  self
end

#export(keys) ⇒ self

Specifies the components to export from the slice.

Slices importing from this slice can import the specified components only.

Examples:

module MySlice
  class Slice < Hanami::Slice
    export ["search", "index_entity"]
  end
end

Parameters:

  • keys (Array<String>) —

    the component keys to export

Returns:

  • (self)

Since:

  • 2.0.0



619
620
621
622
 
# File 'lib/hanami/slice.rb', line 619

def export(keys)
  container.config.exports = keys
  self
end

#import(from: , as: nil, keys: nil) ⇒ Object

Specifies components to import from another slice.

Booting a slice will register all imported components. For a prepared slice, these components will be be imported automatically when resolved.

Examples:

module MySlice
  class Slice < Hanami:Slice
    # Component from Search::Slice will import as "search.index_entity"
    import keys: ["index_entity"], from: :search
  end
end

Other import variations

# Different key namespace: component will be "search_backend.index_entity"
import keys: ["index_entity"], from: :search, as: "search_backend"

# Import to root key namespace: component will be "index_entity"
import keys: ["index_entity"], from: :search, as: nil

# Import all components
import from: :search

Parameters:

  • keys (Array<String>, nil) (defaults to: nil) —

    Array of component keys to import. To import all available components, omit this argument.

  • from (Symbol) (defaults to: ) —

    name of the slice to import from

  • as (Symbol, String, nil) (defaults to: nil)

See Also:

Since:

  • 2.0.0

Since:

  • 2.0.0



657
658
659
660
661
662
663
664
665
666
667
668
669
670
 
# File 'lib/hanami/slice.rb', line 657

def import(from:, **kwargs)
  slice = self

  container.after(:configure) do
    if from.is_a?(Symbol) || from.is_a?(String)
      slice_name = from
      from = slice.parent.slices[from.to_sym].container
    end

    as = kwargs[:as] || slice_name

    import(from: from, as: as, **kwargs)
  end
end

#inflector ⇒ Dry::Inflector

Returns the slice’s configured inflector.

Unless explicitly re-configured for the slice, this will be the app’s inflector.

Returns:

  • (Dry::Inflector)

See Also:

Since:

  • 2.0.0



217
218
219
 
# File 'lib/hanami/slice.rb', line 217

def inflector
  config.inflector
end

#key?(key) ⇒ Boolean

Returns true if the component with the given key is registered in the container.

For a prepared slice, calling ‘key?` will also try to load the component if not loaded already.

Parameters:

  • key (String, Symbol) —

    the component key

Returns:

  • (Boolean)

Since:

  • 2.0.0

Since:

  • 2.0.0



558
559
560
 
# File 'lib/hanami/slice.rb', line 558

def key?(...)
  container.key?(...)
end

#keys ⇒ Array<String>

Returns an array of keys for all currently registered components in the container.

For a prepared slice, this will be the set of components that have been previously resolved. For a booted slice, this will be all components available for the slice.

Returns:

  • (Array<String>)

Since:

  • 2.0.0



571
572
573
 
# File 'lib/hanami/slice.rb', line 571

def keys
  container.keys
end

#namespace ⇒ Module

Returns the constant for the slice’s module namespace.

Examples:

MySlice::Slice.namespace # => MySlice

Returns:

  • (Module) —

    the namespace module constant

See Also:

Since:

  • 2.0.0



178
179
180
 
# File 'lib/hanami/slice.rb', line 178

def namespace
  slice_name.namespace
end

#prepare ⇒ self #prepare(provider_name) ⇒ self

Overloads:

  • #prepare ⇒ self

    Prepares the slice.

    This will define the slice’s ‘Slice` and `Deps` constants, make all Ruby source files inside the slice’s root dir autoloadable, as well as lazily loadable as container components.

    Call ‘prepare` when you want to access particular components within the slice while still minimizing load time. Preparing slices is the approach taken when loading the Hanami console or when running tests.

    Returns:

    • (self)

    See Also:

    Since:

    • 2.0.0

  • #prepare(provider_name) ⇒ self

    Prepares a provider.

    This triggers the provider’s ‘prepare` lifecycle step.

    Parameters:

    • provider_name (Symbol) —

      the name of the provider to start

    Returns:

    • (self)

    Since:

    • 2.0.0

Since:

  • 2.0.0



250
251
252
253
254
255
256
257
258
 
# File 'lib/hanami/slice.rb', line 250

def prepare(provider_name = nil)
  if provider_name
    container.prepare(provider_name)
  else
    prepare_slice
  end

  self
end

#prepare_container {|container| ... } ⇒ self

Captures the given block to be called with the slice’s container during the slice’s ‘prepare` step, after the slice has already configured the container.

This is intended for advanced usage only and should not be needed for ordinary slice configuration and usage.

Examples:

module MySlice
  class Sliice < Hanami::Slice
    prepare_container do |container|
      # ...
    end
  end
end

Yield Parameters:

  • container (Dry::System::Container) —

    the slice’s container

Returns:

  • (self)

See Also:

Since:

  • 2.0.0



283
284
285
286
 
# File 'lib/hanami/slice.rb', line 283

def prepare_container(&block)
  @prepare_container_block = block
  self
end

#prepared? ⇒ Boolean

Returns true if the slice has been prepared.

Returns:

  • (Boolean)

See Also:

Since:

  • 2.0.0



338
339
340
 
# File 'lib/hanami/slice.rb', line 338

def prepared?
  !!@prepared
end

#rack_app ⇒ #call?

Returns a [Rack] app for the slice, or nil if no routes are defined.

The rack app will be memoized on first access.

[rack]: github.com/rack/rack

Returns:

  • (#call, nil) —

    the rack app, or nil if no routes are defined

See Also:

Since:

  • 2.0.0



738
739
740
741
742
 
# File 'lib/hanami/slice.rb', line 738

def rack_app
  return unless router

  @rack_app ||= router.to_rack_app
end

#register(key, object) ⇒ container #reigster(key, memoize: false, &block) ⇒ container #reigster(key, call: true, &block) ⇒ container

Registers a component in the slice’s container.

Overloads:

  • #register(key, object) ⇒ container

    Registers the given object as the component. This same object will be returned whenever the component is resolved.

    Parameters:

    • key (String) —

      the component’s key

    • object (Object) —

      the object to register as the component

  • #reigster(key, memoize: false, &block) ⇒ container

    Registers the given block as the component. When the component is resolved, the return value of the block will be returned.

    Since the block is not called until resolution-time, this is a useful way to register components that have dependencies on other components in the container, which as yet may be unavailable at the time of registration.

    All auto-registered components are registered in block form.

    When ‘memoize` is true, the component will be memoized upon first resolution and the same object returned on all subsequent resolutions, meaning the block is only called once. Otherwise, the block will be called and a new object returned on every resolution.

    Parameters:

    • key (String) —

      the component’s key

    • memoize (Boolean) (defaults to: false)

    Yield Returns:

    • (Object) —

      the object to register as the component

  • #reigster(key, call: true, &block) ⇒ container

    Registers the given block as the component. When ‘call: false` is given, then the block itself will become the component.

    When such a component is resolved, the block will not be called, and instead the ‘Proc` object for that block will be returned.

    Parameters:

    • key (String) —

      the component’s key

    • call (Booelan) (defaults to: true)

Returns:

See Also:

Since:

  • 2.0.0



442
443
444
 
# File 'lib/hanami/slice.rb', line 442

def register(...)
  container.register(...)
end

#register_provider(name, namespace: nil, from: nil, source: nil) ⇒ container

Registers a provider and its lifecycle hooks.

In most cases, you should call this from a dedicated file for the provider in your app or slice’s ‘config/providers/` dir. This allows the provider to be loaded when individual matching components are resolved (for prepared slices) or when slices are booted.

Examples:

Simple provider

# config/providers/db.rb
Hanami.app.register_provider(:db) do
  start do
    require "db"
    register("db", DB.new)
  end
end

Provider with lifecycle steps, also using dependencies from the target container

# config/providers/db.rb
Hanami.app.register_provider(:db) do
  prepare do
    require "db"
    db = DB.new(target_container["settings"].database_url)
    register("db", db)
  end

  start do
    container["db"].establish_connection
  end

  stop do
    container["db"].close_connection
  end
end

Probvider registration under a namespace

# config/providers/db.rb
Hanami.app.register_provider(:persistence, namespace: true) do
  start do
    require "db"

    # Namespace option above means this will be registered as "persistence.db"
    register("db", DB.new)
  end
end

Parameters:

  • name (Symbol) —

    the unique name for the provider

  • namespace (Boolean, String, nil) (defaults to: nil) —

    register components from the provider with given namespace. May be an explicit string, or ‘true` for the namespace to be the provider’s name

  • from (Symbol, nil) (defaults to: nil) —

    the group for an external provider source to use, with the provider source name inferred from ‘name` or passsed explicitly as `source:`

  • source (Symbol, nil) (defaults to: nil) —

    the name of the external provider source to use, if different from the value provided as ‘name`

  • if (Boolean) —

    a boolean-returning expression to determine whether to register the provider

Returns:

Since:

  • 2.0.0

Since:

  • 2.0.0



506
507
508
 
# File 'lib/hanami/slice.rb', line 506

def register_provider(...)
  container.register_provider(...)
end

#register_slice(name) {|slice| ... } ⇒ slices #register_slice(name, slice_class) ⇒ slices

Overloads:

  • #register_slice(name) {|slice| ... } ⇒ slices

    Registers a nested slice with the given name.

    This will define a new Hanami::Slice subclass for the slice. If a block is given, it is passed the class object, and will be evaluated in the context of the class like ‘class_eval`.

    Examples:

    MySlice::Slice.register_slice do
  # Configure the slice or do other class-level things here
end

    Parameters:

    • name (Symbol) —

      the identifier for the slice to be registered

    Yield Parameters:

  • #register_slice(name, slice_class) ⇒ slices

    Registers a nested slice with the given name.

    The given ‘slice_class` will be registered as the slice. It must be a subclass of Hanami::Slice.

    Parameters:

    • name (Symbol) —

      the identifier for the slice to be registered

    • slice_class (Hanami::Slice)

Returns:

See Also:

Since:

  • 2.0.0



394
395
396
 
# File 'lib/hanami/slice.rb', line 394

def register_slice(...)
  slices.register(...)
end

#resolve ⇒ Object

See Also:

Since:

  • 2.0.0



598
599
600
 
# File 'lib/hanami/slice.rb', line 598

def resolve(...)
  container.resolve(...)
end

#root ⇒ Pathname

Returns the slice’s root, either the root as explicitly configured, or a default fallback of the slice’s name within the app’s ‘slices/` dir.

Returns:

  • (Pathname)

See Also:

Since:

  • 2.0.0



191
192
193
194
195
196
197
198
199
200
201
202
203
204
 
# File 'lib/hanami/slice.rb', line 191

def root
  # Provide a best guess for a root when it is not yet configured.
  #
  # This is particularly useful for user-defined slice classes that access `settings` inside
  # the class body (since the root needed to find the settings file). In this case,
  # `configuration.root` may be nil when `settings` is called, since the root is configured by
  # `SliceRegistrar#configure_slice` _after_ the class is loaded.
  #
  # In common cases, this best guess will be correct since most Hanami slices will be expected
  # to live in the app SLICES_DIR. For advanced cases, the correct slice root should be
  # explicitly configured at the beginning of the slice class body, before any calls to
  # `settings`.
  config.root || app.root.join(SLICES_DIR, slice_name.to_s)
end

#router(inspector: nil) ⇒ Hanami::Slice::Router?

Returns the slice’s router, if or nil if no routes are defined.

An optional ‘inspector`, implementing the `Hanami::Router::Inspector` interface, may be provided at first call (the router is then memoized for subsequent accesses). An inspector is used by the `hanami routes` CLI comment to provide a list of available routes.

The returned router is a Router, which provides all ‘Hanami::Router` functionality, with the addition of support for slice mounting with the Router#slice.

Parameters:

  • inspector (Hanami::Router::Inspector, nil) (defaults to: nil) —

    an optional routes inspector

Returns:

Raises:

Since:

  • 2.0.0



717
718
719
720
721
722
723
 
# File 'lib/hanami/slice.rb', line 717

def router(inspector: nil)
  raise SliceLoadError, "#{self} must be prepared before loading the router" unless prepared?

  @_mutex.synchronize do
    @_router ||= load_router(inspector: inspector)
  end
end

#routes ⇒ Hanami::Routes?

Returns the slice’s routes, or nil if no routes are defined.

You can define your routes in ‘config/routes.rb`.

Returns:

See Also:

Since:

  • 2.0.0



698
699
700
 
# File 'lib/hanami/slice.rb', line 698

def routes
  @routes ||= load_routes
end

#settings ⇒ Hanami::Settings?

Returns the slice’s settings, or nil if no settings are defined.

You can define your settings in ‘config/settings.rb`.

Returns:

See Also:

Since:

  • 2.0.0



682
683
684
685
686
 
# File 'lib/hanami/slice.rb', line 682

def settings
  return @settings if instance_variable_defined?(:@settings)

  @settings = Settings.load_for_slice(self)
end

#shutdown ⇒ self

Shuts down the slice’s providers, as well as the providers in any nested slices.

Returns:

  • (self)

Since:

  • 2.0.0



324
325
326
327
328
 
# File 'lib/hanami/slice.rb', line 324

def shutdown
  slices.each(&:shutdown)
  container.shutdown!
  self
end

#slice_name ⇒ SliceName

Returns a Hanami::SliceName for the slice, an object with methods returning the name of the slice in various formats.

Returns:

Since:

  • 2.0.0



163
164
165
 
# File 'lib/hanami/slice.rb', line 163

def slice_name
  @slice_name ||= SliceName.new(self, inflector: method(:inflector))
end

#slices ⇒ SliceRegistrar

Returns the slice’s collection of nested slices.

Returns:

See Also:

Since:

  • 2.0.0



362
363
364
 
# File 'lib/hanami/slice.rb', line 362

def slices
  @slices ||= SliceRegistrar.new(self)
end

#start(provider_name) ⇒ container

Starts a provider.

This triggers the provider’s ‘prepare` and `start` lifecycle steps.

Examples:

MySlice::Slice.start(:persistence)

Parameters:

  • provider_name (Symbol) —

    the name of the provider to start

Returns:

Since:

  • 2.0.0

Since:

  • 2.0.0



524
525
526
 
# File 'lib/hanami/slice.rb', line 524

def start(...)
  container.start(...)
end

#stop(provider_name) ⇒ container

Stops a provider.

This triggers the provider’s ‘stop` lifecycle hook.

Examples:

MySlice::Slice.stop(:persistence)

Parameters:

  • provider_name (Symbol) —

    the name of the provider to start

Returns:

Since:

  • 2.0.0

Since:

  • 2.0.0



542
543
544
 
# File 'lib/hanami/slice.rb', line 542

def stop(...)
  container.stop(...)
end