class BBS::Application::Builder

The DSL of Application.define. Its methods record the application’s parts; build makes an Application from them for one session, and run runs it with its doors.

Public Class Methods

new ()

Source

# File lib/bbs/application/builder.rb, line 10
def initialize
  @statusbar_hints = []
  @helper_module   = Module.new
  @services        = {}
  @window_specs    = {}
  @doors           = {}
end

Creates an empty Builder; Application.define makes one.

Public Instance Methods

body (&block)

Source

# File lib/bbs/application/builder.rb, line 95
def body(&block)
  @body_block = block
end

Sets the block that fills the root container, evaluated in a BodyContext each time build makes an application.

build (session:, session_id:, context: {})

Source

# File lib/bbs/application/builder.rb, line 104
def build(session:, session_id:, context: {})
  app = new_application(session, session_id, context)
  app.menubar = build_menubar(app) if @menubar_block
  app.statusbar = build_statusbar(app) unless @statusbar_hints.empty?
  app.instance_exec(&@init_block) if @init_block
  BodyContext.new(app).instance_exec(&@body_block) if @body_block
  app
end

Makes an Application for session from the recorded parts: theme (default BBS.config.theme, then BBS::Theme.synchronet), helpers, services, window specs, doors, on_tick, on_idle, menubar and statusbar, then runs the init and body blocks. Returns the Application, not yet running.

door (name, program, label: nil, hint: nil)

Source

# File lib/bbs/application/builder.rb, line 23
def door(name, program, label: nil, hint: nil)
  @doors[name.to_sym] = Door.new(name, program, label: label, hint: hint)
end

Declares a door: program is a BBS::FakeOS definition, a BBS::Flow or a callable call(session, context); label is its menu item (default: the upcased name), hint a line about it for the statusbar while its menu item is highlighted. Returns the BBS::Door. Raises ArgumentError when program is none of these.

helpers (&)

Source

# File lib/bbs/application/builder.rb, line 80
def helpers(&) = @helper_module.module_eval(&)

Evaluates the block in the helper module: the methods it defines become methods of every Application this builder makes.

init (&block)

Source

# File lib/bbs/application/builder.rb, line 64
def init(&block) = (@init_block = block)

Sets the block run on the new application (with self the Application) each time build makes one, after the menubar and statusbar and before body.

menubar (&block)

Source

# File lib/bbs/application/builder.rb, line 83
def menubar(&block) = (@menubar_block = block)

Sets the block that builds the menubar, evaluated in a MenubarBuilder.

on_door (&block)

Source

# File lib/bbs/application/builder.rb, line 77
def on_door(&block) = (@door_block = block)

Runs with the door and the context just before Builder#run hands the line to a door: who is where, a log line.

on_idle (&block)

Source

# File lib/bbs/application/builder.rb, line 73
def on_idle(&block) = (@idle_block = block)

Runs on the application when the caller reaches the idle limit, before the line is dropped. Return :keep to keep the caller on (a “still there?” dialog that got an answer); anything else ends the run.

on_tick (&block)

Source

# File lib/bbs/application/builder.rb, line 68
def on_tick(&block) = (@tick_block = block)

Runs on the application (like a menu item) once a second while the caller is idle: a clock, a counter on the statusbar, a poll.

run (session:, session_id:, context: {})

Source

# File lib/bbs/application/builder.rb, line 117
def run(session:, session_id:, context: {})
  loop do
    app = build(session: session, session_id: session_id, context: context)
    app.run
    door = context.delete(:door)
    break if door.nil? || app.line_lost?

    @door_block&.call(door, context)
    door.run(session, context)
  end
end

Builds and runs the application. When the caller leaves it through a door, runs the door and builds the application again; returns when the caller leaves without one or the line drops. The context lives through it all. Calls the on_door block before each door.

services (hash = nil)

Source

# File lib/bbs/application/builder.rb, line 29
def services(hash = nil)
  return @services if hash.nil?
  @services = @services.merge(hash)
end

Merges hash into the services handed to window callbacks and returns the merged Hash. Without an argument returns the services so far.

status_hint (key, label, hidden: false, &on_activate)

Source

# File lib/bbs/application/builder.rb, line 89
def status_hint(key, label, hidden: false, &on_activate)
  @statusbar_hints << [key, label, on_activate, hidden]
end

Adds a statusbar hint for key (a key Symbol such as :f1) with label. The block runs on the application when the key is pressed or the hint clicked. A hidden hint is a key binding that takes no room on the statusbar.

theme (base = nil, &block)

Source

# File lib/bbs/application/builder.rb, line 54
def theme(base = nil, &block)
  return @theme if base.nil? && block.nil?

  starting = base.nil? ? BBS.config.theme || Theme.synchronet : Theme.fetch(base)
  @theme   = block ? ThemeBuilder.new(starting).tap { |b| b.instance_eval(&block) }.build : starting
end

Sets the application’s theme: theme BBS::Theme.dosnavigator, theme :dosnavigator, or either with a block that overrides roles (evaluated in a ThemeBuilder; a block alone starts from BBS.config.theme, or BBS::Theme.synchronet). Without arguments it returns the theme set so far (nil before any). With no theme call at all the application gets BBS.config.theme (see Application.new). Raises ArgumentError for a name that is not one of BBS::Theme::PRESETS, NoMethodError for a role the block sets that no preset knows.

window (name, type:, &block)

Source

# File lib/bbs/application/builder.rb, line 38
def window(name, type:, &block)
  spec = WindowSpec.new(name, type: type)
  block&.call(spec)
  @window_specs[name] = spec
  spec
end

Registers a BBS::WindowSpec of type (:info, :form, :master_detail or :stream) under name, for Application#open_window. The block gets the spec to configure. Returns the spec.