184 lines
6.2 KiB
Markdown
184 lines
6.2 KiB
Markdown
# rubbs
|
|
|
|
A Ruby gem for building telnet BBS servers. Three interaction layers, from
|
|
simplest to richest:
|
|
|
|
| Layer | What it is | When to use |
|
|
|---|---|---|
|
|
| `BBS::Flow` | Line-oriented declarative dialogue DSL (ask / say / menu / persist) | Login, registration, simple wizards |
|
|
| `BBS::TUI` | Page-router with frame-buffer delta rendering | Single-purpose full-screen UIs |
|
|
| `BBS::Application` | Full widget framework: Menubar, Window, Button, TextInput, ListBox, … | Multi-window Synchronet-style BBSes |
|
|
|
|
A single session can switch between layers — typically `Flow` for login then
|
|
`Application` for the main shell.
|
|
|
|
## Installation
|
|
|
|
```ruby
|
|
# Gemfile
|
|
gem 'bbs', git: 'https://git.teletype.hu/tools/rubbs.git'
|
|
```
|
|
|
|
## Quick start — Flow + Application
|
|
|
|
```ruby
|
|
require 'bbs'
|
|
|
|
MAIN = BBS::Application.define do
|
|
theme BBS::Theme.synchronet
|
|
|
|
menubar do
|
|
menu '&File' do
|
|
item '&About' do BBS::Dialogs.message(self, 'Hello from rubbs!') end
|
|
item 'E&xit' do :halt end
|
|
end
|
|
end
|
|
|
|
status_hint('F1', 'Help') { BBS::Dialogs.message(self, 'No help yet.') }
|
|
status_hint('F10', 'Menu') { menubar.open(0) }
|
|
end
|
|
|
|
BBS.configure do |c|
|
|
c.mouse = true
|
|
c.idle_seconds = 600
|
|
c.flow = BBS::Flow.define do
|
|
big_banner 'MY BBS', style: :success
|
|
ask :username, prompt: 'Name'
|
|
app MAIN
|
|
say 'Goodbye!'
|
|
end
|
|
end
|
|
|
|
BBS.start
|
|
```
|
|
|
|
Connect with `telnet localhost 2323`.
|
|
|
|
## Configuration
|
|
|
|
`BBS.configure` yields a `BBS::Config`:
|
|
|
|
| Option | Default | Description |
|
|
|---|---|---|
|
|
| `flow` | — | A `BBS::Flow` object (required) |
|
|
| `port` | `ENV["BBS_PORT"] \|\| 2323` | TCP port |
|
|
| `mouse` | `false` | Enable xterm SGR mouse reporting |
|
|
| `idle_seconds` | `nil` | Disconnect after N idle seconds (nil = never) |
|
|
| `theme` | — | Default theme for Applications (overridable per app) |
|
|
| `screens_dir` | `nil` | Directory for ERB screens used by `BBS::Flow#screen` |
|
|
| `on_session_end` | `nil` | Lambda called when a session ends |
|
|
|
|
## The Application layer
|
|
|
|
`BBS::Application` is a widget event loop with:
|
|
|
|
- a root container drawn behind windows;
|
|
- an optional `Menubar` with Alt-letter pulldown menus and F10 access;
|
|
- an optional `Statusbar` with clickable hotkey hints;
|
|
- a stack of modal `Window`s (the top one receives input first);
|
|
- xterm SGR mouse events delivered to widgets;
|
|
- a 1 Hz internal tick for chat polling, clocks, etc.
|
|
|
|
### Built-in widgets (`BBS::Widgets`)
|
|
|
|
| Widget | Purpose |
|
|
|---|---|
|
|
| `Label` | Static text, optionally aligned, themed via `style_key` |
|
|
| `Button` | `&Save`-style hotkey, fires `on_click(self)`; mouse-clickable |
|
|
| `TextInput` | Single-line input with cursor, scroll, `on_submit`/`on_change` |
|
|
| `TextArea` | Multi-line editor with arrow-key navigation |
|
|
| `Checkbox` | Toggle with `on_change(checked, self)` |
|
|
| `ListBox` | Scrolling list with mouse + keyboard, wheel scrolling |
|
|
| `ScrollView` | Read-only scrolling text view, with scrollbar |
|
|
| `ProgressBar`, `Spinner` | Progress feedback |
|
|
| `Panel`, `HBox`, `VBox` | Containers / layout |
|
|
| `Window` | Top-level modal container with title bar, close gadget, shadow |
|
|
|
|
### Built-in dialogs (`BBS::Dialogs`)
|
|
|
|
```ruby
|
|
BBS::Dialogs.message(app, "Saved!", title: ' Done ')
|
|
BBS::Dialogs.confirm(app, "Delete?", on_yes: -> { ... })
|
|
BBS::Dialogs.input(app, prompt: 'Name?', on_submit: ->(value) { ... })
|
|
```
|
|
|
|
### Menubar DSL
|
|
|
|
```ruby
|
|
menubar do
|
|
menu '&File' do
|
|
item '&Open', shortcut: 'Ctrl-O' do … end
|
|
separator
|
|
item 'E&xit' do :halt end
|
|
end
|
|
end
|
|
```
|
|
|
|
The block runs in the Application's context (so you can call `open_window`,
|
|
`close_window`, `cols`, `rows`, etc.). Return `:halt` from any handler to end
|
|
the session.
|
|
|
|
### Theming
|
|
|
|
`BBS::Theme.synchronet` (default) is a yellow/cyan Synchronet-inspired palette.
|
|
`BBS::Theme.mono` provides a colour-free fallback. Create your own with
|
|
`BBS::Theme.new(:my_theme, { window_border: "\e[1;36m", … })`.
|
|
|
|
## The Flow layer
|
|
|
|
The DSL for line-based dialogue. Available steps:
|
|
|
|
| Step | Purpose |
|
|
|---|---|
|
|
| `screen :name` | Render an ERB screen from `screens/` |
|
|
| `banner`, `big_banner` | Box-drawing / FIGlet ASCII art header |
|
|
| `say`, `text`, `section`, `line`, `body` | Text output |
|
|
| `ask :field`, `set :field, value`, `persist :field, store:` | Input + persistence |
|
|
| `pause`, `wait_enter`, `gate`, `confirm` | Control flow |
|
|
| `menu`, `exit_menu` | Numbered option menus |
|
|
| `fetch`, `pick` | Data fetch + list selection |
|
|
| `rows`, `table` | Formatted output |
|
|
| `call { \|ctx, runner\| … }` | Arbitrary code; return `:halt` to end |
|
|
| `tui DEFINITION` | Hand off to a `BBS::TUI` page router |
|
|
| `app DEFINITION` | Hand off to a `BBS::Application` widget app |
|
|
|
|
## Input model
|
|
|
|
`Session#readkey(timeout:)` returns one of:
|
|
|
|
- a single-character `String` (printable input)
|
|
- a `Symbol`: `:enter`, `:tab`, `:shift_tab`, `:backspace`, `:escape`,
|
|
`:up`, `:down`, `:left`, `:right`, `:home`, `:end`,
|
|
`:page_up`, `:page_down`, `:insert`, `:delete`,
|
|
`:f1` … `:f12`, `:ctrl_a` … `:ctrl_z`,
|
|
`:alt_a` … (any printable character preceded by ESC),
|
|
`:interrupt`, `:idle`
|
|
- a `BBS::Telnet::MouseEvent` with `kind`, `button`, `x`, `y`, `mods` —
|
|
delivered when `BBS.config.mouse = true`
|
|
|
|
## Stores
|
|
|
|
`BBS::Store` is a thread-safe upsert-by-`session_id` CSV file with an
|
|
in-memory cache; appends are O(1), full rewrites only on update.
|
|
|
|
## Architecture
|
|
|
|
| File | Responsibility |
|
|
|---|---|
|
|
| `bbs/server.rb` | TCP accept loop, one thread per client |
|
|
| `bbs/session.rb` | Telnet negotiation, mouse enable/disable, idle timer |
|
|
| `bbs/telnet.rb` | Telnet protocol, full key parsing, xterm SGR mouse |
|
|
| `bbs/flow.rb`, `bbs/flow_runner.rb` | Flow DSL + interpreter |
|
|
| `bbs/tui.rb`, `bbs/tui_runner.rb` | Page-router with frame-buffer rendering |
|
|
| `bbs/frame_buffer.rb` | Double-buffer, delta diff, drawing helpers |
|
|
| `bbs/application.rb` | Widget event loop, window stack, ticking |
|
|
| `bbs/widget.rb`, `bbs/container.rb` | Widget tree base |
|
|
| `bbs/widgets.rb` | Built-in widgets |
|
|
| `bbs/window.rb`, `bbs/menu.rb`, `bbs/statusbar.rb`, `bbs/dialogs.rb` | Chrome |
|
|
| `bbs/focus_manager.rb` | Tab/Shift-Tab focus traversal |
|
|
| `bbs/theme.rb` | Style palette (synchronet / mono) |
|
|
| `bbs/event.rb` | Unified key + mouse event objects |
|
|
| `bbs/store.rb` | Thread-safe cached CSV upsert |
|
|
| `bbs/banner.rb`, `bbs/renderer.rb` | FIGlet + ERB |
|
|
| `bbs/color.rb` | Simple ANSI colour helper |
|