diff --git a/examples/bank/src/account.bt b/examples/bank/src/account.bt index 0871a3df8..c656f5914 100644 --- a/examples/bank/src/account.bt +++ b/examples/bank/src/account.bt @@ -1,19 +1,18 @@ // Copyright 2026 James Casey // SPDX-License-Identifier: Apache-2.0 -// Account actor — an independent process managing a single bank balance -// -// Each Account is a BEAM process. Deposits and withdrawals are message sends, -// making them inherently serialised per-account. Overdraft protection raises -// a structured error via `self error:` -// -// Usage: -// acct := Account spawn -// acct deposit: 500 -// acct balance // => 500 -// acct withdraw: 200 // => 300 -// acct withdraw: 9999 // => ERROR: Insufficient funds - +/// Account actor — an independent process managing a single bank balance +/// +/// Each Account is a BEAM process. Deposits and withdrawals are message sends, +/// making them inherently serialised per-account. Overdraft protection raises +/// a structured error via `self error:` +/// +/// Usage: +/// acct := Account spawn +/// acct deposit: 500 +/// acct balance // => 500 +/// acct withdraw: 200 // => 300 +/// acct withdraw: 9999 // => ERROR: Insufficient funds Actor subclass: Account state: balance = 0 state: owner = "" diff --git a/examples/bank/src/bank.bt b/examples/bank/src/bank.bt index 641a4187d..ce0ead2a4 100644 --- a/examples/bank/src/bank.bt +++ b/examples/bank/src/bank.bt @@ -1,18 +1,17 @@ // Copyright 2026 James Casey // SPDX-License-Identifier: Apache-2.0 -// Bank actor — a registry and factory for Account actors -// -// The Bank maintains a Dictionary mapping account names to Account actor -// references. Opening an account spawns a new Account process and registers -// it. Looking up an account returns the live actor reference -// -// Usage: -// bank := Bank spawn -// bank openAccount: "Alice" -// alice := bank accountFor: "Alice" -// alice deposit: 1000 - +/// Bank actor — a registry and factory for Account actors +/// +/// The Bank maintains a Dictionary mapping account names to Account actor +/// references. Opening an account spawns a new Account process and registers +/// it. Looking up an account returns the live actor reference +/// +/// Usage: +/// bank := Bank spawn +/// bank openAccount: "Alice" +/// alice := bank accountFor: "Alice" +/// alice deposit: 1000 Actor subclass: Bank state: accounts = #{} state: lastCreated = nil diff --git a/examples/bank/src/transaction.bt b/examples/bank/src/transaction.bt index 094fcc493..950d805b9 100644 --- a/examples/bank/src/transaction.bt +++ b/examples/bank/src/transaction.bt @@ -1,16 +1,15 @@ // Copyright 2026 James Casey // SPDX-License-Identifier: Apache-2.0 -// Transaction — an immutable value recording a transfer -// -// Transactions are value objects (Object subclass), not actors. They capture -// the details of a transfer as an immutable record -// -// Usage: -// txn := Transaction new: #{#amount => 250, #from => "Alice", #to => "Bob", #status => "completed"} -// txn getAmount // => 250 -// txn getStatus // => "completed" - +/// Transaction — an immutable value recording a transfer +/// +/// Transactions are value objects (Object subclass), not actors. They capture +/// the details of a transfer as an immutable record +/// +/// Usage: +/// txn := Transaction new: #{#amount => 250, #from => "Alice", #to => "Bob", #status => "completed"} +/// txn getAmount // => 250 +/// txn getStatus // => "completed" Object subclass: Transaction state: amount = 0 state: from = "" diff --git a/examples/bank/src/transfer_agent.bt b/examples/bank/src/transfer_agent.bt index 8450ddf24..7b0db806f 100644 --- a/examples/bank/src/transfer_agent.bt +++ b/examples/bank/src/transfer_agent.bt @@ -1,20 +1,19 @@ // Copyright 2026 James Casey // SPDX-License-Identifier: Apache-2.0 -// TransferAgent actor — coordinates transfers between two Account actors -// -// A TransferAgent moves money between accounts by sending withdraw and -// deposit messages synchronously. Each Account handles its own validation -// (e.g. overdraft protection) independently -// -// This demonstrates the actor coordination pattern: the TransferAgent -// orchestrates two independent actors, and each actor enforces its own -// invariants -// -// Usage: -// agent := TransferAgent spawn -// agent transfer: 250 from: alice to: bob - +/// TransferAgent actor — coordinates transfers between two Account actors +/// +/// A TransferAgent moves money between accounts by sending withdraw and +/// deposit messages synchronously. Each Account handles its own validation +/// (e.g. overdraft protection) independently +/// +/// This demonstrates the actor coordination pattern: the TransferAgent +/// orchestrates two independent actors, and each actor enforces its own +/// invariants +/// +/// Usage: +/// agent := TransferAgent spawn +/// agent transfer: 250 from: alice to: bob Actor subclass: TransferAgent state: lastAmount = 0 diff --git a/examples/bank/src/typed_account.bt b/examples/bank/src/typed_account.bt index 12e4e7c7d..b140267de 100644 --- a/examples/bank/src/typed_account.bt +++ b/examples/bank/src/typed_account.bt @@ -1,13 +1,12 @@ // Copyright 2026 James Casey // SPDX-License-Identifier: Apache-2.0 -// TypedAccount — typed variant of the Account actor -// -// Demonstrates ADR 0025 syntax: -// - typed class modifier -// - typed state fields -// - typed parameters and return annotations - +/// TypedAccount — typed variant of the Account actor +/// +/// Demonstrates ADR 0025 syntax: +/// - typed class modifier +/// - typed state fields +/// - typed parameters and return annotations typed Actor subclass: TypedAccount state: balance: Integer = 0 state: owner: String = "" diff --git a/examples/chat-room/src/chat_member.bt b/examples/chat-room/src/chat_member.bt index 556b20b5b..1f40cb569 100644 --- a/examples/chat-room/src/chat_member.bt +++ b/examples/chat-room/src/chat_member.bt @@ -1,28 +1,27 @@ // Copyright 2026 James Casey // SPDX-License-Identifier: Apache-2.0 -// Chat Member Actor — Part of Chat Room Demo (BT-431, BT-568) -// -// ChatMember represents a chat participant with a name, inbox, and room ref -// It demonstrates: -// - Actor-to-actor references (room field) -// - Receiving formatted messages from other actors -// - State mutations (name, inbox, room) -// -// Try it in the REPL: -// $ beamtalk repl -// > :load examples/chat-room/message.bt -// > :load examples/chat-room/chat_room.bt -// > :load examples/chat-room/chat_member.bt -// > room := ChatRoom spawn -// > alice := ChatMember spawn -// > alice setName: "Alice" -// > alice setRoom: room -// > room join: alice -// > room say: "Hello!" from: "Alice" -// -// See examples/chat-room/README.md for a full walkthrough - +/// Chat Member Actor — Part of Chat Room Demo (BT-431, BT-568) +/// +/// ChatMember represents a chat participant with a name, inbox, and room ref +/// It demonstrates: +/// - Actor-to-actor references (room field) +/// - Receiving formatted messages from other actors +/// - State mutations (name, inbox, room) +/// +/// Try it in the REPL: +/// $ beamtalk repl +/// > :load examples/chat-room/message.bt +/// > :load examples/chat-room/chat_room.bt +/// > :load examples/chat-room/chat_member.bt +/// > room := ChatRoom spawn +/// > alice := ChatMember spawn +/// > alice setName: "Alice" +/// > alice setRoom: room +/// > room join: alice +/// > room say: "Hello!" from: "Alice" +/// +/// See examples/chat-room/README.md for a full walkthrough Actor subclass: ChatMember state: name = "Guest" // Member's display name state: inbox = #() // List of received messages diff --git a/examples/chat-room/src/chat_room.bt b/examples/chat-room/src/chat_room.bt index 33c1d36e6..3dce1606d 100644 --- a/examples/chat-room/src/chat_room.bt +++ b/examples/chat-room/src/chat_room.bt @@ -30,14 +30,12 @@ // =========================================================================== // CHATROOM ACTOR // =========================================================================== -// -// ChatRoom manages a Set of member actors and a List of message strings -// It demonstrates: -// - Storing actor references (PIDs) in a Set -// - String concatenation for formatted messages -// - Broadcasting via do: iteration over actor Set -// - List concatenation for message history - +/// ChatRoom manages a Set of member actors and a List of message strings +/// It demonstrates: +/// - Storing actor references (PIDs) in a Set +/// - String concatenation for formatted messages +/// - Broadcasting via do: iteration over actor Set +/// - List concatenation for message history Actor subclass: ChatRoom state: members = Set new // Set of ChatMember actor references state: history = #() // List of formatted message strings diff --git a/examples/chat-room/src/message.bt b/examples/chat-room/src/message.bt index ed250d981..cf39bba6d 100644 --- a/examples/chat-room/src/message.bt +++ b/examples/chat-room/src/message.bt @@ -1,21 +1,20 @@ // Copyright 2026 James Casey // SPDX-License-Identifier: Apache-2.0 -// Message — Value type for chat messages (BT-568) -// -// Demonstrates: -// 1. **Value types** — Object subclass (not Actor), no process overhead -// 2. **State** — text and sender fields with defaults -// 3. **Immutability** — value types are immutable Erlang maps -// 4. **new: initialization** — creating instances with field values -// -// Usage in REPL: -// > :load examples/chat-room/message.bt -// > args := #{#text => "Hello!", #sender => "Alice"} -// > msg := Message new: args -// > msg getText -// > msg describe - +/// Message — Value type for chat messages (BT-568) +/// +/// Demonstrates: +/// 1. **Value types** — Object subclass (not Actor), no process overhead +/// 2. **State** — text and sender fields with defaults +/// 3. **Immutability** — value types are immutable Erlang maps +/// 4. **new: initialization** — creating instances with field values +/// +/// Usage in REPL: +/// > :load examples/chat-room/message.bt +/// > args := #{#text => "Hello!", #sender => "Alice"} +/// > msg := Message new: args +/// > msg getText +/// > msg describe Object subclass: Message state: text = "" state: sender = "Anonymous" diff --git a/examples/chat-room/src/moderator.bt b/examples/chat-room/src/moderator.bt index dd8146614..648ebc15e 100644 --- a/examples/chat-room/src/moderator.bt +++ b/examples/chat-room/src/moderator.bt @@ -1,25 +1,24 @@ // Copyright 2026 James Casey // SPDX-License-Identifier: Apache-2.0 -// Moderator — Actor subclass of ChatMember (BT-568) -// -// Demonstrates: -// 1. **Actor inheritance** — ChatMember subclass: Moderator -// 2. **super calls** — Moderator overrides say: to add "[MOD]" prefix -// 3. **New methods** — kick: and mute: for moderation actions -// -// Usage in REPL: -// > :load examples/chat-room/message.bt -// > :load examples/chat-room/chat_room.bt -// > :load examples/chat-room/chat_member.bt -// > :load examples/chat-room/moderator.bt -// > room := ChatRoom spawn -// > mod := Moderator spawn -// > mod setName: "Admin" -// > mod setRoom: room -// > room join: mod -// > mod say: "Welcome!" - +/// Moderator — Actor subclass of ChatMember (BT-568) +/// +/// Demonstrates: +/// 1. **Actor inheritance** — ChatMember subclass: Moderator +/// 2. **super calls** — Moderator overrides say: to add "[MOD]" prefix +/// 3. **New methods** — kick: and mute: for moderation actions +/// +/// Usage in REPL: +/// > :load examples/chat-room/message.bt +/// > :load examples/chat-room/chat_room.bt +/// > :load examples/chat-room/chat_member.bt +/// > :load examples/chat-room/moderator.bt +/// > room := ChatRoom spawn +/// > mod := Moderator spawn +/// > mod setName: "Admin" +/// > mod setRoom: room +/// > room join: mod +/// > mod say: "Welcome!" ChatMember subclass: Moderator state: muted = Set new // Set of muted member names diff --git a/examples/getting-started/src/counter.bt b/examples/getting-started/src/counter.bt index 1f9212389..87ff23ef6 100644 --- a/examples/getting-started/src/counter.bt +++ b/examples/getting-started/src/counter.bt @@ -1,23 +1,22 @@ // Copyright 2026 James Casey // SPDX-License-Identifier: Apache-2.0 -// Counter actor class example -// A simple stateful actor that can increment, decrement, and return its value -// -// Try it in the REPL: -// $ beamtalk repl -// > :load examples/counter.bt -// > c := Counter spawn -// > c increment -// > c increment -// > c getValue -// 2 -// > c decrement -// > c getValue -// 1 -// -// See examples/repl-tutorial.md for a full beginner's guide - +/// Counter actor class example +/// A simple stateful actor that can increment, decrement, and return its value +/// +/// Try it in the REPL: +/// $ beamtalk repl +/// > :load examples/counter.bt +/// > c := Counter spawn +/// > c increment +/// > c increment +/// > c getValue +/// 2 +/// > c decrement +/// > c getValue +/// 1 +/// +/// See examples/repl-tutorial.md for a full beginner's guide Actor subclass: Counter state: value = 0 diff --git a/examples/getting-started/src/hanoi.bt b/examples/getting-started/src/hanoi.bt index b91b9b686..4434fbd94 100644 --- a/examples/getting-started/src/hanoi.bt +++ b/examples/getting-started/src/hanoi.bt @@ -1,23 +1,22 @@ // Copyright 2026 James Casey // SPDX-License-Identifier: Apache-2.0 -// Towers of Hanoi -// A classic recursive algorithm that moves n disks between three pegs -// -// Try it in the REPL: -// $ beamtalk repl -// > :load examples/hanoi.bt -// > h := Hanoi new -// > h solve: 3 from: "A" to: "C" via: "B" -// Move disk from A to C -// Move disk from A to B -// Move disk from C to B -// Move disk from A to C -// Move disk from B to A -// Move disk from B to C -// Move disk from A to C -// nil - +/// Towers of Hanoi +/// A classic recursive algorithm that moves n disks between three pegs +/// +/// Try it in the REPL: +/// $ beamtalk repl +/// > :load examples/hanoi.bt +/// > h := Hanoi new +/// > h solve: 3 from: "A" to: "C" via: "B" +/// Move disk from A to C +/// Move disk from A to B +/// Move disk from C to B +/// Move disk from A to C +/// Move disk from B to A +/// Move disk from B to C +/// Move disk from A to C +/// nil Object subclass: Hanoi solve: n from: source to: target via: auxiliary => diff --git a/examples/getting-started/src/hello.bt b/examples/getting-started/src/hello.bt index c7832cd1e..469ccf22d 100644 --- a/examples/getting-started/src/hello.bt +++ b/examples/getting-started/src/hello.bt @@ -1,15 +1,14 @@ // Copyright 2026 James Casey // SPDX-License-Identifier: Apache-2.0 -// Simple hello world example -// -// Try it in the REPL: -// $ beamtalk repl -// > :load examples/hello.bt -// Loaded Hello -// > Hello new -// {__class__: Hello} - +/// Simple hello world example +/// +/// Try it in the REPL: +/// $ beamtalk repl +/// > :load examples/hello.bt +/// Loaded Hello +/// > Hello new +/// {__class__: Hello} Object subclass: Hello greeting => "Hello, World!" diff --git a/examples/getting-started/src/logging_counter.bt b/examples/getting-started/src/logging_counter.bt index fd3c9574d..d3b4c6ab8 100644 --- a/examples/getting-started/src/logging_counter.bt +++ b/examples/getting-started/src/logging_counter.bt @@ -1,16 +1,15 @@ // Copyright 2026 James Casey // SPDX-License-Identifier: Apache-2.0 -// LoggingCounter demonstrates the "super" keyword for calling superclass methods -// -// This class extends Counter and adds logging functionality. -// When increment is called, it logs the action and then delegates -// to the superclass implementation using "super". -// -// IMPORTANT: Load counter.bt first to define the Counter class: -// > :load examples/counter.bt -// > :load examples/logging_counter.bt - +/// LoggingCounter demonstrates the "super" keyword for calling superclass methods +/// +/// This class extends Counter and adds logging functionality. +/// When increment is called, it logs the action and then delegates +/// to the superclass implementation using "super". +/// +/// IMPORTANT: Load counter.bt first to define the Counter class: +/// > :load examples/counter.bt +/// > :load examples/logging_counter.bt Counter subclass: LoggingCounter // Override increment to add logging before delegating to superclass diff --git a/examples/getting-started/src/point.bt b/examples/getting-started/src/point.bt index 44f97b37f..38c1e2eb9 100644 --- a/examples/getting-started/src/point.bt +++ b/examples/getting-started/src/point.bt @@ -1,24 +1,23 @@ // Copyright 2026 James Casey // SPDX-License-Identifier: Apache-2.0 -// Point — a 2D point value object (BT-926 example). -// -// Demonstrates the `Value subclass:` pattern (ADR 0042): -// - Three construction forms: new, new:, keyword constructor -// - Auto-generated getters and with*: functional setters -// - Immutability: originals are never modified -// - Value equality: two Points with the same coordinates are == -// - User-defined methods on a value type -// - Usage in collections (collect:, select:, inject:into:) -// -// Try it in the REPL: -// $ beamtalk repl -// > :load src/point.bt -// > p := Point x: 3 y: 4 -// > p distanceSquared => 25 -// > (p withX: 0) distanceSquared => 16 -// > (Point x: 3 y: 4) == (Point x: 3 y: 4) => true - +/// Point — a 2D point value object (BT-926 example). +/// +/// Demonstrates the `Value subclass:` pattern (ADR 0042): +/// - Three construction forms: new, new:, keyword constructor +/// - Auto-generated getters and with*: functional setters +/// - Immutability: originals are never modified +/// - Value equality: two Points with the same coordinates are == +/// - User-defined methods on a value type +/// - Usage in collections (collect:, select:, inject:into:) +/// +/// Try it in the REPL: +/// $ beamtalk repl +/// > :load src/point.bt +/// > p := Point x: 3 y: 4 +/// > p distanceSquared => 25 +/// > (p withX: 0) distanceSquared => 16 +/// > (Point x: 3 y: 4) == (Point x: 3 y: 4) => true Value subclass: Point state: x = 0 state: y = 0 diff --git a/examples/getting-started/src/protoobject_proxy.bt b/examples/getting-started/src/protoobject_proxy.bt index 24aaf92cb..f0f2616ee 100644 --- a/examples/getting-started/src/protoobject_proxy.bt +++ b/examples/getting-started/src/protoobject_proxy.bt @@ -53,10 +53,10 @@ // // ============================================================================= -// TransparentProxy - Forwards all unknown messages to a target object -// -// This demonstrates ProtoObject's doesNotUnderstand:args: and perform:withArguments: -// working together to create a proxy that's indistinguishable from the target. +/// TransparentProxy - Forwards all unknown messages to a target object +/// +/// This demonstrates ProtoObject's doesNotUnderstand:args: and perform:withArguments: +/// working together to create a proxy that's indistinguishable from the target. Actor subclass: TransparentProxy state: target = nil diff --git a/examples/gof-patterns/src/adapter/celsius_thermometer.bt b/examples/gof-patterns/src/adapter/celsius_thermometer.bt index 01dc896fa..28a98e431 100644 --- a/examples/gof-patterns/src/adapter/celsius_thermometer.bt +++ b/examples/gof-patterns/src/adapter/celsius_thermometer.bt @@ -1,14 +1,13 @@ // Copyright 2026 James Casey // SPDX-License-Identifier: Apache-2.0 -// Adapter Pattern — CelsiusThermometer (adaptee) -// Intent: Convert the interface of a class into another interface clients expect. -// Adapter lets classes work together that couldn't otherwise because of -// incompatible interfaces. -// -// CelsiusThermometer is an existing class whose interface we cannot change. -// It speaks only Celsius. CelsiusToFahrenheitAdapter wraps it to speak Fahrenheit. - +/// Adapter Pattern — CelsiusThermometer (adaptee) +/// Intent: Convert the interface of a class into another interface clients expect. +/// Adapter lets classes work together that couldn't otherwise because of +/// incompatible interfaces. +/// +/// CelsiusThermometer is an existing class whose interface we cannot change. +/// It speaks only Celsius. CelsiusToFahrenheitAdapter wraps it to speak Fahrenheit. Object subclass: CelsiusThermometer state: celsius = 0.0 diff --git a/examples/gof-patterns/src/adapter/celsius_to_fahrenheit_adapter.bt b/examples/gof-patterns/src/adapter/celsius_to_fahrenheit_adapter.bt index 5bc445256..1da78ac06 100644 --- a/examples/gof-patterns/src/adapter/celsius_to_fahrenheit_adapter.bt +++ b/examples/gof-patterns/src/adapter/celsius_to_fahrenheit_adapter.bt @@ -1,16 +1,15 @@ // Copyright 2026 James Casey // SPDX-License-Identifier: Apache-2.0 -// Adapter Pattern — CelsiusToFahrenheitAdapter -// Wraps a CelsiusThermometer (adaptee) and exposes the FahrenheitThermometer -// interface (target), translating units on the fly. -// -// Usage: -// sensor := CelsiusThermometer withCelsius: 100.0. -// adapted := CelsiusToFahrenheitAdapter wrap: sensor. -// adapted readFahrenheit // => 212.0 -// adapted readCelsius // => 100.0 - +/// Adapter Pattern — CelsiusToFahrenheitAdapter +/// Wraps a CelsiusThermometer (adaptee) and exposes the FahrenheitThermometer +/// interface (target), translating units on the fly. +/// +/// Usage: +/// sensor := CelsiusThermometer withCelsius: 100.0. +/// adapted := CelsiusToFahrenheitAdapter wrap: sensor. +/// adapted readFahrenheit // => 212.0 +/// adapted readCelsius // => 100.0 FahrenheitThermometer subclass: CelsiusToFahrenheitAdapter state: adaptee = nil diff --git a/examples/gof-patterns/src/adapter/fahrenheit_thermometer.bt b/examples/gof-patterns/src/adapter/fahrenheit_thermometer.bt index da18820b9..ed84c679c 100644 --- a/examples/gof-patterns/src/adapter/fahrenheit_thermometer.bt +++ b/examples/gof-patterns/src/adapter/fahrenheit_thermometer.bt @@ -1,9 +1,8 @@ // Copyright 2026 James Casey // SPDX-License-Identifier: Apache-2.0 -// Adapter Pattern — FahrenheitThermometer (target interface) -// The interface that client code expects: readings in both Fahrenheit and Celsius. - +/// Adapter Pattern — FahrenheitThermometer (target interface) +/// The interface that client code expects: readings in both Fahrenheit and Celsius. Object subclass: FahrenheitThermometer /// Return the current temperature in degrees Fahrenheit. readFahrenheit => self subclassResponsibility diff --git a/examples/gof-patterns/src/builder/html_builder.bt b/examples/gof-patterns/src/builder/html_builder.bt index 6eef6ce74..8e4675aa4 100644 --- a/examples/gof-patterns/src/builder/html_builder.bt +++ b/examples/gof-patterns/src/builder/html_builder.bt @@ -1,18 +1,17 @@ // Copyright 2026 James Casey // SPDX-License-Identifier: Apache-2.0 -// Builder Pattern — HtmlBuilder -// Fluently assembles HtmlElement objects step-by-step. Because all values are -// immutable, each step returns a new builder — callers chain calls and finish -// with build to obtain the completed HtmlElement. -// -// Usage: -// el := ((HtmlBuilder buildTag: "a") -// withAttr: "href" value: "https://example.com") -// withText: "Click here"; -// build. -// el render // => "Click here" - +/// Builder Pattern — HtmlBuilder +/// Fluently assembles HtmlElement objects step-by-step. Because all values are +/// immutable, each step returns a new builder — callers chain calls and finish +/// with build to obtain the completed HtmlElement. +/// +/// Usage: +/// el := ((HtmlBuilder buildTag: "a") +/// withAttr: "href" value: "https://example.com") +/// withText: "Click here"; +/// build. +/// el render // => "Click here" Object subclass: HtmlBuilder state: element = nil diff --git a/examples/gof-patterns/src/builder/html_element.bt b/examples/gof-patterns/src/builder/html_element.bt index bd529a2fa..61e5fb58c 100644 --- a/examples/gof-patterns/src/builder/html_element.bt +++ b/examples/gof-patterns/src/builder/html_element.bt @@ -1,12 +1,11 @@ // Copyright 2026 James Casey // SPDX-License-Identifier: Apache-2.0 -// Builder Pattern — HtmlElement (the product) -// Intent: Separate the construction of a complex object from its representation. -// -// HtmlElement is an immutable value object. Its state is assembled step-by-step -// by HtmlBuilder. Callers never construct HtmlElement directly. - +/// Builder Pattern — HtmlElement (the product) +/// Intent: Separate the construction of a complex object from its representation. +/// +/// HtmlElement is an immutable value object. Its state is assembled step-by-step +/// by HtmlBuilder. Callers never construct HtmlElement directly. Object subclass: HtmlElement state: tag = "div" state: attributes = #{} diff --git a/examples/gof-patterns/src/command/command_history.bt b/examples/gof-patterns/src/command/command_history.bt index f9b1cc05b..4de01912f 100644 --- a/examples/gof-patterns/src/command/command_history.bt +++ b/examples/gof-patterns/src/command/command_history.bt @@ -1,18 +1,17 @@ // Copyright 2026 James Casey // SPDX-License-Identifier: Apache-2.0 -// Command Pattern — CommandHistory (invoker) -// Executes commands on a TextBuffer, tracking buffer snapshots for undo support. -// Each execute: runs the command first, then saves the previous buffer state. -// undo restores the most recent saved state. No command needs to implement its own undo logic. -// -// Usage: -// h := CommandHistory on: (TextBuffer withText: "hello"). -// h := h execute: (InsertCommand at: 6 insert: " world"). -// h buffer text // => "hello world" -// h := h undo. -// h buffer text // => "hello" - +/// Command Pattern — CommandHistory (invoker) +/// Executes commands on a TextBuffer, tracking buffer snapshots for undo support. +/// Each execute: runs the command first, then saves the previous buffer state. +/// undo restores the most recent saved state. No command needs to implement its own undo logic. +/// +/// Usage: +/// h := CommandHistory on: (TextBuffer withText: "hello"). +/// h := h execute: (InsertCommand at: 6 insert: " world"). +/// h buffer text // => "hello world" +/// h := h undo. +/// h buffer text // => "hello" Object subclass: CommandHistory state: buffer = nil state: history = #() // stack of prior buffer snapshots diff --git a/examples/gof-patterns/src/command/delete_command.bt b/examples/gof-patterns/src/command/delete_command.bt index de01f4fd7..4d14c9c5b 100644 --- a/examples/gof-patterns/src/command/delete_command.bt +++ b/examples/gof-patterns/src/command/delete_command.bt @@ -1,10 +1,9 @@ // Copyright 2026 James Casey // SPDX-License-Identifier: Apache-2.0 -// Command Pattern — DeleteCommand (concrete command) -// Deletes len characters starting at pos (1-based). -// Undo is provided by CommandHistory snapshot rollback, not by this class. - +/// Command Pattern — DeleteCommand (concrete command) +/// Deletes len characters starting at pos (1-based). +/// Undo is provided by CommandHistory snapshot rollback, not by this class. TextCommand subclass: DeleteCommand state: position = 1 state: length = 0 diff --git a/examples/gof-patterns/src/command/insert_command.bt b/examples/gof-patterns/src/command/insert_command.bt index 256b63073..2b7a774e3 100644 --- a/examples/gof-patterns/src/command/insert_command.bt +++ b/examples/gof-patterns/src/command/insert_command.bt @@ -1,9 +1,8 @@ // Copyright 2026 James Casey // SPDX-License-Identifier: Apache-2.0 -// Command Pattern — InsertCommand (concrete command) -// Inserts a string at a given position (1-based). - +/// Command Pattern — InsertCommand (concrete command) +/// Inserts a string at a given position (1-based). TextCommand subclass: InsertCommand state: position = 1 state: text = "" diff --git a/examples/gof-patterns/src/command/text_buffer.bt b/examples/gof-patterns/src/command/text_buffer.bt index 0be1193bc..71b95207d 100644 --- a/examples/gof-patterns/src/command/text_buffer.bt +++ b/examples/gof-patterns/src/command/text_buffer.bt @@ -1,14 +1,13 @@ // Copyright 2026 James Casey // SPDX-License-Identifier: Apache-2.0 -// Command Pattern — TextBuffer (receiver) -// Intent: Encapsulate a request as an object, letting you parameterise clients -// with different requests, queue or log requests, and support undoable operations. -// -// TextBuffer holds text content. Commands operate on it by calling insertAt:text: -// and deleteFrom:length:. Because value objects are immutable, both methods return -// a new TextBuffer — CommandHistory stores the successive snapshots. - +/// Command Pattern — TextBuffer (receiver) +/// Intent: Encapsulate a request as an object, letting you parameterise clients +/// with different requests, queue or log requests, and support undoable operations. +/// +/// TextBuffer holds text content. Commands operate on it by calling insertAt:text: +/// and deleteFrom:length:. Because value objects are immutable, both methods return +/// a new TextBuffer — CommandHistory stores the successive snapshots. Object subclass: TextBuffer state: text = "" diff --git a/examples/gof-patterns/src/command/text_command.bt b/examples/gof-patterns/src/command/text_command.bt index 912c607aa..b044e249e 100644 --- a/examples/gof-patterns/src/command/text_command.bt +++ b/examples/gof-patterns/src/command/text_command.bt @@ -1,11 +1,10 @@ // Copyright 2026 James Casey // SPDX-License-Identifier: Apache-2.0 -// Command Pattern — TextCommand (abstract command) -// Declares execute:, which takes a TextBuffer and returns a new TextBuffer. -// Undo is handled by CommandHistory, which saves buffer snapshots before each -// command so no command needs to implement its own reverse logic. - +/// Command Pattern — TextCommand (abstract command) +/// Declares execute:, which takes a TextBuffer and returns a new TextBuffer. +/// Undo is handled by CommandHistory, which saves buffer snapshots before each +/// command so no command needs to implement its own reverse logic. Object subclass: TextCommand /// Apply this command to buffer and return the resulting buffer. execute: _buffer => self subclassResponsibility diff --git a/examples/gof-patterns/src/composite/fs_dir.bt b/examples/gof-patterns/src/composite/fs_dir.bt index 4d446a197..615b7bb5f 100644 --- a/examples/gof-patterns/src/composite/fs_dir.bt +++ b/examples/gof-patterns/src/composite/fs_dir.bt @@ -1,19 +1,18 @@ // Copyright 2026 James Casey // SPDX-License-Identifier: Apache-2.0 -// Composite Pattern — FsDir (composite) -// A directory that holds any number of FsEntry objects (files or subdirectories). -// Because value objects are immutable, add: returns a new FsDir. -// Implements the same interface as FsFile (name, size, describe:) via duck typing. -// -// Usage: -// f1 := FsFile name: "main.bt" size: 120. -// f2 := FsFile name: "lib.bt" size: 340. -// src := ((FsDir name: "src") add: f1) add: f2. -// src size // => 460 -// src describe: "" -// // => "src/ (460 bytes)\n main.bt (120 bytes)\n lib.bt (340 bytes)" - +/// Composite Pattern — FsDir (composite) +/// A directory that holds any number of FsEntry objects (files or subdirectories). +/// Because value objects are immutable, add: returns a new FsDir. +/// Implements the same interface as FsFile (name, size, describe:) via duck typing. +/// +/// Usage: +/// f1 := FsFile name: "main.bt" size: 120. +/// f2 := FsFile name: "lib.bt" size: 340. +/// src := ((FsDir name: "src") add: f1) add: f2. +/// src size // => 460 +/// src describe: "" +/// // => "src/ (460 bytes)\n main.bt (120 bytes)\n lib.bt (340 bytes)" FsEntry subclass: FsDir state: name = "" state: children = #() diff --git a/examples/gof-patterns/src/composite/fs_entry.bt b/examples/gof-patterns/src/composite/fs_entry.bt index 9fc9b6c69..a25da18a3 100644 --- a/examples/gof-patterns/src/composite/fs_entry.bt +++ b/examples/gof-patterns/src/composite/fs_entry.bt @@ -1,11 +1,10 @@ // Copyright 2026 James Casey // SPDX-License-Identifier: Apache-2.0 -// Composite Pattern — FsEntry (abstract component) -// Intent: Compose objects into tree structures to represent part-whole hierarchies. -// Composite lets clients treat individual objects (FsFile) and compositions -// (FsDir) uniformly through a single interface. - +/// Composite Pattern — FsEntry (abstract component) +/// Intent: Compose objects into tree structures to represent part-whole hierarchies. +/// Composite lets clients treat individual objects (FsFile) and compositions +/// (FsDir) uniformly through a single interface. Object subclass: FsEntry /// Return the name of this entry (file or directory name, without path). name => self subclassResponsibility diff --git a/examples/gof-patterns/src/composite/fs_file.bt b/examples/gof-patterns/src/composite/fs_file.bt index bf13b9b82..3f0b843c0 100644 --- a/examples/gof-patterns/src/composite/fs_file.bt +++ b/examples/gof-patterns/src/composite/fs_file.bt @@ -1,15 +1,14 @@ // Copyright 2026 James Casey // SPDX-License-Identifier: Apache-2.0 -// Composite Pattern — FsFile (leaf) -// A single file with a fixed name and byte size. Has no children. -// Implements the same interface as FsDir (name, size, describe:) via duck typing. -// -// Usage: -// f := FsFile name: "main.bt" size: 120. -// f size // => 120 -// f describe: "" // => "main.bt (120 bytes)" - +/// Composite Pattern — FsFile (leaf) +/// A single file with a fixed name and byte size. Has no children. +/// Implements the same interface as FsDir (name, size, describe:) via duck typing. +/// +/// Usage: +/// f := FsFile name: "main.bt" size: 120. +/// f size // => 120 +/// f describe: "" // => "main.bt (120 bytes)" FsEntry subclass: FsFile state: name = "" state: size = 0 diff --git a/examples/gof-patterns/src/decorator/beverage.bt b/examples/gof-patterns/src/decorator/beverage.bt index 2dea5869d..8925fb49c 100644 --- a/examples/gof-patterns/src/decorator/beverage.bt +++ b/examples/gof-patterns/src/decorator/beverage.bt @@ -1,14 +1,13 @@ // Copyright 2026 James Casey // SPDX-License-Identifier: Apache-2.0 -// Decorator Pattern — Beverage (abstract component) -// Intent: Attach additional responsibilities to an object dynamically. -// Decorators provide a flexible alternative to subclassing for extending -// functionality by wrapping objects rather than changing their class. -// -// Any Beverage has a description and a cost. Both concrete beverages and -// condiment decorators satisfy this interface. - +/// Decorator Pattern — Beverage (abstract component) +/// Intent: Attach additional responsibilities to an object dynamically. +/// Decorators provide a flexible alternative to subclassing for extending +/// functionality by wrapping objects rather than changing their class. +/// +/// Any Beverage has a description and a cost. Both concrete beverages and +/// condiment decorators satisfy this interface. Object subclass: Beverage /// Return a human-readable description of this beverage and its condiments. description => self subclassResponsibility diff --git a/examples/gof-patterns/src/decorator/condiment_decorator.bt b/examples/gof-patterns/src/decorator/condiment_decorator.bt index 6e59b42e1..1c2905f6b 100644 --- a/examples/gof-patterns/src/decorator/condiment_decorator.bt +++ b/examples/gof-patterns/src/decorator/condiment_decorator.bt @@ -1,10 +1,9 @@ // Copyright 2026 James Casey // SPDX-License-Identifier: Apache-2.0 -// Decorator Pattern — CondimentDecorator (abstract decorator) -// Wraps any beverage object. Concrete subclasses override description and cost to -// add their own contribution on top of the wrapped drink's values. -// +/// Decorator Pattern — CondimentDecorator (abstract decorator) +/// Wraps any beverage object. Concrete subclasses override description and cost to +/// add their own contribution on top of the wrapped drink's values. Beverage subclass: CondimentDecorator state: beverage = nil diff --git a/examples/gof-patterns/src/decorator/espresso.bt b/examples/gof-patterns/src/decorator/espresso.bt index 57183c57a..698880511 100644 --- a/examples/gof-patterns/src/decorator/espresso.bt +++ b/examples/gof-patterns/src/decorator/espresso.bt @@ -1,8 +1,7 @@ // Copyright 2026 James Casey // SPDX-License-Identifier: Apache-2.0 -// Decorator Pattern — Espresso (concrete component) - +/// Decorator Pattern — Espresso (concrete component) Beverage subclass: Espresso /// Return "Espresso". description => "Espresso" diff --git a/examples/gof-patterns/src/decorator/house_blend.bt b/examples/gof-patterns/src/decorator/house_blend.bt index e20feca0e..f0447837a 100644 --- a/examples/gof-patterns/src/decorator/house_blend.bt +++ b/examples/gof-patterns/src/decorator/house_blend.bt @@ -1,8 +1,7 @@ // Copyright 2026 James Casey // SPDX-License-Identifier: Apache-2.0 -// Decorator Pattern — HouseBlend (concrete component) - +/// Decorator Pattern — HouseBlend (concrete component) Beverage subclass: HouseBlend /// Return "House Blend". description => "House Blend" diff --git a/examples/gof-patterns/src/decorator/milk.bt b/examples/gof-patterns/src/decorator/milk.bt index 18d85dcb3..34a0c7daa 100644 --- a/examples/gof-patterns/src/decorator/milk.bt +++ b/examples/gof-patterns/src/decorator/milk.bt @@ -1,8 +1,7 @@ // Copyright 2026 James Casey // SPDX-License-Identifier: Apache-2.0 -// Decorator Pattern — Milk (concrete decorator) - +/// Decorator Pattern — Milk (concrete decorator) CondimentDecorator subclass: Milk /// Append ", Milk" to the wrapped beverage's description. description => "{self.beverage description}, Milk" diff --git a/examples/gof-patterns/src/decorator/sugar.bt b/examples/gof-patterns/src/decorator/sugar.bt index a3726ae8d..d26901810 100644 --- a/examples/gof-patterns/src/decorator/sugar.bt +++ b/examples/gof-patterns/src/decorator/sugar.bt @@ -1,8 +1,7 @@ // Copyright 2026 James Casey // SPDX-License-Identifier: Apache-2.0 -// Decorator Pattern — Sugar (concrete decorator) - +/// Decorator Pattern — Sugar (concrete decorator) CondimentDecorator subclass: Sugar /// Append ", Sugar" to the wrapped beverage's description. description => "{self.beverage description}, Sugar" diff --git a/examples/gof-patterns/src/decorator/whipped_cream.bt b/examples/gof-patterns/src/decorator/whipped_cream.bt index 715752951..446097270 100644 --- a/examples/gof-patterns/src/decorator/whipped_cream.bt +++ b/examples/gof-patterns/src/decorator/whipped_cream.bt @@ -1,8 +1,7 @@ // Copyright 2026 James Casey // SPDX-License-Identifier: Apache-2.0 -// Decorator Pattern — WhippedCream (concrete decorator) - +/// Decorator Pattern — WhippedCream (concrete decorator) CondimentDecorator subclass: WhippedCream /// Append ", Whipped Cream" to the wrapped beverage's description. description => "{self.beverage description}, Whipped Cream" diff --git a/examples/gof-patterns/src/factory_method/circle.bt b/examples/gof-patterns/src/factory_method/circle.bt index 0bace7d9a..48ff8a834 100644 --- a/examples/gof-patterns/src/factory_method/circle.bt +++ b/examples/gof-patterns/src/factory_method/circle.bt @@ -1,8 +1,7 @@ // Copyright 2026 James Casey // SPDX-License-Identifier: Apache-2.0 -// Factory Method Pattern — Circle (concrete product) - +/// Factory Method Pattern — Circle (concrete product) Shape subclass: Circle state: radius = 1.0 diff --git a/examples/gof-patterns/src/factory_method/circle_factory.bt b/examples/gof-patterns/src/factory_method/circle_factory.bt index 8eb0feb5c..5d30b0dbe 100644 --- a/examples/gof-patterns/src/factory_method/circle_factory.bt +++ b/examples/gof-patterns/src/factory_method/circle_factory.bt @@ -1,8 +1,7 @@ // Copyright 2026 James Casey // SPDX-License-Identifier: Apache-2.0 -// Factory Method Pattern — CircleFactory (concrete creator) - +/// Factory Method Pattern — CircleFactory (concrete creator) ShapeFactory subclass: CircleFactory state: radius = 1.0 diff --git a/examples/gof-patterns/src/factory_method/rectangle.bt b/examples/gof-patterns/src/factory_method/rectangle.bt index 508294576..1bd438ffa 100644 --- a/examples/gof-patterns/src/factory_method/rectangle.bt +++ b/examples/gof-patterns/src/factory_method/rectangle.bt @@ -1,8 +1,7 @@ // Copyright 2026 James Casey // SPDX-License-Identifier: Apache-2.0 -// Factory Method Pattern — Rectangle (concrete product) - +/// Factory Method Pattern — Rectangle (concrete product) Shape subclass: Rectangle state: width = 1.0 state: height = 1.0 diff --git a/examples/gof-patterns/src/factory_method/rectangle_factory.bt b/examples/gof-patterns/src/factory_method/rectangle_factory.bt index 16e867cec..0d67c64f7 100644 --- a/examples/gof-patterns/src/factory_method/rectangle_factory.bt +++ b/examples/gof-patterns/src/factory_method/rectangle_factory.bt @@ -1,8 +1,7 @@ // Copyright 2026 James Casey // SPDX-License-Identifier: Apache-2.0 -// Factory Method Pattern — RectangleFactory (concrete creator) - +/// Factory Method Pattern — RectangleFactory (concrete creator) ShapeFactory subclass: RectangleFactory state: width = 1.0 state: height = 1.0 diff --git a/examples/gof-patterns/src/factory_method/shape.bt b/examples/gof-patterns/src/factory_method/shape.bt index c233f0841..199a1582c 100644 --- a/examples/gof-patterns/src/factory_method/shape.bt +++ b/examples/gof-patterns/src/factory_method/shape.bt @@ -1,10 +1,9 @@ // Copyright 2026 James Casey // SPDX-License-Identifier: Apache-2.0 -// Factory Method Pattern — Shape (abstract product) -// Intent: Define the common product interface implemented by concrete shapes -// created by factory method creators. - +/// Factory Method Pattern — Shape (abstract product) +/// Intent: Define the common product interface implemented by concrete shapes +/// created by factory method creators. Object subclass: Shape /// Return the area of this shape. area => self subclassResponsibility diff --git a/examples/gof-patterns/src/factory_method/shape_factory.bt b/examples/gof-patterns/src/factory_method/shape_factory.bt index 986ce655b..4c8464587 100644 --- a/examples/gof-patterns/src/factory_method/shape_factory.bt +++ b/examples/gof-patterns/src/factory_method/shape_factory.bt @@ -1,11 +1,10 @@ // Copyright 2026 James Casey // SPDX-License-Identifier: Apache-2.0 -// Factory Method Pattern — ShapeFactory (abstract creator) -// Declares the factory method createShape and a template method describeShape -// that uses it, demonstrating that the base class can call the factory method -// without knowing which concrete product will be returned. - +/// Factory Method Pattern — ShapeFactory (abstract creator) +/// Declares the factory method createShape and a template method describeShape +/// that uses it, demonstrating that the base class can call the factory method +/// without knowing which concrete product will be returned. Object subclass: ShapeFactory /// Factory method — subclasses override this to return the appropriate Shape. createShape => self subclassResponsibility diff --git a/examples/gof-patterns/src/main.bt b/examples/gof-patterns/src/main.bt index dfc7b22e8..36141140a 100644 --- a/examples/gof-patterns/src/main.bt +++ b/examples/gof-patterns/src/main.bt @@ -1,10 +1,9 @@ // Copyright 2026 James Casey // SPDX-License-Identifier: Apache-2.0 -// Main entry point for gang_of_four. -// Auto-runs via [run].entry in beamtalk.toml when you start `beamtalk repl`. -// Or load manually: :load src/main.bt - +/// Main entry point for gang_of_four. +/// Auto-runs via [run].entry in beamtalk.toml when you start `beamtalk repl`. +/// Or load manually: :load src/main.bt Object subclass: Main class run => diff --git a/examples/gof-patterns/src/observer/event_bus.bt b/examples/gof-patterns/src/observer/event_bus.bt index 3f2e1ad72..1e51e415f 100644 --- a/examples/gof-patterns/src/observer/event_bus.bt +++ b/examples/gof-patterns/src/observer/event_bus.bt @@ -1,21 +1,20 @@ // Copyright 2026 James Casey // SPDX-License-Identifier: Apache-2.0 -// Observer Pattern — EventBus (subject) -// Intent: Define a one-to-many dependency so that when one object changes state, -// all its dependents are notified automatically. -// -// EventBus is an Actor (a BEAM process) so its subscriber list can be safely -// shared and mutated across the system. Observers are any actors that respond -// to receive:. -// -// Usage: -// bus := EventBus spawn. -// watcher := EventCollector spawn. -// bus subscribe: watcher. -// bus notify: "order.placed". -// watcher eventCount // => 1 - +/// Observer Pattern — EventBus (subject) +/// Intent: Define a one-to-many dependency so that when one object changes state, +/// all its dependents are notified automatically. +/// +/// EventBus is an Actor (a BEAM process) so its subscriber list can be safely +/// shared and mutated across the system. Observers are any actors that respond +/// to receive:. +/// +/// Usage: +/// bus := EventBus spawn. +/// watcher := EventCollector spawn. +/// bus subscribe: watcher. +/// bus notify: "order.placed". +/// watcher eventCount // => 1 Actor subclass: EventBus state: subscribers = #() diff --git a/examples/gof-patterns/src/observer/event_collector.bt b/examples/gof-patterns/src/observer/event_collector.bt index 717b3fbf0..43fa3d348 100644 --- a/examples/gof-patterns/src/observer/event_collector.bt +++ b/examples/gof-patterns/src/observer/event_collector.bt @@ -1,10 +1,9 @@ // Copyright 2026 James Casey // SPDX-License-Identifier: Apache-2.0 -// Observer Pattern — EventCollector (concrete observer) -// Accumulates every event it receives. Useful as a test double and as a simple -// audit log. Real observers would react to events (update UI, write to DB, etc.). - +/// Observer Pattern — EventCollector (concrete observer) +/// Accumulates every event it receives. Useful as a test double and as a simple +/// audit log. Real observers would react to events (update UI, write to DB, etc.). Actor subclass: EventCollector state: events = #() diff --git a/examples/gof-patterns/src/singleton/app_logger.bt b/examples/gof-patterns/src/singleton/app_logger.bt index acea82edd..a34019ced 100644 --- a/examples/gof-patterns/src/singleton/app_logger.bt +++ b/examples/gof-patterns/src/singleton/app_logger.bt @@ -1,21 +1,20 @@ // Copyright 2026 James Casey // SPDX-License-Identifier: Apache-2.0 -// Singleton Pattern — AppLogger -// Intent: Ensure a class has only one instance and provide a global point of access. -// -// In Beamtalk/BEAM the idiomatic Singleton is a named actor process. -// Spawn AppLogger once at application startup and share the actor reference. -// Because the reference is a PID there is exactly one instance per node, -// enforced by the BEAM scheduler — no synchronisation boilerplate needed. -// -// Usage: -// logger := AppLogger spawn. // spawn once; share this reference -// logger log: "app started". -// logger log: "processing request". -// logger size // => 2 -// logger entries // => #("app started", "processing request") - +/// Singleton Pattern — AppLogger +/// Intent: Ensure a class has only one instance and provide a global point of access. +/// +/// In Beamtalk/BEAM the idiomatic Singleton is a named actor process. +/// Spawn AppLogger once at application startup and share the actor reference. +/// Because the reference is a PID there is exactly one instance per node, +/// enforced by the BEAM scheduler — no synchronisation boilerplate needed. +/// +/// Usage: +/// logger := AppLogger spawn. // spawn once; share this reference +/// logger log: "app started". +/// logger log: "processing request". +/// logger size // => 2 +/// logger entries // => #("app started", "processing request") Actor subclass: AppLogger state: entries = #() diff --git a/examples/gof-patterns/src/strategy/sorter.bt b/examples/gof-patterns/src/strategy/sorter.bt index 6074ce573..ebb469d66 100644 --- a/examples/gof-patterns/src/strategy/sorter.bt +++ b/examples/gof-patterns/src/strategy/sorter.bt @@ -1,23 +1,22 @@ // Copyright 2026 James Casey // SPDX-License-Identifier: Apache-2.0 -// Strategy Pattern — Sorter -// Intent: Define a family of algorithms, encapsulate each one, and make them -// interchangeable. The algorithm varies independently from the clients that use it. -// -// Sorter holds a pluggable comparison block (the strategy) and applies it to sort -// any list. Factory methods provide the most common orderings. -// -// Usage: -// asc := Sorter ascending. -// asc sort: #(3, 1, 2). // => #(1, 2, 3) -// -// desc := Sorter descending. -// desc sort: #(3, 1, 2). // => #(3, 2, 1) -// -// byLen := Sorter withStrategy: [:a :b | a length < b length]. -// byLen sort: #("banana", "fig", "apple"). // smallest first - +/// Strategy Pattern — Sorter +/// Intent: Define a family of algorithms, encapsulate each one, and make them +/// interchangeable. The algorithm varies independently from the clients that use it. +/// +/// Sorter holds a pluggable comparison block (the strategy) and applies it to sort +/// any list. Factory methods provide the most common orderings. +/// +/// Usage: +/// asc := Sorter ascending. +/// asc sort: #(3, 1, 2). // => #(1, 2, 3) +/// +/// desc := Sorter descending. +/// desc sort: #(3, 1, 2). // => #(3, 2, 1) +/// +/// byLen := Sorter withStrategy: [:a :b | a length < b length]. +/// byLen sort: #("banana", "fig", "apple"). // smallest first Object subclass: Sorter state: strategy = nil diff --git a/examples/gof-patterns/src/template_method/csv_exporter.bt b/examples/gof-patterns/src/template_method/csv_exporter.bt index 7a2c30da2..57c76385f 100644 --- a/examples/gof-patterns/src/template_method/csv_exporter.bt +++ b/examples/gof-patterns/src/template_method/csv_exporter.bt @@ -1,14 +1,13 @@ // Copyright 2026 James Casey // SPDX-License-Identifier: Apache-2.0 -// Template Method Pattern — CsvExporter -// Formats rows as comma-separated values. -// -// Usage: -// rows := #(#("Alice", "30"), #("Bob", "25")). -// CsvExporter new export: rows -// // => "Alice,30\nBob,25\n" - +/// Template Method Pattern — CsvExporter +/// Formats rows as comma-separated values. +/// +/// Usage: +/// rows := #(#("Alice", "30"), #("Bob", "25")). +/// CsvExporter new export: rows +/// // => "Alice,30\nBob,25\n" DataExporter subclass: CsvExporter /// No header line for CSV output. header => "" diff --git a/examples/gof-patterns/src/template_method/data_exporter.bt b/examples/gof-patterns/src/template_method/data_exporter.bt index b5ad1ce98..912c85c38 100644 --- a/examples/gof-patterns/src/template_method/data_exporter.bt +++ b/examples/gof-patterns/src/template_method/data_exporter.bt @@ -1,14 +1,13 @@ // Copyright 2026 James Casey // SPDX-License-Identifier: Apache-2.0 -// Template Method Pattern — DataExporter (abstract base) -// Intent: Define the skeleton of an algorithm in a base-class method, deferring -// specific steps to subclasses. The overall structure stays fixed; only the -// customisable steps change. -// -// export: is the template method. It calls header, formatRow:, and footer in -// order. Subclasses (CsvExporter, HtmlExporter) implement those three hooks. - +/// Template Method Pattern — DataExporter (abstract base) +/// Intent: Define the skeleton of an algorithm in a base-class method, deferring +/// specific steps to subclasses. The overall structure stays fixed; only the +/// customisable steps change. +/// +/// export: is the template method. It calls header, formatRow:, and footer in +/// order. Subclasses (CsvExporter, HtmlExporter) implement those three hooks. Object subclass: DataExporter /// Template method — fixed algorithm skeleton. diff --git a/examples/gof-patterns/src/template_method/html_exporter.bt b/examples/gof-patterns/src/template_method/html_exporter.bt index 39efbd52c..3db909fe8 100644 --- a/examples/gof-patterns/src/template_method/html_exporter.bt +++ b/examples/gof-patterns/src/template_method/html_exporter.bt @@ -1,14 +1,13 @@ // Copyright 2026 James Casey // SPDX-License-Identifier: Apache-2.0 -// Template Method Pattern — HtmlExporter -// Formats rows as an HTML table. -// -// Usage: -// rows := #(#("Alice", "30"), #("Bob", "25")). -// HtmlExporter new export: rows -// // => "\n\n...\n
Alice30
\n" - +/// Template Method Pattern — HtmlExporter +/// Formats rows as an HTML table. +/// +/// Usage: +/// rows := #(#("Alice", "30"), #("Bob", "25")). +/// HtmlExporter new export: rows +/// // => "\n\n...\n
Alice30
\n" DataExporter subclass: HtmlExporter /// Return the opening tag. header => "
\n" diff --git a/stdlib/src/Boolean.bt b/stdlib/src/Boolean.bt index 686d9503b..c2f4db9a1 100644 --- a/stdlib/src/Boolean.bt +++ b/stdlib/src/Boolean.bt @@ -13,7 +13,6 @@ /// true and: [false] // => false /// false or: [true] // => true /// ``` - abstract Value subclass: Boolean // === Abstract protocol (subclasses must implement) === diff --git a/stdlib/src/ClassBuilder.bt b/stdlib/src/ClassBuilder.bt index 6ad8e8ee2..e83243eb9 100644 --- a/stdlib/src/ClassBuilder.bt +++ b/stdlib/src/ClassBuilder.bt @@ -21,7 +21,6 @@ /// ## References /// * ADR 0038: `docs/ADR/0038-subclass-classbuilder-protocol.md` /// * Pattern: `stdlib/src/Actor.bt` (ClassBuilder is Actor subclass) - Actor subclass: ClassBuilder state: className = nil state: superclassRef = nil diff --git a/stdlib/src/False.bt b/stdlib/src/False.bt index 6d7b76b4a..057d730e6 100644 --- a/stdlib/src/False.bt +++ b/stdlib/src/False.bt @@ -12,7 +12,6 @@ /// false ifFalse: ["no"] // => "no" /// false not // => true /// ``` - sealed Boolean subclass: False /// If true, evaluate `trueBlock`; otherwise evaluate `falseBlock`. Returns `falseBlock` result. /// diff --git a/stdlib/src/TestResult.bt b/stdlib/src/TestResult.bt index b5561779d..b408d597f 100644 --- a/stdlib/src/TestResult.bt +++ b/stdlib/src/TestResult.bt @@ -15,7 +15,6 @@ /// result summary // => "5 tests, 5 passed (0.1s)" /// result failures // => [] or [#{ name => ..., error => ... }, ...] /// ``` - Object subclass: TestResult /// Number of test methods that passed. diff --git a/stdlib/src/TestRunner.bt b/stdlib/src/TestRunner.bt index def43f5bf..83730a92e 100644 --- a/stdlib/src/TestRunner.bt +++ b/stdlib/src/TestRunner.bt @@ -14,7 +14,6 @@ /// TestRunner run: CounterTest // => TestResult for one class /// TestRunner run: CounterTest method: #testIncrement // => one method /// ``` - Object subclass: TestRunner /// Run all test methods across all discovered TestCase subclasses. diff --git a/stdlib/src/True.bt b/stdlib/src/True.bt index 4eb227f9d..a1baf19d8 100644 --- a/stdlib/src/True.bt +++ b/stdlib/src/True.bt @@ -12,7 +12,6 @@ /// true ifTrue: ["yes"] // => "yes" /// true not // => false /// ``` - sealed Boolean subclass: True /// If true, evaluate `trueBlock`; otherwise evaluate `falseBlock`. Returns `trueBlock` result. ///