Home /Modules/impl/common_rails_banner.hpp

common_rails_banner.hpp

impl/frontend/common_rails_banner.hpp · 154 line(s) · c

// ===========================================================================
// common_rails_banner.hpp -- route toolchain banners through CommonRails.
// ===========================================================================
// A thin adapter over the native CommonRails "heritage" printing layer
// (common-rails/heritage/printing/cpp/CommonRailsPrinting.hpp), so the four
// SLeeLa output producers -- the compiler (Sleelvac), the Nordshrift
// transpiler, running programs, and the debugger -- share ONE professional
// printing surface instead of ad-hoc std::cout lines. This mirrors the
// Sleela-side /lib/common-rails PrintRail class: the same component lines,
// state-labelled status lines, progress square, and 21x21 cell model.
//
// CONTRACT PRESERVATION: several banner lines are machine-parsed by the test
// suite and by downstream tooling (e.g. "sleelvac: <src> -> <dst> (runnable
// Sleela Core artifact)", Nordshrift's "0 error(s)" / "OK: target-language").
// The helpers here are OPT-IN decoration for human-progress banners; the exact
// contract strings are emitted verbatim by their call sites and are NOT routed
// through a formatter that could change their text. Where a helper does wrap a
// contract token, it embeds that token unchanged.
//
// The CommonRails state vocabulary (Beautiful Design): START, WORKING,
// PROGRESS, COMPLETE, WARN, ERROR.
#ifndef SLEELA_COMMON_RAILS_BANNER_H
#define SLEELA_COMMON_RAILS_BANNER_H

#include "CommonRailsPrinting.hpp"   // commonrails::printing (heritage layer)
#include <ostream>
#include <iostream>
#include <string>
#include <cstdio>
#if defined(_WIN32)
#  include <io.h>
#  define SLEELA_ISATTY(fd) _isatty(fd)
#else
#  include <unistd.h>
#  define SLEELA_ISATTY(fd) isatty(fd)
#endif
// Portable short sleep for the transient "Loading ..." hold (header-only, no
// extra link deps): std::this_thread::sleep_for is fine for a one-shot banner.
#include <chrono>
#include <thread>
#define SLEELA_BANNER_SLEEP_MS(ms) \
    std::this_thread::sleep_for(std::chrono::milliseconds(ms))

