rsformat 1.0.0 → 1.1.2

package/README.md

@@ -31,23 +31,25 @@ 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.
+
+To reference a previous or following argument, use `rs.ref` with the argument number. This is useful if you want to reuse a complicated expression without having to declare it separately.
 
 ```js
 import { rs, println } from 'rsformat';      // ESM
 const { rs, println } = require('rsformat'); // CommonJS
 
-let number = 15;
+let number = 14;
 
-let info = rs`${number} is ${rs.ref(0)}:x in hex`; // info == '15 is f in hex'
+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 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.
 
 The printing functions can be called with plain strings, instances of `String` or templates formatted with `rs`:
 
 ```ts
 println('Hello World');
+println(`This template did ${'Not'} need fancy formatting`);
 println(rs`...`);
 ```
 

package/lib/format.d.ts

@@ -3,23 +3,25 @@
  * An extension of `String`.
  */
 export declare class RsString extends String {
-    __debugColors: boolean;
-    private cachedColor;
-    private cachedPlain;
-    private strings;
-    private params;
+    /**
+     * A version of the string that includes ANSI escape codes for debug formatting.
+     */
+    colored: string;
     constructor(strings: TemplateStringsArray, params: any[]);
-    toString(): string;
-    valueOf(): string;
+    toString(debugColors?: boolean): string;
 }
 /**
- * Format a template literal with rust-style formatting and return it as a string.
+ * Format a template literal with rust-style formatting and return it as a raw and colored string.
  *
  * @param strings String parts of the template
  * @param params Template parameters
- * @returns a string primitive of the formatted string
+ *
+ * @returns An object with raw and colored versions of the formatted parameter
  */
-export declare function buildString(strings: TemplateStringsArray, params: any[], debugColors?: boolean): string;
+export declare function buildString(strings: TemplateStringsArray, params: any[]): {
+    raw: string;
+    colored: string;
+};
 type AlignDirection = '<' | '^' | '>';
 type Sign = '-' | '+' | '';
 type FormatType = '?' | 'o' | 'x' | 'X' | 'b' | 'e' | 'E' | 'n' | 'N' | '';
@@ -35,11 +37,12 @@ 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
  */
-export declare function formatParam(param: any, format: FormatSpecifier, debugColors: boolean): string;
+export declare function formatParam(param: any, format: FormatSpecifier): string;
 export {};

package/lib/format.js

@@ -12,48 +12,32 @@ const error = (param, char, reason) => new Error(`rs[param ${param}, char ${char
  * An extension of `String`.
  */
 class RsString extends String {
-    __debugColors = false;
-    cachedColor = null;
-    cachedPlain = null;
-    strings;
-    params;
+    /**
+     * A version of the string that includes ANSI escape codes for debug formatting.
+     */
+    colored;
     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;
-        }
-        ;
+        let { raw, colored } = buildString(strings, params);
+        super(raw);
+        this.colored = colored;
     }
-    valueOf() {
-        return this.toString();
+    toString(debugColors = false) {
+        if (debugColors)
+            return this.colored;
+        return this.valueOf();
     }
 }
 exports.RsString = RsString;
 /**
- * Format a template literal with rust-style formatting and return it as a string.
+ * Format a template literal with rust-style formatting and return it as a raw and colored string.
  *
  * @param strings String parts of the template
  * @param params Template parameters
- * @returns a string primitive of the formatted string
+ *
+ * @returns An object with raw and colored versions of the formatted parameter
  */
-function buildString(strings, params, debugColors = false) {
-    let out = [strings[0]];
+function buildString(strings, params) {
+    let out = strings[0];
     for (let i = 1; i < strings.length; ++i) {
         let string = strings[i];
         let param = params[i - 1];
@@ -73,12 +57,12 @@ function buildString(strings, params, debugColors = false) {
         // 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));
+                out += param.toString() + string.substring(1);
                 continue;
             }
         }
         else {
-            out.push(param.toString() + string);
+            out += param.toString() + string;
             continue;
         }
         ;
@@ -150,8 +134,12 @@ function buildString(strings, params, debugColors = false) {
         if (string[idx] == ':') {
             idx++;
         }
-        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 if (string[idx] != ' '
+            && string[idx] != '\t'
+            && string[idx] != '\r'
+            && string[idx] != '\n'
+            && string[idx] !== undefined) {
+            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, {
@@ -163,23 +151,23 @@ function buildString(strings, params, debugColors = false) {
             width,
             precision,
             type: format_type
-        }, debugColors);
-        out.push(formatted + string.substring(idx));
+        });
+        out += formatted + string.substring(idx);
     }
-    return out.join('');
+    return { raw: node_util_1.default.stripVTControlCharacters(out), colored: out };
 }
 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
  */
-function formatParam(param, format, debugColors) {
+function formatParam(param, format) {
     let param_type = typeof param;
-    let true_length = -1;
     // Process parameter type
     switch (format.type) {
         case 'o':
@@ -238,14 +226,9 @@ function formatParam(param, format, debugColors) {
             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,
+                colors: true,
                 compact: !format.pretty
             });
             // Do not force sign, pad with zeroes or align to precision when using debug formatting
@@ -256,9 +239,6 @@ function formatParam(param, format, debugColors) {
             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('.');
@@ -269,10 +249,8 @@ function formatParam(param, format, debugColors) {
             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;
+    // let filled = false;
     if ((param_type == 'number') || (param_type == 'bigint')) {
         // Compute parameter sign
         let maybe_sign = param.substring(0, 1);
@@ -305,20 +283,18 @@ function formatParam(param, format, debugColors) {
         }
         //pad with zeroes if specified  
         if (format.pad_zeroes) {
-            filled = true;
+            // 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) {
+    if ( /*!filled && */format.width > param.length) {
         // Compute fill/align
         let left = '';
         let right = '';
-        let diff = format.width - true_length;
+        let diff = format.width - param.length;
         switch (format.align) {
             case '>':
                 left = format.fill.repeat(diff);

package/lib/index.d.ts

@@ -1,5 +1,5 @@
 import { RsString } from './format';
-export { print, println, eprint, eprintln } from './print';
+export { print, println, eprint, eprintln, dbg } from './print';
 /**
  * Tag to use Rust-style formatting in a template literal.
  * Returns an extended `String` object.

package/lib/index.js

@@ -1,12 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.rs = exports.eprintln = exports.eprint = exports.println = exports.print = void 0;
+exports.rs = exports.dbg = 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; } });
+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.
@@ -24,7 +25,7 @@ exports.rs = rs;
  * @returns a string primitive of the formatted string
  */
 rs.raw = function (strings, ...params) {
-    return (0, format_1.buildString)(strings, params);
+    return (0, format_1.buildString)(strings, params).raw;
 };
 /**
  * Reference another parameter in a `rs`-tagged template.

package/lib/print.js

@@ -4,7 +4,6 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 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(".");
 /**
@@ -16,13 +15,8 @@ const _1 = require(".");
  * @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 (string instanceof String) {
+        string = string.toString(true);
     }
     if (newline)
         string = string + '\n';

package/package.json

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