briefly 0.1.0

data/lib/briefly/builder.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module Briefly
+  # Receives the DSL. {Briefly.define}'s block and {Briefly::Facade#configure}'s block are
+  # +instance_eval+'d here, never on the facade, so DSL verbs can never collide with shortcut names.
+  #
+  # The block only collects; {#compile!} then validates, and {Briefly::Facade#configure} installs.
+  class Builder
+    # @return [Briefly::Facade] the facade under construction, for packs that need lifecycle hooks
+    attr_reader :facade
+
+    # @api private
+    # @param facade [Briefly::Facade]
+    # @param defs [Hash{Symbol => Briefly::Definition}] copies of the facade's current definitions
+    # @param children [Hash{Symbol => Briefly::Facade}] the facade's namespaces, by name
+    def initialize(facade, defs, children)
+      @facade = facade
+      @defs = defs
+      @children = children
+      @errors = []
+      @pending = {}
+    end
+
+    # Applies a pack: any object responding to +#install(builder)+, or a name {Briefly.register}'d for
+    # one. Any keywords are forwarded to the pack's +install+. Ruby drops an empty +**+ splat, so a
+    # pack taking no options needs no keyword parameter.
+    #
+    #   use Briefly::Rails::DB, base: "SecondaryApplicationRecord"
+    #   use "rails/db", base: "SecondaryApplicationRecord"
+    #
+    # @param pack [#install, String, Symbol]
+    # @return [self]
+    # @raise [Briefly::UnknownPackError] if +pack+ is a name that is not registered
+    def use(pack, **)
+      pack = Briefly.pack(pack) unless pack.respond_to?(:install)
+      pack.install(self, **)
+      self
+    end
+
+    # Declares a namespace: a shortcut returning a child facade, so +App.db.query+ works. The block is
+    # the child's own DSL — +shortcut+, +memoize+, +use+, +rescue_from+, and further namespaces.
+    #
+    # The child is created once and reused by later passes, so its memos survive +configure+.
+    # {Briefly::Facade#clear_memos!} cascades into it. Two limits, both deliberate: a child body cannot
+    # reach a root shortcut by bare name, and a root +rescue_from+ does not scope into the child.
+    #
+    # The child's pass is *collected*, not run: its builder is held until {#compile!} has validated the
+    # whole tree, so a later failure in this pass cannot leave an already-reachable child mutated. One
+    # builder per name, so a second +namespace(:db)+ in the same pass extends the first rather than
+    # replacing it.
+    #
+    # @param name [Symbol] the shortcut the child answers to
+    # @yield [] evaluated against the child's {Briefly::Builder}
+    # @return [Symbol] +name+
+    # @raise [Briefly::ReservedNameError] if +name+ shadows a facade method
+    def namespace(name, &block)
+      raise ArgumentError, "namespace(#{name.inspect}) requires a block" unless block
+
+      validate_name!(name)
+      child = @children[name] || Facade.new
+      pending = @pending[name] || child.send(:__prepare)
+      pending.instance_eval(&block)
+      # Routes through `shortcut` for purge and validation, which drops the child this call just
+      # resolved — so re-register both afterwards. An external `shortcut(name)` gets no such reprieve.
+      shortcut(name) { child }
+      # The proc above is a literal in this file. Point the compiled method at the caller's block instead.
+      @defs[name].source_location = block.source_location
+      @children[name] = child
+      @pending[name] = pending
+      name
+    end
+
+    # Declares a shortcut. Redeclaring a name (canonical or alias) silently overrides it.
+    #
+    # @param canonical [Symbol] the primary method name; may end in +?+ or +!+
+    # @param aliases [Array<Symbol>] extra names sharing the body and the memo cell
+    # @yield the implementation, bound to the facade at call time
+    # @return [Symbol] the canonical name
+    # @raise [Briefly::ReservedNameError] if any name shadows a facade method
+    def shortcut(canonical, *aliases, &body)
+      raise ArgumentError, "shortcut(#{canonical.inspect}) requires a block" unless body
+
+      # A `&:upcase`-style Proc carries no location of its own; fall back to this call site so the compiled
+      # method points at the user's declaration, never a fabricated file. `namespace` overwrites it anyway.
+      location = body.source_location || caller_locations(1, 1).first.then { |l| [l.path, l.lineno] }
+      defn = Definition.new(canonical, aliases, body, location)
+      defn.names.each { |name| validate_name!(name) }
+      purge(defn.names, except: canonical)
+      @defs[canonical] = defn
+      canonical
+    end
+
+    # Marks an already-declared shortcut as memoized: computed once, cached for the process lifetime.
+    #
+    # @param name [Symbol] a canonical name or an alias
+    # @param opts [Hash] reserved for future use; none are accepted
+    # @return [Symbol] the canonical name
+    # @raise [Briefly::UnknownShortcutError] if +name+ does not resolve
+    def memoize(name, **opts)
+      raise ArgumentError, "memoize(#{name.inspect}) got unknown options: #{opts.keys.join(", ")}" unless opts.empty?
+
+      defn = fetch(name)
+      defn.memoize!
+      defn.canonical
+    end
+
+    # Registers an error handler. The handler's return value becomes the shortcut's return value.
+    #
+    # Because +{}+ binds to the nearest token, +rescue_from StandardError { }+ is a call to a method
+    # named +StandardError+. Use +rescue_from Err, :name do |e| ... end+ or +rescue_from(Err, :name) { |e| ... }+.
+    #
+    # @param error_class [Class] matched against the raised error and its subclasses
+    # @param names [Array<Symbol>] shortcuts to scope to; none means facade-wide
+    # @yield [error, shortcut_name] the recovery block
+    # @return [self]
+    def rescue_from(error_class, *names, &handler)
+      unless error_class.is_a?(Class)
+        raise ArgumentError, "rescue_from expects the error class first, e.g. rescue_from(StandardError, :name) { }"
+      end
+      raise ArgumentError, "rescue_from(#{error_class}) requires a block" unless handler
+
+      scoped = names.flatten.map { |name| fetch(name).canonical }
+      @errors << [error_class, (scoped.empty? ? nil : scoped), handler]
+      self
+    end
+
+    # Validates everything collected in this pass, and recursively every namespace pass it collected.
+    # {Briefly::Facade#configure} installs the result. Validation of the whole tree finishes before any
+    # of it is installed.
+    #
+    # @api private
+    # @return [Array] +[definitions, error_entries, children, child_plans]+
+    # @raise [Briefly::Error] if a memoized shortcut's body takes arguments
+    def compile!
+      @defs.each_value do |defn|
+        # `parameters`, not `arity`: a `{ |&blk| }` body has arity 0 but its block would be dropped.
+        next unless defn.memoized? && !defn.body.parameters.empty?
+
+        raise Error, "cannot memoize #{defn.canonical}: its body takes arguments"
+      end
+      [@defs, @errors, @children, @pending.map { |name, builder| [@children[name], builder.compile!] }]
+    end
+
+    private
+
+    def validate_name!(name)
+      raise ArgumentError, "shortcut names must be Symbols, got #{name.inspect}" unless name.is_a?(Symbol)
+      raise ReservedNameError, "#{name} is reserved by Briefly::Facade" if Facade::RESERVED.include?(name)
+      # Candor raises here too, but as an ArgumentError, and only once the pass is already committing.
+      return unless name.start_with?(Candor::BODY_PREFIX)
+
+      raise ReservedNameError, "#{name} is reserved: #{Candor::BODY_PREFIX}* names hold compiled shortcut bodies"
+    end
+
+    # Frees the incoming names from any definition that currently owns them, so a redeclaration
+    # never leaves a stale alias pointing at the old body.
+    def purge(names, except:)
+      @defs.delete_if { |canonical, _| canonical != except && names.include?(canonical) }
+      @defs.each_value { |defn| defn.aliases.replace(defn.aliases - names) }
+      # A namespace is just a shortcut returning its child, so redeclaring the name — as a canonical or
+      # as someone else's alias — must drop the child too. Keeping it would leave `clear_memos!` walking
+      # a facade nothing can reach. `except` gets no exemption: `namespace` re-registers its own child.
+      @children.delete_if { |name, _| names.include?(name) }
+      @pending.delete_if { |name, _| names.include?(name) }
+    end
+
+    def fetch(name)
+      defn = @defs[name] || @defs.each_value.find { |d| d.aliases.include?(name) }
+      raise UnknownShortcutError, "unknown shortcut: #{name.inspect}" unless defn
+
+      defn
+    end
+  end
+end

