Standard Library

os

The os module provides program control, shell command execution, and process management functionality.

import "conjure/os"

Program Control

exit

Terminates the program with the specified exit code. By convention, an exit code of 0 indicates success, and non-zero values indicate errors.

func main() {
    if not validateInput() {
        io.println("Invalid input")
        os.exit(1)
    }

    // Normal execution...
    os.exit(0)
}

Signature:

func exit(code i32)

Shell Commands

system

Executes a shell command using the system shell. Returns the exit status of the command. This is useful for running shell pipelines or commands with redirection.

var exitCode = os.system("ls -la | grep .cjr")
var result = os.system("echo 'Hello' > output.txt")

Signature:

func system(command string) i32

Process Execution

exec

Executes a command and waits for it to finish. The command’s output is captured (not displayed). Returns the exit code of the process.

var exitCode = os.exec("ls", "-la", "/tmp")
if exitCode != 0 {
    io.println("Command failed with code: #{exitCode}")
}

Signature:

func exec(program string, ...args string) i32

run

Executes a command with inherited stdio, making it suitable for interactive programs. The command’s input/output is connected to the terminal. Returns the exit code of the process.

// Run an interactive editor
var exitCode = os.run("vim", "config.json")

// Run a command that needs user input
os.run("npm", "init")

Signature:

func run(program string, ...args string) i32

Process Management

which

Finds an executable in the system PATH. Returns the full path to the executable, or an empty string if not found.

var gitPath = os.which("git")
if gitPath.len == 0 {
    io.println("Git is not installed")
} else {
    io.println("Git found at: #{gitPath}")
}

Signature:

func which(name string) string

wait

Waits for a process with the given PID to finish. Returns the exit code of the process.

var pid = spawnProcess()  // hypothetical spawn function
var exitCode = os.wait(pid)
io.println("Process exited with: #{exitCode}")

Signature:

func wait(pid i32) i32

terminate

Terminates a process with the given PID. Returns true on success, false on failure.

var success = os.terminate(pid)
if not success {
    io.println("Failed to terminate process")
}

Signature:

func terminate(pid i32) bool

Example: Simple CLI

import "conjure/os"
import "conjure/runtime"
import "conjure/io"

func main() {
    // Check for required argument
    if runtime.argCount() < 2 {
        io.println("Usage: program <filename>")
        os.exit(1)
    }

    var filename = runtime.arg(1)
    io.println("Processing: #{filename}")

    // ... process the file ...

    os.exit(0)
}

Example: Build Script

import "conjure/os"
import "conjure/io"

func main() {
    io.println("Building project...")

    // Check for required tools
    if os.which("gcc").len == 0 {
        io.println("Error: GCC not found")
        os.exit(1)
    }

    // Compile
    var result = os.exec("gcc", "-o", "output", "main.c")
    if result != 0 {
        io.println("Compilation failed")
        os.exit(result)
    }

    io.println("Build successful!")
}

Example: Running Tests

import "conjure/os"
import "conjure/io"

func runTests() bool {
    io.println("Running tests...")

    // Run test suite with visible output
    var exitCode = os.run("pytest", "-v")

    return exitCode == 0
}

Example: Shell Pipelines

import "conjure/os"
import "conjure/io"

func countSourceLines() {
    // Use system() for shell features like pipes
    var exitCode = os.system("find . -name '*.cjr' | xargs wc -l")
    if exitCode != 0 {
        io.println("Failed to count lines")
    }
}