rsformat 1.3.0 → 1.4.0

package/README.md

@@ -12,6 +12,21 @@ println(rs`${'a'}:^5`);
 // Prints '  a  '
 ```
 
+## Table of Contents
+
+- [Motivation](#motivation)
+- [Usage](#usage)
+    - [Basic formatting and printing to console](#basic-formatting-and-printing-to-console)
+    - [Decorating terminal output](#decorating-terminal-output)
+    - [Format specifiers](#format-specifiers)
+        - [Different formatting types](#different-formatting-types)
+        - [Padding, Alignment](#padding-alignment)
+        - [Pretty printing with `#`](#pretty-printing-with-)
+        - [Specific number formatting](#specific-number-formatting)
+        - [Specific string formatting](#specific-string-formatting)
+    - [Formatting without `rs`](#formatting-without-rs)
+- [Older versions of RSFormat](#older-versions-of-rsformat)
+
 ## 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`.
@@ -43,7 +58,7 @@ let number = 14;
 let info = rs`${number+1} 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`.
+> NB: templates tagged with `rs` are instances of a special class `RsString` that extends `String`, rather than a primitive value. This is to enable colours 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`:
 
@@ -53,23 +68,24 @@ println(`This template did ${'Not'} need fancy formatting`);
 println(rs`...`);
 ```
 
-### Format Specifiers
+### Decorating terminal output
+
+If you want to decorate text for terminal output, you can use `rs.style`, which will format a string using one (or more with an array) of [the modifiers provided by node's `util` module](https://nodejs.org/docs/latest-v22.x/api/util.html#modifiers).
 
-Format specifiers can be used by adding a `:` after the format argument, and will format the value differently inside the string. See `docs.md` for more detailed information on format specifiers.
+This is a re-export of node's `util.styleText`, and is thus aware of whether the current stdout will support the provided styles.
 
-This implementation differs from the Rust one in a few ways:
+```ts
+println(rs.style("red", "I am angry"));
+println(rs.style(["red", "bold", "underline"], "I am very angry"));
+```
 
-- 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 `+`.
-- When used on strings, `+` and `-` sign specifiers will conver them to uppercase and lowercase respectively
-- 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)
+This also works if passed inside `rs` tagged templates.
+
+### Format Specifiers
+
+Format specifiers can be used by adding a `:` after the format argument, and will format the value differently inside the string. 
+
+See [docs.md](./docs.md) for a detailed yet quick reference for format specifiers.
 
 #### Different formatting types
 
@@ -81,7 +97,7 @@ 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 provided printing functions will display colours in the output of `util.inspect`, but otherwise it will be formatted without colour.
 
 The specifiers `b`,`o`,`x`,`X`,`e`,`E`,`n`,`N` will convert a `number` or `bigint` parameter to:
 - `b`: binary 
@@ -115,13 +131,20 @@ let pyramidLevels = ['a', 'aaa', 'aaaaa'];
 for(let value of pyramidLevels) {
     println(rs`${value}:^5`);
 }
+
+// More powerful equivalent:
+const character = 'a';
+const baseWidth = 5;
+for(let width = 1; width <= baseWidth; width += 2) {
+    println(rs`${character.repeat(width)}:^${baseWidth}`);
+}
 ```
 
 ```js
-rs`${[1,2]}:.>${7}` // '....1,2'
+rs`${[1,2]}:.>7` // '....1,2'
 ```
 
-#### Pretty Printing
+#### Pretty printing with `#`
 
 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.
 
@@ -129,18 +152,18 @@ In some instances (namely debug, binary, octal and hexadecimal formatting), addi
 rs`${255}:#X` // '0xFF'
 ```
 
-#### Specific Number Formatting
+#### 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'
+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.23456789}:.3` // '1.235'
 rs`${-1}:.${3}`      // '-1.000'
 ```
 
@@ -152,7 +175,7 @@ rs`${1}:+` // '+1'
 rs`${1}:-` // ' 1'
 ```
 
-#### String formatting
+#### Specific string formatting
 
 Adding a `+` or `-` to a formatting specifier of a string will instead convert it to uppercase or lowercase respectively.
 
@@ -162,6 +185,37 @@ let str_upper = rs`${str}:+` // 'HELLO!'
 let str_lower = rs`${str}:-` // 'hello!'
 ```
 
+Specifying precision will truncate the string to the given length.
+
+```js
+let str  = "Hello!"
+let str_truncated = rs`${str}:.3` // 'Hel'
+```
+
+## Formatting without `rs`
+
+If you want to format a single value without using an `rs` template, you can use the `formatParam` function. It provides a more explicit, object‑based API and avoids parsing format specifiers.
+
+> NB: formatParam returns an array with the raw and debug-colored string at indices `0` and `1` respectively.
+
+```ts
+import { formatParam } from "rsformat/format";
+
+// Equivalent to `${255}:+#09X` or `${255}:<+#09.0X`
+let [ pretty255 ] = formatParam(255, {
+    fill: '',
+    align: '<',
+    force_sign: '+',
+    pretty: true,
+    pad_zeroes: true,
+    width: 9,
+    precision: 0,
+    type: "X"
+});
+
+// pretty255 == '+0x0000FF'
+```
+
 ## 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:

package/docs.md

@@ -6,24 +6,54 @@ A rsformat format specifier is parsed as follows:
 
 - `${value}:[fill][align][sign][#][0][width][.(precision)][format_type][:]` is an unescaped format specifier and will parse the string as follows:
 
-| Name          | Syntax                                 | Purpose                                                                                                                             | Default value |
-| ------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------- |
-| `fill`        | any single chacter                     | The fill character for alignment                                                                                                    | space (` `)   |
-| `align`       | `<`, `^` or `>`                        | The alignment direction (left, center, right)                                                                                       | right (`>`)   |
-| `sign`        | `+` or `-`                             | Pad a positive number with `+` or a space ` ` (or convert a string to uppercase/lowercase)                                          | None          |
-| `#`           | `#`                                    | Pretty printing (Add prefixes `0b`, `0o` and `0x` to binary, octal and hex-formatted numbers, and use non-compact debug formatting) | None          |
-| `0`           | `0`                                    | Pads numbers with `0` characters instead of using fill/align                                                                        | None          |
-| `width`       | any positive integer                   | Minimum width for fill/alignment                                                                                                    | 0             |
-| `precision`   | `.` + any positive integer             | Minimum precision for non-integer numbers                                                                                           | 0             |
-| `format_type` | `?`,`o`,`x`,`X`,`b`,`e`,`E`,`n` or `N` | Format type (see "Different Formatting Types" in README.md)                                                                                                      | None          |
-| `:`           | `:`                                    | Add to the end of a format specifier to not have to insert a space after it                                                         | None          |
+| Name          | Syntax                                                                 | Purpose                                                                                                                             | Default value |
+| ------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------- |
+| `fill`        | any single character                                                     | The fill character for alignment                                                                                                    | space (` `)   |
+| `align`       | `<`, `^` or `>`                                                        | The alignment direction (left, center, right)                                                                                       | right (`>`)   |
+| `sign`        | `+` or `-`                                                             | Pad a positive number with `+` or a space ` ` (or convert a string to uppercase/lowercase)                                          | None          |
+| `#`           | `#`                                                                    | Pretty printing (Add prefixes `0b`, `0o` and `0x` to binary, octal and hex-formatted numbers, and use non-compact debug formatting) | None          |
+| `0`           | `0`                                                                    | Pads numbers with `0` characters instead of using fill/align                                                                        | None          |
+| `width`       | any positive integer (in string or as ${} parameter)                   | Minimum width for fill/alignment                                                                                                    | 0             |
+| `precision`   | `.` + any positive integer (in string or as ${} parameter)             | Minimum precision for non-integer numbers                                                                                           | 0             |
+| `format_type` | `?`,`o`,`x`,`X`,`b`,`e`,`E`,`n` or `N`                                 | Format type (see [Format types](#format-types))                                                                                     | None          |
+| `:`           | `:`                                                                    | Add to the end of a format specifier to not have to insert a space after it                                                         | None          |
 
 Every single one of the above values is optional, but must be included in that order.
 
+## Format types
+
+| Character | Purpose                                                      | Example                    |
+| :-------: | ------------------------------------------------------------ | -------------------------- |
+|    `?`    | Debug formatting (`util.inspect` rather than `toString`)     | `[10]` -> `[10]`           |
+|    `o`    | Octal number formatting                                      | `10` -> `12` or `0o12`     |
+|    `x`    | Hexadecimal number formatting                                | `10` -> `a` or `0xa`       |
+|    `X`    | Uppercase hexadecimal number formatting                      | `10` -> `A` or `0xA`       |
+|    `b`    | Binary number formatting                                     | `10` -> `1010` or `0b1010` |
+|    `e`    | Scientific notation number formatting                        | `10` -> `1e1`              |
+|    `E`    | Uppercase scientific notation number formatting              | `10` -> `1E1`              |
+|    `n`    | Ordinal-suffixed number formatting                           | `10` -> `10th`             |
+|    `N`    | Uppercase ordinal-suffixed number formatting                 | `10` -> `10TH`             |
+
 ## Examples
 
 `${"abc"}:+:!` Will capitalise `"abc"` with an exclamation mark right after it, ie. `ABC!`
 
 `${15}:#08x` Will convert `15` to hexadecimal, add `0x` and pad it with 0s until it is 8 characters wide, ie. `0x00000F`
 
-`${1.2345678}:,^10.${3}` will round `1.2345678` to 3 decimal places and center align it with `,` untill it is 10 characters wide, ie. `,,1.234,,,`
+`${1.2345678}:,^10.${3}` will round `1.2345678` to 3 decimal places and center align it with `,` until it is 10 characters wide, ie. `,,1.234,,,`
+
+## rsformat specifiers for those familiar with Rust formatting
+
+This implementation parses formatting very similarly to Rust, but differing in a few key 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 `+`.
+- When used on strings, `+` and `-` sign specifiers will conver them to uppercase and lowercase respectively
+- 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)

package/lib/format.d.ts

@@ -1,3 +1,4 @@
+import util from 'node:util';
 /**
  * Type representing a string formatted by `rs`.
  * An extension of `String`.
@@ -43,4 +44,6 @@ type FormatSpecifier = {
  * @returns `param` as a debug-colored and raw formatted string
  */
 export declare function formatParam(param: any, format: FormatSpecifier): [string, string];
+/** Re-export of node's `util.styleText`. */
+export declare const style: typeof util.styleText;
 export {};

package/lib/format.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RsString = void 0;
+exports.style = exports.RsString = void 0;
 exports.buildString = buildString;
 exports.formatParam = formatParam;
 const node_util_1 = __importDefault(require("node:util"));
@@ -103,7 +103,7 @@ function buildString(strings, params) {
                 idx++;
             width = Number(string.substring(width_substring_start, idx));
         }
-        else if (idx == string.length) {
+        else if (idx == string.length && i < params.length) {
             // Grab the next parameter and fuse the string with the next one
             width = params[i];
             if (typeof width != 'number')
@@ -116,7 +116,7 @@ function buildString(strings, params) {
                 // 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.`);
+                    throw error(i - 1, idx, `Expected a number or number parameter for precision specifier after . (found ${string[idx] ? "'" + string[idx] + "'" : typeof precision + ' 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 {
@@ -176,69 +176,80 @@ function buildString(strings, params) {
  */
 function formatParam(param, format) {
     let param_type = typeof param;
+    let base = 10;
+    switch (format.type) {
+        case 'o':
+            base = 8;
+            break;
+        case 'x':
+        case 'X':
+            base = 16;
+            break;
+        case 'b':
+            base = 2;
+            break;
+    }
+    let param_raw;
     let param_colored = "";
-    // embed RsStrings directly
+    // embed Strings directly
     if (param instanceof String && format.type != '?') {
+        param_raw = param.toString(false);
         param_colored = param.toString(true);
-        param = param.toString(false);
     }
     else
         switch (format.type) {
             // Process 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);
+                param_raw = roundInBase(param, base, format.precision);
+                if (format.type == "X")
+                    param_raw = param_raw.toUpperCase();
                 break;
             case 'e':
             case 'E':
                 if (param_type != 'number' && param_type != 'bigint') {
-                    param = param.toString();
+                    param_raw = param.toString();
                     break;
                 }
-                param = param.toLocaleString('en-US', { notation: 'scientific', maximumFractionDigits: 20 });
+                param_raw = param.toLocaleString('en-US', { notation: 'scientific', maximumFractionDigits: 20 });
                 if (format.type == 'e')
-                    param = param.toLowercase();
+                    param_raw = param_raw.toLowerCase();
+                // Do not pad with zeroes when using scientific formatting
+                format.pad_zeroes = false;
                 break;
             case 'n':
             case 'N':
                 if (param_type != 'number' && param_type != 'bigint') {
-                    param = param.toString();
+                    param_raw = param.toString();
                     break;
                 }
                 // Round and add suffix
                 if (param_type == 'number')
                     param = Math.round(param);
-                param = param.toString();
-                let last_2_digits = param.substring(param.length - 2);
+                param_raw = param.toString();
+                let last_2_digits = param_raw.substring(param_raw.length - 2);
                 if (last_2_digits == '11' || last_2_digits == '12' || last_2_digits == '13') {
-                    param = param + 'th';
+                    param_raw += 'th';
                 }
                 else
                     switch (last_2_digits[last_2_digits.length - 1]) {
                         case '1':
-                            param = param + 'st';
+                            param_raw += 'st';
                             break;
                         case '2':
-                            param = param + 'nd';
+                            param_raw += 'nd';
                             break;
                         case '3':
-                            param = param + 'rd';
+                            param_raw += 'rd';
                             break;
-                        default: param = param + 'th';
+                        default: param_raw += 'th';
                     }
                 if (format.type == 'N')
-                    param = param.toUpperCase();
-                // Do not pad with zeroes or align to precision when using ordinal formatting
+                    param_raw = param_raw.toUpperCase();
+                // Do not pad with zeroes  when using ordinal formatting
                 format.pad_zeroes = false;
-                format.precision = -1;
                 break;
             case '?':
                 param_colored = node_util_1.default.inspect(param, {
@@ -246,36 +257,25 @@ function formatParam(param, format) {
                     colors: true,
                     compact: !format.pretty
                 });
-                param = node_util_1.default.stripVTControlCharacters(param_colored);
+                param_raw = node_util_1.default.stripVTControlCharacters(param_colored);
                 // Do not force sign, pad with zeroes or align to precision when using debug formatting
                 param_type = 'string';
-                format.force_sign = '';
+                // format.force_sign = '';
                 break;
             default:
-                param = param.toString();
+                param_raw = roundInBase(param, base, format.precision);
                 break;
         }
     ;
     if (param_type == 'string' && format.force_sign != '') {
-        param = format.force_sign == '+' ? param.toUpperCase() : param.toLowercase();
-    }
-    // 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;
-        }
+        param_raw = format.force_sign == '+' ? param_raw.toUpperCase() : param_raw.toLowerCase();
     }
     // let filled = false;
     if ((param_type == 'number') || (param_type == 'bigint')) {
         // Compute parameter sign
-        let maybe_sign = param.substring(0, 1);
+        let maybe_sign = param_raw.substring(0, 1);
         if (maybe_sign === '-') {
-            param = param.substring(1, param.length);
+            param_raw = param_raw.substring(1, param_raw.length);
         }
         else if (format.force_sign == '+') {
             maybe_sign = '+';
@@ -304,19 +304,20 @@ function formatParam(param, format) {
         //pad with zeroes if specified  
         if (format.pad_zeroes) {
             // filled = true;
-            while (param.length < format.width - maybe_sign.length) {
-                param = '0' + param;
+            while (param_raw.length < format.width - maybe_sign.length) {
+                param_raw = '0' + param_raw;
             }
         }
-        param = maybe_sign + param;
+        param_raw = maybe_sign + param_raw;
     }
     if (param_colored == "")
-        param_colored = param;
-    if (format.width > param.length) {
+        param_colored = param_raw;
+    let visible_length = [...param_raw].length;
+    if (format.width > visible_length) {
         // Compute fill/align
         let left = '';
         let right = '';
-        let diff = format.width - param.length;
+        let diff = format.width - visible_length;
         switch (format.align) {
             case '>':
                 left = format.fill.repeat(diff);
@@ -330,8 +331,37 @@ function formatParam(param, format) {
                 right = format.fill.repeat(diff / 2 + diff % 2);
                 break;
         }
-        param = left + param + right;
+        param_raw = left + param_raw + right;
         param_colored = left + param_colored + right;
     }
-    return [param_colored, param];
+    return [param_colored, param_raw];
+}
+/**
+ * Helper function to round a number to a given precision in a given base.
+ * Will also truncate strings to the desired length.
+ */
+function roundInBase(n, base, precision) {
+    if (typeof n == "string") {
+        if (precision == -1)
+            return n;
+        return n.slice(0, precision);
+    }
+    if (typeof n != "number" && typeof n != "bigint") {
+        return n.toString();
+    }
+    if (precision < 0) {
+        return n.toString(base);
+    }
+    if (precision == 0) {
+        return (typeof n == "bigint" ? n : Math.round(n)).toString(base);
+    }
+    const factor = base ** precision;
+    const rounded = typeof n == "bigint" ? n * BigInt(factor) : Math.round((n + Number.EPSILON) * factor);
+    const str = rounded.toString(base);
+    // Insert radix point from the right
+    const intPart = str.slice(0, -precision) || "0";
+    const fracPart = str.slice(-precision).padStart(precision, "0");
+    return intPart + "." + fracPart;
 }
+/** Re-export of node's `util.styleText`. */
+exports.style = node_util_1.default.styleText;

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-import { RsString } from './format';
+import { RsString, style } from './format';
 export { print, println, eprint, eprintln, dbg } from './print';
 type ParameterReference = {
     __rs_param_ref: number;
@@ -25,6 +25,11 @@ type rs = {
      * @returns A reference to the `n`th parameter
      */
     ref: (n: number) => ParameterReference;
+    /**
+     * Format a string using one or more of [the modifiers provided by node's `util` module](https://nodejs.org/docs/latest-v22.x/api/util.html#modifiers).
+     * This is a re-export of `util.styleText`.
+     */
+    style: typeof style;
 };
 /**
 * Tag to use Rust-style formatting in a template literal.

package/lib/index.js

@@ -23,3 +23,4 @@ Object.defineProperty(exports, "dbg", { enumerable: true, get: function () { ret
 exports.rs = ((strings, ...params) => new format_1.RsString(strings, params));
 exports.rs.raw = (strings, ...params) => (0, format_1.buildString)(strings, params).raw;
 exports.rs.ref = (n) => ({ __rs_param_ref: n });
+exports.rs.style = format_1.style;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rsformat",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Formatting/printing library for JavaScript that takes after rust's string formatting ",
   "files": [
     "lib",
@@ -31,11 +31,16 @@
   "author": "Alfio (https://github.com/p2js)",
   "license": "ISC",
   "devDependencies": {
-    "@types/node": "^22.8.6"
+    "@types/jest": "^30.0.0",
+    "@types/node": "^22.8.6",
+    "jest": "^30.2.0",
+    "typescript": "^5.9.3"
   },
   "scripts": {
-    "build": "tsc",
-    "prepublish": "pnpm build",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "build": "pnpm exec tsc",
+    "build:test": "pnpm exec tsc -p tsconfig.test.json",
+    "pretest": "pnpm build && pnpm build:test",
+    "test": "pnpm exec jest test-build",
+    "posttest": "rm -r test-build"
   }
 }