data/lib/briefly/definition.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Briefly
+  # One shortcut declaration: its canonical name, its aliases, its body, and whether it memoizes.
+  #
+  # @api private
+  class Definition
+    # @return [Symbol] the primary method name
+    attr_reader :canonical
+
+    # @return [Array<Symbol>] additional method names delegating to the same body and memo cell
+    attr_reader :aliases
+
+    # @return [Proc] the implementation, bound to the facade at call time
+    attr_reader :body
+
+    # @return [Symbol] the private singleton method the body compiles to
+    attr_reader :raw_name
+
+    # The +[file, line]+ the compiled methods report. {Briefly::Builder#shortcut} resolves it — the body's
+    # own location, or the +shortcut+ call site for a bodiless-of-location Proc like +&:upcase+ — and
+    # {Briefly::Builder#namespace} overwrites it: its child-returning proc literal lives in +builder.rb+,
+    # and a namespace that pointed there would reintroduce, for namespaces, the lie this field exists to
+    # remove.
+    #
+    # @return [Array(String, Integer)]
+    attr_accessor :source_location
+
+    # @param canonical [Symbol]
+    # @param aliases [Array<Symbol>]
+    # @param body [Proc]
+    # @param source_location [Array(String, Integer)]
+    def initialize(canonical, aliases, body, source_location)
+      @canonical = canonical
+      @aliases = aliases
+      @body = body
+      @raw_name = Candor.body_name(canonical)
+      @memoized = false
+      @source_location = source_location
+    end
+
+    # Builder copies the facade's definitions before mutating them, so an aborted pass cannot
+    # leave the live facade half-configured. Hash#dup would share this array.
+    #
+    # @param other [Briefly::Definition]
+    # @return [void]
+    def initialize_copy(other)
+      super
+      @aliases = other.aliases.dup
+    end
+
+    # Marks the value as computed once and cached. A redeclared shortcut is a fresh, unmemoized
+    # Definition, so there is no un-memoize.
+    #
+    # @return [void]
+    def memoize! = @memoized = true
+
+    # @return [Boolean]
+    def memoized? = @memoized
+
+    # @return [Array<Symbol>] canonical name followed by every alias
+    def names = [@canonical, *@aliases]
+  end
+end

