Re-commiting whole course squashed into one commit

The history is non-sensical and messy (including every dumb typo)
so I squashed it all to avoid the rabbit hole of thinking how to split
it in a meaningful way.

.gitignore

@@ -16,3 +16,5 @@ bin/
 **/.DS_Store
 *.swp
 *~
+
+your_program.strace

codecrafters.yml

@@ -2,7 +2,7 @@
 #
 # These can be VERY verbose, so we suggest turning them off
 # unless you really need them.
-debug: false
+debug: true
 
 # Use this to change the Zig version used to run your code
 # on Codecrafters.

src/bltn.zig

@@ -0,0 +1,323 @@
+const std = @import("std");
+
+const shell = @import("shell.zig");
+const util = @import("util.zig");
+const cmd = @import("cmd.zig");
+
+const StdIO = shell.StdIO;
+const Loop = shell.Loop;
+const Shell = shell.Shell;
+
+const PEDANTIC = false;
+
+pub const BltnCtx = struct {
+    loop: *Loop,
+    cmd_name: []const u8,
+    args: []const []const u8,
+    allocator: std.mem.Allocator,
+    shell: *Shell,
+    stdio: StdIO,
+
+    fn get_sopt(self: @This(), idx: usize) ?u8 {
+        if (self.args.len < 1) return null;
+        if (idx > self.args.len - 1) return null;
+        const candidate = self.args[idx];
+        if (candidate.len != 2) return null;
+        if (candidate[0] != '-') return null;
+        return candidate[1];
+    }
+
+    fn clone_arg(self: @This(), idx: usize) ![]const u8 {
+        std.debug.assert(idx < self.args.len);
+        return try self.allocator.dupe(u8, self.args[idx]);
+    }
+
+    fn clone_args(self: @This()) ![]const []const u8 {
+        var al = std.ArrayList([]u8).init(self.allocator);
+        for (self.args) |arg| try al.append(try self.allocator.dupe(u8, arg));
+        return try al.toOwnedSlice();
+    }
+
+    fn usage_unknown(
+        self: @This(),
+        comptime B: type,
+        arg: []const u8,
+    ) error{UsageError} {
+        self.stdio.err(B.USAGE_TEXT);
+        self.stdio.err("\n\n");
+        self.stdio.errf("unknown argument: '{s}'", .{arg});
+        return error.UsageError;
+    }
+
+    fn usage_missing(
+        self: @This(),
+        comptime B: type,
+        comptime label: []const u8,
+    ) error{UsageError} {
+        self.stdio.err(B.USAGE_TEXT);
+        self.stdio.err("\n\n");
+        self.stdio.err("no " ++ label ++ "?");
+        return error.UsageError;
+    }
+
+    fn usage_toomany(
+        self: @This(),
+        comptime B: type,
+    ) error{UsageError} {
+        self.stdio.err(B.USAGE_TEXT);
+        self.stdio.err("\n\n");
+        self.stdio.err("too many arguments");
+        return error.UsageError;
+    }
+
+    fn usage(
+        self: @This(),
+        comptime B: type,
+        comptime fmt: []const u8,
+        args: anytype,
+    ) error{UsageError} {
+        self.stdio.err(B.USAGE_TEXT);
+        self.stdio.err("\n\n");
+        self.stdio.errf(fmt, args);
+        return error.UsageError;
+    }
+};
+
+const ExitBltn = struct {
+    const Self = @This();
+    const Params = struct {
+        es: u7,
+    };
+
+    const USAGE_TEXT =
+        \\usage: exit [N]
+    ;
+
+    fn _parse(ctx: BltnCtx) !Params {
+        if (ctx.args.len == 0) return Params{ .es = shell.EXIT_OK };
+        if (ctx.args.len > 1) return ctx.usage_toomany(Self);
+        const es_str = ctx.args[0];
+        const es = std.fmt.parseInt(u7, es_str, 10) catch {
+            return ctx.usage(
+                Self,
+                "N must be a base-10 integer between 0 and 127: '{s}'",
+                .{es_str},
+            );
+        };
+        return Params{ .es = es };
+    }
+
+    fn run(ctx: BltnCtx) !void {
+        const params: Params = try Self._parse(ctx);
+        ctx.shell.exit(params.es);
+    }
+};
+
+const EchoBltn = struct {
+    const Self = @This();
+    const Params = struct {
+        operands: []const []const u8,
+    };
+
+    const USAGE_TEXT =
+        \\usage: echo [STRING..]
+    ;
+
+    fn _parse(ctx: BltnCtx) !Params {
+        return Params{ .operands = try ctx.clone_args() };
+    }
+
+    fn run(ctx: BltnCtx) !void {
+        const params: Params = try Self._parse(ctx);
+        const w = ctx.stdio.stdout_f.writer().any();
+        for (params.operands, 0..) |operand, idx| {
+            if (idx > 0) try w.writeByte(' ');
+            try w.writeAll(operand);
+        }
+        try w.writeByte('\n');
+    }
+};
+
+const TypeBltn = struct {
+    const Self = @This();
+    const Params = struct {
+        cmd_name: []const u8,
+    };
+
+    const USAGE_TEXT =
+        \\usage: type COMMAND_NAME
+    ;
+
+    fn _parse(ctx: BltnCtx) !Params {
+        if (ctx.args.len == 0) return ctx.usage_missing(Self, "COMMAND_NAME");
+        if (ctx.args.len > 1) return ctx.usage_toomany(Self);
+        const cmd_name = try ctx.clone_arg(0);
+        if (std.mem.indexOfAny(u8, cmd_name, shell.CMD_NAME_INVALID)) |pos| return ctx.usage(
+            Self,
+            "COMMAND_NAME contains invalid character: {x} at position {d}",
+            .{ cmd_name[pos], pos },
+        );
+        return Params{ .cmd_name = cmd_name };
+    }
+
+    fn run(ctx: BltnCtx) !void {
+        const params = try Self._parse(ctx);
+        if (Bltn.exists(params.cmd_name)) {
+            try ctx.stdio.outf("{s} is a shell builtin", .{params.cmd_name});
+        } else if (try cmd.find_exec_path(params.cmd_name, ctx.allocator)) |exec_path| {
+            try ctx.stdio.outf("{s} is {s}", .{ params.cmd_name, exec_path });
+        } else {
+            try ctx.stdio.outf("{s}: not found", .{params.cmd_name});
+        }
+    }
+};
+
+const PwdBltn = struct {
+    const Self = @This();
+    const Params = struct {
+        mode: Mode,
+    };
+    const Mode = enum { L, P };
+    const USAGE_TEXT =
+        \\usage: pwd [-L|-P]
+    ;
+
+    fn _parse(ctx: BltnCtx) !Params {
+        var cur: usize = 0;
+        var mode: Mode = .L;
+        while (cur < ctx.args.len) {
+            const arg = ctx.args[cur];
+            const maybe_opt_letter = ctx.get_sopt(cur);
+            if (maybe_opt_letter == null) return ctx.usage_unknown(Self, arg);
+            switch (maybe_opt_letter.?) {
+                'L' => mode = .L,
+                'P' => mode = .P,
+                else => return ctx.usage_unknown(Self, arg),
+            }
+            cur += 1;
+        }
+        return Params{ .mode = mode };
+    }
+
+    fn run(ctx: BltnCtx) !void {
+        const params = try Self._parse(ctx);
+        const out = b: {
+            if (PEDANTIC) {
+                const PwdComputer = @import("pedantic.zig").PwdComputer;
+                const pc = try PwdComputer.create(ctx.allocator);
+                defer pc.destroy();
+                switch (params.mode) {
+                    .P => break :b pc.getpath_P(),
+                    .L => break :b pc.getpath_L(),
+                }
+            } else {
+                break :b try std.process.getCwdAlloc(ctx.allocator);
+            }
+        };
+        try ctx.stdio.out(out);
+    }
+};
+
+const CdBltn = struct {
+    const USAGE_TEXT =
+        \\usage: cd PATH
+    ;
+    const Self = @This();
+    const Target = union(enum) {
+        path: []const u8,
+        home: void,
+        old: void,
+    };
+
+    fn _parse_target(ctx: BltnCtx) !Target {
+        if (ctx.args.len == 0) return Target{ .home = {} };
+        if (ctx.args.len > 1) return ctx.usage_toomany(Self);
+        if (ctx.args[0].len == 1 and ctx.args[0][0] == '-') return Target{ .old = {} };
+        return Target{ .path = try ctx.clone_arg(0) };
+    }
+
+    fn _err2msg(err: anyerror) ?[]const u8 {
+        return (switch (err) {
+            error.AccessDenied => "Access denied",
+            error.FileNotFound => "No such file or directory",
+            error.NotDir => "Not a directory",
+            error.BadPathName => "Invalid path name",
+            else => null,
+        });
+    }
+
+    fn _chdir(ctx: BltnCtx, path: []const u8) !void {
+        const initial_path = try std.process.getCwdAlloc(ctx.allocator);
+        defer ctx.allocator.free(initial_path);
+        const untilded = try util.realpathWithTilde(ctx.allocator, path);
+        try std.process.changeCurDir(untilded);
+        try ctx.shell.setOldPwd(initial_path);
+    }
+
+    fn run(ctx: BltnCtx) !void {
+        const target = try Self._parse_target(ctx);
+        const path = switch (target) {
+            .path => |path| path,
+            .home => try std.process.getEnvVarOwned(ctx.allocator, "HOME"),
+            .old => ctx.shell.vars.OLDPWD orelse {
+                ctx.stdio.err("cd: OLDPWD not set");
+                return;
+            },
+        };
+        Self._chdir(ctx, path) catch |e| {
+            const msg = Self._err2msg(e) orelse return e;
+            ctx.stdio.errf("cd: {s}: {s}", .{ path, msg });
+        };
+    }
+};
+
+const _VarsBltn = struct {
+    const USAGE_TEXT =
+        \\usage: _vars
+    ;
+    const Self = @This();
+    const Params = struct {};
+
+    fn run(ctx: BltnCtx) !void {
+        if (ctx.args.len > 0) return ctx.usage_toomany(Self);
+        if (ctx.shell.vars.OLDPWD) |path| ctx.stdio.errf("OLDPWD={s}", .{path});
+        ctx.stdio.errf("ES={d}", .{ctx.shell.vars.ES});
+    }
+};
+
+const Bltn = enum {
+    exit,
+    echo,
+    type,
+    pwd,
+    cd,
+    _vars,
+
+    fn exists(cmd_name: []const u8) bool {
+        if (Bltn.select(cmd_name)) |_| return true;
+        return false;
+    }
+
+    fn select(cmd_name: []const u8) ?Bltn {
+        if (std.mem.eql(u8, cmd_name, "exit")) return .exit;
+        if (std.mem.eql(u8, cmd_name, "echo")) return .echo;
+        if (std.mem.eql(u8, cmd_name, "type")) return .type;
+        if (std.mem.eql(u8, cmd_name, "pwd")) return .pwd;
+        if (std.mem.eql(u8, cmd_name, "cd")) return .cd;
+        if (std.mem.eql(u8, cmd_name, "_vars")) return ._vars;
+        return null;
+    }
+};
+
+pub fn run_bltn(ctx: BltnCtx) !void {
+    const bltn = Bltn.select(ctx.cmd_name) orelse return error.NoSuchBltn;
+    std.log.debug("running bltn: {any}", .{bltn});
+    return switch (bltn) {
+        .exit => ExitBltn.run(ctx),
+        .echo => EchoBltn.run(ctx),
+        .type => TypeBltn.run(ctx),
+        .pwd => PwdBltn.run(ctx),
+        .cd => CdBltn.run(ctx),
+        ._vars => _VarsBltn.run(ctx),
+    };
+}

