saladplate 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 - present Zach Snow
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+# Saladplate
+
+_Simple templating; it's smaller than usual._
+
+Saladplate is a very simple templating tool, with 3 features:
+
+1. Replace `${{ VAR }}` with the contents of the environment variable `VAR`.
+2. Replace `$<< filename >>` with the contents of the file `filename`.
+3. Replace `$(( some command ))` with the output of the command `some command`.
+
+If you need more functionality that that, this is not the templating tool for you.
+
+## Installation
+
+```bash
+$ npm -g install saladplate
+$ saladplate --version
+saladplate: version 0.1.0
+```
+
+## Usage
+
+The easiest way to use Saladplate with via the `saladplate` command line tool:
+
+```bash
+$ saladplate --help
+
+Usage: saladplate [options] <file>...
+Options:
+  --debug          enable debug mode
+  -v, --version    show version information
+  -h, --help       show this help message
+  -d, --directory  output directory
+  -s, --suffix     output suffix; only applies when using --directory
+  -o, --output     output file; overrides --directory and --suffix
+```
+
+Saladplate generally operates in 2 modes. If you pass `--directory`, then
+each file you pass will be templated independently, and the output written
+into the given directory. Use `--suffix` to change the extension of the output
+file -- for instance, if you template the files `some.template` and `another.txt`
+with `--directory=out` and `--suffix=.html` you will end up with a file `out/some.html`
+and `out/another.html`:
+
+```bash
+$ saladplate --directory=out --suffix=.html *.template
+```
+
+If instead you pass `--output`, then each file will be templated, with the
+results _concatenated_ into the single given output file.
+
+```bash
+$ saladplate --output=index.html *.template
+```
+
+You can also use the exported `template` function to template a string:
+
+```typescript
+import { template } from "saladplate";
+console.info(template("The current PATH is: $PATH"));
+```
+
+## Development
+
+When developing locally, you can test your changes using the *script* `saladplate`,
+which uses `ts-node`. Note the use of `run` below, as well as the use of `--` to
+separate arguments to `npm run` from arguments to `saladplate`:
+
+```bash
+$ npm run saladplate -- --version
+
+> saladplate@0.1.0 saladplate
+> ts-node ./bin/saladplate.ts
+
+saladplate: version 0.1.0
+```
+
+Tests are located in `tests/` and consist of input templates `tests/*.test` and
+corresponding expected outputs `tests/*.expected`. To run tests:
+
+```bash
+$ npm run test
+```

package/dist/bin/simplate.d.ts

@@ -0,0 +1,2 @@
+#! /usr/bin/env ts-node
+export {};

package/dist/bin/simplate.js

@@ -0,0 +1,156 @@
+#! /usr/bin/env node
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import fs from "fs";
+import path from "path";
+import process from "process";
+import util from "util";
+import { BIN, template } from "../src/index";
+const parseArgsConfig = {
+    // Exclude the first two arguments: node and the script itself.
+    args: process.argv.slice(2),
+    options: {
+        debug: {
+            type: "boolean",
+            default: false,
+            description: "enable debug mode",
+        },
+        version: {
+            type: "boolean",
+            default: false,
+            short: "v",
+            description: "show version information",
+        },
+        help: {
+            type: "boolean",
+            default: false,
+            short: "h",
+            description: "show this help message",
+        },
+        directory: {
+            type: "string",
+            short: "d",
+            description: "output directory",
+        },
+        suffix: {
+            type: "string",
+            short: "s",
+            description: "output suffix; only applies when using --directory",
+        },
+        output: {
+            type: "string",
+            short: "o",
+            description: "output file; overrides --directory and --suffix",
+        },
+    },
+    allowPositionals: true,
+};
+function help() {
+    console.info(`Usage: ${BIN} [options] <file>...`);
+    console.info(`Options:`);
+    const entries = Object.entries(parseArgsConfig.options);
+    const prefixes = {};
+    entries.forEach(([name, option]) => {
+        const short = "short" in option ? `-${option.short}, ` : "";
+        const prefix = `  ${short}--${name}`;
+        prefixes[name] = prefix;
+    });
+    const len = Math.max(...entries.map(([name, option]) => prefixes[name].length)) + 2;
+    entries.forEach(([name, option]) => {
+        var _a;
+        const prefix = prefixes[name];
+        console.info(`${prefix}${" ".repeat(len - prefix.length)}${(_a = option.description) !== null && _a !== void 0 ? _a : ""}`);
+    });
+    console.info("");
+}
+function version() {
+    const version = process.env.npm_package_version;
+    console.info(`${BIN}: version ${version !== null && version !== void 0 ? version : "unknown"}`);
+}
+const parseArgs = () => {
+    const { values: options, positionals: filenames } = util.parseArgs(parseArgsConfig);
+    return { options, filenames };
+};
+let output = null;
+function outputForFilename(filename, options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (output) {
+            return output;
+        }
+        if (options.output) {
+            output = {
+                file: yield fs.promises.open(options.output, "w"),
+                filename: options.output,
+            };
+            return output;
+        }
+        if (options.directory) {
+            const basename = path.basename(filename);
+            let outputFilename = path.join(options.directory, basename);
+            if (options.suffix) {
+                outputFilename = outputFilename.replace(/\.[^.]+$/, options.suffix);
+            }
+            return {
+                file: outputFilename,
+                filename: outputFilename,
+            };
+        }
+        output = {
+            file: yield fs.promises.open("/dev/stdout", "w"),
+            filename: "/dev/stdout",
+        };
+        return output;
+    });
+}
+function main() {
+    return __awaiter(this, void 0, void 0, function* () {
+        const { options, filenames } = parseArgs();
+        if (options.debug) {
+            console.debug(`${BIN}: debug mode enabled`);
+        }
+        if (options.help) {
+            help();
+            return;
+        }
+        if (options.version) {
+            version();
+            return;
+        }
+        if (filenames.length === 0) {
+            console.error(`${BIN}: no input files; use -- for stdin`);
+            help();
+            return -1;
+        }
+        yield Promise.all(filenames.map((filename) => __awaiter(this, void 0, void 0, function* () {
+            if (filename === "--") {
+                filename = "/dev/stdin";
+            }
+            options.debug && console.debug(`${BIN}: reading ${filename}...`);
+            const content = yield fs.promises.readFile(filename, {
+                encoding: "utf-8",
+            });
+            options.debug && console.debug(`${BIN}: templating ${filename}...`);
+            const output = yield template(content, filename, options);
+            const { file: outputFile, filename: outputFilename } = yield outputForFilename(filename, options);
+            options.debug && console.debug(`${BIN}: writing ${outputFilename}...`);
+            yield fs.promises.writeFile(outputFile, output, {
+                encoding: "utf-8",
+            });
+        })));
+    });
+}
+main()
+    .then((i) => {
+    process.exit(i !== null && i !== void 0 ? i : 0);
+})
+    .catch((e) => {
+    console.error(`${BIN}: unhandled error:`, e);
+    process.exit(-1);
+});