data/lib/briefly/error_registry.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Briefly
+  # An ordered list of +rescue_from+ registrations, queried at dispatch time.
+  #
+  # Entries are stored oldest-first and returned newest-first, so the most recent registration for a
+  # given error class wins. Reads are lock-free against a frozen array; writes rebind it under a
+  # mutex, because rebinding alone would drop concurrent registrations.
+  class ErrorRegistry
+    # A single registration. +names+ is +nil+ for facade-wide/global handlers.
+    Entry = Struct.new(:klass, :names, :handler)
+
+    def initialize
+      @entries = [].freeze
+      @mutex = Mutex.new
+    end
+
+    # @param klass [Class] matched against the raised error and its subclasses
+    # @param names [Array<Symbol>, nil] canonical shortcut names, or +nil+ for every shortcut
+    # @param handler [Proc] called with +(error, shortcut_name)+
+    # @return [self]
+    def add(klass, names, handler)
+      @mutex.synchronize { @entries = [*@entries, Entry.new(klass, names&.freeze, handler)].freeze }
+      self
+    end
+
+    # @param name [Symbol] a canonical shortcut name
+    # @return [Array<Entry>] handlers scoped to +name+, most recently registered first
+    def scoped(name) = @entries.reverse_each.select { |entry| entry.names&.include?(name) }
+
+    # @return [Array<Entry>] handlers scoped to no shortcut in particular, most recent first
+    def wide = @entries.reverse_each.select { |entry| entry.names.nil? }
+
+    # @return [self]
+    def clear
+      @mutex.synchronize { @entries = [].freeze }
+      self
+    end
+  end
+end

