ludic/tools/ludic-cli/prelude.ludic

# prelude.ludic — the shared runtime for both command-line programs: `ludic`,
# which a user of the language runs, and `ludic-dev`, the contributor tool that
# builds the toolchain itself. Both are native binaries written in Ludic and
# compiled by Ludic, driving clang, the compiler and the unix tools through
# `run`. This fragment is the tiny standard library their commands lean on:
# process control, file IO, strings and a colored PASS/FAIL test harness. It
# carries no ECS, so both link as plain CLI programs.
#
# `ludic`'s commands work from any directory, against whatever toolchain is
# installed. `ludic-dev`'s tasks run relative to the current directory and expect
# the toolchain repo root.

# ---- file IO ----------------------------------------------------------------

# read a whole file into a fresh NUL-terminated buffer (null if it cannot open)
function read_file(path: pointer) -> string {
  let f = file_open(path, "rb")
  if (f == null) { return null }
  file_seek(f, 0, 2)
  let n = file_tell(f)
  file_seek(f, 0, 0)
  let buf = bytes(n + 1)
  file_read(f, buf, n)
  buf[n] = 0
  file_close(f)
  return buf
}

# overwrite `path` with `s`; returns false if it could not be opened
function write_file(path: pointer, s: pointer) -> bool {
  let f = file_open(path, "wb")
  if (f == null) { return false }
  file_write(f, s, len(s))
  file_close(f)
  return true
}

# ---- byte strings ------------------------------------------------------------------
# s[a, b) as a fresh NUL-terminated string; out-of-range ends are clamped.
function str_sub(s: pointer, a: int, b: int) -> pointer {
  var lo = a
  if lo < 0 { lo = 0 }
  var hi = b
  if hi < lo { hi = lo }
  let out = bytes(hi - lo + 1)
  var i = lo
  var k = 0
  while i < hi { out[k] = s[i];  k += 1;  i += 1 }
  out[k] = 0
  return out
}
function str_space(c: int) -> bool { return c == 32 or c == 9 or c == 13 }

function file_exists(path: pointer) -> bool { return shq(`test -e {path}`) }
function is_exec(path: pointer) -> bool { return shq(`test -x {path}`) }
# is `a` newer than `b` (like the shell's `-nt`)?
function newer(a: pointer, b: pointer) -> bool { return shq(`test {a} -nt {b}`) }

# ---- process control --------------------------------------------------------
#
# Every command this tool issues is POSIX shell: mkdir -p, rm -rf, test -x, pipes
# through tr and sed. On macOS and Linux the C library's system() is /bin/sh, so
# `shell` is `run`. On Windows system() is cmd.exe, which speaks none of it, so each
# command is written to a scratch script and handed to Git for Windows' bash - the
# Windows toolchain's one requirement beyond LLVM; $LUDIC_BASH names another bash.
# A script rather than `bash -c "..."`: a command line goes through cmd.exe's quoting
# and then bash's startup parser, and a command with quotes of its own does not
# survive both.

function host_windows() -> bool {
  let os = getenv("OS")
  if os == null { return false }
  return os == "Windows_NT"
}

var g_bash: pointer = null
function win_bash() -> pointer {
  if g_bash == null { g_bash = getenv_or("LUDIC_BASH", "C:/Program Files/Git/bin/bash.exe") }
  return g_bash
}

var g_shell_n: int = 0
function shell(cmd: pointer) -> int {
  if not host_windows() { return run(cmd) }
  # numbered, so a command that is itself running this tool's script cannot have it
  # rewritten underneath it
  g_shell_n += 1
  let script = tmp_path(`sh_{string(g_shell_n)}.sh`)
  if not write_file(script, cmd + "\n") { return 1 }
  # cmd.exe takes the first and last quote off a line that starts with one, so the
  # whole line wears one more pair for it to remove
  let st = run(`""{win_bash()}" "{script}""`)
  Fs.remove(script)
  return st
}

# `run` returns the raw wait status on POSIX, where the exit code is the high byte;
# Windows' system() returns the exit code itself.
function exit_code(st: int) -> int {
  if host_windows() { return st }
  return (st >> 8) & 255
}
# run a command, returning its exit code (0 = success)
function sh(cmd: pointer) -> int { return exit_code(shell(cmd)) }
# run a command, true when it succeeded
function shq(cmd: pointer) -> bool { return exit_code(shell(cmd)) == 0 }

# ---- scratch files ------------------------------------------------------------
# Every scratch file the runner writes lives under one per-process directory
# (`$TMPDIR/x_<pid>`), so `ludic-dev test` and an `x check-*` can run side by side without
# clobbering each other's captures. main removes it on the way out.
var x_tmp: pointer = null