src/cmd.zig

@@ -0,0 +1,117 @@
+const std = @import("std");
+
+const util = @import("util.zig");
+const shell_ = @import("shell.zig");
+
+const Shell = shell_.Shell;
+const StdIO = shell_.StdIO;
+const Files = shell_.StdIO.Files;
+const Term = std.process.Child.Term;
+const CMD_NAME_INVALID = shell_.CMD_NAME_INVALID;
+const EXEC_PATH: enum { resolve, keep } = .keep;
+
+fn resolve_exec_path(
+    cmd_name: []const u8,
+    dir_entry: []const u8,
+    allocator: std.mem.Allocator,
+) ![]u8 {
+    const dir_path = try util.realpathWithTilde(allocator, dir_entry);
+    defer allocator.free(dir_path);
+    const dir_fd = try std.fs.openDirAbsolute(dir_path, .{});
+    const stat = try dir_fd.statFile(cmd_name);
+    if (stat.kind != .file) return error.NotAFile;
+    const file_path = try std.fs.path.join(allocator, &.{ dir_path, cmd_name });
+    errdefer allocator.free(file_path);
+    try std.posix.access(file_path, std.posix.X_OK);
+    return file_path;
+}
+
+pub fn find_exec_path(
+    cmd_name: []const u8,
+    allocator: std.mem.Allocator,
+) !?[]u8 {
+    std.debug.assert(std.mem.indexOfAny(u8, cmd_name, CMD_NAME_INVALID) == null);
+    const entrylist = try std.process.getEnvVarOwned(allocator, "PATH");
+    defer allocator.free(entrylist);
+    var iter = std.mem.tokenizeScalar(u8, entrylist, ':');
+    while (iter.next()) |entry| {
+        const file_path = resolve_exec_path(cmd_name, entry, allocator) catch continue;
+        return file_path;
+    }
+    return null;
+}
+
+/// stolen from std.process.Child
+fn statusToTerm(status: u32) Term {
+    return if (std.posix.W.IFEXITED(status))
+        Term{ .Exited = std.posix.W.EXITSTATUS(status) }
+    else if (std.posix.W.IFSIGNALED(status))
+        Term{ .Signal = std.posix.W.TERMSIG(status) }
+    else if (std.posix.W.IFSTOPPED(status))
+        Term{ .Stopped = std.posix.W.STOPSIG(status) }
+    else
+        Term{ .Unknown = status };
+}
+
+pub fn run_command(
+    argv: []const []const u8,
+    files: Files,
+    allocator: std.mem.Allocator,
+) !u8 {
+    if (argv.len == 0) return error.NoArgv;
+
+    // copy env
+    const env = try std.process.createEnvironFromExisting(
+        allocator,
+        @ptrCast(std.os.environ.ptr),
+        .{},
+    );
+
+    // check that the command exits
+    const exec_path = try find_exec_path(argv[0], allocator) orelse return error.NoSuchCommand;
+    // FIXME: THIS IS NOT SAFE, since there's space for race condition between
+    //        the check and the execvpeZ call below.
+    //        I haven't found any better way to check, though: execvpeZ() call below
+    //        is running in child process so its error.FileNotFound is not really useful
+
+    // set up argv
+    const argv_ = a: {
+        var al = std.ArrayList([]const u8).init(allocator);
+        try al.append(switch (EXEC_PATH) {
+            .keep => argv[0],
+            .resolve => exec_path,
+        });
+        try al.appendSlice(argv[1..]);
+        break :a try al.toOwnedSlice();
+    };
+
+    // make it into zero-terminated
+    const argv_buf = try allocator.allocSentinel(?[*:0]const u8, argv_.len, null);
+    for (argv_, 0..) |arg, i| {
+        argv_buf[i] = (try allocator.dupeZ(u8, arg)).ptr;
+    }
+
+    // fork()!
+    const child_pid = try std.posix.fork();
+    if (child_pid == 0) {
+        // WE ARE THE CHILD
+
+        // copy the file handles
+        if (files.stdin) |f| std.posix.dup2(f.handle, std.posix.STDIN_FILENO) catch {};
+        if (files.stdout) |f| std.posix.dup2(f.handle, std.posix.STDOUT_FILENO) catch {};
+        if (files.stderr) |f| std.posix.dup2(f.handle, std.posix.STDERR_FILENO) catch {};
+        const err = std.posix.execvpeZ(argv_buf.ptr[0].?, argv_buf.ptr, env.ptr);
+        _ = err catch std.process.exit(shell_.EXIT_ERROR); // nobody should see this, though..
+    } else {
+        // WE ARE THE PARENT
+
+        // close all the files and wait
+        // if (files.stdin) |f| f.close();
+        // if (files.stdout) |f| f.close();
+        // if (files.stderr) |f| f.close();
+        const res = std.posix.waitpid(child_pid, 0);
+        const term = statusToTerm(res.status);
+        if (term == .Exited) return term.Exited;
+        return error.UnsupportedWaitResult;
+    }
+}

