Module: Hanami::Slice::ClassMethods

Defined in:
lib/hanami/slice.rb

Overview

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



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

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



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

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



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

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



634
635
636
 
# File 'lib/hanami/slice.rb', line 634

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

#app ⇒ Hanami::App

Returns the Hanami app.

Returns:

Since:

  • 2.0.0



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

def app
  Hanami.app
end

#app? ⇒ Boolean

Returns true if the slice is Hanami.app

Returns:

  • (Boolean)

Since:

  • 2.2.0



109
110
111
 
# File 'lib/hanami/slice.rb', line 109

def app?
  eql?(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



336
337
338
339
340
341
342
343
344
345
346
347
 
# File 'lib/hanami/slice.rb', line 336

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



381
382
383
 
# File 'lib/hanami/slice.rb', line 381

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

no routes are defined.

Parameters:

  • rack_env (Hash) —

    the Rack environment for the request

Returns:

  • (Array) —

    the three-element Rack response array

Raises:

See Also:

Since:

  • 2.0.0

Since:

  • 2.0.0



806
807
808
809
810
811
812
813
814
815
816
817
 
# File 'lib/hanami/slice.rb', line 806

def call(...)
  if rack_app
    rack_app.call(...)
  else
    error_message = if Hanami.bundled?("hanami-router")
                      "Could not handle this rack request because no routes are defined"
                    else
                      "Could not handle this rack request because the hanami router gem is missing, please add it"
                    end
    raise NoRoutesDefinedError, error_message
  end
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



123
124
125
126
127
128
 
# File 'lib/hanami/slice.rb', line 123

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

#configure_provider(*args, **kwargs, &block) ⇒ Object

Since:

  • 2.1.0



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

def configure_provider(*args, **kwargs, &block)
  container.register_provider(*args, **kwargs, from: :hanami, &block)
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



160
161
162
163
 
# File 'lib/hanami/slice.rb', line 160

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



663
664
665
666
 
# File 'lib/hanami/slice.rb', line 663

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) —

    name of the slice to import from

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

See Also:

Since:

  • 2.0.0

Since:

  • 2.0.0



701
702
703
704
705
706
707
708
709
710
711
712
713
714
 
# File 'lib/hanami/slice.rb', line 701

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



248
249
250
 
# File 'lib/hanami/slice.rb', line 248

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



595
596
597
 
# File 'lib/hanami/slice.rb', line 595

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



615
616
617
 
# File 'lib/hanami/slice.rb', line 615

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



187
188
189
 
# File 'lib/hanami/slice.rb', line 187

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



281
282
283
284
285
286
287
288
289
 
# File 'lib/hanami/slice.rb', line 281

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 Slice < 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



314
315
316
317
 
# File 'lib/hanami/slice.rb', line 314

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



369
370
371
 
# File 'lib/hanami/slice.rb', line 369

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



784
785
786
787
788
 
# File 'lib/hanami/slice.rb', line 784

def rack_app
  return unless router

  @rack_app ||= router.to_rack_app
end

#register(key, object) ⇒ container #register(key, memoize: false, &block) ⇒ container #register(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

  • #register(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

  • #register(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 (Boolean) (defaults to: true)

Returns:

See Also:

Since:

  • 2.0.0



473
474
475
 
# File 'lib/hanami/slice.rb', line 473

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 passed 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



537
538
539
 
# File 'lib/hanami/slice.rb', line 537

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



425
426
427
 
# File 'lib/hanami/slice.rb', line 425

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

#registered? ⇒ Boolean

Required for the slice to act as a provider target

Returns:

  • (Boolean)

Since:

  • 2.2.0



602
603
604
 
# File 'lib/hanami/slice.rb', line 602

def registered?(...)
  container.registered?(...)
end

#relative_source_path ⇒ Pathname

Returns the slice’s root component directory, as a path relative to the app’s root.

Returns:

  • (Pathname)

See Also:

Since:

  • 2.3.0



233
234
235
 
# File 'lib/hanami/slice.rb', line 233

def relative_source_path
  source_path.relative_path_from(app.root)
end

#resolve ⇒ Object

See Also:

Since:

  • 2.0.0



642
643
644
 
# File 'lib/hanami/slice.rb', line 642

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



200
201
202
203
204
205
206
207
208
209
210
211
212
213
 
# File 'lib/hanami/slice.rb', line 200

def root
  # Provides 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



763
764
765
766
767
768
769
 
# File 'lib/hanami/slice.rb', line 763

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



742
743
744
745
746
 
# File 'lib/hanami/slice.rb', line 742

def routes
  return @routes if instance_variable_defined?(:@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



726
727
728
729
730
 
# File 'lib/hanami/slice.rb', line 726

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



355
356
357
358
359
 
# File 'lib/hanami/slice.rb', line 355

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



172
173
174
 
# File 'lib/hanami/slice.rb', line 172

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



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

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

#source_path ⇒ Pathname

Returns the slice’s root component directory, accounting for App as a special case.

Returns:

  • (Pathname)

Since:

  • 2.2.0



221
222
223
 
# File 'lib/hanami/slice.rb', line 221

def source_path
  app? ? root.join(APP_DIR) : root
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



561
562
563
 
# File 'lib/hanami/slice.rb', line 561

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



579
580
581
 
# File 'lib/hanami/slice.rb', line 579

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