diff --git a/.gitignore b/.gitignore index 51b3b14..1635c0c 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,2 @@ -typst-oxifmt.pdf +oxifmt.pdf strfmt-tests.pdf diff --git a/README.md b/README.md index d5c4382..7f04eae 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# typst-oxifmt (v0.1.0) +# typst-oxifmt (v0.2.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. @@ -19,10 +19,16 @@ A few extras (beyond the Rust-like syntax) will be added over time, though (feel ## Usage -Download the `typst-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): +You can use this library through Typst's package manager (for Typst v0.6.0+): ```js -#import "typst-oxifmt.typ": strfmt +#import "@preview/oxifmt:0.2.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): + +```js +#import "oxifmt.typ": strfmt ``` Doing the above will give you access to the main function provided by this library (`strfmt`), which accepts a format string, followed by zero or more replacements to insert in that string (according to `{...}` formats inserted in that string), an optional `fmt-decimal-separator` parameter, and returns the formatted string, as described below. @@ -30,10 +36,10 @@ 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`): ```js -#import "typst-oxifmt.typ": strfmt +#import "@preview/oxifmt:0.2.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}.") +#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}.") ``` Note that `{}` extracts positional arguments after the string sequentially (the first `{}` extracts the first one, the second `{}` extracts the second one, and so on), while `{0}`, `{1}`, etc. will always extract the first, the second etc. positional arguments after the string. Additionally, `{bananas}` will extract the named argument "bananas". @@ -68,7 +74,7 @@ You can use `{:spec}` to customize your output. See the Rust docs linked above f Some examples: ```js -#import "typst-oxifmt.typ": strfmt +#import "@preview/oxifmt:0.2.0": strfmt #let s1 = strfmt("{0:?}, {test:+012e}, {1:-<#8x}", "hi", -74, test: 569.4) #assert.eq(s1, "\"hi\", +00005.694e2, -0x4a---") @@ -84,7 +90,7 @@ Some examples: - **Inserting labels, text and numbers into strings:** ```js -#import "typst-oxifmt.typ": strfmt +#import "@preview/oxifmt:0.2.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})") @@ -92,7 +98,7 @@ Some examples: - **Forcing `repr()` with `{:?}`** (which adds quotes around strings, and other things - basically represents a Typst value): ```js -#import "typst-oxifmt.typ": strfmt +#import "@preview/oxifmt:0.2.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