function tmp_dir() -> pointer {
  if x_tmp == null {
    var base = Os.temp_dir()
    if len(base) > 1 and base[len(base) - 1] == '/' { base = base[0..len(base) - 1] }   # macOS: TMPDIR ends in '/'
    x_tmp = `{base}/ludic_{Os.pid()}`
    Fs.mkdir(x_tmp)                         # not the shell: on Windows it keeps its scripts here
  }
  return x_tmp
}

# a scratch path under tmp_dir(): tmp_path("foo.out")
function tmp_path(name: pointer) -> string { return `{tmp_dir()}/{name}` }

# remove the scratch directory (idempotent; a no-op when nothing was written).
# LUDIC_KEEP_TMP=1 leaves it in place, and says where, for debugging a failing case.
function tmp_cleanup() -> void {
  if x_tmp == null { return }
  if getenv_or("LUDIC_KEEP_TMP", "0") == "1" { print(`scratch kept: {x_tmp}`) }
  # on Windows the shell's own script is open in this directory while it runs, so it is
  # removed by cmd.exe instead
  else if host_windows() { run(`rmdir /s /q "{win_backslashes(x_tmp)}" 2>nul`) }
  else { run(`rm -rf {x_tmp}`) }
  x_tmp = null
}

# run `cmd` and return its stdout (stderr discarded). Never null.
function capture(cmd: pointer) -> pointer {
  let tmp = tmp_path("capture.out")
  shell(`{cmd} > {tmp} 2>/dev/null`)
  let s = read_file(tmp)
  if (s == null) { return "" }
  return s
}

# run `cmd`, join its output lines with single spaces and trim — the Ludic twin
# of the shell idiom `$(cmd | tr '\n' ' ' | sed 's/ *$//')`.
function capture_line(cmd: pointer) -> string {
  return capture(`{cmd} | tr '\n' ' ' | sed 's/ *$//'`)
}

# the last line of a command's output (for one-line error messages)
function capture_tail(cmd: pointer) -> pointer {
  return capture(`{cmd} 2>&1 | tail -1`)
}

function getenv_or(name: pointer, dflt: pointer) -> pointer {
  let v = getenv(name)
  if (v == null) { return dflt }
  return v
}

# flatten a relative example path into a filesystem-safe token: '/' -> '_', so a
# categorised path like "games/snake" yields a single-segment temp name
# ("games_snake") that never implies a missing /tmp subdirectory.
function flat(p: pointer) -> pointer {
  let n = len(p)
  let b = bytes(n + 1)
  for i in 0 .. n {
    var c = p[i]
    if (c == '/') { c = 95 }   # '/' (47) -> '_' (95)
    b[i] = c
  }
  b[n] = 0
  return b
}

# ---- stdout helpers ---------------------------------------------------------

# write `s` with no trailing newline (print() always adds one)
function out(s: pointer) -> void { file_write(file_stdout(), s, len(s)) }
function err(s: pointer) -> void { file_write(file_stderr(), s, len(s)) }

# an ESC byte — the lexer has no \033, so build it by hand
function esc() -> pointer { let b = bytes(2); b[0] = 27; b[1] = 0; return b }
function c_green() -> pointer { return esc() + "[32m" }
function c_red() -> pointer { return esc() + "[31m" }
function c_reset() -> pointer { return esc() + "[0m" }

# ---- the PASS/FAIL test harness ---------------------------------------------

var PASS: int = 0
var FAIL: int = 0

function ok(msg: pointer) -> void {
  PASS += 1
  print(`  {c_green()}PASS{c_reset()} {msg}`)
}
function bad(msg: pointer) -> void {
  FAIL += 1
  print(`  {c_red()}FAIL{c_reset()} {msg}`)
}
function bad2(msg: pointer, detail: pointer) -> void {
  bad(msg)
  print(`        {detail}`)
}
# assert two strings equal, reporting the mismatch
function check(label: pointer, got: pointer, want: pointer) -> void {
  if (got == want) { ok(label) }
  else { bad2(label, `expected [{want}] got [{got}]`) }
}

