Home /Modules/advantage/README.md

README.md

lib/advantage/connect/README.md · 87 line(s) · markdown

artifact; pure; gasoline;

lib/advantage/connect — the connectivity medium

The in-between component structure that connects Advantage™ SLeeLa programs to the outside world: databases, national clocks, networks, and money sources. It is a medium — a thin, uniform layer that sits between a pure Advantage model and the messy, stateful systems it must talk to — so the model code stays clean and every external call is validated, status-coded, and fault-recorded the same way.

artifact; pure; gasoline; — an Advantage™ subject. These classes model lifecycle and the native boundary; they do not dial a live database, clock, socket, or bank from inside the SLeeLa VM, and this is not financial advice.

The medium at a glance

ClassConnects toNative entry points (documented, host-adapter supplied)
SLConnectStatus— (shared)the universal integer status vocabulary (OK … NATIVE_ADAPTER_REQUIRED … INTERNAL)
SLConnectFault— (shared)the structured fault record every connector raises
SLSqlConnectorMySQL / databasesslsql_open / ping / execute / query / close (mirrors lib/connector/mysql)
SLClockConnectornational clocks / NTPslntp_open / sync / now / close
SLNetConnectornetwork connectivityslnet_connect / probe / write / close
SLMoneyConnectormoney sources (banks, cards, wallets)slbank_open / authorize / capture / refund / void / close

A runnable connect-demo.sleela drives all four through their lifecycle, their native-adapter boundary, and a fault path, and ends in ALL CHECKS PASSED.

Exception handling for all classes of perform

SLeeLa the language has try/catch/throw, but the standard library signals failure with integer status codes plus a structured fault record — a single, uniform convention across every connector. That is the "exception handling for all these classes of perform":

Every method returns a status code; a non-OK code leaves a fully populated fault behind. No connector throws.

The native boundary (where the real connection plugs in)

Each connector models its lifecycle and accounting in the VM (so a program can be written, type-checked, and validated offline) and defers the operation that actually touches the outside world to a host adapter, returning NATIVE_ADAPTER_REQUIRED(9). The native entry points are named in each class's header doc comment (and in the table above); a host runtime registers adapters that implement them. This mirrors the existing precedent in lib/advantage/output/SLAdvantageSink.sleela (slnet_*) and the native ABI in lib/connector/mysql.

Host-adapter callbacks let a real result flow back in without breaking the status model: SLClockConnector.acceptSync(offset, stratum), SLNetConnector.acceptProbe(rtt), and SLMoneyConnector.acceptAuthorization / declineAuthorization.

Safety notes baked into the classes

Run it

./working-binaries/sleela run lib/advantage/connect/connect-demo.sleela