Home /Modules/advantage/SLAdvantageSink.sleela

SLAdvantageSink.sleela

lib/advantage/output/SLAdvantageSink.sleela · 202 line(s) · sleela

<< lib/advantage/output/SLAdvantageSink.sleela
   SLeeLa Standard Library Definition.
   Definition: An output sink for the advantage package -- routes rendered
   lines to the terminal, a CommonRails surface, a socket/connector, or a
   silent capture buffer. >>
#sleela 3.0
material;
artifact;
pure;
gasoline;
< Every advantage module can EMIT output; this sink decides WHERE it goes. >
< Targets: >
<   0 TERMINAL    -- print() to stdout / the controlling terminal >
<   1 COMMONRAILS -- print() a CommonRails-formatted line (same stdout surface, >
<                    but column-aligned via PrintRail; the emitter does the >
<                    formatting and hands the finished line here) >
<   2 SOCKET      -- frame the line and BUFFER it for a network connector. A >
<                    live socket is not available under `run`, so this target >
<                    records each framed line (newline-terminated) into a >
<                    capture the host can forward with slnet_write when running >
<                    natively. lastFrame()/drain()/frameCount() expose it. >
<   3 SILENT      -- capture only, no stdout (useful for tests). >
< TERMINAL and COMMONRAILS also append to the capture, so any target is >
< inspectable after the fact. >
class SLAdvantageSink {
  < ---- Descriptive metadata (version 1.11 nested-friendly accessors) ---- >
  << Eleven catalogued attributes with getter/setter pairs, so a GUI, loader,
     or catalog can read and (where appropriate) override this record.
     Values are faithful to the subject's real origin where publicly known. >>
  String metaVersion = "1.0.0";
  int metaId = 10560;
  String metaAuthor = "Kiro Agent";
  String metaDate = "2026-11-08";
  String metaCopyright = "SLeeLa project";
  String metaTrademark = "none";
  String metaCorporation = "none";
  < metaOrigin: National | <nation> | International | Galactic >
  String metaOrigin = "International";
  String metaBirthDate = "2026-11-08";
  < metaScienceRating: maturity/robustness on a 1..10 scale >
  int metaScienceRating = 8;
  < metaNationalSchedule: a real, citable instrument or "none" >
  String metaNationalSchedule = "none";

  String getMetaVersion() { return metaVersion; }
  void setMetaVersion(String v) { metaVersion = v; }
  int getMetaId() { return metaId; }
  void setMetaId(int v) { metaId = v; }
  String getAuthor() { return metaAuthor; }
  void setAuthor(String v) { metaAuthor = v; }
  String getDate() { return metaDate; }
  void setDate(String v) { metaDate = v; }
  String getCopyright() { return metaCopyright; }
  void setCopyright(String v) { metaCopyright = v; }
  String getTrademark() { return metaTrademark; }
  void setTrademark(String v) { metaTrademark = v; }
  String getCorporation() { return metaCorporation; }
  void setCorporation(String v) { metaCorporation = v; }
  String getOrigin() { return metaOrigin; }
  void setOrigin(String v) { metaOrigin = v; }
  String getBirthDate() { return metaBirthDate; }
  void setBirthDate(String v) { metaBirthDate = v; }
  int getScienceRating() { return metaScienceRating; }
  void setScienceRating(int v) { metaScienceRating = v; }
  String getNationalSchedule() { return metaNationalSchedule; }
  void setNationalSchedule(String v) { metaNationalSchedule = v; }

  < ---- Target constants (methods cost no layout slot) ---- >
  int TERMINAL()    { return 0; }
  int COMMONRAILS() { return 1; }
  int SOCKET()      { return 2; }
  int SILENT()      { return 3; }

  < ---- Sink state ---- >
  int target;
  < connector identity for the socket target, e.g. "host:port" >
  String endpoint;
  < capture of everything emitted (framed), joined with newlines >
  String capture;
  int lines;
  < SOCKET connector lifecycle: is the connector open, and how many content >
  < bytes have been handed to it (the wire-faithful byte account CommonRails >
  < also insists on, since Core has no string-length primitive). >
  boolean connectorOpen;
  int bytesWritten;