namespace sleela { namespace rails {

using commonrails::printing::PrintState;
using commonrails::printing::PrintComponent;
using commonrails::printing::PrintFormatter;
using commonrails::printing::PrintRenderer;
using commonrails::printing::PrintProgress;
using commonrails::printing::PrintLayout;

// ---------------------------------------------------------------------------
// Product brand line.
//
// Prints the tool's trademarked product name (e.g. "Sleelvac(TM)") on its own
// line, in RED + CLASSIC (ANSI SGR 31 -- normal-intensity red, no bold/bright),
// then resets so the tool's natural output below stays the terminal default
// (white/classic). It is the first thing a user sees when they compile or run.
//
// COLOR IS PRESENTATION-ONLY (Beautiful Design sec 7: "Color ... Optional; it
// does not change width semantics" / "readable when color is unavailable").
// The whole line is therefore TTY-GATED: it is emitted ONLY when the target
// stream is an interactive terminal. Under a pipe, a redirect, or test capture
// (every harness uses $(... 2>&1)), nothing is emitted -- so machine-parsed
// output is byte-for-byte unchanged and no escape codes ever leak into logs.
//
// `streamFd` is the destination's file descriptor: 1 (stdout) for std::cout,
// 2 (stderr) for std::cerr. The brand goes to the same stream the natural
// output will use, so the two are never split across stdout/stderr.
inline bool brandColorEnabled(int streamFd) {
    return SLEELA_ISATTY(streamFd) != 0;
}
inline void brand(std::ostream& o, int streamFd, const std::string& product) {
    if (!brandColorEnabled(streamFd)) return;               // plain contexts: no brand line
    o << "\033[31m" << product << "\u2122" << "\033[0m\n";   // red + classic, then reset
}
// Convenience: the product identities, to stdout (fd 1) or stderr (fd 2).
inline void brandSleelvac(std::ostream& o, int fd)   { brand(o, fd, "Sleelvac"); }
inline void brandSleela(std::ostream& o, int fd)     { brand(o, fd, "Sleela"); }
inline void brandNordshrift(std::ostream& o, int fd) { brand(o, fd, "Nordshrift"); }
// Advantage(TM): the /lib/advantage library family's product identity, rendered
// in the same customary red + classic as Sleela and Sleelvac. TTY-gated, so it
// decorates interactive output only and never pollutes machine-parsed logs.
inline void brandAdvantage(std::ostream& o, int fd)  { brand(o, fd, "Advantage"); }

// ---------------------------------------------------------------------------
// Transient subsystem "Loading ..." banner (Beautiful Design, Option B).
//
// Prints a short red "Loading <Subsystem>(TM)" line while a subsystem warms up
// (the Registry seeding its defaults, Modium resolving its catalog), then makes
// that line DISAPPEAR before the subsystem's normal output begins -- so the
// user sees a brief, calm "loading" flash that leaves no residue above the real
// output. This is used ONLY by the dedicated subsystem entry points
// (`sleela registry`, `sleela modium`) and the installer first-run, NOT by
// every `sleela run` of a user program.
//
// Mechanics mirror the SleelaTerminal transient banner (sleela-terminal/slsh.cpp):
//   \r        -- return to column 1
//   \033[2K   -- erase the entire current line
// The line is drawn, briefly held, then erased in place with "\r\033[2K", so
// the cursor ends exactly where the banner began and the following output
// overwrites nothing.
//
// STRICT TTY GATE + NO-OP OFF-TERMINAL: like brand(), the whole effect is
// emitted only to an interactive terminal (brandColorEnabled). Under a pipe, a
// redirect, or test capture nothing is written -- so machine-parsed registry /
// modium output stays byte-for-byte identical and no escape codes leak.
//
// `holdMillis` is how long the line is visible before it is erased; a short
// hold (default ~450ms) reads as "loaded" without stalling the command.
inline void transientLoading(std::ostream& o, int streamFd,
                             const std::string& subsystem,
                             unsigned holdMillis = 450) {
    if (!brandColorEnabled(streamFd)) return;   // off-terminal: emit nothing at all
    // draw: red "Loading <Subsystem>(TM)" with no trailing newline (same line).
    o << "\033[31m" << "Loading " << subsystem << "\u2122" << "\033[0m" << std::flush;
    // hold briefly so the flash is perceptible.
    SLEELA_BANNER_SLEEP_MS(holdMillis);
    // erase in place: carriage return + clear the whole line, leaving the cursor
    // at column 1 of the now-blank line so normal output begins cleanly.
    o << "\r\033[2K" << std::flush;
}

// A professional component line for a tool/unit currently being worked on:
//   -- : [Object ID: 0000000001] [Date: <date>] [Current: @<name>] . <msg> .
// `name` is the tool or unit (e.g. "Sleelvac", "Nordshrift", or a source file).
inline void component(std::ostream& o, const std::string& name,
                      unsigned long objectId, unsigned long date,
                      const std::string& message) {
    PrintComponent::write(o, name, objectId, date, message);
}

// A state-labelled status line: "[STATE] message", laid out to the rail width.
inline void status(std::ostream& o, PrintState state, const std::string& message) {
    PrintFormatter::status(o, state, message);
}

// Convenience state shims so call sites read intention-first.
inline void start(std::ostream& o, const std::string& m)    { status(o, PrintState::START, m); }
inline void working(std::ostream& o, const std::string& m)  { status(o, PrintState::WORKING, m); }
inline void progress(std::ostream& o, const std::string& m) { status(o, PrintState::PROGRESS, m); }
inline void complete(std::ostream& o, const std::string& m) { status(o, PrintState::COMPLETE, m); }
inline void warn(std::ostream& o, const std::string& m)     { status(o, PrintState::WARN, m); }
inline void error(std::ostream& o, const std::string& m)    { status(o, PrintState::ERROR, m); }

// The 21x21 progress square (441 cells) and its percent header.
inline void square(std::ostream& o, int filledCells) { PrintRenderer::square(o, filledCells); }
inline void progressPercent(std::ostream& o, int percent) { PrintProgress::write(o, percent); }

}} // namespace sleela::rails

#endif // SLEELA_COMMON_RAILS_BANNER_H