ternaria_os/

cli.rs

//! The command-line front end: boots the operating system against a real
//! terminal.
//!
//! This lives in the library rather than in a binary so that more than one
//! entry point can reach it. There is one inside this workspace and one in the
//! launcher package alongside the repositories, and neither should hold a
//! second copy of the logic.
//!
//! ```text
//!   cargo run                  a fresh disk with a few files on it
//!   cargo run -- disk.tfs      that image, created if it does not exist
//!   cargo run -- --format d    a fresh image written to d, overwriting it
//! ```
//!
//! The image is written back when the shell exits, so anything created inside
//! the machine is still there next time. Leave with `exit` or Ctrl-D; Ctrl-C
//! kills the host before it can write.

use std::io::{BufRead, Write};

use crate::source;
use ternaria_arith::{Tryte, Word};
use ternaria_dev::{BlockDevice, Bus, Console, Timer};
use ternaria_fs::Builder;
use ternaria_mem::Addressable;
use ternaria_vm::assemble_and_load;

/// Blocks in a freshly formatted disk.
const DISK_BLOCKS: usize = 243;

/// Instructions the machine may execute before the host gives up.
///
/// Generous: a session is a few thousand instructions per command, and the
/// limit exists to stop a runaway rather than to bound normal use.
const STEP_LIMIT: u64 = 2_000_000_000;

/// Runs the front end. Exits the process on failure.
pub fn main() {
    let mut args = std::env::args().skip(1);
    let mut format = false;
    let mut path: Option<String> = None;
    for arg in args.by_ref() {
        match arg.as_str() {
            "--format" | "-f" => format = true,
            "--help" | "-h" => {
                print_help();
                return;
            }
            other => path = Some(other.to_string()),
        }
    }

    let image = match load_image(path.as_deref(), format) {
        Ok(image) => image,
        Err(e) => {
            eprintln!("ternaria: {e}");
            std::process::exit(1);
        }
    };

    match run(image, path.as_deref()) {
        Ok(()) => {}
        Err(e) => {
            eprintln!("ternaria: {e}");
            std::process::exit(1);
        }
    }
}

/// Prints the usage text.
fn print_help() {
    println!("ternaria - a balanced ternary machine running a small operating system");
    println!();
    println!("  cargo run                 boot a fresh disk held in memory");
    println!("  cargo run -- <image>      boot <image>, creating it if absent");
    println!("  cargo run -- --format <image>");
    println!("                            overwrite <image> with a fresh disk");
    println!();
    println!("Commands inside the machine:");
    println!("  ls              list the working directory");
    println!("  cd <name>       enter a directory");
    println!("  cat <name>      print a file");
    println!("  mkdir <name>    create a directory");
    println!("  touch <name>    create an empty file");
    println!("  write <name>    create a file from the lines that follow,");
    println!("                  ending with a line holding only a full stop");
    println!("  rm <name>       remove a file or an empty directory");
    println!();
    println!("  run <name>      load and run a program, at user level");
    println!("  exit, logout    leave the machine");
    println!();
    println!("An image given on the command line is written back when the shell");
    println!("exits, whether through `exit` or Ctrl-D. Interrupting with Ctrl-C");
    println!("kills the host before it can write, and loses the session.");
}

/// Reads the image named, or builds a fresh one.
fn load_image(path: Option<&str>, format: bool) -> std::io::Result<Vec<u8>> {
    match path {
        Some(p) if !format && std::path::Path::new(p).exists() => std::fs::read(p),
        _ => Ok(fresh_disk()),
    }
}

/// A formatted disk with enough on it to have something to look at.
fn fresh_disk() -> Vec<u8> {
    let mut b = Builder::new(DISK_BLOCKS);
    b.write_file(
        "/readme",
        b"This machine computes in base three.\n\
          Digits are -1, 0 and +1.\n\
          \n\
          Try: ls, cat readme, mkdir work, cd work, write notes\n",
    )
    .expect("the fresh disk fits");
    b.mkdir("/docs").expect("mkdir");
    b.write_file(
        "/docs/trits",
        b"A trit holds -1, 0 or +1.\nNine trits are a tryte.\n",
    )
    .expect("write");
    b.finish()
}

/// Boots the machine and hands it the terminal.
fn run(image: Vec<u8>, save_to: Option<&str>) -> Result<(), Box<dyn std::error::Error>> {
    let mut bus = Bus::new(Console::new(), Timer::new(), BlockDevice::new(image));

    // The data segment holds the shell's strings. The guest reads them as
    // ordinary memory, so the host writes them before the machine starts.
    place_data(&mut bus)?;
    let mut cpu = assemble_and_load(&mut bus, Word::ZERO, &source())?;

    let stdin = std::io::stdin();
    let mut lines = stdin.lock().lines();
    let mut emitted = 0usize;
    let mut stopped: Option<String> = None;

    loop {
        // A trap ends the session, and the image must still be written: work
        // done before the fault is no less real for the fault happening.
        match cpu.step(&mut bus) {
            Ok(true) => {}
            Ok(false) => break,
            Err(trap) => {
                stopped = Some(trap.to_string());
                break;
            }
        }
        bus.tick();

        // Everything the guest has printed since the last look. Doing this
        // every step keeps the prompt appearing before the read that follows
        // it, which is what makes the session feel like a terminal.
        let out = bus.console.output();
        if out.len() > emitted {
            let mut stdout = std::io::stdout();
            stdout.write_all(&out[emitted..])?;
            stdout.flush()?;
            emitted = out.len();
        }

        // The guest looked for input and found none, so it is waiting on a
        // person. This is the console's third status value earning its keep:
        // without it the guest could not tell waiting from ended.
        if bus.console.take_starved() {
            match lines.next() {
                Some(line) => {
                    let mut line = line?;
                    line.push('\n');
                    bus.console.push_input(line.as_bytes());
                }
                None => {
                    // Ctrl-D. Closing the console makes the status read
                    // negative, and the guest stops on its own.
                    println!();
                    bus.console.close();
                }
            }
        }

        if cpu.steps() > STEP_LIMIT {
            stopped = Some("step limit reached".to_string());
            break;
        }
    }

    // Flush anything printed after the last check.
    let out = bus.console.output();
    if out.len() > emitted {
        let mut stdout = std::io::stdout();
        stdout.write_all(&out[emitted..])?;
        stdout.flush()?;
    }

    if let Some(p) = save_to {
        std::fs::write(p, bus.block.image())?;
        eprintln!("ternaria: wrote {p}");
    }
    if let Some(why) = stopped {
        eprintln!("ternaria: {why}");
    }
    Ok(())
}

/// Writes the shell's strings into guest memory.
fn place_data(bus: &mut Bus) -> Result<(), ternaria_mem::MemoryError> {
    for (at, text) in crate::data_placement() {
        for (k, byte) in text.bytes().enumerate() {
            bus.write_tryte(
                Word::from_value(at + k as i64),
                Tryte::from_value(byte as i32),
            )?;
        }
        bus.write_tryte(Word::from_value(at + text.len() as i64), Tryte::ZERO)?;
    }
    Ok(())
}