data/lib/briefly/errors.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Briefly
+  # Base class for every error raised by Briefly.
+  class Error < StandardError; end
+
+  # Raised when +memoize+ or +rescue_from+ names a shortcut that does not exist.
+  class UnknownShortcutError < Error; end
+
+  # Raised when a shortcut name or alias would shadow a facade method.
+  class ReservedNameError < Error; end
+
+  # Raised when +use+ names a pack that is not registered.
+  class UnknownPackError < Error; end
+
+  # Sentinel distinguishing "not memoized yet" from a memoized +nil+.
+  UNSET = Object.new.freeze
+end

data/lib/briefly/facade.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module Briefly
+  # The object returned by {Briefly.define}. Shortcuts are compiled onto its singleton class as real
+  # methods, so +respond_to?+, console tab-completion and test stubbing all work unaided.
+  #
+  # Memo store: reads are lock-free against a frozen snapshot hash; writes swap in a new frozen hash
+  # under a reentrant +Monitor+, because a memoized body may call another memoized shortcut.
+  class Facade
+    def initialize
+      @__defs = {}
+      @__aliases = {}
+      @__memos = {}.freeze
+      @__monitor = Monitor.new
+      @__errors = ErrorRegistry.new
+      @__public = [].freeze
+      @__children = {}
+    end
+
+    # @return [Array<Symbol>] canonical shortcut names, sorted; aliases excluded
+    def shortcuts = @__defs.keys.sort
+
+    # @param name [Symbol] a canonical name or an alias
+    # @return [Boolean]
+    def shortcut?(name) = @__defs.key?(name) || @__aliases.key?(name)
+
+    # Drops every memoized value, here and in every namespace. Thread-safe.
+    #
+    # @return [self]
+    def clear_memos!
+      @__monitor.synchronize { @__memos = {}.freeze }
+      # Each namespace owns its memo store and its own lock, so a child clears outside our monitor.
+      # One `Reload` on the root therefore clears the whole tree, including namespaces holding no pack.
+      @__children.each_value(&:clear_memos!)
+      self
+    end
+    alias reset! clear_memos!
+
+    # Reopens the facade for another builder pass and recompiles. The builder starts from copies of the
+    # current definitions, so a pass that raises leaves the live facade — and every namespace under it
+    # — untouched.
+    #
+    # @yield [] evaluated against a {Briefly::Builder}
+    # @return [self]
+    def configure(&block)
+      builder = __prepare
+      builder.instance_eval(&block) if block
+      # `compile!` validates the whole tree before `__commit` installs any of it. Splitting the two is
+      # what keeps a namespace pass atomic: `Builder#namespace` collects its child's pass rather than
+      # running it, so a later failure anywhere cannot leave an already-reachable child half-updated.
+      __commit(builder.compile!)
+      self
+    end
+
+    # @return [String] a summary listing shortcut names; never dumps memo internals
+    def inspect = "#<#{self.class.name} shortcuts=#{shortcuts.inspect}>"
+    alias to_s inspect
+
+    private
+
+    # A builder seeded with copies of everything a pass may mutate. {Briefly::Builder#namespace} calls
+    # this on the child it collects.
+    #
+    # @return [Briefly::Builder]
+    def __prepare = Builder.new(self, @__defs.transform_values(&:dup), @__children.dup)
+
+    # Installs a validated pass, children first. Nothing here may raise: every check ran in +compile!+.
+    #
+    # @param plan [Array] +compile!+'s +[defs, error_entries, children, child_plans]+
+    # @return [self]
+    def __commit(plan)
+      defs, error_entries, children, child_plans = plan
+      child_plans.each { |child, child_plan| child.send(:__commit, child_plan) }
+      @__children = children
+      __install(defs, error_entries)
+    end
+
+    # Compiles definitions onto the singleton class and appends error registrations.
+    def __install(defs, error_entries)
+      wanted = defs.each_value.flat_map(&:names)
+      __remove_methods(@__public - wanted)
+      defs.each_value { |defn| __define(defn) }
+
+      @__public = wanted.freeze
+      @__defs = defs
+      @__aliases = defs.each_value.flat_map { |d| d.aliases.map { |a| [a, d.canonical] } }.to_h
+      error_entries.each { |klass, names, handler| @__errors.add(klass, names, handler) }
+      self
+    end
+
+    def __remove_methods(names)
+      names.each { |name| singleton_class.send(:remove_method, name) }
+    end
+
+    # Candor installs the body privately under its reserved prefix, reads that *compiled* method's
+    # `parameters` — never `defn.body.parameters`, which reports every positional as `:opt` and would
+    # silently destroy arity strictness — and compiles a dispatch of the same arity onto every name.
+    # Arity is enforced there, before `__call` and its rescue layer are entered.
+    #
+    # No `parameters:` override for a memoized shortcut: `compile!` has already refused any memoized body
+    # that takes an argument, so its compiled shape is empty and `App.catalog(1)` raises on its own.
+    #
+    # `source_location:` because `namespace` rewrites it: its body is a `proc { child }` literal in
+    # `builder.rb`, and the compiled method must point at the caller's block instead.
+    def __define(defn)
+      Candor.define(singleton_class, defn.canonical,
+                    aliases: defn.aliases,
+                    via: :__call,
+                    source_location: defn.source_location,
+                    body: defn.body)
+    end
+
+    def __call(name, ...)
+      # Outside the rescue: an internal KeyError must never be laundered into a user's fallback.
+      defn = @__defs.fetch(name)
+      begin
+        return __memo(name) { send(defn.raw_name) } if defn.memoized?
+
+        send(defn.raw_name, ...)
+      rescue StandardError => e
+        __handle(e, name)
+      end
+    end
+
+    def __memo(name)
+      value = @__memos.fetch(name, UNSET)
+      return value unless UNSET.equal?(value)
+
+      # One reentrant lock for the whole facade: first computations of unrelated memoized shortcuts
+      # serialize. Per-shortcut locks would deadlock on a body that reaches another memoized body.
+      @__monitor.synchronize do
+        value = @__memos.fetch(name, UNSET)
+        return value unless UNSET.equal?(value)
+
+        computed = yield # raising here stores nothing: a rescued fallback is never memoized
+        @__memos = @__memos.merge(name => computed).freeze
+        computed
+      end
+    end
+
+    def __handle(error, name)
+      entry = @__errors.scoped(name).find { |e| error.is_a?(e.klass) } ||
+              @__errors.wide.find { |e| error.is_a?(e.klass) } ||
+              Briefly.errors.wide.find { |e| error.is_a?(e.klass) }
+      # Kernel.raise, not bare raise: a shortcut may not be named `raise`, but a pack could still
+      # define one on a subclass, and this must never dispatch back into the facade.
+      Kernel.raise(error) unless entry
+
+      entry.handler.call(error, name)
+    end
+  end
+
+  # Names a shortcut may not take: every facade method, plus Briefly's own private ones, plus the
+  # Kernel private methods the facade itself calls with an implicit receiver. Other Kernel privates
+  # (+puts+, +format+, ...) are deliberately absent: shadowing those is the user's call.
+  Facade::RESERVED = (Facade.instance_methods + Facade.private_instance_methods(false) + %i[raise]).freeze
+end