src/main.zig

@@ -1,14 +1,18 @@
 const std = @import("std");
 
+const shell = @import("shell.zig");
+
+pub const std_options: std.Options = .{ .log_level = .info };
+
 pub fn main() !void {
-    // Uncomment this block to pass the first stage
-    // const stdout = std.io.getStdOut().writer();
-    // try stdout.print("$ ", .{});
+    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
+    var arena = std.heap.ArenaAllocator.init(gpa.allocator());
+    defer arena.deinit();
 
-    const stdin = std.io.getStdIn().reader();
-    var buffer: [1024]u8 = undefined;
-    const user_input = try stdin.readUntilDelimiter(&buffer, '\n');
+    var s = shell.Shell.init(arena.allocator());
+    try s.run();
+}
 
-    // TODO: Handle user input
-    _ = user_input;
+test {
+    std.testing.refAllDecls(@This());
 }

src/pedantic.zig

@@ -0,0 +1,110 @@
+const std = @import("std");
+
+pub const PwdComputer = struct {
+    byenv: []const u8,
+    byenv_resolved: []const u8,
+    byenv_realpath: []const u8,
+    actual: []const u8,
+    actual_resolved: []const u8,
+    allocator: std.mem.Allocator,
+
+    // POSIX (speaks in POSIXese)
+    //
+    // About pwd options (<https://pubs.opengroup.org/onlinepubs/9699919799/utilities/pwd.html>):
+    //
+    // > The following options shall be supported by the implementation:
+    // >
+    // >  * `-L` - If the PWD environment variable contains an absolute pathname
+    // >    of the current directory and the pathname does not contain any components
+    // >    that are dot or dot-dot, pwd shall write this pathname to standard output,
+    // >    except that if the PWD environment variable is longer than {PATH_MAX} bytes
+    // >    including the terminating null, it is unspecified whether pwd writes this
+    // >    pathname to standard output or behaves as if the -P option had been specified.
+    // >
+    // >    Otherwise, the -L option shall behave as the -P option.
+    // >
+    // > *  `-P` - The pathname written to standard output shall not contain any components
+    // >    that refer to files of type symbolic link. If there are multiple pathnames
+    // >    that the pwd utility could write to standard output, one beginning with a single
+    // >    *slash* character and one or more beginning with two *slash* characters,
+    // >    then it shall write the pathname beginning with a single *slash* character.
+    // >
+    // >    The pathname shall not contain any unnecessary *slash* characters after the
+    // >    leading one or two *slash* characters.
+    // >
+    // > If both -L and -P are specified, the last one shall apply. If neither -L nor -P is
+    // > specified, the pwd utility shall behave as if -L had been specified.
+    //
+    // About PWD (<https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html>):
+    //
+    // > This variable shall represent an absolute pathname of the current working directory.
+    // > It shall not contain any components that are dot or dot-dot. The value is set by the
+    // > cd utility, and by the sh utility during initialization.
+
+    pub fn create(allocator: std.mem.Allocator) !PwdComputer {
+        const byenv = std.process.getEnvVarOwned(allocator, "PWD") catch |e| switch (e) {
+            error.EnvironmentVariableNotFound => return error.UndefinedBehavior,
+            else => return e,
+        };
+        const actual = try std.process.getCwdAlloc(allocator);
+        return PwdComputer{
+            .byenv = byenv,
+            .byenv_resolved = try std.fs.path.resolvePosix(allocator, &.{byenv}),
+            .byenv_realpath = try std.fs.realpathAlloc(allocator, byenv),
+            .actual = actual,
+            .actual_resolved = try std.fs.path.resolvePosix(allocator, &.{actual}),
+            .allocator = allocator,
+        };
+    }
+
+    pub fn destroy(self: @This()) void {
+        self.allocator.free(self.byenv);
+        self.allocator.free(self.byenv_resolved);
+        self.allocator.free(self.actual);
+        self.allocator.free(self.actual_resolved);
+    }
+
+    fn _has_dot_or_dotdot(path: []const u8) bool {
+        var it = std.mem.tokenizeScalar(u8, path, '/');
+        while (it.next()) |component| switch (component.len) {
+            0 => continue,
+            1 => if (component[0] == '.') return true,
+            2 => if (component[0] == '.' and component[1] == '.') return true,
+            else => continue,
+        };
+        return false;
+    }
+
+    fn _is_too_long(path: []const u8) bool {
+        return (path.len + 1) > std.posix.PATH_MAX;
+    }
+
+    fn _l_applies(self: @This()) bool {
+        // > If the PWD environment variable contains an absolute pathname
+        if (self.byenv.len < 1) return false; // empty
+        if (self.byenv[0] != '/') return false; // not absolute
+        // > ... of the current directory
+        if (!std.mem.eql(u8, self.byenv_resolved, self.actual_resolved)) return false;
+        // > ... and the pathname does not contain any components that are dot or dot-dot,
+        if (_has_dot_or_dotdot(self.byenv)) return false;
+        return true;
+    }
+
+    pub fn getpath_P(self: @This()) []const u8 {
+        return self.byenv_realpath;
+    }
+
+    pub fn getpath_L(self: @This()) []const u8 {
+        if (!self._l_applies()) return self.getpath_P();
+        // > .. except that if the PWD environment variable is longer than {PATH_MAX} bytes
+        // > including the terminating null..
+        if ((self.byenv.len + 1) > std.posix.PATH_MAX) {
+            // > .. it is unspecified whether pwd writes this pathname to standard output
+            // > or behaves as if the -P option had been specified
+            //
+            // We choose the second. option
+            return self.getpath_P();
+        }
+        return self.byenv;
+    }
+};

