rsformat 1.1.2 → 1.2.0

package/README.md

@@ -43,7 +43,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` with ANSI control characters escaped.
+> 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`:
 

package/lib/format.d.ts

@@ -37,12 +37,10 @@ type FormatSpecifier = {
 };
 /**
  * Format a parameter as a string according to a specifier.
- * Will include colors in the output of debug formating
  *
  * @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
+ * @returns `param` as a debug-colored and raw formatted string
  */
-export declare function formatParam(param: any, format: FormatSpecifier): string;
+export declare function formatParam(param: any, format: FormatSpecifier): [string, string];
 export {};

package/lib/format.js

@@ -3,7 +3,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.formatParam = exports.buildString = exports.RsString = void 0;
+exports.RsString = void 0;
+exports.buildString = buildString;
+exports.formatParam = formatParam;
 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}`);
@@ -37,7 +39,8 @@ exports.RsString = RsString;
  * @returns An object with raw and colored versions of the formatted parameter
  */
 function buildString(strings, params) {
-    let out = strings[0];
+    let raw = strings[0];
+    let colored = strings[0];
     for (let i = 1; i < strings.length; ++i) {
         let string = strings[i];
         let param = params[i - 1];
@@ -45,7 +48,9 @@ function buildString(strings, params) {
         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) {
+                || ref_number < 0
+                || ref_number >= params.length
+                || !Number.isInteger(ref_number)) {
                 throw new Error(`Parameter ${i - 1}: Invalid reference`);
             }
             if (ref_number == i - 1)
@@ -55,14 +60,18 @@ function buildString(strings, params) {
         // 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
+        let skipParsing = false;
         if (string[0] == ':') {
             if (string[1] == ':') {
-                out += param.toString() + string.substring(1);
-                continue;
+                string = string.substring(1);
+                skipParsing = true;
             }
         }
-        else {
-            out += param.toString() + string;
+        else
+            skipParsing = true;
+        if (skipParsing) {
+            raw += param.toString(param instanceof String ? false : undefined) + string;
+            colored += param.toString(param instanceof String ? true : undefined) + string;
             continue;
         }
         ;
@@ -142,7 +151,7 @@ function buildString(strings, params) {
             throw error(i - 1, idx, `Expected colon (':') or space character (' '/'\\t'/'\\r'/'\\n') at end of formatting specifier (found '${string[idx]}')`);
         }
         // Format parameter according to specifier
-        let formatted = formatParam(param, {
+        let [formatted_colored, formatted_raw] = formatParam(param, {
             fill,
             align,
             force_sign,
@@ -152,92 +161,100 @@ function buildString(strings, params) {
             precision,
             type: format_type
         });
-        out += formatted + string.substring(idx);
+        let escaped_string = string.substring(idx);
+        colored += formatted_colored + escaped_string;
+        raw += formatted_raw + escaped_string;
     }
-    return { raw: node_util_1.default.stripVTControlCharacters(out), colored: out };
+    return { raw, colored };
 }
-exports.buildString = buildString;
 /**
  * Format a parameter as a string according to a specifier.
- * Will include colors in the output of debug formating
  *
  * @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
+ * @returns `param` as a debug-colored and raw formatted string
  */
 function formatParam(param, format) {
     let param_type = typeof param;
-    // 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') {
+    let param_colored = "";
+    // embed RsStrings directly
+    if (param instanceof String && format.type != '?') {
+        console.log("rsString passed");
+        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);
+                break;
+            case 'e':
+            case 'E':
+                if (param_type != 'number' && param_type != 'bigint') {
+                    param = param.toString();
+                    break;
+                }
+                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;
+                }
+                // 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';
+                }
+                else
+                    switch (last_2_digits[last_2_digits.length - 1]) {
+                        case '1':
+                            param = param + 'st';
+                            break;
+                        case '2':
+                            param = param + 'nd';
+                            break;
+                        case '3':
+                            param = param + 'rd';
+                            break;
+                        default: param = param + 'th';
+                    }
+                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;
-            }
-            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') {
+            case '?':
+                param_colored = node_util_1.default.inspect(param, {
+                    depth: Infinity,
+                    colors: true,
+                    compact: !format.pretty
+                });
+                param = 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';
+                break;
+            default:
                 param = 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);
-            if (last_2_digits == '11' || last_2_digits == '12' || last_2_digits == '13') {
-                param = param + 'th';
-            }
-            else
-                switch (last_2_digits[last_2_digits.length - 1]) {
-                    case '1':
-                        param = param + 'st';
-                        break;
-                    case '2':
-                        param = param + 'nd';
-                        break;
-                    case '3':
-                        param = param + 'rd';
-                        break;
-                    default: param = param + 'th';
-                }
-            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 '?':
-            param = node_util_1.default.inspect(param, {
-                depth: Infinity,
-                colors: true,
-                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;
-    }
+        }
     ;
     // Compute radix-point precision on numbers
     if (param_type == 'number' && format.precision != -1) {
@@ -290,7 +307,9 @@ function formatParam(param, format) {
         }
         param = maybe_sign + param;
     }
-    if ( /*!filled && */format.width > param.length) {
+    if (param_colored == "")
+        param_colored = param;
+    if (format.width > param.length) {
         // Compute fill/align
         let left = '';
         let right = '';
@@ -309,7 +328,7 @@ function formatParam(param, format) {
                 break;
         }
         param = left + param + right;
+        param_colored = left + param_colored + right;
     }
-    return param;
+    return [param_colored, param];
 }
-exports.formatParam = formatParam;

package/lib/index.d.ts

@@ -1,15 +1,41 @@
 import { RsString } from './format';
 export { print, println, eprint, eprintln, dbg } from './print';
+type ParameterReference = {
+    __rs_param_ref: number;
+};
+type rs = {
+    (strings: TemplateStringsArray, ...params: any[]): RsString;
+    /**
+     * Tag to use Rust-style formatting in a template literal.
+     * Returns a `string` primitive.
+     *
+     * ```js
+     * let number = 14;
+     * let info = rs.raw`${number+1} is ${rs.ref(0)}:x in hex`;
+     * // info === '15 is f in hex'
+     * ```
+     *
+     * @returns a string primitive of the formatted string
+     */
+    raw: (strings: TemplateStringsArray, ...params: any[]) => string;
+    /**
+     * Reference another parameter in a `rs`-tagged template.
+     *
+     * @param n Number of parameter to reference
+     * @returns A reference to the `n`th parameter
+     */
+    ref: (n: number) => ParameterReference;
+};
 /**
- * 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;
-    };
-}
+* Tag to use Rust-style formatting in a template literal.
+* Returns an extended `String` object.
+*
+* ```js
+* let number = 14;
+* let info = rs`${number+1} is ${rs.ref(0)}:x in hex`;
+* // info == '15 is f in hex'
+* ```
+*
+* @returns a String object with the formatted string
+*/
+export declare let rs: rs;

package/lib/index.js

@@ -9,28 +9,17 @@ Object.defineProperty(exports, "eprint", { enumerable: true, get: function () {
 Object.defineProperty(exports, "eprintln", { enumerable: true, get: function () { return print_1.eprintln; } });
 Object.defineProperty(exports, "dbg", { enumerable: true, get: function () { return print_1.dbg; } });
 /**
- * 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).raw;
-};
-/**
- * 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 });
+* Tag to use Rust-style formatting in a template literal.
+* Returns an extended `String` object.
+*
+* ```js
+* let number = 14;
+* let info = rs`${number+1} is ${rs.ref(0)}:x in hex`;
+* // info == '15 is f in hex'
+* ```
+*
+* @returns a String object with the formatted string
+*/
+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 });

package/lib/print.d.ts

@@ -1,7 +1,6 @@
-/// <reference types="node" />
-import { Writable } from 'node:stream';
+import type { Writable } from 'node:stream';
 /**
- * Print a string (or instance of String/RsString) to a stream.
+ * Print a string (or instance of String/RsString) to a `Writable` stream.
  *
  * @param stream Stream to print the string to
  * @param string String to print
@@ -36,6 +35,13 @@ export declare function eprintln(string: string | String): void;
 /**
  * Debug print a value to stderr and return it.
  *
+ * ```js
+ * let r = Math.random();
+ * if(dbg(r < 0.3)) { // prints 'true' or 'false'
+ *     println("Unlucky!");
+ * }
+ * ```
+ *
  * @param value Value to debug print
  */
 export declare function dbg(value: any): any;

package/lib/print.js

@@ -3,11 +3,16 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.dbg = exports.eprintln = exports.eprint = exports.println = exports.print = exports.printToStream = void 0;
+exports.printToStream = printToStream;
+exports.print = print;
+exports.println = println;
+exports.eprint = eprint;
+exports.eprintln = eprintln;
+exports.dbg = dbg;
 const node_process_1 = __importDefault(require("node:process"));
 const _1 = require(".");
 /**
- * Print a string (or instance of String/RsString) to a stream.
+ * Print a string (or instance of String/RsString) to a `Writable` stream.
  *
  * @param stream Stream to print the string to
  * @param string String to print
@@ -16,13 +21,12 @@ const _1 = require(".");
  */
 function printToStream(stream, string, newline = false, colored = false) {
     if (string instanceof String) {
-        string = string.toString(true);
+        string = string.toString(colored);
     }
     if (newline)
         string = string + '\n';
     stream.write(string);
 }
-exports.printToStream = printToStream;
 /**
  * Print a string to stdout.
  *
@@ -31,7 +35,6 @@ exports.printToStream = printToStream;
 function print(string) {
     printToStream(node_process_1.default.stdout, string, false, true);
 }
-exports.print = print;
 /**
  * Print a string to stdout and append a newline.
  *
@@ -40,7 +43,6 @@ exports.print = print;
 function println(string) {
     printToStream(node_process_1.default.stdout, string, true, true);
 }
-exports.println = println;
 /**
  * Print a string to stderr.
  *
@@ -49,7 +51,6 @@ exports.println = println;
 function eprint(string) {
     printToStream(node_process_1.default.stderr, string, false, true);
 }
-exports.eprint = eprint;
 /**
  * Print a string to stderr and append a newline.
  *
@@ -58,14 +59,19 @@ exports.eprint = eprint;
 function eprintln(string) {
     printToStream(node_process_1.default.stderr, string, true, true);
 }
-exports.eprintln = eprintln;
 /**
  * Debug print a value to stderr and return it.
  *
+ * ```js
+ * let r = Math.random();
+ * if(dbg(r < 0.3)) { // prints 'true' or 'false'
+ *     println("Unlucky!");
+ * }
+ * ```
+ *
  * @param value Value to debug print
  */
 function dbg(value) {
     eprintln((0, _1.rs) `${value}:?`);
     return value;
 }
-exports.dbg = dbg;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rsformat",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "description": "Formatting/printing library for JavaScript that takes after rust's string formatting ",
   "files": [
     "lib",