package/dist/src/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The name of the tool; prefixes most output.
+ */
+export declare const BIN = "simplate";
+/**
+ * Templating options for `template`.
+ */
+export type Options = {
+    debug?: boolean;
+};
+/**
+ * Replace variables, file includes, and command executions in the given `content`, which
+ * is assumed to have been read from the given `filename` (or stdin). Collapses newlines
+ * at the end of the output so that there's just one.
+ */
+export declare const template: (content: string, filename?: string, options?: Options) => Promise<string>;

package/dist/src/index.js

@@ -0,0 +1,75 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { exec } from "child_process";
+import fs from "fs";
+import path from "path";
+import process from "process";
+import util from "util";
+/**
+ * The name of the tool; prefixes most output.
+ */
+export const BIN = "simplate";
+const cwdForFilename = (filename) => {
+    return filename === "/dev/stdin" ? process.cwd() : path.dirname(filename);
+};
+const VAR_RE = /\$\{\{([^\}]+)\}\}/g;
+const FILE_RE = /\$\<\<([^\>]+)\>\>/g;
+const EXEC_RE = /\$\(\(([^\)]+)\)\)/g;
+function replaceAsync(input, regexp, fn) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const replacements = yield Promise.all(Array.from(input.matchAll(regexp), (match) => fn(match)));
+        let i = 0;
+        return input.replace(regexp, () => replacements[i++]);
+    });
+}
+const replaceVar = (variable, filename, options) => {
+    var _a;
+    options.debug && console.debug(`${BIN}: ${filename}: evaluating ${variable} for replacement...`);
+    return (_a = process.env[variable]) !== null && _a !== void 0 ? _a : "";
+};
+const replaceFile = (includeFilename, filename, options) => __awaiter(void 0, void 0, void 0, function* () {
+    // Resolve the include filename relative to the current file; if the current file is stdin
+    // then keep the current working directory.
+    const cwd = cwdForFilename(filename);
+    const include = path.join(cwd, includeFilename);
+    options.debug && console.debug(`${BIN}: ${filename}: reading ${include} for replacement...`);
+    const content = yield fs.promises.readFile(include, { encoding: "utf-8" });
+    return template(content, include, options);
+});
+const replaceExec = (command, filename, options) => __awaiter(void 0, void 0, void 0, function* () {
+    // Execute the command in the working directory containing the file we are processing; if
+    // the current file is stdin then keep the current working directory.
+    const cwd = cwdForFilename(filename);
+    options.debug && console.debug(`${BIN}: ${filename}: executing ${command} for replacement...`);
+    const { stdout } = yield util.promisify(exec)(command, {
+        cwd,
+    });
+    return stdout;
+});
+/**
+ * Replace variables, file includes, and command executions in the given `content`, which
+ * is assumed to have been read from the given `filename` (or stdin). Collapses newlines
+ * at the end of the output so that there's just one.
+ */
+export const template = (content, filename, options) => __awaiter(void 0, void 0, void 0, function* () {
+    filename !== null && filename !== void 0 ? filename : (filename = "/dev/stdin");
+    options !== null && options !== void 0 ? options : (options = {});
+    content = yield replaceAsync(content, VAR_RE, (match) => {
+        return replaceVar(match[1].trim(), filename, options);
+    });
+    content = yield replaceAsync(content, FILE_RE, (match) => {
+        return replaceFile(match[1].trim(), filename, options);
+    });
+    content = yield replaceAsync(content, EXEC_RE, (match) => {
+        return replaceExec(match[1].trim(), filename, options);
+    });
+    content = content.replace(/\n+$/m, "\n");
+    return content;
+});

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "saladplate",
+  "version": "0.1.0",
+  "description": "Very simple templating.",
+  "keywords": [
+    "template",
+    "templating"
+  ],
+  "main": "./dist/src/saladplate.js",
+  "bin": {
+    "saladplate": "dist/bin/saladplate.js"
+  },
+  "scripts": {
+    "types": "tsc --noEmit",
+    "build": "./build.sh",
+    "saladplate": "ts-node ./bin/saladplate.ts",
+    "test": "./test.sh"
+  },
+  "devDependencies": {
+    "@types/node": "^20.12.12",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.4.5"
+  },
+  "files": [
+    "dist/**/*"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zachsnow/saladplate.git"
+  },
+  "bugs": {
+    "url": "https://github.com/zachsnow/saladplate/issues"
+  }
+}