src/shell.zig

@@ -0,0 +1,311 @@
+const std = @import("std");
+
+const bltn_ = @import("bltn.zig");
+const cmd_ = @import("cmd.zig");
+const syntax = @import("syntax.zig");
+const util = @import("util.zig");
+
+const Bltn = bltn_.Bltn;
+const RedirOp = syntax.RedirOp;
+const run_command = cmd_.run_command;
+
+pub const EXIT_OK = 0;
+pub const EXIT_NO = 1;
+pub const EXIT_USAGE_ERROR = 2;
+pub const EXIT_ERROR = 3;
+pub const EXIT_ERRPANIC = 4;
+pub const EXIT_IOPANIC = 5;
+
+pub const CMD_NAME_INVALID = "/\x00\n";
+
+pub const DEVEL_MODE: enum { devel, release } = .devel;
+pub const DEVEL_MODE_SHOW_BUFFER: bool = false;
+
+const BUFSIZE_REPL = 8192;
+const BUFSIZE_INPUT = 1024;
+
+pub const StdIO = struct {
+    stdin_f: std.fs.File,
+    stdout_f: std.fs.File,
+    stderr_f: std.fs.File,
+    shell_stderr_f: std.fs.File,
+    stdin_redir: ?RedirOp,
+    stdout_redir: ?RedirOp,
+    stderr_redir: ?RedirOp,
+
+    fn _handle_stderr_error(self: @This(), e: anyerror) void {
+        // in case of external stdin, we can fall
+        if (self.stderr_redir == null) iopanic(); // not redirected
+        const path = self.stderr_redir.?.path;
+        const w = self.shell_stderr_f.writer();
+        w.print("cannot write to redirected stderr: {!} when writing to {s}\n", .{ e, path }) catch iopanic();
+    }
+
+    /// Try to write details of error *e* to file handle *err_f* and die.
+    /// This exits the process with EXIT_ERRPANIC, except when the write fails
+    /// in which case it exits with EXIT_IOPANIC.
+    fn errpanic(err_f: std.fs.File, e: anyerror) noreturn {
+        err_f.writeAll("panic: ") catch iopanic();
+        err_f.writeAll(@errorName(e)) catch iopanic();
+        err_f.writeAll("\n") catch iopanic();
+        std.process.exit(EXIT_ERRPANIC);
+    }
+
+    pub const Files = struct {
+        stdin: ?std.fs.File = null,
+        stdout: ?std.fs.File = null,
+        stderr: ?std.fs.File = null,
+    };
+
+    fn redird_files(self: @This()) Files {
+        var fs = Files{};
+        if (self.stdin_redir != null) fs.stdin = self.stdin_f;
+        if (self.stdout_redir != null) fs.stdout = self.stdout_f;
+        if (self.stderr_redir != null) fs.stderr = self.stderr_f;
+        return fs;
+    }
+
+    fn close(self: @This()) void {
+        if (self.stdin_redir) |op| {
+            std.log.debug("closing stdin redirect: {s}", .{op.path});
+            self.stdin_f.close();
+        }
+        if (self.stdout_redir) |op| {
+            std.log.debug("closing stdout redirect: {s}", .{op.path});
+            self.stdout_f.close();
+        }
+        if (self.stderr_redir) |op| {
+            std.log.debug("closing stderr redirect: {s}", .{op.path});
+            self.stderr_f.close();
+        }
+    }
+
+    pub fn err(self: @This(), msg: []const u8) void {
+        self.stderr_f.writeAll(msg) catch |e| self._handle_stderr_error(e);
+        self.stderr_f.writeAll("\n") catch |e| self._handle_stderr_error(e);
+    }
+
+    pub fn errf(self: @This(), comptime fmt: []const u8, args: anytype) void {
+        self.stderr_f.writer().print(fmt, args) catch |e| self._handle_stderr_error(e);
+        self.stderr_f.writeAll("\n") catch |e| self._handle_stderr_error(e);
+    }
+
+    pub fn outw(self: @This(), msg: []const u8) !void {
+        try self.stdout_f.writeAll(msg);
+    }
+
+    pub fn out(self: @This(), msg: []const u8) !void {
+        try self.stdout_f.writeAll(msg);
+        try self.stdout_f.writeAll("\n");
+    }
+
+    pub fn outf(self: @This(), comptime fmt: []const u8, args: anytype) !void {
+        try self.stdout_f.writer().print(fmt, args);
+        try self.stdout_f.writeAll("\n");
+    }
+};
+
+/// Context of single REPL iteration
+pub const Loop = struct {
+    shell: *Shell,
+    allocator: std.mem.Allocator,
+
+    /// Get input from user
+    fn _get_input(self: *@This()) ![]const u8 {
+        try self.shell.outw("$ ");
+        const r = self.shell.stdin_f.reader();
+        return try r.readUntilDelimiter(self.shell.input_buffer.?, '\n');
+    }
+
+    /// Open path for IO redirect
+    fn _open_redir_file(op: RedirOp) !std.fs.File {
+        const cwd_fd = std.fs.cwd();
+        switch (op.dir) {
+            .in => return try cwd_fd.openFile(op.path, .{ .mode = .read_only }),
+            .out => return try cwd_fd.createFile(op.path, .{}),
+            .app => {
+                // zls fails here; thinks `res` is `File` correct is `?File`
+                const res: ?std.fs.File = cwd_fd.openFile(op.path, .{ .mode = .write_only }) catch |e| switch (e) {
+                    error.FileNotFound => null,
+                    else => return e,
+                };
+                if (res) |fd| {
+                    try fd.seekFromEnd(0);
+                    return fd;
+                }
+                return try cwd_fd.createFile(op.path, .{});
+            },
+        }
+    }
+
+    /// Create StdIO object with redirects applied and the proper filehandles open
+    fn _create_stdio(
+        self: @This(),
+        stdin_redir: ?RedirOp,
+        stdout_redir: ?RedirOp,
+        stderr_redir: ?RedirOp,
+    ) !StdIO {
+        return StdIO{
+            .stdin_f = if (stdin_redir) |op| try _open_redir_file(op) else self.shell.stdin_f,
+            .stdout_f = if (stdout_redir) |op| try _open_redir_file(op) else self.shell.stdout_f,
+            .stderr_f = if (stderr_redir) |op| try _open_redir_file(op) else self.shell.stderr_f,
+            .shell_stderr_f = self.shell.stderr_f,
+            .stdin_redir = stdin_redir,
+            .stdout_redir = stdout_redir,
+            .stderr_redir = stderr_redir,
+        };
+    }
+
+    /// Do one loop of REPL
+    fn run(self: *@This()) !void {
+        const user_input = self._get_input() catch |e| switch (e) {
+            error.EndOfStream => self.shell.exit_eof(),
+            else => return e,
+        };
+
+        if (user_input.len == 0) return;
+        const stmt = try syntax.parse_stmt(user_input, self.allocator);
+        if (stmt.argv.len == 0) return;
+
+        const stdio = try self._create_stdio(
+            stmt.stdin_redir,
+            stmt.stdout_redir,
+            stmt.stderr_redir,
+        );
+        defer stdio.close();
+
+        const ctx = bltn_.BltnCtx{
+            .shell = self.shell,
+            .stdio = stdio,
+            .loop = self,
+            .cmd_name = stmt.argv[0],
+            .args = stmt.argv[1..],
+            .allocator = self.allocator,
+        };
+
+        bltn_.run_bltn(ctx) catch |e| switch (e) {
+            error.UsageError => {},
+            error.NoSuchBltn => {
+                const es = run_command(
+                    stmt.argv,
+                    stdio.redird_files(),
+                    self.allocator,
+                ) catch |run_e| switch (run_e) {
+                    error.NoSuchCommand => {
+                        self.shell.errf("{s}: command not found", .{stmt.argv[0]});
+                        return;
+                    },
+                    else => return run_e,
+                };
+                _ = es;
+            },
+            else => return e,
+        };
+    }
+};
+
+/// Just die after realizing even IO does not work
+///
+/// Use this as last resort, when catching from a call which is not expected
+/// to have any other mode of failure than stderr writing error.
+///
+/// In any other cases (eg. when the call involves formatting, ie. the failure
+/// could be something like memory allocation), catch the error and use
+/// `errpanic(fh, e)` at least, so that user has a chance of understanding what
+/// is wrong.
+///
+/// Since EXIT_IOPANIC is not used anywhere else, at least seeing that exit
+/// status can hint towards the fact that there was error but stderr was broken
+/// so we could not provide any info.
+pub fn iopanic() noreturn {
+    std.process.exit(EXIT_IOPANIC);
+}
+
+/// Try to write details of error *e* to file handle *err_f* and die.
+/// This exits the process with EXIT_ERRPANIC, except when the write fails
+/// in which case it exits with EXIT_IOPANIC.
+pub fn errpanic(err_f: std.fs.File, e: anyerror) noreturn {
+    err_f.writeAll("panic: ") catch iopanic();
+    err_f.writeAll(@errorName(e)) catch iopanic();
+    err_f.writeAll("\n") catch iopanic();
+    std.process.exit(EXIT_ERRPANIC);
+}
+
+pub const Shell = struct {
+    stdin_f: std.fs.File,
+    stdout_f: std.fs.File,
+    stderr_f: std.fs.File,
+    allocator: std.mem.Allocator,
+    repl_buffer: ?[]u8 = null,
+    input_buffer: ?[]u8 = null,
+    vars: Vars,
+
+    const Vars = struct {
+        OLDPWD: ?[]const u8 = null,
+        ES: u8 = 0,
+    };
+
+    pub fn init(allocator: std.mem.Allocator) Shell {
+        return Shell{
+            .stdout_f = std.io.getStdOut(),
+            .stdin_f = std.io.getStdIn(),
+            .stderr_f = std.io.getStdErr(),
+            .allocator = allocator,
+            .vars = Vars{},
+        };
+    }
+
+    pub fn setOldPwd(self: *@This(), path: []const u8) !void {
+        if (self.vars.OLDPWD) |pwd| {
+            self.allocator.free(pwd);
+        }
+        self.vars.OLDPWD = try self.allocator.dupe(u8, path);
+    }
+
+    fn errf(self: @This(), comptime fmt: []const u8, args: anytype) void {
+        self.stderr_f.writer().print(fmt, args) catch |e| errpanic(self.stderr_f, e);
+        self.stderr_f.writeAll("\n") catch iopanic();
+    }
+
+    fn outw(self: @This(), msg: []const u8) !void {
+        try self.stdout_f.writeAll(msg);
+    }
+
+    fn exit_eof(self: @This()) noreturn {
+        self.stdout_f.writeAll("\n") catch iopanic();
+        std.process.exit(EXIT_OK);
+    }
+
+    pub fn exit(self: @This(), es: u7) noreturn {
+        _ = self;
+        std.process.exit(@as(u8, es));
+    }
+
+    fn repl(self: *@This()) !void {
+        var fba = std.heap.FixedBufferAllocator.init(self.repl_buffer.?);
+        while (true) {
+            fba.reset();
+            var loop = Loop{
+                .shell = self,
+                .allocator = fba.allocator(),
+            };
+            try loop.run();
+        }
+    }
+
+    pub fn run(self: *@This()) !void {
+        self.repl_buffer = self.allocator.alloc(u8, BUFSIZE_REPL) catch |e| errpanic(self.stderr_f, e);
+        self.input_buffer = self.allocator.alloc(u8, BUFSIZE_INPUT) catch |e| errpanic(self.stderr_f, e);
+        defer self.allocator.free(self.repl_buffer.?);
+        defer self.allocator.free(self.input_buffer.?);
+        _ = self.repl() catch |e| {
+            switch (DEVEL_MODE) {
+                .devel => {
+                    if (DEVEL_MODE_SHOW_BUFFER) self.errf("REPL buffer: {s}", .{util.qb(self.repl_buffer.?, 100000)});
+                    return e;
+                },
+                .release => errpanic(self.stderr_f, e),
+            }
+        };
+    }
+};

