rsformat 0.1.0

package/README.md

@@ -0,0 +1,133 @@
+# RSFormat
+
+RSFormat is a string formatting/printing library for JavaScript. It offers an alternative to the string formatting and printing provided by `console.log`.
+
+## Motivation
+
+`console.log` is an odd method: its output can be affected by functions called before/after it (such as `console.group`), or their order affected by what parameters there are. For example, when calling `console.log(string, number)`, number can come either after or inside `string` depending on the value of `string`.
+
+RSFormat provides alternative functions with standardised behaviour: its `format`, `println` and all other functions will always output in the same manner, and have a standardised syntax which will only print the initial string, formatted with the parameters provided afterwards.
+
+Rust formatting also includes a lot of convenient operators for formatting text, such as padding/alignment, printing numbers in a given base, specifying decimal precision, etc.. This makes it a more ergonomic and convenient approach to printing things to the console.
+
+## Usage
+
+you can install rsformat using [npm](https://www.npmjs.com/package/rsformat):
+
+```
+npm install rsformat
+```
+
+### Basic formatting and printing to console
+
+RSFormat functions are called using a format string, and any number of format arguments following it.
+
+Any instance of `{}` in the format strings will get replaced with a value.
+
+You can specify what value you want in the parameters by using a number inside the insertion point.
+
+```js
+import { format, println } from 'rsformat';      // ESM
+const { format, println } = require('rsformat'); // CommonJS
+
+let name = 'everyone';
+
+let greeting = format('Hello {}!', name); // Evaluates to the string 'Hello, everyone!'
+
+println('I have {1} apples and {0} oranges', 13, 14); // Will print 'I have 14 apples and 13 oranges' to the console
+```
+
+### Format Specifiers
+
+Format specifiers can be used by adding `:` inside the insertion point (after the optional argument number), and will format the value differently inside the string. See the [rust format docs](https://doc.rust-lang.org/std/fmt/#syntax) for more detailed information on format specifiers.
+
+This implementation differs from the rust one in a few ways:
+
+- Named arguments before or in format specifiers or in values aren't allowed, only numbers can be used.
+- The `-` sign (unused in rust) is unsupported.
+- Pointer format type `p` is unsupported.
+- Hexadecimal debug types `x?` and `X?` are unsupported. 
+- Specifying precision with `*` is unsupported.
+
+#### Different formatting types
+
+```js
+// Debug format specifier: ?, uses util.inspect rather than toString
+
+println('{}', { a: 1 }); //prints '[object Object]'
+println('{:?}', { a: 1 }); //prints "{ a:1 }"
+
+// Number base specifiers: x, X, b, o - for lower/uppercase hexadecimal, binary, octal
+
+format('{} is {0:x} in hex, {0:b} in binary and {0:o} in octal', 15); // '15 is f in hex, 1111 in binary and 17 in octal'
+
+// Scientific notation specifiers: e, E - for lower/uppercase scientific notation
+
+let hugeNumber = 1000n;
+format('{:E}', hugeNumber); // '1E3';
+```
+
+#### Padding, Alignment
+
+Values can be aligned using any fill character (will default to a space ` `), and either left, center or right aligned with `<`, `^` or `>` respectively (will default to right alignment `>`). You will also have to specify a width with an integer after the alignment:
+
+```js
+/*
+Will print a pyramid of 'a's:
+'  a  '
+' aaa '
+'aaaaa'
+*/
+let pyramidLevels = ['a', 'aaa', 'aaaaa'];
+for(let value of pyramidLevels) {
+    println('{:^5}', value);
+}
+```
+
+```js
+format('{:.>7}', [1,2]); // '....1,2'
+```
+
+#### Pretty Printing
+
+In some instances (namely debug and hexadecimal formatting), adding a `#` before the format specifier will use an alternative 'pretty' printing style. This amounts to using non-compact `util.inspect` for debug printing (spanning multiple lines), and adding 0x to hexadecimal numbers.
+
+```js
+format('{:#X}', 255); // '0xFF'
+```
+
+#### Specific Number Formatting
+
+Specifically for `number` and `bigint` values, a 0 can be placed before the width to pad the number with 0s instead. This will account for signs and possible formatting differences.
+
+```js
+format('{:#07x}', 15) // '0x0000F'
+```
+
+Decimal precision can be specified for numbers by adding a . and specifying an integer for precision.
+
+```js
+format('{:.3}', 1.23456789); // '1.234'
+format('{:.3}', -1);         // '-1.000'
+```
+
+Adding a + to the formatting specifier will print the sign regardless of whether the number is negative.
+
+```js
+format('{:+}', 1); // '+1'
+```
+
+## Custom output
+
+If you want to use the print function to output to anything other than `process.stdout` and `process.stderr`, you can import the `Printer` function to create your own print functions, using any output and error streams that are instances of node's `Writable`.
+
+```ts
+// Custom output example (ts)
+import { Printer } from 'rsformat-local/print';
+import { Writable } from 'stream';
+
+let someOutputStream: Writable = /* ... */;
+let someErrorStream: Writable = /* ... */;
+
+let { print, println, eprint, eprintln } = Printer(someOutputStream, someErrorStream);
+```

package/lib/format.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Format a string similarly to rust's format! macro.
+ *
+ * @param str String used for formatting
+ * @param params Parameters to be inserted into the format string
+ */
+export declare function format(str: string, ...params: any[]): string;

package/lib/format.js

@@ -0,0 +1,187 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.format = void 0;
+const util_1 = require("util");
+/**
+ * Regex to match for possible formatting insertion points.
+ * Similar to the way formatting is parsed in rust,
+ * but with a few key differences:
+ * - Named arguments before format specifiers aren't allowed, only numbers can be used.
+ * - The - sign (unused in rust) is unsupported.
+ * - Pointer format type 'p' is unsupported.
+ * - Hexadecimal debug types 'x?' and 'X?' are unsupported.
+ * - Specifying precision with * is unsupported.
+ *
+ * The formatter currently matches with a regex
+ * instead of a full-blown parser for simplicity
+ * and performance, as built-in regex matching is
+ * likely to be faster than a js-implemented parser.
+ * However, this will not match incorrectly formatted
+ * insertion points.
+ */
+const FORMAT_REGEX = (/\{{2}|\}{2}|\{(\d*?)(?::(?:(.?)(\^|>|<))?(\+)?(#)?(0)?(\d*)?(\.\d*)?(\?|o|x|X|b|e|E)?)?\}/g);
+/**
+ * Format a string similarly to rust's format! macro.
+ *
+ * @param str String used for formatting
+ * @param params Parameters to be inserted into the format string
+ */
+function format(str, ...params) {
+    // Counter used for insertion of unnumbered values
+    let param_counter = 0;
+    str = str.replace(FORMAT_REGEX, ($, $param_number, $fill_character, $align_direction, $sign, $pretty, $pad_zeroes, $width, $precision, $type) => {
+        // Return a bracket if the regex matched an escaped bracket
+        if ($ === '{{') {
+            return '{';
+        }
+        if ($ === '}}') {
+            return '}';
+        }
+        // Process parameter number; increment param_counter if not included
+        let param = $param_number === undefined
+            ? params[param_counter++]
+            : params[+$param_number];
+        if (param === undefined) {
+            throw new Error(`parameter ${$param_number || param_counter - 1} either NaN or not provided`);
+        }
+        let param_type = typeof param;
+        // Process parameter type
+        switch ($type) {
+            case "o":
+                param = param.toString(8);
+                break;
+            case "x":
+                param = param.toString(16);
+                break;
+            case "X":
+                param = param.toString(16).toUpperCase();
+                break;
+            case "b":
+                param = param.toString(2);
+                break;
+            case "e":
+                switch (param_type) {
+                    case 'number':
+                        param = param.toExponential();
+                        break;
+                    case 'bigint':
+                        param = param.toLocaleString('en-US', {
+                            notation: 'scientific',
+                            maximumFractionDigits: 20,
+                        }).toLowerCase();
+                        break;
+                    default:
+                        param = param.toString();
+                        break;
+                }
+                break;
+            case "E":
+                switch (param_type) {
+                    case 'number':
+                        param = param.toExponential().toUpperCase();
+                        break;
+                    case 'bigint':
+                        param = param.toLocaleString('en-US', {
+                            notation: 'scientific',
+                            maximumFractionDigits: 20
+                        });
+                        break;
+                    default:
+                        param = param.toString();
+                        break;
+                }
+                break;
+            case "?":
+                param = (0, util_1.inspect)(param, {
+                    depth: Infinity,
+                    colors: true,
+                    compact: $pretty !== '#'
+                });
+                break;
+            default:
+                param = param.toString();
+                break;
+        }
+        ;
+        // Compute radix-point precision on numbers
+        if (param_type == 'number' && $precision) {
+            let [pre, post] = param.split(".");
+            if (post === undefined) {
+                post = "";
+            }
+            let precision = +$precision.substring(1, $precision.length);
+            if (post.length > precision) {
+                post = post.substring(0, precision);
+            }
+            else
+                while (post.length < precision) {
+                    post = post + '0';
+                }
+            param = pre + "." + post;
+        }
+        let width;
+        if ($width === undefined) {
+            width = 0;
+        }
+        else {
+            width = +$width;
+            if (Number.isNaN(width))
+                throw new Error(`invalid width specifier '${$width}' (must be an integer)`);
+        }
+        let filled = false;
+        if ((param_type == 'number') || (param_type == 'bigint')) {
+            // Compute parameter sign
+            let maybe_sign = param.substring(0, 1);
+            if (maybe_sign === '-') {
+                param = param.substring(1, param.length);
+            }
+            else if ($sign === '+') {
+                maybe_sign = '+';
+            }
+            else {
+                maybe_sign = '';
+            }
+            //If the type is x or X and pretty printing enabled, add 0x
+            if ((($type === 'x') || ($type === 'X')) && ($pretty === '#')) {
+                maybe_sign += '0x';
+            }
+            //pad with zeroes if specified  
+            if ($pad_zeroes === '0') {
+                filled = true;
+                while (param.length < width - maybe_sign.length) {
+                    param = '0' + param;
+                }
+            }
+            param = maybe_sign + param;
+        }
+        if (!filled && width) {
+            // Compute fill/align
+            $align_direction ||= '>';
+            $fill_character ||= ' ';
+            switch ($align_direction) {
+                case '>':
+                    while (width - param.length > 0) {
+                        param = $fill_character + param;
+                    }
+                    break;
+                case '<':
+                    while (width - param.length > 0) {
+                        param = param + $fill_character;
+                    }
+                    break;
+                case '^':
+                    while (width - param.length > 1) {
+                        param = $fill_character + param + $fill_character;
+                    }
+                    // Prioritise right-aligment on uneven alignment
+                    if (width - param.length == 1) {
+                        param = $fill_character + param;
+                    }
+                    break;
+            }
+        }
+        return param;
+    });
+    return str;
+}
+exports.format = format;

package/lib/index.d.ts

@@ -0,0 +1,2 @@
+export { format } from './format';
+export { print, println, eprint, eprintln } from './print';

package/lib/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.eprintln = exports.eprint = exports.println = exports.print = exports.format = void 0;
+var format_1 = require("./format");
+Object.defineProperty(exports, "format", { enumerable: true, get: function () { return format_1.format; } });
+var print_1 = require("./print");
+Object.defineProperty(exports, "print", { enumerable: true, get: function () { return print_1.print; } });
+Object.defineProperty(exports, "println", { enumerable: true, get: function () { return print_1.println; } });
+Object.defineProperty(exports, "eprint", { enumerable: true, get: function () { return print_1.eprint; } });
+Object.defineProperty(exports, "eprintln", { enumerable: true, get: function () { return print_1.eprintln; } });

package/lib/print.d.ts

@@ -0,0 +1,35 @@
+/// <reference types="node" />
+import { Writable } from 'stream';
+export declare function Printer(outStream?: Writable, errStream?: Writable): {
+    /**
+     * Print a format string to an output stream (usually process.stdout).
+     *
+     * @param format_string String used for formatting
+     * @param params Parameters to be inserted into the format string
+     */
+    print: (format_string: string, ...params: any[]) => void;
+    /**
+     * Print a format string to an output stream (usually process.stdout)
+     * and append a newline.
+     *
+     * @param format_string String used for formatting
+     * @param params Parameters to be inserted into the format string
+     */
+    println: (format_string: string, ...params: any[]) => void;
+    /**
+     * Print a format string to an error stream (usually process.stderr).
+     *
+     * @param format_string String used for formatting
+     * @param params Parameters to be inserted into the format string
+     */
+    eprint: (format_string: string, ...params: any[]) => void;
+    /**
+     * Print a format string to an error stream (usually process.stderr)
+     * and append a newline.
+     *
+     * @param format_string String used for formatting
+     * @param params Parameters to be inserted into the format string
+     */
+    eprintln: (format_string: string, ...params: any[]) => void;
+};
+export declare const print: (format_string: string, ...params: any[]) => void, println: (format_string: string, ...params: any[]) => void, eprint: (format_string: string, ...params: any[]) => void, eprintln: (format_string: string, ...params: any[]) => void;

package/lib/print.js

@@ -0,0 +1,49 @@
+"use strict";
+var _a;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.eprintln = exports.eprint = exports.println = exports.print = exports.Printer = void 0;
+const format_1 = require("./format");
+function Printer(outStream = process.stdout, errStream = process.stderr) {
+    return {
+        /**
+         * Print a format string to an output stream (usually process.stdout).
+         *
+         * @param format_string String used for formatting
+         * @param params Parameters to be inserted into the format string
+         */
+        print: function print(format_string, ...params) {
+            outStream.write((0, format_1.format)(format_string, ...params));
+        },
+        /**
+         * Print a format string to an output stream (usually process.stdout)
+         * and append a newline.
+         *
+         * @param format_string String used for formatting
+         * @param params Parameters to be inserted into the format string
+         */
+        println: function println(format_string, ...params) {
+            outStream.write((0, format_1.format)(format_string, ...params) + "\n");
+        },
+        /**
+         * Print a format string to an error stream (usually process.stderr).
+         *
+         * @param format_string String used for formatting
+         * @param params Parameters to be inserted into the format string
+         */
+        eprint: function eprint(format_string, ...params) {
+            errStream.write((0, format_1.format)(format_string, ...params));
+        },
+        /**
+         * Print a format string to an error stream (usually process.stderr)
+         * and append a newline.
+         *
+         * @param format_string String used for formatting
+         * @param params Parameters to be inserted into the format string
+         */
+        eprintln: function eprintln(format_string, ...params) {
+            errStream.write((0, format_1.format)(format_string, ...params) + "\n");
+        },
+    };
+}
+exports.Printer = Printer;
+_a = Printer(), exports.print = _a.print, exports.println = _a.println, exports.eprint = _a.eprint, exports.eprintln = _a.eprintln;

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "rsformat",
+  "version": "0.1.0",
+  "description": "Formatting/printing library for JavaScript that takes after rust's string formatting ",
+  "files": [
+    "lib",
+    "README.MD"
+  ],
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./*": {
+      "types": "./lib/*.d.ts",
+      "default": "./lib/*.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "fmt",
+    "format",
+    "strings",
+    "print",
+    "println",
+    "printf",
+    "console",
+    "log"
+  ],
+  "author": "Alfio (https://github.com/p2js)",
+  "license": "ISC",
+  "devDependencies": {
+    "@types/node": "^22.8.6"
+  }
+}