data/lib/briefly/rails/db.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Briefly
+  module Rails
+    # Shortcut pack for a single database, reached through one Active Record class.
+    #
+    #   App = Briefly.define do
+    #     namespace(:db)  { use Briefly::Rails::DB }
+    #     namespace(:db2) { use Briefly::Rails::DB, base: "SecondaryApplicationRecord" }
+    #   end
+    #
+    #   App.db.txn { App.db.query("select * from users where id = ?", 1) }
+    #
+    # +base+ is a constant path, resolved on every call. Pass a String, not the class: a pack is
+    # +use+d from an initializer, where naming an autoloadable constant is what Rails warns about, and
+    # the captured class would go stale on the first code reload — permanently, since {Reload} clears
+    # memos, not closures. A Module is accepted for applications outside the autoloader, with that caveat.
+    #
+    # Nothing here memoizes: a connection is leased from the pool, and +query+ takes arguments. So the
+    # pack does not wire {Reload}, and works without a booted application.
+    #
+    # Inside this file the framework is always +::Rails+ — bare +Rails+ would resolve to the parent module.
+    module DB
+      module_function
+
+      # @param builder [Briefly::Builder]
+      # @param base [String, Symbol, Module] the Active Record class this database hangs off
+      # @return [Briefly::Builder]
+      def install(builder, base: "ApplicationRecord")
+        model = -> { base.is_a?(Module) ? base : Object.const_get(base) }
+
+        builder.shortcut(:connection, :conn) { model.call.lease_connection }
+        builder.shortcut(:transaction, :txn) { |**opts, &blk| model.call.transaction(**opts, &blk) }
+        # `with_connection`, not `connection`: the latter is soft-deprecated, and raises outright under
+        # `ActiveRecord.permanent_connection_checkout = :disallowed`.
+        #
+        # A bindless statement must skip `sanitize_sql_array`, which would fall through to its
+        # `statement % values` branch and raise on any literal `%` — `... like '%foo%'`.
+        #
+        # No `**` parameter here, deliberately: taking no keywords is what makes Ruby pack
+        # `query(sql, id: 1)` into `binds` as a trailing Hash, which is how named binds reach
+        # `sanitize_sql_array`. A `**opts` would swallow them and send the statement unbound.
+        builder.shortcut(:query) do |sql, *binds|
+          record = model.call
+          statement = binds.empty? ? sql : record.sanitize_sql_array([sql, *binds])
+          record.with_connection { |connection| connection.exec_query(statement) }
+        end
+        builder
+      end
+    end
+  end
+end