src/util.zig

@@ -0,0 +1,155 @@
+const std = @import("std");
+
+pub fn realpathWithTilde(allocator: std.mem.Allocator, path: []const u8) ![]u8 {
+    const replaced = try subst_tilde(allocator, path);
+    defer allocator.free(replaced);
+    return try std.fs.realpathAlloc(allocator, replaced);
+}
+
+/// leverage expectEqualStrings() when possible
+pub fn assert_equal_slices(
+    comptime T: type,
+    comptime fmtfn: *const fn (T) []const u8,
+    oracle: []const T,
+    result: []const T,
+) !void {
+    var ew = std.io.getStdErr().writer();
+    const max_checks = @max(oracle.len, result.len);
+    for (0..max_checks) |idx| {
+        if (idx >= result.len) {
+            const missing = oracle[idx..];
+            for (missing) |item| try ew.print(
+                "expected but missing: {s} at index {d}\n",
+                .{ fmtfn(item), idx },
+            );
+            return error.TestFailMissingItems;
+        }
+        if (idx >= oracle.len) {
+            const extra = result[idx..];
+            for (extra) |item| try ew.print(
+                "unexpected extra item: {s} at index {d}\n",
+                .{ fmtfn(item), idx },
+            );
+            return error.TestFailExtraItems;
+        }
+        try std.testing.expectEqualStrings(
+            fmtfn(oracle[idx]),
+            fmtfn(result[idx]),
+        );
+    }
+}
+
+/// leverage expectEqualStrings() when possible
+pub fn assert_optional_strings(
+    oracle: ?[]const u8,
+    result: ?[]const u8,
+) !void {
+    if (oracle == null and result == null) return;
+    if (oracle != null and result == null) {
+        try std.io.getStdErr().writer().print("expected \"{s}\", got null\n", .{oracle.?});
+        return error.TestFailOptinalString;
+    }
+    if (oracle == null and result != null) {
+        try std.io.getStdErr().writer().print("expected null, got \"{s}\"\n", .{result.?});
+        return error.TestFailOptinalString;
+    }
+    try std.testing.expectEqualStrings(oracle.?, result.?);
+}
+
+pub fn subst_tilde(allocator: std.mem.Allocator, path: []const u8) ![]u8 {
+    var home: []const u8 = undefined;
+    var delim: []const u8 = "/";
+    var replaced: []u8 = undefined;
+    if (!std.mem.startsWith(u8, path, "~")) {
+        replaced = try allocator.dupe(u8, path);
+        return replaced;
+    }
+    home = try std.process.getEnvVarOwned(allocator, "HOME");
+    defer allocator.free(home);
+    if (std.mem.eql(u8, path, "~")) {
+        replaced = try allocator.dupe(u8, home);
+        return replaced;
+    }
+    if (!std.mem.startsWith(u8, path, "~/")) {
+        replaced = try allocator.dupe(u8, path);
+        return replaced;
+    }
+    if (std.mem.endsWith(u8, home, "/")) delim = "";
+    return try std.fmt.allocPrint(allocator, "{s}{s}{s}", .{ home, delim, path[2..] });
+}
+
+const QMAX: usize = 64;
+
+pub fn qb(blob: []const u8, max: ?usize) []const u8 {
+    var al = std.ArrayList(u8).init(std.heap.page_allocator);
+    qblob(blob, max orelse QMAX, al.writer().any()) catch unreachable;
+    return al.toOwnedSlice() catch unreachable;
+}
+
+pub fn qbs(blobs: []const []const u8, max: ?usize) []const u8 {
+    var al = std.ArrayList(u8).init(std.heap.page_allocator);
+    al.writer().writeAll("&.{") catch unreachable;
+    for (blobs, 0..) |blob, idx| {
+        if (idx > 0) al.writer().writeByte(',') catch unreachable;
+        qblob(blob, max orelse QMAX, al.writer().any()) catch unreachable;
+    }
+    al.writer().writeByte('}') catch unreachable;
+    return al.toOwnedSlice() catch unreachable;
+}
+
+pub fn qs(str: []const u8, max: ?usize) []const u8 {
+    var al = std.ArrayList(u8).init(std.heap.page_allocator);
+    qstr(str, max orelse QMAX, al.writer().any()) catch unreachable;
+    return al.toOwnedSlice() catch unreachable;
+}
+
+pub fn qss(strs: []const []const u8, max: ?usize) []const u8 {
+    var al = std.ArrayList(u8).init(std.heap.page_allocator);
+    al.writer().writeAll("&.{") catch unreachable;
+    for (strs, 0..) |str, idx| {
+        if (idx > 0) al.writer().writeByte(',') catch unreachable;
+        qstr(str, max orelse QMAX, al.writer().any()) catch unreachable;
+    }
+    al.writer().writeByte('}') catch unreachable;
+    return al.toOwnedSlice() catch unreachable;
+}
+
+pub fn qblob(blob: []const u8, max: usize, writer: std.io.AnyWriter) !void {
+    const last_idx = @min(blob.len, max);
+    try writer.print("[{d}]|", .{blob.len});
+    try escape_nonascii(blob[0..last_idx], writer);
+    if (blob.len > max) _ = try writer.write("..");
+    try writer.writeByte('|');
+}
+
+pub fn qstr(str: []const u8, max: usize, writer: std.io.AnyWriter) !void {
+    const last_idx = @min(str.len, max);
+    try writer.writeByte('"');
+    try escape(str[0..last_idx], writer);
+    if (str.len > max) try writer.print("..({d} more)", .{str.len - max});
+    try writer.writeByte('"');
+}
+
+pub fn escape(str: []const u8, writer: std.io.AnyWriter) !void {
+    for (str) |c| _ = switch (c) {
+        '\n' => try writer.write("\\n"),
+        '\r' => try writer.write("\\r"),
+        '\t' => try writer.write("\\t"),
+        '\\' => try writer.write("\\\\"),
+        '\'' => try writer.write("\\'"),
+        '"' => try writer.write("\\\""),
+        else => try writer.writeByte(c),
+    };
+}
+
+pub fn escape_nonascii(str: []const u8, writer: std.io.AnyWriter) !void {
+    for (str) |c| _ = switch (c) {
+        '\n' => try writer.write("\\n"),
+        '\r' => try writer.write("\\r"),
+        '\t' => try writer.write("\\t"),
+        '\\' => try writer.write("\\\\"),
+        '\'' => try writer.write("\\'"),
+        '"' => try writer.write("\\\""),
+        else => if (std.ascii.isASCII(c)) try writer.writeByte(c) else try writer.print("\\x{x}", .{c}),
+    };
+}