  void configure(int tgt) {
    target = tgt;
    endpoint = "none";
    capture = "";
    lines = 0;
    connectorOpen = false;
    bytesWritten = 0;
  }

  < For the SOCKET target: name the connector endpoint (modelled, not dialed). >
  < (Named bindEndpoint, not connect: connect is a reserved Munction builtin.) >
  void bindEndpoint(String ep) {
    endpoint = ep;
  }

  << Open the connector for the SOCKET target. Under `run` there is no live
     socket, so this marks the connector open and resets the byte account; a
     native host maps this to slnet_connect(endpoint). Idempotent. Returns
     true if the connector is open afterward (always true for a valid
     endpoint, false if no endpoint was bound). >>
  boolean openConnector() {
    if (endpoint == "none") { return false; }
    connectorOpen = true;
    return true;
  }

  < Close the connector (native: slnet_close). Idempotent. >
  void closeConnector() {
    connectorOpen = false;
  }

  boolean isOpen() { return connectorOpen; }

  int getTarget() { return target; }
  String getEndpoint() { return endpoint; }
  int frameCount() { return lines; }
  int getBytesWritten() { return bytesWritten; }

  < Append to the capture with a separating newline between frames. >
  void appendFrame(String framed) {
    if (lines == 0) { capture = framed; }
    else { capture = capture + "\n" + framed; }
    lines = lines + 1;
  }

  << The wire-write bridge for the SOCKET target. `framed` is the line already
     prefixed with the endpoint; `byteCount` is its length in bytes, supplied
     by the caller (Core has no string-length). Under `run` this buffers the
     frame and accrues the byte account; the native host replaces the body
     with slnet_write(handle, framed, byteCount). Returns the bytes accepted
     this call (0 if the connector is not open). >>
  int wireWrite(String framed, int byteCount) {
    if (connectorOpen == false) { return 0; }
    appendFrame(framed);
    bytesWritten = bytesWritten + byteCount;
    return byteCount;
  }

  << Emit one already-rendered line to the configured target. `byteCount` is
     the line's byte length (used only by the SOCKET target's wire account;
     ignored by the others). >>
  void emit(String line, int byteCount) {
    if (target == 0) {
      print(line);
      appendFrame(line);
    } else if (target == 1) {
      print(line);
      appendFrame(line);
    } else if (target == 2) {
      < Frame the line for the wire and hand it to the connector. Auto-open on >
      < first write so simple callers need not open explicitly. The endpoint >
      < prefix adds endpoint length + 3 ("[" "]" " ") to the byte account. >
      if (connectorOpen == false) { openConnector(); }
      String framed = "[" + endpoint + "] " + line;
      wireWrite(framed, byteCount + 3);
    } else {
      appendFrame(line);
    }
  }

  < Backward-compatible emit without a byte count (socket account uses 0 for >
  < the body; the endpoint prefix is still counted). >
  void emitLine(String line) {
    emit(line, 0);
  }

  < The most recent framed line (empty if nothing emitted). >
  String lastFrame() {
    return capture;
  }

  < Drain and clear the capture, returning everything buffered. A native >
  < socket producer calls this and writes the result to the connector. The >
  < byte account and open state are preserved across a drain (the connector >
  < stays open until closeConnector). >
  String drain() {
    String out = capture;
    capture = "";
    lines = 0;
    return out;
  }

  String targetName() {
    if (target == 0) { return "terminal"; }
    if (target == 1) { return "commonrails"; }
    if (target == 2) { return "socket"; }
    return "silent";
  }

  String describe() {
    return "sink target=" + targetName() + " endpoint=" + endpoint
         + " open=" + connectorOpen + " frames=" + lines
         + " bytes=" + bytesWritten;
  }
}