Add errno utility, which prints out error codes

Including the full text output in the tests might be annoying in future
if this format changes, but the tests can be made smarter if that's an
issue in the future.

src/platform/PosixError.js

@@ -57,6 +57,15 @@ export const ErrorMetadata = new Map([
     [ErrorCodes.ECONNREFUSED, { code: 111, description: 'Connection refused' }],
 ]);
 
+export const errorFromIntegerCode = (code) => {
+    for (const [errorCode, metadata] of ErrorMetadata) {
+        if (metadata.code === code) {
+            return errorCode;
+        }
+    }
+    return undefined;
+};
+
 export class PosixError extends Error {
     // posixErrorCode can be either a string, or one of the ErrorCodes above.
     // If message is undefined, a default message will be used.

src/puter-shell/coreutils/__exports__.js

@@ -28,6 +28,7 @@ import module_dcall from './dcall.js'
 import module_dirname from './dirname.js'
 import module_echo from './echo.js'
 import module_env from './env.js'
+import module_errno from './errno.js'
 import module_false from './false.js'
 import module_grep from './grep.js'
 import module_head from './head.js'
@@ -67,6 +68,7 @@ export default {
     "dirname": module_dirname,
     "echo": module_echo,
     "env": module_env,
+    "errno": module_errno,
     "false": module_false,
     "grep": module_grep,
     "head": module_head,

src/puter-shell/coreutils/errno.js

@@ -0,0 +1,113 @@
+/*
+ * Copyright (C) 2024  Puter Technologies Inc.
+ *
+ * This file is part of Phoenix Shell.
+ *
+ * Phoenix Shell is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+import { ErrorCodes, ErrorMetadata, errorFromIntegerCode } from '../../platform/PosixError.js';
+import { Exit } from './coreutil_lib/exit.js';
+
+const maxErrorNameLength = Object.keys(ErrorCodes)
+    .reduce((longest, name) => Math.max(longest, name.length), 0);
+const maxNumberLength = 3;
+
+async function printSingleErrno(errorCode, out) {
+    const metadata = ErrorMetadata.get(errorCode);
+    const paddedName = errorCode.description + ' '.repeat(maxErrorNameLength - errorCode.description.length);
+    const code = metadata.code.toString();
+    const paddedCode = ' '.repeat(maxNumberLength - code.length) + code;
+    await out.write(`${paddedName} ${paddedCode} ${metadata.description}\n`);
+}
+
+export default {
+    name: 'errno',
+    usage: 'errno [OPTIONS] [NAME-OR-CODE...]',
+    description: 'Look up and describe errno codes.',
+    args: {
+        $: 'simple-parser',
+        allowPositionals: true,
+        options: {
+            list: {
+                description: 'List all errno values',
+                type: 'boolean',
+                short: 'l'
+            },
+            search: {
+                description: 'Search for errors whose descriptions contain NAME-OR-CODEs, case-insensitively',
+                type: 'boolean',
+                short: 's'
+            }
+        }
+    },
+    execute: async ctx => {
+        const { err, out } = ctx.externs;
+        const { positionals, values } = ctx.locals;
+
+        if (values.search) {
+            for (const [errorCode, metadata] of ErrorMetadata) {
+                const description = metadata.description.toLowerCase();
+                let matches = true;
+                for (const nameOrCode of positionals) {
+                    if (! description.includes(nameOrCode.toLowerCase())) {
+                        matches = false;
+                        break;
+                    }
+                }
+                if (matches) {
+                    await printSingleErrno(errorCode, out);
+                }
+            }
+            return;
+        }
+
+        if (values.list) {
+            for (const errorCode of ErrorMetadata.keys()) {
+                await printSingleErrno(errorCode, out);
+            }
+            return;
+        }
+
+        let failedToMatchSomething = false;
+        const fail = async (nameOrCode) => {
+            await err.write(`ERROR: Not understood: ${nameOrCode}\n`);
+            failedToMatchSomething = true;
+        };
+
+        for (const nameOrCode of positionals) {
+            let errorCode = ErrorCodes[nameOrCode.toUpperCase()];
+            if (errorCode) {
+                await printSingleErrno(errorCode, out);
+                continue;
+            }
+
+            const code = Number.parseInt(nameOrCode);
+            if (!isFinite(code)) {
+                await fail(nameOrCode);
+                continue;
+            }
+            errorCode = errorFromIntegerCode(code);
+            if (errorCode) {
+                await printSingleErrno(errorCode, out);
+                continue;
+            }
+
+            await fail(nameOrCode);
+        }
+
+        if (failedToMatchSomething) {
+            throw new Exit(1);
+        }
+    }
+};

test/coreutils.test.js

@@ -20,6 +20,7 @@ import { runBasenameTests } from "./coreutils/basename.js";
 import { runDirnameTests } from "./coreutils/dirname.js";
 import { runEchoTests } from "./coreutils/echo.js";
 import { runEnvTests } from "./coreutils/env.js";
+import { runErrnoTests } from './coreutils/errno.js';
 import { runFalseTests } from "./coreutils/false.js";
 import { runHeadTests } from "./coreutils/head.js";
 import { runPrintfTests } from './coreutils/printf.js';
@@ -34,6 +35,7 @@ describe('coreutils', function () {
     runDirnameTests();
     runEchoTests();
     runEnvTests();
+    runErrnoTests();
     runFalseTests();
     runHeadTests();
     runPrintfTests();

test/coreutils/errno.js

@@ -0,0 +1,144 @@
+/*
+ * Copyright (C) 2024  Puter Technologies Inc.
+ *
+ * This file is part of Phoenix Shell.
+ *
+ * Phoenix Shell is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+import assert from 'assert';
+import { MakeTestContext } from './harness.js'
+import builtins from '../../src/puter-shell/coreutils/__exports__.js';
+import { ErrorCodes, ErrorMetadata } from '../../src/platform/PosixError.js';
+
+export const runErrnoTests = () => {
+    describe('errno', function () {
+
+        const testCases = [
+            {
+                description: 'exits normally if nothing is passed in',
+                input: [ ],
+                values: {},
+                expectedStdout: '',
+                expectedStderr: '',
+                expectedFail: false,
+            },
+            {
+                description: 'can search by number',
+                input: [ ErrorMetadata.get(ErrorCodes.EFBIG).code.toString() ],
+                values: {},
+                expectedStdout: 'EFBIG         27 File too big\n',
+                expectedStderr: '',
+                expectedFail: false,
+            },
+            {
+                description: 'can search by number',
+                input: [ ErrorCodes.EIO.description ],
+                values: {},
+                expectedStdout: 'EIO            5 IO error\n',
+                expectedStderr: '',
+                expectedFail: false,
+            },
+            {
+                description: 'prints an error message and returns a code > 0 if an error is not found',
+                input: [ 'NOT-A-REAL-ERROR' ],
+                values: {},
+                expectedStdout: '',
+                expectedStderr: 'ERROR: Not understood: NOT-A-REAL-ERROR\n',
+                expectedFail: true,
+            },
+            {
+                description: 'accepts multiple arguments and prints each',
+                input: [ ErrorMetadata.get(ErrorCodes.ENOENT).code.toString(), 'NOT-A-REAL-ERROR', ErrorCodes.EPIPE.description ],
+                values: {},
+                expectedStdout:
+                    'ENOENT         2 File or directory not found\n' +
+                    'EPIPE         32 Pipe broken\n',
+                expectedStderr: 'ERROR: Not understood: NOT-A-REAL-ERROR\n',
+                expectedFail: true,
+            },
+            {
+                description: 'searches descriptions if --search is provided',
+                input: [ 'directory' ],
+                values: { search: true },
+                expectedStdout:
+                    'ENOENT         2 File or directory not found\n' +
+                    'ENOTDIR       20 Is not a directory\n' +
+                    'EISDIR        21 Is a directory\n' +
+                    'ENOTEMPTY     39 Directory is not empty\n',
+                expectedStderr: '',
+                expectedFail: false,
+            },
+            {
+                description: 'lists all errors if --list is provided, ignoring parameters',
+                input: [ 'directory' ],
+                values: { list: true },
+                expectedStdout:
+                    'EPERM          1 Operation not permitted\n' +
+                    'ENOENT         2 File or directory not found\n' +
+                    'EIO            5 IO error\n' +
+                    'EACCES        13 Permission denied\n' +
+                    'EEXIST        17 File already exists\n' +
+                    'ENOTDIR       20 Is not a directory\n' +
+                    'EISDIR        21 Is a directory\n' +
+                    'EINVAL        22 Argument invalid\n' +
+                    'EMFILE        24 Too many open files\n' +
+                    'EFBIG         27 File too big\n' +
+                    'ENOSPC        28 Device out of space\n' +
+                    'EPIPE         32 Pipe broken\n' +
+                    'ENOTEMPTY     39 Directory is not empty\n' +
+                    'EADDRINUSE    98 Address already in use\n' +
+                    'ECONNRESET   104 Connection reset\n' +
+                    'ETIMEDOUT    110 Connection timed out\n' +
+                    'ECONNREFUSED 111 Connection refused\n',
+                expectedStderr: '',
+                expectedFail: false,
+            },
+            {
+                description: '--search overrides --list',
+                input: [ 'directory' ],
+                values: { list: true, search: true },
+                expectedStdout:
+                    'ENOENT         2 File or directory not found\n' +
+                    'ENOTDIR       20 Is not a directory\n' +
+                    'EISDIR        21 Is a directory\n' +
+                    'ENOTEMPTY     39 Directory is not empty\n',
+                expectedStderr: '',
+                expectedFail: false,
+            },
+        ];
+
+        for (const { description, input, values, expectedStdout, expectedStderr, expectedFail } of testCases) {
+            it(description, async () => {
+                let ctx = MakeTestContext(builtins.errno, { positionals: input, values });
+                let hadError = false;
+                try {
+                    const result = await builtins.errno.execute(ctx);
+                    if (!expectedFail) {
+                        assert.equal(result, undefined, 'should exit successfully, returning nothing');
+                    }
+                } catch (e) {
+                    hadError = true;
+                    if (!expectedFail) {
+                        assert.fail(e);
+                    }
+                }
+                if (expectedFail && !hadError) {
+                    assert.fail('should have returned an error code');
+                }
+                assert.equal(ctx.externs.out.output, expectedStdout, 'wrong output written to stdout');
+                assert.equal(ctx.externs.err.output, expectedStderr, 'wrong output written to stderr');
+            });
+        }
+    });
+}