data/lib/briefly/rails/reload.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Briefly
+  module Rails
+    # Lifecycle pack: clears the facade's memos at boot and on every code reload.
+    #
+    # Usable on its own, for a facade that has no framework shortcuts but does memoize objects
+    # holding on to reloadable application classes:
+    #
+    #   Admin = Briefly.define { use Briefly::Rails::Reload }
+    #
+    # The callback holds the facade for the process lifetime and cannot be deregistered. Install it
+    # on long-lived facades assigned to constants, not on facades built per request.
+    module Reload
+      # Marks a facade so a second +configure+ pass does not register a duplicate callback.
+      INSTALLED = :@__briefly_rails_reload
+      private_constant :INSTALLED
+
+      module_function
+
+      # @param builder [Briefly::Builder]
+      # @return [Briefly::Builder]
+      # @raise [Briefly::Error] outside a booted application
+      def install(builder)
+        facade = builder.facade
+        return builder if facade.instance_variable_defined?(INSTALLED)
+
+        app = ::Rails.application if defined?(::Rails)
+        unless app.respond_to?(:reloader)
+          raise Briefly::Error, "Briefly::Rails::Reload needs a booted application; use it from an initializer"
+        end
+
+        facade.instance_variable_set(INSTALLED, true)
+        app.reloader.to_prepare { facade.clear_memos! }
+        builder
+      end
+    end
+  end
+end