# ---- host platform ----------------------------------------------------------
# A few cases exercise macOS-specific runtime ABI — Cocoa windowing, the BSD
# utsname/dirent layout — or compare against renders blessed on macOS. The
# self-hosted compiler and its C-free bootstrap are host-neutral (they produce
# byte-identical IR on any host), so the bulk of the suite runs anywhere; only
# these platform-bound cases are skipped — visibly, never silently — when the
# suite runs off Darwin. That lets a Linux CI runner gate every portable
# guarantee without red from the parts that are macOS-only today.
function host_os() -> pointer { return capture_line("uname -s") }
function is_darwin() -> bool { return host_os() == "Darwin" }
function skip(msg: pointer) -> void { print(`  skip  {msg}`) }

# print the "== N passed, M failed ==" footer and return the process exit code
function report() -> int {
  print("")
  print(`== {string(PASS)} passed, {string(FAIL)} failed ==`)
  if (FAIL == 0) { return 0 }
  return 1
}

# a positional argument, or a default when it is absent
function argn(i: int, dflt: pointer) -> string {
  if (i < arg_count()) { return arg(i) }
  return dflt
}

# ---- the toolchain install ---------------------------------------------------
#
# The user-facing commands run anywhere, so they cannot assume a `bin/` in the
# current directory the way the old repo-root-only task runner did. They ask
# here instead, and get the same answer in both layouts that exist: an install
# (~/.ludic/bin/ludic, root ~/.ludic) and a checkout of the toolchain repo
# (bin/ludic, root the repo). The compiler derives its own root by the identical
# rule (see ludic_home() in selfhost/frontend/parse.ludic), so the two never
# disagree about where the runtime and the bundled packages live.

var g_home: pointer = null

# the directory holding this binary, with a trailing '/'. argv[0] carries no
# directory when the CLI was found on $PATH, which is the normal case for an
# install — ask the shell where it found it.
function self_dir() -> pointer {
  var a0 = arg(0)
  var slash = -1
  var i = 0
  while a0[i] != 0 { if a0[i] == '/' or a0[i] == 92 { slash = i };  i += 1 }
  if slash < 0 {
    var lookup = `command -v {a0}`
    if host_windows() { lookup = `cygpath -m "$(command -v {a0})"` }
    let found = capture_line(lookup)
    if found == "" { return "" }
    a0 = found
    slash = -1
    i = 0
    while a0[i] != 0 { if a0[i] == '/' or a0[i] == 92 { slash = i };  i += 1 }
    if slash < 0 { return "" }
  }
  return win_slashes(a0[0..slash + 1])
}

# The toolchain install root, with a trailing '/', or "" for the current
# directory. $LUDIC_HOME wins; otherwise the binary's own directory decides, and
# a directory named `bin` means the root is its parent.
function ludic_home() -> pointer {
  if g_home != null { return g_home }
  let env = getenv("LUDIC_HOME")
  if env != null {
    var e = env
    if len(e) > 0 and e[len(e) - 1] != '/' { e = e + "/" }
    g_home = e
    return g_home
  }
  var d = self_dir()
  if len(d) >= 4 and d[len(d) - 4..len(d)] == "bin/" { d = d[0..len(d) - 4] }
  # a source checkout the CLI was run from elsewhere in: prefer a ./bin here
  if not is_exec(`{d}bin/{exe_name("ludicc")}`) and is_exec(`bin/{exe_name("ludicc")}`) { d = "" }
  g_home = d
  return g_home
}

# the path to a toolchain binary (ludicc, ludic-fmt, ludic-lsp). Falls back to
# the bare name — on $PATH — when the install root has no bin/ of its own.
function tool(name: pointer) -> pointer {
  let p = `{ludic_home()}bin/{exe_name(name)}`
  if is_exec(p) { return p }
  return name
}

function ludicc() -> pointer { return tool("ludicc") }

# true in a checkout of the toolchain repo itself, where a seed is present to
# assemble the compiler from.
# a program's file name on this host: `name` everywhere but Windows, `name.exe` there
function exe_name(name: pointer) -> pointer {
  if host_windows() { return name + ".exe" }
  return name
}

# the compiler's IR seed for this host. The IR is not portable between the two: each
# names its own C library (see selfhost/backend/stdlib/emit_win.ludic).
function seed_file() -> pointer {
  if host_windows() { return "selfhost/ludicc.win.seed.ll" }
  return "selfhost/ludicc.seed.ll"
}

# a copy of a path with every '\' as '/', and one with every '/' as '\' (for cmd.exe)
function win_slashes(p: pointer) -> pointer {
  let n = len(p)
  let b = bytes(n + 1)
  for i in 0 .. n { if p[i] == 92 { b[i] = '/' } else { b[i] = p[i] } }
  b[n] = 0
  return b
}
function win_backslashes(p: pointer) -> pointer {
  let n = len(p)
  let b = bytes(n + 1)
  for i in 0 .. n { if p[i] == '/' { b[i] = 92 } else { b[i] = p[i] } }
  b[n] = 0
  return b
}

