diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..03f646f --- /dev/null +++ b/LICENSE @@ -0,0 +1 @@ +MIT OR Apache-2.0 diff --git a/README.md b/README.md index ac10e3c..c52e57f 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,44 @@ -# typst-oxifmt (v0.2.1) +# typst-oxifmt (v0.3.0) -A Typst library that brings convenient string formatting and interpolation through the `strfmt` function. Its syntax is taken directly from Rust's `format!` syntax, so feel free to read its page for more information (https://doc.rust-lang.org/std/fmt/); however, this README should have enough information and examples for all expected uses of the library. Only a few things aren't supported from the Rust syntax, such as the `p` (pointer) format type, or the `.*` precision specifier. +A Typst library that brings convenient string formatting and interpolation through the `strfmt` function. Its syntax is taken directly from Rust's `format!` syntax, so feel free to read its page for more information (https://doc.rust-lang.org/std/fmt/); however, this README should have enough information and examples for all expected uses of the library. Only a few things aren't supported from the Rust syntax, such as the `p` (pointer) format type, or the `.*` precision specifier. Check out the ["Examples" section](#examples) for more. -A few extras (beyond the Rust-like syntax) will be added over time, though (feel free to drop suggestions at the repository: https://github.com/PgBiel/typst-oxifmt). The first "extra" so far is the `fmt-decimal-separator: "string"` parameter, which lets you customize the decimal separator for decimal numbers (floats) inserted into strings. E.g. `strfmt("Result: {}", 5.8, fmt-decimal-separator: ",")` will return the string `"Result: 5,8"` (comma instead of dot). See more below. +A few extras (beyond the Rust-like syntax) will be added over time, though (feel free to drop suggestions at the repository: https://github.com/PgBiel/typst-oxifmt). The first "extra" so far is the `fmt-decimal-separator: "string"` parameter, which lets you customize the decimal separator for decimal numbers (floats) inserted into strings. E.g. `strfmt("Result: {}", 5.8, fmt-decimal-separator: ",")` will return the string `"Result: 5,8"` (comma instead of dot). We also provide thousands separator support with `fmt-thousands-separator: "_"` for example. See more at ["Custom options"](#custom-options). -**Compatible with:** [Typst](https://github.com/typst/typst) v0.4.0+ +**Compatible with:** [Typst](https://github.com/typst/typst) v0.7.0+ + +## Quick examples + +```typ +#import "@preview/oxifmt:0.3.0": strfmt + +// "User John has 10 apples." +#strfmt("User {} has {} apples.", "John", 10) + +// "if exp > 100 { true }" +#strfmt("if {var} > {num} {{ true }}", var: "exp", num: 100) + +// "1.10e2 meters" +#strfmt("{:.2e} meters", 110.0) + +// "20_000 players have more than +002,300 points." +#strfmt( + "{} players have more than {:+08.3} points.", + 20000, + 2.3, + fmt-decimal-separator: ",", + fmt-thousands-separator: "_" +) + +// "The byte value is 0x8C or 10001100" +#strfmt("The byte value is {:#02X} or {0:08b}", 140) +``` ## Table of Contents - [Usage](#usage) - [Formatting options](#formatting-options) - [Examples](#examples) + - [Custom options](#custom-options) - [Grammar](#grammar) - [Issues and Contributing](#issues-and-contributing) - [Testing](#testing) @@ -22,7 +50,7 @@ A few extras (beyond the Rust-like syntax) will be added over time, though (feel You can use this library through Typst's package manager (for Typst v0.6.0+): ```typ -#import "@preview/oxifmt:0.2.1": strfmt +#import "@preview/oxifmt:0.3.0": strfmt ``` For older Typst versions, download the `oxifmt.typ` file either from Releases or directly from the repository. Then, move it to your project's folder, and write at the top of your Typst file(s): @@ -36,7 +64,7 @@ Doing the above will give you access to the main function provided by this libra Its syntax is almost identical to Rust's `format!` (as specified here: https://doc.rust-lang.org/std/fmt/). You can escape formats by duplicating braces (`{{` and `}}` become `{` and `}`). Here's an example (see more examples in the file `tests/strfmt-tests.typ`): ```typ -#import "@preview/oxifmt:0.2.1": strfmt +#import "@preview/oxifmt:0.3.0": strfmt #let s = strfmt("I'm {}. I have {num} cars. I'm {0}. {} is {{cool}}.", "John", "Carl", num: 10) #assert.eq(s, "I'm John. I have 10 cars. I'm John. Carl is {cool}.") @@ -67,6 +95,8 @@ You can use `{:spec}` to customize your output. See the Rust docs linked above f - Add `e` or `E` at the end of the `spec` to ensure the number is represented in scientific notation (with `e` or `E` as the exponent separator, respectively). - For decimal numbers (floats), you can specify `fmt-decimal-separator: ","` to `strfmt` to have the decimal separator be a comma instead of a dot, for example. - To have this be the default, you can alias `strfmt`, such as using `#let strfmt = strfmt.with(fmt-decimal-separator: ",")`. + - You can enable thousands separators for numbers with `fmt-thousands-separator: "_"` to separate with an underscore, for example. + - By default, thousands separators are inserted after every third digit from the end of the number. Use `fmt-thousands-count: 2` to change that to every second digit as an example. - Number spec arguments (such as `.5`) are ignored when the argument is not a number, but e.g. a string, even if it looks like a number (such as `"5"`). - Note that all spec arguments above **have to be specified in order** - if you mix up the order, it won't work properly! - Check the grammar below for the proper order, but, in summary: fill (character) with align (`<`, `>` or `^`) -> sign (`+` or `-`) -> `#` -> `0` (for 0 left-padding of numbers) -> width (e.g. `8` from `08` or `9` from `-<9`) -> `.precision` -> spec type (`?`, `x`, `X`, `b`, `o`, `e`, `E`)). @@ -74,7 +104,7 @@ You can use `{:spec}` to customize your output. See the Rust docs linked above f Some examples: ```typ -#import "@preview/oxifmt:0.2.1": strfmt +#import "@preview/oxifmt:0.3.0": strfmt #let s1 = strfmt("{0:?}, {test:+012e}, {1:-<#8x}", "hi", -74, test: 569.4) #assert.eq(s1, "\"hi\", +00005.694e2, -0x4a---") @@ -90,7 +120,7 @@ Some examples: - **Inserting labels, text and numbers into strings:** ```typ -#import "@preview/oxifmt:0.2.1": strfmt +#import "@preview/oxifmt:0.3.0": strfmt #let s = strfmt("First: {}, Second: {}, Fourth: {3}, Banana: {banana} (brackets: {{escaped}})", 1, 2.1, 3, label("four"), banana: "Banana!!") #assert.eq(s, "First: 1, Second: 2.1, Fourth: four, Banana: Banana!! (brackets: {escaped})") @@ -98,7 +128,7 @@ Some examples: - **Forcing `repr()` with `{:?}`** (which adds quotes around strings, and other things - basically represents a Typst value): ```typ -#import "@preview/oxifmt:0.2.1": strfmt +#import "@preview/oxifmt:0.3.0": strfmt #let s = strfmt("The value is: {:?} | Also the label is {:?}", "something", label("label")) #assert.eq(s, "The value is: \"something\" | Also the label is