rsformat 1.2.1 → 1.3.0

package/README.md

@@ -1,163 +1,174 @@
-# 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 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 = 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`.
-
-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`...`);
-```
-
-### 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'
-```
-
+# 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 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 = 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`.
+
+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`...`);
+```
+
+### 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` 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 `+`.
+- 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)
+
+#### 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'
+```
+
+#### String formatting
+
+Adding a `+` or `-` to a formatting specifier of a string will instead convert it to uppercase or lowercase respectively.
+
+```js
+let str  = "Hello!"
+let str_upper = rs`${str}:+` // 'HELLO!'
+let str_lower = rs`${str}:-` // 'hello!'
+```
+
+## 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/docs.md

@@ -0,0 +1,29 @@
+# rsformat Format Specifier Documentation
+
+A rsformat format specifier is parsed as follows:
+
+- `${value}::` Will escape the colon character and replace it with a single `:`. Stringification of `value` will occur as in normal format strings.
+
+- `${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          |
+
+Every single one of the above values is optional, but must be included in that order.
+
+## 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,,,`

package/lib/format.js

@@ -249,12 +249,16 @@ function formatParam(param, format) {
                 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';
+                format.force_sign = '';
                 break;
             default:
                 param = param.toString();
                 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('.');

package/lib/print.js

@@ -72,6 +72,6 @@ function eprintln(string) {
  * @param value Value to debug print
  */
 function dbg(value) {
-    eprintln((0, _1.rs) `${value}:?`);
+    eprintln((0, _1.rs) `${value}:#?`);
     return value;
 }

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "rsformat",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "Formatting/printing library for JavaScript that takes after rust's string formatting ",
   "files": [
     "lib",
-    "README.MD"
+    "README.md",
+    "docs.md"
   ],
   "exports": {
     ".": {