function in_toolchain_repo() -> bool {
  return file_exists(seed_file()) and file_exists("tools/ludic-cli/main.ludic")
}

# ---- strings ----------------------------------------------------------------
# Shared by every command, so they live here rather than in whichever file
# happened to need them first.

# length of a NUL-terminated buffer
function slen(s: pointer) -> int { var n = 0;  while s[n] != 0 { n += 1 };  return n }

# a fresh NUL-terminated copy of s[start .. end) (end exclusive)
function sslice(s: pointer, start: int, end: int) -> pointer {
  if end < start { return "" }
  let n = end - start
  let b = bytes(n + 1)
  var i = 0
  while i < n { b[i] = s[start + i];  i += 1 }
  b[n] = 0
  return b
}

# index of the first byte of `needle` in `hay` at or after `from`, else -1
function s_index(hay: pointer, needle: pointer, from: int) -> int {
  let hn = slen(hay)
  let nn = slen(needle)
  if nn == 0 { return from }
  var i = from
  while i + nn <= hn {
    var j = 0
    while j < nn and hay[i + j] == needle[j] { j += 1 }
    if j == nn { return i }
    i += 1
  }
  return -1
}

function s_contains(hay: pointer, needle: pointer) -> bool { return s_index(hay, needle, 0) >= 0 }

# does `hay` contain `needle` exactly at position `at`?
function s_starts_at(hay: pointer, at: int, needle: pointer) -> bool {
  let nn = slen(needle)
  var i = 0
  while i < nn { if hay[at + i] != needle[i] { return false };  i += 1 }
  return true
}

# does `s` (a whole line) begin with `pre`?
function s_starts(s: pointer, pre: pointer) -> bool {
  let pn = slen(pre)
  var i = 0
  while i < pn { if s[i] != pre[i] { return false };  i += 1 }
  return true
}

# is byte c an ASCII space/tab?
function is_ws(c: int) -> bool { return c == ' ' or c == '\t' }

# the substring from `start` up to the next '\n' (or end)
function line_at(s: pointer, start: int) -> pointer {
  var e = start
  while s[e] != 0 and s[e] != '\n' { e += 1 }
  return sslice(s, start, e)
}

# trim leading/trailing ASCII whitespace (space, tab, cr, nl)
function s_trim(s: pointer) -> string {
  let n = slen(s)
  var a = 0
  while a < n and (is_ws(s[a]) or s[a] == '\n' or s[a] == '\r') { a += 1 }
  var b = n
  while b > a and (is_ws(s[b - 1]) or s[b - 1] == '\n' or s[b - 1] == '\r') { b -= 1 }
  return sslice(s, a, b)
}

# lowercase ASCII A-Z
function lower_ascii(s: pointer) -> pointer {
  let n = slen(s)
  let b = bytes(n + 1)
  var i = 0
  while i < n {
    var c = s[i]
    if c >= 'A' and c <= 'Z' { c += 32 }
    b[i] = c
    i += 1
  }
  b[n] = 0
  return b
}

# Python str.title(): capitalise the first letter of each alpha run, lower the rest
function title_case(s: pointer) -> pointer {
  let n = slen(s)
  let b = bytes(n + 1)
  var i = 0
  var prev_alpha = false
  while i < n {
    var c = s[i]
    let al = (c >= 'A' and c <= 'Z') or (c >= 'a' and c <= 'z')
    if al {
      if prev_alpha { if c >= 'A' and c <= 'Z' { c += 32 } }
      else { if c >= 'a' and c <= 'z' { c -= 32 } }
    }
    b[i] = c
    prev_alpha = al
    i += 1
  }
  b[n] = 0
  return b
}

# ---- the C toolchain --------------------------------------------------------
# clang assembles the emitted IR and drives the linker. -Wno-override-module for
# the same reason the compiler itself passes it (see selfhost/main.ludic): the IR
# names no target triple, so clang substitutes the host's and warns every time.
# On Windows the LLVM installer leaves clang off %PATH% unless asked, so its own
# location is the default there.
function cc() -> pointer {
  let env = getenv("LUDIC_CC")
  if env != null { return env + " -Wno-override-module" }
  if host_windows() and Fs.exists("C:/Program Files/LLVM/bin/clang.exe") {
    return "\"C:/Program Files/LLVM/bin/clang.exe\" -Wno-override-module"
  }
  return "clang -Wno-override-module"
}