data/lib/briefly/rails.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "briefly"
+require "briefly/rails/db"
+require "briefly/rails/reload"
+
+module Briefly
+  # Shortcut pack for Rails applications.
+  #
+  #   App = Briefly.define { use Briefly::Rails }
+  #   App.c            # => Rails.configuration
+  #   App.render(...)  # => ApplicationController.renderer.render(...)
+  #   App.db.txn { }   # => ApplicationRecord.transaction { }
+  #
+  # An umbrella over {Config}, {Env}, {View} and {Reload}, plus {DB} under the +db+ namespace. Each is
+  # a pack in its own right, so a facade can take only the parts it wants:
+  #
+  #   Admin = Briefly.define do
+  #     use "rails/env"
+  #     namespace(:primary) { use "rails/db" }
+  #   end
+  #
+  # Nothing here memoizes. Every shortcut is a live lookup: the framework already caches the
+  # expensive ones (+helpers+, +routes+, +renderer+) on objects it refreshes on reload, so caching
+  # them again would only go stale. {Reload} is still wired in, because the *application's* own
+  # memoized shortcuts need clearing; the mini-packs, having nothing to clear, leave it alone.
+  #
+  # Inside this file the framework is always +::Rails+ — bare +Rails+ would resolve to this module.
+  module Rails
+    module_function
+
+    # @param builder [Briefly::Builder]
+    # @return [Briefly::Builder]
+    def install(builder)
+      builder.use(Reload)
+      builder.use(Config)
+      builder.use(Env)
+      builder.use(View)
+      builder.namespace(:db) { use DB }
+      builder
+    end
+
+    # Configuration, paths and the application-wide singletons.
+    module Config
+      module_function
+
+      # @param builder [Briefly::Builder]
+      # @return [Briefly::Builder]
+      def install(builder)
+        builder.shortcut(:config, :c) { ::Rails.configuration }
+        builder.shortcut(:config_x, :x) { ::Rails.configuration.x }
+        builder.shortcut(:root) { ::Rails.root }
+        builder.shortcut(:cache) { ::Rails.cache }
+        builder.shortcut(:logger, :log) { ::Rails.logger }
+        builder.shortcut(:credentials, :cred) { ::Rails.application.credentials }
+        builder
+      end
+    end
+
+    # The environment and its predicates.
+    module Env
+      module_function
+
+      # @param builder [Briefly::Builder]
+      # @return [Briefly::Builder]
+      def install(builder)
+        builder.shortcut(:env) { ::Rails.env }
+        builder.shortcut(:production?) { ::Rails.env.production? }
+        builder.shortcut(:development?) { ::Rails.env.development? }
+        builder.shortcut(:test?) { ::Rails.env.test? }
+        builder.shortcut(:local?) { ::Rails.env.local? }
+        builder
+      end
+    end
+
+    # Helpers, routes and rendering outside a controller.
+    module View
+      module_function
+
+      # @param builder [Briefly::Builder]
+      # @return [Briefly::Builder]
+      def install(builder)
+        builder.shortcut(:helpers, :h) { ::ApplicationController.helpers }
+        builder.shortcut(:routes, :r) { ::Rails.application.routes.url_helpers }
+        builder.shortcut(:renderer) { ::ApplicationController.renderer }
+        builder.shortcut(:render) { |*args, **kwargs, &blk| renderer.render(*args, **kwargs, &blk) }
+        builder
+      end
+    end
+  end
+end

data/lib/briefly/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Briefly
+  # The gem version.
+  VERSION = "0.1.0"
+end