utils/tgen.sh

@@ -0,0 +1,125 @@
+#!/bin/bash
+
+
+warn() {
+    echo "$@" >&2
+}
+
+die() {
+    echo "$@" >&2
+    exit 3
+}
+
+content_desc() {
+    local c=$1
+    case $c in
+        \ ) echo space ;;
+        \!) echo exclamation mark ;;
+        \$) echo dollar sign ;;
+        \&) echo ampersand ;;
+        \() echo opening bracket ;;
+        \)) echo closing bracket ;;
+        \*) echo asterisk ;;
+        \;) echo semicolon ;;
+        \?) echo question mark ;;
+        \\) echo backslash ;;
+        \`) echo tick mark;;
+        \>) echo greater than ;;
+        \<) echo less than ;;
+        \{) echo opening curly brace ;;
+        \|) echo pipe symbol ;;
+        \}) echo closing curly brace ;;
+        BS) echo backslash ;;
+        SQ) echo single quote ;;
+        DQ) echo double quote ;;
+        TAB) echo tab ;;
+        ES) echo empty string ;;
+        NL) echo newline ;;
+        A) echo letter A ;;
+    esac
+}
+
+mode_name() {
+    local mode=$1
+    case $mode in
+        bs) echo backslash escaping ;;
+        sq) echo single quoting ;;
+        dq) echo double quoting ;;
+    esac
+}
+
+
+mktest() {
+    local mode=$1; shift
+    local mode_name
+    local content_desc
+    mode_name="$(mode_name "$mode")"
+    local c
+    local self=$0
+    printf 'test "parse: %s (generated)" {\n' "$mode_name"
+    printf '    // TEST GENERATED BY %s\n' "$self"
+    #shellcheck disable=SC2016
+    for c in "$@"; do
+        content_desc="$(content_desc "$c")"
+        # every backslash needs to be doubled because of printf.
+        # some backslashes need to be doubled again becase of syntax (eg. `"\\\\" is 2 backslashes in Zig)
+        case $mode:$c in
+            bs:BS)      printf '    try parse_t("\\\\\\\\", Result{ .tokens = &.{"\\\\"} });  // %s `\\` (%s)\n' "$mode_name" "$content_desc" ;;
+            bs:DQ)      printf '    try parse_t("\\\\\\"", Result{ .tokens = &.{"\\""} });  // %s `"` (%s)\n' "$mode_name" "$content_desc" ;;
+            bs:ES)      true ;;     # impossible case
+            bs:NL)      printf '    try parse_t("\\\\\\n", Result{ .tokens = &.{"\\n"} });  // %s `\\n` (%s)\n' "$mode_name" "$content_desc" ;;
+            bs:SQ)      printf '    try parse_t("\\\\%s", Result{ .tokens = &.{"%s"} });  // %s `%s` (%s)\n' "'" "'" "$mode_name" "'" "$content_desc" ;;
+            bs:TAB)     printf '    try parse_t("\\\\\\t", Result{ .tokens = &.{"\\t"} });  // %s `\\t` (%s)\n' "$mode_name" "$content_desc"  ;;
+            bs:*)       printf '    try parse_t("\\\\%s", Result{ .tokens = &.{"%s"} });  // %s `%s` (%s)\n' "$c" "$c" "$mode_name" "$c" "$content_desc" ;;
+            sq:NL)      printf '    try parse_t("%s\\n%s", Result{ .tokens = &.{"\\n"} });  // %s `\\n` (%s)\n' "'" "'" "$mode_name" "$content_desc" ;;
+            sq:TAB)     printf '    try parse_t("%s\\t%s", Result{ .tokens = &.{"\\t"} });  // %s `\\t` (%s)\n' "'" "'" "$mode_name" "$content_desc" ;;
+            sq:DQ)      printf '    try parse_t("%s\\"%s", Result{ .tokens = &.{"\\""} });  // %s `"` (%s)\n' "'" "'" "$mode_name" "$content_desc" ;;
+            sq:ES)      printf '    try parse_t("%s%s", Result{ .tokens = &.{""} });  // %s `\\` (%s)\n' "'" "'" "$mode_name" "$content_desc" ;;
+            sq:BS)      printf '    try parse_t("%s\\\\%s", Result{ .tokens = &.{"\\\\"} });  // %s `\\` (%s)\n' "'" "'" "$mode_name" "$content_desc" ;;
+            sq:SQ)      true ;;     # impossible case
+            sq:*)       printf '    try parse_t("'"'"'%s'"'"'", Result{ .tokens = &.{"%s"} });  // %s `%s` (%s)\n' "$c" "$c" "$mode_name" "$c" "$content_desc" ;;
+            dq:BS)      printf '    try parse_t("\\"\\\\\\\\\\"", Result{ .tokens = &.{"\\\\"} });  // %s `\\` (%s)\n' "$mode_name" "$content_desc" ;;
+            dq:DQ)      printf '    try parse_t("\\"\\\\\\"\\"", Result{ .tokens = &.{"\\""} });  // %s `"` (%s)\n' "$mode_name" "$content_desc" ;;
+            dq:ES)      printf '    try parse_t("\\"\\"", Result{ .tokens = &.{""} });  // %s `\\` (%s)\n' "$mode_name" "$content_desc" ;;
+            dq:NL)      printf '    try parse_t("\\"\\n\\"", Result{ .tokens = &.{"\\n"} });  // %s `\\n` (%s)\n' "$mode_name" "$content_desc" ;;
+            dq:SQ)      printf '    try parse_t("\\"%s\\"", Result{ .tokens = &.{"%s"} });  // %s `%s` (%s)\n' "'" "'" "$mode_name" "'" "$content_desc" ;;
+            dq:TAB)     printf '    try parse_t("\\"\\t\\"", Result{ .tokens = &.{"\\t"} });  // %s `\\t` (tab)\n' "$mode_name" ;;
+            dq:*)       printf '    try parse_t("\\"%s\\"", Result{ .tokens = &.{"%s"} });  // %s `%s` (%s)\n' "$c" "$c" "$mode_name" "$c" "$content_desc" ;;
+            *)  die "unknown character or mode: c=$c mode=$mode" ;;
+        esac
+    done
+    printf '}\n'
+    echo
+}
+
+main() {
+    local cases=(
+        '!'
+        '$'
+        '&'
+        '('
+        ')'
+        '*'
+        ';'
+        '?'
+        '`'
+        '{'
+        '>'
+        '<'
+        '|'
+        '}'
+        ' '
+        SQ
+        DQ
+        BS
+        TAB
+        NL
+        ES
+        A
+    )
+    mktest bs "${cases[@]}"
+    mktest sq "${cases[@]}"
+    mktest dq "${cases[@]}"
+}
+
+main "$@"

your_program.sh

@@ -21,4 +21,4 @@ set -e # Exit early if any commands fail
 #
 # - Edit this to change how your program runs locally
 # - Edit .codecrafters/run.sh to change how your program runs remotely
-exec zig-out/bin/main "$@"
+exec strace -f -o your_program.strace zig-out/bin/main "$@"