rsformat 1.1.0 → 1.1.3

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,11 +37,10 @@ type FormatSpecifier = {
 };
 /**
  * Format a parameter as a string according to a specifier.
- * Will include colors in the output of debug formating
+ * 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): string;

package/lib/format.js

@@ -37,7 +37,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 +46,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)
@@ -57,12 +60,16 @@ function buildString(strings, params) {
         // If it has two the first : is being escaped and can be removed
         if (string[0] == ':') {
             if (string[1] == ':') {
-                out += param.toString() + string.substring(1);
+                let stringified = param.toString() + string.substring(1);
+                raw += stringified;
+                colored += stringified;
                 continue;
             }
         }
         else {
-            out += param.toString() + string;
+            let stringified = param.toString() + string;
+            raw += stringified;
+            colored += stringified;
             continue;
         }
         ;
@@ -134,8 +141,12 @@ function buildString(strings, params) {
         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, {
@@ -148,18 +159,21 @@ function buildString(strings, params) {
             precision,
             type: format_type
         });
-        out += formatted + string.substring(idx);
+        let escaped_string = string.substring(idx);
+        colored += formatted + escaped_string;
+        if (format_type == '?')
+            formatted = node_util_1.default.stripVTControlCharacters(formatted);
+        raw += formatted + 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
+ * 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) {

package/lib/index.d.ts

@@ -1,15 +1,41 @@
 import { RsString } from './format';
-export { print, println, eprint, eprintln } from './print';
+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

@@ -1,35 +1,25 @@
 "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.
- *
- * @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,7 @@
 /// <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 +36,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

@@ -7,7 +7,7 @@ exports.dbg = exports.eprintln = exports.eprint = exports.println = exports.prin
 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
@@ -62,6 +62,13 @@ 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) {

package/package.json

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