rsformat 0.2.4 → 1.0.0

package/README.md

@@ -1,170 +1,161 @@
-# RSFormat
-
-RSFormat is a string formatting/printing library for JavaScript. It offers a minimal, yet powerful and flexible 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, binary, octal 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 0b/0o/0x as a prefix for the numbers formatted as powers of two.
-
-```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/print';
-import { Writable } from 'stream';
-
-let someOutputStream: Writable = /* ... */;
-let someErrorStream: Writable = /* ... */;
-
-let { print, println, eprint, eprintln } = Printer(someOutputStream, someErrorStream);
-```
-
-## A Note on Performance
-
-You might think that these utilities might have a performance impact on RSFormat's printing functions. And while they do, the functions are still consistently faster than `console.log`.
-
-A simple benchmark setup like the one below will demonstrate that `println` is more performant, even when doing things like base conversions and text alignment, compared to `console.log` logging a simple string:
-
-```js
-// benchmark.mjs
-import { println } from 'rsformat';
-
-const time = (fn, iter) => {
-    let time = Date.now();
-    while (iter-- > 0) {
-        fn();
-    }
-    return Date.now() - time;
-}
-
-let iterations = 100000;
-
-let logTime = time(() => console.log('hello'), iterations);
-let printlnTime = time(() => println('{:>+#7X}', 255), iterations);
-
-println('console.log time for {} executions: {}ms', iterations, logTime);
-println('rsformat.println time for {} executions: {}ms', iterations, printlnTime);
-```
-
-```
-> node benchmark.mjs
-...After a lot of output...
-
-console.log time for 100000 executions: 7217ms
-rsformat.println time for 100000 executions: 5900ms
-```
-
-_Tested on node.js using a Windows laptop on an Intel core I7-1360P, on battery power. Performance will vary, but this benchmark was just to show that RSFormat has no performance penalty._
+# RSFormat
+
+RSFormat is a string formatting/printing library for JavaScript. It offers a minimal, yet powerful and flexible alternative to the string formatting and printing provided by `console.log`.
+
+```js
+import { rs, println } from 'rsformat';
+
+let s = rs`${15} is ${15}:#X in hex`;
+// s == '15 is 0xF in hex'
+
+println(rs`${'a'}:^5`);
+// Prints '  a  '
+```
+
+## 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`.
+
+This behaviour has largely been superseded at a language level by template literals, which allow formatting of parameters directly inside the templates, causing these methods to have unnecessary overhead and undesired behaviour.
+
+RSFormat builds onto template literals by implementing Rust-style format specifiers and lightweight printing functions. Rust formatting includes a lot of convenient operators for formatting text, such as padding/alignment, printing numbers in a given base, specifying decimal precision, etc.
+
+## Usage
+
+You can install RSFormat from [npm](https://www.npmjs.com/package/rsformat):
+
+```sh
+npm install rsformat
+```
+
+### Basic formatting and printing to console
+
+The `rs` template tag can be used to enable rust-style formatting in a template.
+To reference a previous or following argument, use `rs.ref` with the parameter number.
+
+```js
+import { rs, println } from 'rsformat';      // ESM
+const { rs, println } = require('rsformat'); // CommonJS
+
+let number = 15;
+
+let info = rs`${number} is ${rs.ref(0)}:x in hex`; // info == '15 is f in hex'
+```
+
+> NB: templates tagged with `rs` are instances of a special class `RsString` that extends `String`, rather than a primitive value. This is to enable colors for debug formatting inside the printing functions. This difference should not affect normal usage, but `rs.raw` can be used as an alternative tag to get a primitive `string`.
+
+The printing functions can be called with plain strings, instances of `String` or templates formatted with `rs`:
+
+```ts
+println('Hello World');
+println(rs`...`);
+```
+
+### Format Specifiers
+
+Format specifiers can be used by adding `:` after the format argument, and will format the value differently inside the string. See the [rust format docs](https://doc.rust-lang.org/std/fmt/) for more detailed information on format specifiers.
+
+This implementation differs from the Rust one in a few ways:
+
+- Rather than escaping the braces using `{{` or `}}`, the formatting colon can be escaped using `::`.
+- Different parameters are referenced using `rs.ref(n)` rather than the number literal `n`.
+- To separate a formatting specifier from the rest of the string without adding a space, an extra closing colon must be added (eg. `:#?:foo` - specifier gets parsed as `:#?`)
+- The `-` sign (unused in Rust) will add a space if the number is positive to align it with negative numbers without showing a `+`.
+- Pointer format type `p` is unsupported.
+- Hexadecimal debug types `x?` and `X?` are unsupported. 
+- Specifying precision dynamically with `*` is unsupported. Instead, precision and width can both be specified dynamically by using a separate number parameter in place of the number.
+- New format types have been added:
+    - `N` for uppercase ordinal suffixing of numbers (rounded to integers)
+    - `n` for lowercase ordinal suffixing of numbers (rounded to integers)
+
+#### Different formatting types
+
+The debug format specifier `?` uses `util.inspect` to stringify the parameter rather than `toString`.
+ 
+```js
+let obj = { a: 1 };
+println(rs`${obj}`);   // prints '[object Object]'
+println(rs`${obj}:?`); // prints '{ a: 1 }'
+```
+
+The provided printing functions will display colors in the output of `util.inspect`, but otherwise it will be formatted without color.
+
+The specifiers `b`,`o`,`x`,`X`,`e`,`E`,`n`,`N` will convert a `number` or `bigint` parameter to:
+- `b`: binary 
+- `o`: octal 
+- `x`/`X`: lowercase/uppercase hexadecimal
+- `e`/`E`: lowercase/uppercase scientific notation
+- `n`/`N`: lowercase/uppercase ordinal suffixed string (rounded to integer)
+
+```js
+let advancedInfo = (n) => rs`${n} is ${n}:x in hex, ${n}:b in binary and ${n}:o in octal`;
+
+advancedInfo(15); // '15 is f in hex, 1111 in binary and 17 in octal'
+
+let hugeNumber = 1000n;
+let science = rs`${hugeNumber}:E`; // '1E3'
+let ordinal = rs`${hugeNumber}:n`; // '1000th'
+```
+
+#### 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, or provide a separate number parameter.
+
+```js
+/*
+Will print a pyramid of 'a's:
+'  a  '
+' aaa '
+'aaaaa'
+*/
+let pyramidLevels = ['a', 'aaa', 'aaaaa'];
+for(let value of pyramidLevels) {
+    println(rs`${value}:^5`);
+}
+```
+
+```js
+rs`${[1,2]}:.>${7}` // '....1,2'
+```
+
+#### Pretty Printing
+
+In some instances (namely debug, binary, octal and hexadecimal formatting), adding a `#` before the format specifier will use an alternative 'pretty' printing style. This amounts to using multiline `util.inspect` for debug printing (spanning multiple lines), and adding `0b`/`0o`/`0x` as a prefix for the numbers in the respective bases.
+
+```js
+rs`${255}:#X` // '0xFF'
+```
+
+#### Specific Number Formatting
+
+Specifically for `number` and `bigint` values, a `0` can be placed before the width to pad the number with zeroes instead. This will account for signs and possible formatting differences.
+
+```js
+rs`${15}:#07x` // '0x0000F'
+```
+
+Decimal precision can be specified for numbers by adding a `.` and specifying an integer for precision. An additional parameter can also be provided to do this dynamically.
+
+```js
+rs`${1.23456789}:.3` // '1.234'
+rs`${-1}:.${3}`      // '-1.000'
+```
+
+Adding a `+` to the formatting specifier will print the sign regardless of whether the number is negative.
+Adding a `-` will instead add a space if the number is positive.
+
+```js
+rs`${1}:+` // '+1'
+rs`${1}:-` // ' 1'
+```
+
+## Older versions of RSFormat
+
+Versions of RSFormat on npm prior to `1.0.0` provide formatting and printing functions that are more similar in syntax to Rust, using plain strings instead of tagged templates:
+
+```js
+import { format } from 'rsformat';
+format('{} is {0:#x} in hex', 15); // '15 is 0xf in hex'
+```
+
+See the `old` branch for more detailed documentation. The last version to use this formatting was `0.2.5`.

package/lib/format.d.ts

@@ -1,17 +1,45 @@
 /**
- * Format a string similarly to rust's format! macro.
+ * Type representing a string formatted by `rs`.
+ * An extension of `String`.
+ */
+export declare class RsString extends String {
+    __debugColors: boolean;
+    private cachedColor;
+    private cachedPlain;
+    private strings;
+    private params;
+    constructor(strings: TemplateStringsArray, params: any[]);
+    toString(): string;
+    valueOf(): string;
+}
+/**
+ * Format a template literal with rust-style formatting and return it as a string.
  *
- * @param str String used for formatting
- * @param params Parameters to be inserted into the format string
+ * @param strings String parts of the template
+ * @param params Template parameters
+ * @returns a string primitive of the formatted string
  */
-export declare function format(str: string, ...params: any[]): string;
+export declare function buildString(strings: TemplateStringsArray, params: any[], debugColors?: boolean): string;
+type AlignDirection = '<' | '^' | '>';
+type Sign = '-' | '+' | '';
+type FormatType = '?' | 'o' | 'x' | 'X' | 'b' | 'e' | 'E' | 'n' | 'N' | '';
+type FormatSpecifier = {
+    fill: string;
+    align: AlignDirection;
+    force_sign: Sign;
+    pretty: boolean;
+    pad_zeroes: boolean;
+    width: number;
+    precision: number;
+    type: FormatType;
+};
 /**
- * Raw formatting behaviour function called by `format` and printing functions.
+ * Format a parameter as a string according to a specifier.
  *
- * @param str String used for formatting
- * @param params Parameters to be inserted into the format string
- * @param options Options passed into formatting (Whether to use colors in debug formatting - false by default)
+ * @param param parameter to format
+ * @param format format specifier object
+ * @param debugColors whether to use colors in debug formatting
+ * @returns `param` as a formatted string
  */
-export declare function fmt_raw(str: string, params: any[], options?: {
-    colors: boolean;
-}): string;
+export declare function formatParam(param: any, format: FormatSpecifier, debugColors: boolean): string;
+export {};

package/lib/format.js

@@ -1,212 +1,339 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.format = format;
-exports.fmt_raw = fmt_raw;
-const node_util_1 = require("node:util");
+exports.formatParam = exports.buildString = exports.RsString = void 0;
+const node_util_1 = __importDefault(require("node:util"));
+const is_digit = (c) => c >= '0' && c <= '9';
+const error = (param, char, reason) => new Error(`rs[param ${param}, char ${char}] ${reason}`);
 /**
- * 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.
+ * Type representing a string formatted by `rs`.
+ * An extension of `String`.
  */
-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) {
-    return fmt_raw(str, params);
+class RsString extends String {
+    __debugColors = false;
+    cachedColor = null;
+    cachedPlain = null;
+    strings;
+    params;
+    constructor(strings, params) {
+        super('[use rs.raw to get string primitive]');
+        Object.defineProperties(this, {
+            strings: { value: strings, enumerable: false },
+            params: { value: params, enumerable: false },
+            cachedPlain: { value: null, writable: true, enumerable: false },
+            cachedColor: { value: null, writable: true, enumerable: false },
+            __debugColors: { value: false, writable: true, enumerable: false },
+        });
+    }
+    toString() {
+        if (this.__debugColors) {
+            if (this.cachedColor === null)
+                this.cachedColor = buildString(this.strings, this.params, true);
+            return this.cachedColor;
+        }
+        else {
+            if (this.cachedPlain === null)
+                this.cachedPlain = buildString(this.strings, this.params, false);
+            return this.cachedPlain;
+        }
+        ;
+    }
+    valueOf() {
+        return this.toString();
+    }
 }
+exports.RsString = RsString;
 /**
- * Raw formatting behaviour function called by `format` and printing functions.
+ * Format a template literal with rust-style formatting and return it as a string.
  *
- * @param str String used for formatting
- * @param params Parameters to be inserted into the format string
- * @param options Options passed into formatting (Whether to use colors in debug formatting - false by default)
+ * @param strings String parts of the template
+ * @param params Template parameters
+ * @returns a string primitive of the formatted string
  */
-function fmt_raw(str, params, options = { colors: false }) {
-    // 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 === ''
-            ? 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;
-        let true_length = -1;
-        // Process parameter type
-        switch ($type) {
+function buildString(strings, params, debugColors = false) {
+    let out = [strings[0]];
+    for (let i = 1; i < strings.length; ++i) {
+        let string = strings[i];
+        let param = params[i - 1];
+        // Resolve parameter references recursively
+        while (typeof param == 'object' && '__rs_param_ref' in param) {
+            let ref_number = param.__rs_param_ref;
+            if (typeof ref_number != 'number'
+                || ref_number < 0 || ref_number >= params.length) {
+                throw new Error(`Parameter ${i - 1}: Invalid reference`);
+            }
+            if (ref_number == i - 1)
+                throw new Error(`Parameter ${i - 1} references itself recursively`);
+            param = params[param.__rs_param_ref];
+        }
+        // Parse format specifier
+        // If the string starts with a single : it has a format specifier,
+        // If it has two the first : is being escaped and can be removed
+        if (string[0] == ':') {
+            if (string[1] == ':') {
+                out.push(param.toString() + string.substring(1));
+                continue;
+            }
+        }
+        else {
+            out.push(param.toString() + string);
+            continue;
+        }
+        ;
+        // Keep track of our index in the string to slice the format specifier later
+        let idx = 1;
+        // Compute format based on string
+        let fill = ' ', align = '>', force_sign = '', pretty = false, pad_zeroes = false, width = 0, precision = -1, format_type = '';
+        // Fill/align
+        // If the next character is align, then the current is the fill
+        if (string[idx + 1] == '<' || string[idx + 1] == '^' || string[idx + 1] == '>') {
+            fill = string[idx++];
+        }
+        if (string[idx] == '<' || string[idx] == '^' || string[idx] == '>') {
+            align = string[idx++];
+        }
+        // Force sign
+        if (string[idx] == '+' || string[idx] == '-')
+            force_sign = string[idx++];
+        // Pretty formatting
+        if (string[idx] == '#')
+            pretty = true, idx++;
+        // Padding numbers with zeroes
+        if (string[idx] == '0')
+            pad_zeroes = true, idx++;
+        // Width
+        if (is_digit(string[idx])) {
+            let width_substring_start = idx++;
+            while (is_digit(string[idx]))
+                idx++;
+            width = Number(string.substring(width_substring_start, idx));
+        }
+        else if (idx == string.length) {
+            // Grab the next parameter and fuse the string with the next one
+            width = params[i];
+            if (typeof width != 'number')
+                throw error(i - 1, idx, `Expected a number or number parameter for width specifier (found ${string[idx] ? "'" + string[idx] + "'" : typeof width + ' parameter'}).\nIf the next parameter was not meant to be a width number, add a : to the end of the formatting specifier.`);
+            string += strings[++i];
+        }
+        // Precision
+        if (string[idx] == '.') {
+            if (!is_digit(string[++idx])) {
+                // Grab the next parameter and fuse the string with the next one
+                precision = params[i];
+                if (typeof precision != 'number')
+                    throw error(i - 1, idx, `Expected a number or number parameter for precision specifier after . (found ${string[idx] ? "'" + string[idx] + "'" : typeof width + ' parameter'}).\nIf the next parameter was not meant to be a precision number, add a : to the end of the formatting specifier.`);
+                string += strings[++i];
+            }
+            else {
+                let precision_substring_start = idx;
+                while (is_digit(string[idx]))
+                    idx++;
+                precision = Number(string.substring(precision_substring_start, idx));
+            }
+        }
+        // Format type
+        switch (string[idx]) {
+            case '?':
             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 '?':
-                // Do not force sign or align to precision when using inspect
-                $sign = undefined;
-                $precision = undefined;
-                true_length = (0, node_util_1.inspect)(param, {
-                    depth: Infinity,
-                    colors: false,
-                    compact: $pretty !== '#'
-                }).length;
-                param = (0, node_util_1.inspect)(param, {
-                    depth: Infinity,
-                    colors: options.colors,
-                    compact: $pretty !== '#'
-                });
-                break;
-            default:
-                param = param.toString();
-                break;
+            case 'n':
+            case 'N':
+                format_type = string[idx++];
         }
-        ;
-        if (true_length == -1) {
-            true_length = param.length;
-        }
-        // Compute radix-point precision on numbers
-        if (param_type == 'number' && $precision) {
-            let [pre, post] = param.split('.');
-            let precision = +$precision.substring(1, $precision.length);
-            if (!precision) { // precision = 0, do not include radix point
-                param = pre;
-            }
-            else {
-                post = ((post || '') + '0'.repeat(precision)).slice(0, precision);
-                param = pre + '.' + post;
-            }
+        // End of specifier
+        if (string[idx] == ':') {
+            idx++;
         }
-        let width;
-        if ($width === undefined) {
-            width = 0;
+        else if (string[idx] != ' ' && string[idx] !== undefined) {
+            throw error(i - 1, idx, `Expected colon (':') or space (' ') at end of formatting specifier (found '${string[idx]}')`);
         }
-        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);
+        // Format parameter according to specifier
+        let formatted = formatParam(param, {
+            fill,
+            align,
+            force_sign,
+            pretty,
+            pad_zeroes,
+            width,
+            precision,
+            type: format_type
+        }, debugColors);
+        out.push(formatted + string.substring(idx));
+    }
+    return out.join('');
+}
+exports.buildString = buildString;
+/**
+ * Format a parameter as a string according to a specifier.
+ *
+ * @param param parameter to format
+ * @param format format specifier object
+ * @param debugColors whether to use colors in debug formatting
+ * @returns `param` as a formatted string
+ */
+function formatParam(param, format, debugColors) {
+    let param_type = typeof param;
+    let true_length = -1;
+    // Process parameter type
+    switch (format.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':
+        case 'E':
+            if (param_type != 'number' && param_type != 'bigint') {
+                param = param.toString();
+                break;
             }
-            else if ($sign === '+') {
-                maybe_sign = '+';
+            param = param.toLocaleString('en-US', { notation: 'scientific', maximumFractionDigits: 20 });
+            if (format.type == 'e')
+                param = param.toLowercase();
+            break;
+        case 'n':
+        case 'N':
+            if (param_type != 'number' && param_type != 'bigint') {
+                param = param.toString();
+                break;
             }
-            else {
-                maybe_sign = '';
+            // Round and add suffix
+            if (param_type == 'number')
+                param = Math.round(param);
+            param = param.toString();
+            let last_2_digits = param.substring(param.length - 2);
+            if (last_2_digits == '11' || last_2_digits == '12' || last_2_digits == '13') {
+                param = param + 'th';
             }
-            // If pretty printing is enabled and the formating calls for a prefix, add it
-            if ($pretty === '#') {
-                switch ($type) {
-                    case 'o':
-                        maybe_sign += "0o";
+            else
+                switch (last_2_digits[last_2_digits.length - 1]) {
+                    case '1':
+                        param = param + 'st';
                         break;
-                    case 'x':
-                    case 'X':
-                        maybe_sign += "0x";
+                    case '2':
+                        param = param + 'nd';
                         break;
-                    case 'b':
-                        maybe_sign += "0b";
+                    case '3':
+                        param = param + 'rd';
                         break;
+                    default: param = param + 'th';
                 }
-            }
-            //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 > true_length) {
-            // Compute fill/align
-            $align_direction ||= '>';
-            $fill_character ||= ' ';
-            let left = '';
-            let right = '';
-            let diff = width - true_length;
-            switch ($align_direction) {
-                case '>':
-                    left = $fill_character.repeat(diff);
+            if (format.type == 'N')
+                param = param.toUpperCase();
+            // Do not pad with zeroes or align to precision when using ordinal formatting
+            format.pad_zeroes = false;
+            format.precision = -1;
+            break;
+        case '?':
+            true_length = node_util_1.default.inspect(param, {
+                depth: Infinity,
+                colors: false,
+                compact: !format.pretty
+            }).length;
+            param = node_util_1.default.inspect(param, {
+                depth: Infinity,
+                colors: debugColors,
+                compact: !format.pretty
+            });
+            // Do not force sign, pad with zeroes or align to precision when using debug formatting
+            param_type = 'string';
+            break;
+        default:
+            param = param.toString();
+            break;
+    }
+    ;
+    if (true_length == -1) {
+        true_length = param.length;
+    }
+    // Compute radix-point precision on numbers
+    if (param_type == 'number' && format.precision != -1) {
+        let [pre, post] = param.split('.');
+        if (!format.precision) { // precision = 0, do not include radix point
+            param = pre;
+        }
+        else {
+            post = ((post || '') + '0'.repeat(format.precision)).slice(0, format.precision);
+            param = pre + '.' + post;
+        }
+        // Update true length for fill/align
+        true_length = param.length;
+    }
+    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 (format.force_sign == '+') {
+            maybe_sign = '+';
+        }
+        else if (format.force_sign == '-') {
+            maybe_sign = ' ';
+        }
+        else {
+            maybe_sign = '';
+        }
+        // If pretty printing is enabled and the formating calls for a prefix, add it
+        if (format.pretty) {
+            switch (format.type) {
+                case 'o':
+                    maybe_sign += '0o';
                     break;
-                case '<':
-                    right = $fill_character.repeat(diff);
+                case 'x':
+                case 'X':
+                    maybe_sign += '0x';
                     break;
-                case '^':
-                    left = $fill_character.repeat(diff - diff / 2);
-                    // Prioritise right-aligment on uneven length
-                    right = $fill_character.repeat(diff / 2 + diff % 2);
+                case 'b':
+                    maybe_sign += '0b';
                     break;
             }
-            param = left + param + right;
         }
-        return param;
-    });
-    return str;
+        //pad with zeroes if specified  
+        if (format.pad_zeroes) {
+            filled = true;
+            while (param.length < format.width - maybe_sign.length) {
+                param = '0' + param;
+                true_length++;
+            }
+        }
+        true_length += maybe_sign.length;
+        param = maybe_sign + param;
+    }
+    if (!filled && format.width > true_length) {
+        // Compute fill/align
+        let left = '';
+        let right = '';
+        let diff = format.width - true_length;
+        switch (format.align) {
+            case '>':
+                left = format.fill.repeat(diff);
+                break;
+            case '<':
+                right = format.fill.repeat(diff);
+                break;
+            case '^':
+                left = format.fill.repeat(diff - diff / 2);
+                // Prioritise right-aligment on uneven length
+                right = format.fill.repeat(diff / 2 + diff % 2);
+                break;
+        }
+        param = left + param + right;
+    }
+    return param;
 }
+exports.formatParam = formatParam;

package/lib/index.d.ts

@@ -1,2 +1,15 @@
-export { format } from './format';
+import { RsString } from './format';
 export { print, println, eprint, eprintln } from './print';
+/**
+ * Tag to use Rust-style formatting in a template literal.
+ * Returns an extended `String` object.
+ *
+ * @returns a String object with the formatted string
+ */
+export declare function rs(strings: TemplateStringsArray, ...params: any[]): RsString;
+export declare namespace rs {
+    var raw: (strings: TemplateStringsArray, ...params: any[]) => string;
+    var ref: (n: number) => {
+        __rs_param_ref: number;
+    };
+}

package/lib/index.js

@@ -1,10 +1,35 @@
 "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; } });
+exports.rs = exports.eprintln = exports.eprint = exports.println = exports.print = void 0;
+const format_1 = require("./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; } });
+/**
+ * Tag to use Rust-style formatting in a template literal.
+ * Returns an extended `String` object.
+ *
+ * @returns a String object with the formatted string
+ */
+function rs(strings, ...params) {
+    return new format_1.RsString(strings, params);
+}
+exports.rs = rs;
+/**
+ * Tag to use Rust-style formatting in a template literal.
+ * Returns a `string` primitive.
+ *
+ * @returns a string primitive of the formatted string
+ */
+rs.raw = function (strings, ...params) {
+    return (0, format_1.buildString)(strings, params);
+};
+/**
+ * Reference another parameter in a `rs`-tagged template.
+ *
+ * @param n Number of parameter to reference
+ * @returns A reference to the `n`th parameter
+ */
+rs.ref = (n) => ({ __rs_param_ref: n });

package/lib/print.d.ts

@@ -1,74 +1,41 @@
+/// <reference types="node" />
 import { Writable } from 'node:stream';
 /**
- * Create format printer functions with custom output/error streams.
+ * Print a string (or instance of String/RsString) to a stream.
  *
- * @param outStream Output stream (used by print and println - process.stdout by default)
- * @param errStream Error stream (used by eprint and eprintln - process.stderr by default)
- * @param options Options for the printer functions (Whether to color the debug formatting in the output - true by default)
+ * @param stream Stream to print the string to
+ * @param string String to print
+ * @param newline Whether to append a newline after the string
+ * @param colored Whether to use colors for `rs` debug formatting
+ */
+export declare function printToStream(stream: Writable, string: string | String, newline?: boolean, colored?: boolean): void;
+/**
+ * Print a string to stdout.
  *
- * @returns an object with print, println, eprint and eprintln functions that print to the specified streams
+ * @param string String to print
  */
-export declare function Printer(outStream?: Writable, errStream?: Writable, options?: {
-    debugColors: boolean;
-}): {
-    /**
-     * 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 function print(string: string | String): void;
 /**
- * Print a format string to process.stdout.
+ * Print a string to stdout and append a newline.
  *
- * @param format_string String used for formatting
- * @param params Parameters to be inserted into the format string
+ * @param string String to print
  */
-export declare const print: (format_string: string, ...params: any[]) => void;
+export declare function println(string: string | String): void;
 /**
- * Print a format string to process.stdout
- * and append a newline.
+ * Print a string to stderr.
  *
- * @param format_string String used for formatting
- * @param params Parameters to be inserted into the format string
+ * @param string String to print
  */
-export declare const println: (format_string: string, ...params: any[]) => void;
+export declare function eprint(string: string | String): void;
 /**
- * Print a format string to process.stderr.
+ * Print a string to stderr and append a newline.
  *
- * @param format_string String used for formatting
- * @param params Parameters to be inserted into the format string
+ * @param string String to print
  */
-export declare const eprint: (format_string: string, ...params: any[]) => void;
+export declare function eprintln(string: string | String): void;
 /**
- * Print a format string to process.stderr
- * and append a newline.
+ * Debug print a value to stderr and return it.
  *
- * @param format_string String used for formatting
- * @param params Parameters to be inserted into the format string
+ * @param value Value to debug print
  */
-export declare const eprintln: (format_string: string, ...params: any[]) => void;
+export declare function dbg(value: any): any;

package/lib/print.js

@@ -3,121 +3,75 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.eprintln = exports.eprint = exports.println = exports.print = void 0;
-exports.Printer = Printer;
-const node_process_1 = __importDefault(require("node:process"));
+exports.dbg = exports.eprintln = exports.eprint = exports.println = exports.print = exports.printToStream = void 0;
 const format_1 = require("./format");
+const node_process_1 = __importDefault(require("node:process"));
+const _1 = require(".");
 /**
- * Create format printer functions with custom output/error streams.
+ * Print a string (or instance of String/RsString) to a stream.
  *
- * @param outStream Output stream (used by print and println - process.stdout by default)
- * @param errStream Error stream (used by eprint and eprintln - process.stderr by default)
- * @param options Options for the printer functions (Whether to color the debug formatting in the output - true by default)
+ * @param stream Stream to print the string to
+ * @param string String to print
+ * @param newline Whether to append a newline after the string
+ * @param colored Whether to use colors for `rs` debug formatting
+ */
+function printToStream(stream, string, newline = false, colored = false) {
+    if (string instanceof format_1.RsString) {
+        let previousColors = string.__debugColors;
+        if (colored)
+            string.__debugColors = true;
+        let stringified = string.toString();
+        string.__debugColors = previousColors;
+        string = stringified;
+    }
+    if (newline)
+        string = string + '\n';
+    stream.write(string);
+}
+exports.printToStream = printToStream;
+/**
+ * Print a string to stdout.
  *
- * @returns an object with print, println, eprint and eprintln functions that print to the specified streams
+ * @param string String to print
  */
-function Printer(outStream = node_process_1.default.stdout, errStream = node_process_1.default.stderr, options = { debugColors: true }) {
-    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.fmt_raw)(format_string, params, { colors: options.debugColors }));
-        },
-        /**
-         * 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.fmt_raw)(format_string, params, { colors: options.debugColors }) + '\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.fmt_raw)(format_string, params, { colors: options.debugColors }));
-        },
-        /**
-         * 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.fmt_raw)(format_string, params, { colors: options.debugColors }) + '\n');
-        },
-    };
+function print(string) {
+    printToStream(node_process_1.default.stdout, string, false, true);
 }
-// export const {
-//     /**
-//      * Print a format string to process.stdout.
-//      * 
-//      * @param format_string String used for formatting
-//      * @param params Parameters to be inserted into the format string
-//      */
-//     print,
-//     /**
-//      * Print a format string to process.stdout
-//      * and append a newline.
-//      * 
-//      * @param format_string String used for formatting
-//      * @param params Parameters to be inserted into the format string
-//      */
-//     println,
-//     /**
-//      * Print a format string to process.stderr.
-//      * 
-//      * @param format_string String used for formatting
-//      * @param params Parameters to be inserted into the format string
-//      */
-//     eprint,
-//     /**
-//      * Print a format string to process.stderr
-//      * and append a newline.
-//      * 
-//      * @param format_string String used for formatting
-//      * @param params Parameters to be inserted into the format string
-//      */
-//     eprintln
-// } = Printer();
-const default_printer = Printer();
+exports.print = print;
 /**
- * Print a format string to process.stdout.
+ * Print a string to stdout and append a newline.
  *
- * @param format_string String used for formatting
- * @param params Parameters to be inserted into the format string
+ * @param string String to print
  */
-exports.print = default_printer.print;
+function println(string) {
+    printToStream(node_process_1.default.stdout, string, true, true);
+}
+exports.println = println;
 /**
- * Print a format string to process.stdout
- * and append a newline.
+ * Print a string to stderr.
  *
- * @param format_string String used for formatting
- * @param params Parameters to be inserted into the format string
+ * @param string String to print
  */
-exports.println = default_printer.println;
+function eprint(string) {
+    printToStream(node_process_1.default.stderr, string, false, true);
+}
+exports.eprint = eprint;
 /**
- * Print a format string to process.stderr.
+ * Print a string to stderr and append a newline.
  *
- * @param format_string String used for formatting
- * @param params Parameters to be inserted into the format string
+ * @param string String to print
  */
-exports.eprint = default_printer.eprint;
+function eprintln(string) {
+    printToStream(node_process_1.default.stderr, string, true, true);
+}
+exports.eprintln = eprintln;
 /**
- * Print a format string to process.stderr
- * and append a newline.
+ * Debug print a value to stderr and return it.
  *
- * @param format_string String used for formatting
- * @param params Parameters to be inserted into the format string
+ * @param value Value to debug print
  */
-exports.eprintln = default_printer.eprintln;
+function dbg(value) {
+    eprintln((0, _1.rs) `${value}:?`);
+    return value;
+}
+exports.dbg = dbg;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rsformat",
-  "version": "0.2.4",
+  "version": "1.0.0",
   "description": "Formatting/printing library for JavaScript that takes after rust's string formatting ",
   "files": [
     "lib",
@@ -16,10 +16,6 @@
       "default": "./lib/*.js"
     }
   },
-  "scripts": {
-    "build": "tsc",
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
   "keywords": [
     "fmt",
     "format",
@@ -36,5 +32,8 @@
   "devDependencies": {
     "@types/node": "^22.8.6"
   },
-  "packageManager": "pnpm@9.14.2+sha512.6e2baf77d06b9362294152c851c4f278ede37ab1eba3a55fda317a4a17b209f4dbb973fb250a77abc463a341fcb1f17f17cfa24091c4eb319cda0d9b84278387"
+  "scripts": {
+    "build": "tsc",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  }
 }