Module: Briefly

Defined in:
lib/briefly.rb,
lib/briefly/rails.rb,
lib/briefly/errors.rb,
lib/briefly/facade.rb,
lib/briefly/builder.rb,
lib/briefly/rescues.rb,
lib/briefly/version.rb,
lib/briefly/rails/db.rb,
lib/briefly/shortcut.rb,
lib/briefly/rails/env.rb,
lib/briefly/rails/view.rb,
lib/briefly/rails/config.rb,
lib/briefly/rails/reload.rb,
lib/briefly/rails/instrument.rb,
lib/generators/briefly/install/install_generator.rb

Overview

A terse, curated facade over an application's most frequently reached-for objects.

App = Briefly.define do
use Briefly::Rails
shortcut(:redis) { REDIS_POOL }
end

Defined Under Namespace

Modules: Generators, Rails Classes: Builder, Error, Facade, Rescues, ReservedNameError, Shortcut, UnknownPackError, UnknownShortcutError

Constant Summary collapse

UNSET =

Sentinel distinguishing "not memoized yet" from a memoized nil.

Object.new.freeze
VERSION =

The gem version.

"0.2.0"

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.rescues ⇒ Briefly::Rescues (readonly)

Returns the global registry.

Returns:



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

def rescues
  @rescues
end

Class Method Details

.define { ... } ⇒ Briefly::Facade

Builds a facade. The block is +instance_eval+'d on a Builder.

Yields:

  • [] the shortcut declarations

Returns:



40
 
# File 'lib/briefly.rb', line 40

def define(&) = Facade.new.briefly.configure(&)

.pack(name) ⇒ #install

Resolves a short name to a pack. A registered constant path is resolved here, not at registration, so a pack's file loads only when something uses it.

The path is walked one segment at a time rather than handed to Object.const_get whole, so a NameError raised inside a pack's file as it autoloads propagates untouched. Rescuing around the whole resolution would launder that bug into an UnknownPackError.

Parameters:

  • name (String, Symbol)

Returns:

  • (#install)

Raises:



63
64
65
66
67
68
69
70
71
72
73
74
 
# File 'lib/briefly.rb', line 63

def pack(name)
  entry = @packs.fetch(name.to_s) { raise UnknownPackError, "unknown pack: #{name.inspect}" }
  return entry unless entry.is_a?(String)

  entry.split("::").reduce(Object) do |mod, segment|
    unless mod.const_defined?(segment, false)
      raise UnknownPackError, "pack #{name.inspect} names #{entry.inspect}, which does not resolve"
    end

    mod.const_get(segment, false)
  end
end

.register(name, pack) ⇒ self

Registers a pack under a short name, so use "myapp/redis" resolves it. Re-registering a name overrides it. There is no inflection and no path guessing: this table is the only source of truth.

Parameters:

  • name (String, Symbol) —

    the short name

  • pack (#install, String) —

    the pack, or a constant path resolved on first use

Returns:

  • (self) 


48
49
50
51
 
# File 'lib/briefly.rb', line 48

def register(name, pack)
  @packs[name.to_s] = pack
  self
end

.rescue_from(error_class) {|error, shortcut_name| ... } ⇒ self

Registers a handler that applies to every shortcut on every facade, consulted only after the facade's own handlers. Takes no shortcut names.

Parameters:

  • error_class (Class) —

    matched against the raised error and its subclasses

Yields:

  • (error, shortcut_name) —

    the recovery block; its return value becomes the shortcut's value

Returns:

  • (self) 


82
83
84
85
86
 
# File 'lib/briefly.rb', line 82

def rescue_from(error_class, &handler)
  validate_rescue!(error_class, handler)
  @rescues.add(error_class, handler)
  self
end

.validate_rescue!(error_class, handler) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

The one rescue_from argument check, shared by the global verb here, the facade-wide verb (Briefly::Builder#rescue_from) and the per-shortcut form (Briefly::Shortcut#rescue_from), so the error class must come first, a block is required, and the message never diverges between them. Private, so it stays off +Briefly+'s public surface; the two cross-class callers reach it with Briefly.send(:validate_rescue!, ...), the same +send+-to-internal seam Briefly::Facade::Control uses.

Parameters:

  • error_class (Object) —

    must be a Class

  • handler (Proc, nil) —

    must be present

Raises:

  • (ArgumentError) —

    if error_class is not a Class, or no block was given



99
100
101
102
103
104
105
 
# File 'lib/briefly.rb', line 99

def validate_rescue!(error_class, handler)
  unless error_class.is_a?(Class)
    raise ArgumentError, "rescue_from expects the error class first, got #{error_class.inspect}"
  end

  raise ArgumentError, "rescue_from(#{error_class}) requires a block" unless handler
end