3.7 KiB

Raw Blame History

src/modules/opunk — Alternative Punk Namespace (voo-based classes)

Purpose

Modules under the opunk::* namespace explore value-based class implementations of punk facilities using the vendored voo OO system (src/vendormodules/voo-1.0.0.tm). Objects are plain Tcl list values; class namespaces hold the methods.

Ownership

Agents may edit modules here when working on voo-based reimplementations; the corresponding punk::* modules remain the production implementations until integration is explicitly done.
voo itself is a vendored dependency — change it via the vendormodules workflow, not here.

Local Contracts

Class namespaces are capitalized (::opunk::Str, ::opunk::Console); companion lowercase namespaces (::opunk::str, ::opunk::console) hold package-level procs, PUNKARGS docs and shared state.
Fields use the o_ prefix (even though voo private accessors already get a my. prefix) to distinguish fields from locals in -update method bodies and ease code movement to/from tclOO implementations.
voo makes each field name a class-namespace variable holding the field's list index — avoid variable o_<field> in method bodies.
Classes intended for behavioral subclassing are declared -virtual (slot 0 of each value is the concrete class namespace tag); behaviour-differentiating methods are declared -virtual so calls through the base class dispatch on the tag.
Entity-like objects (e.g. consoles) anchor canonical instances at well-known namespace variables (::opunk::console::instances::<name>) with lowercase wrapper procs owning mutation; the value semantics serve as snapshots/copies where cheap.
Cooperative shared state is pluggable rather than hardwired: the probe-byte waiting store is the array named by ::opunk::console::waiting_chunks_arrayvar (default ::opunk::console::waiting_chunks); integrating layers redirect it to their established store (punk::console::default_console points it at punk::console::input_chunks_waiting) so probe-consumed bytes stay visible to active readers.
Method-entry validity guards use [llength $this] < N (not != N) so field-adding subclasses keep working.
Module filenames use the -999999.0a1.0.tm magic suffix with <modulename>-buildversion.txt per parent conventions.
opunk::console (with its dependency voo) is included in bootsupport via src/bootsupport/modules/include_modules.config for eventual boot/repl-startup console objects; after releasing a new version, rebuild with make.tcl modules then refresh the snapshot with make.tcl bootsupport.

Work Guidance

Use ::opunk::Str (str module) as the reference for voo idioms: unshare/restore scripts, -update copy-on-write avoidance, explicit list-literal construction in constructors.
Keep opunk::console free of punk::console dependencies — integration is planned as punk::console delegating to the class, not the reverse.
Future capability to preserve: a subshell repl attached to a foreign console (e.g ssh channels, or a tk text widget acting as a terminal). Design rules that protect it: behaviour goes through -virtual methods so non-channel subclasses can override everything channel-related; o_in/o_out are uninterpreted strings (a widget subclass may store widget paths); instances are named-multi-anchor (never a singleton); and punk::console integration must keep migrating operations to object-method dispatch rather than entrenching raw channel operations after spec resolution.

Verification

tclsh src/tests/runtests.tcl -report compact -show-passes 0 -include-paths modules/opunk/<module>/** passes for the touched module.
tclsh src/make.tcl modules completes without errors after module additions.

Child DOX Index

(None — flat module files)

3.7 KiB Raw Blame History