typst-oxifmt (v0.2.1)

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 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.

Compatible with: Typst v0.4.0+

Table of Contents

• Usage
  • Formatting options
  • Examples
  • Grammar
• Issues and Contributing
• Testing
• Changelog
• License

Usage

You can use this library through Typst's package manager (for Typst v0.6.0+):

#import "@preview/oxifmt:0.2.1": 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):

#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.

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):

#import "@preview/oxifmt:0.2.1": 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}.")

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".

Formatting options

You can use {:spec} to customize your output. See the Rust docs linked above for more info, but a summary is below.

(You may also want to check out the examples at Examples.)

• Adding a ? at the end of spec (that is, writing e.g. {0:?}) will call repr() to stringify your argument, instead of str(). Note that this only has an effect if your argument is a string, an integer, a float or a label() / <label> - for all other types (such as booleans or elements), repr() is always called (as str() is unsupported for those).
  • For strings, ? (and thus repr()) has the effect of printing them with double quotes. For floats, this ensures a .0 appears after it, even if it doesn't have decimal digits. For integers, this doesn't change anything. Finally, for labels, the <label> (with ?) is printed as <label> instead of label.
  • TIP: Prefer to always use ? when you're inserting something that isn't a string, number or label, in order to ensure consistent results even if the library eventually changes the non-? representation.
• After the :, add e.g. _<8 to align the string to the left, padding it with as many _s as necessary for it to be at least 8 characters long (for example). Replace < by > for right alignment, or ^ for center alignment. (If the _ is omitted, it defaults to ' ' (aligns with spaces).)
  • If you prefer to specify the minimum width (the 8 there) as a separate argument to strfmt instead, you can specify argument$ in place of the width, which will extract it from the integer at argument. For example, _^3$ will center align the output with _s, where the minimum width desired is specified by the fourth positional argument (index 3), as an integer. This means that a call such as strfmt("{:_^3$}", 1, 2, 3, 4) would produce "__1__", as 3$ would evaluate to 4 (the value at the fourth positional argument/index 3). Similarly, named$ would take the width from the argument with name named, if it is an integer (otherwise, error).
• For numbers:
  • Specify + after the : to ensure zero or positive numbers are prefixed with + before them (instead of having no sign). - is also accepted but ignored (negative numbers always specify their sign anyways).
  • Use something like :09 to add zeroes to the left of the number until it has at least 9 digits / characters.
    • The 9 here is also a width, so the same comment from before applies (you can add $ to take it from an argument to the strfmt function).
  • Use :.5 to ensure your float is represented with 5 decimal digits of precision (zeroes are added to the right if needed; otherwise, it is rounded, not truncated).
    • Note that floating point inaccuracies can be sometimes observed here, which is an unfortunate current limitation.
    • Similarly to width, the precision can also be specified via an argument with the $ syntax: .5$ will take the precision from the integer at argument number 5 (the sixth one), while .test$ will take it from the argument named test.
  • Integers only: Add x (lowercase hex) or X (uppercase) at the end of the spec to convert the number to hexadecimal. Also, b will convert it to binary, while o will convert to octal.
    • Specify a hashtag, e.g. #x or #b, to prepend the corresponding base prefix to the base-converted number, e.g. 0xABC instead of ABC.
  • 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: ",").
  • 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)).

Some examples:

#import "@preview/oxifmt:0.2.1": strfmt

#let s1 = strfmt("{0:?}, {test:+012e}, {1:-<#8x}", "hi", -74, test: 569.4)
#assert.eq(s1, "\"hi\", +00005.694e2, -0x4a---")

#let s2 = strfmt("{:_>+11.5}", 59.4)
#assert.eq(s2, "__+59.40000")

#let s3 = strfmt("Dict: {:!<10?}", (a: 5))
#assert.eq(s3, "Dict: (a: 5)!!!!")

Examples

• Inserting labels, text and numbers into strings:

#import "@preview/oxifmt:0.2.1": 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})")

• Forcing repr() with {:?} (which adds quotes around strings, and other things - basically represents a Typst value):

#import "@preview/oxifmt:0.2.1": 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 <label>")

• Inserting other types than numbers and strings (for now, they will always use repr(), even without {...:?}, although that is more explicit):

#import "@preview/oxifmt:0.2.1": strfmt

#let s = strfmt("Values: {:?}, {1:?}, {stuff:?}", (test: 500), ("a", 5.1), stuff: [a])
#assert.eq(s, "Values: (test: 500), (\"a\", 5.1), [a]")

• Padding to a certain width with characters: Use {:x<8}, where x is the character to pad with (e.g. space or _, but can be anything), < is the alignment of the original text relative to the padding (can be < for left aligned (padding goes to the right), > for right aligned (padded to its left) and ^ for center aligned (padded at both left and right)), and 8 is the desired total width (padding will add enough characters to reach this width; if the replacement string already has this width, no padding will be added):

#import "@preview/oxifmt:0.2.1": strfmt

#let s = strfmt("Left5 {:-<5}, Right6 {:=>6}, Center10 {centered: ^10?}, Left3 {tleft:_<3}", "xx", 539, tleft: "okay", centered: [a])
#assert.eq(s, "Left5 xx---, Right6 ===539, Center10     [a]    , Left3 okay")
// note how 'okay' didn't suffer any padding at all (it already had at least the desired total width).

• Padding numbers with zeroes to the left: It's a similar functionality to the above, however you write {:08} for 8 characters (for instance) - note that any characters in the number's representation matter for width (including sign, dot and decimal part):

#import "@preview/oxifmt:0.2.1": strfmt

#let s = strfmt("Left-padded7 numbers: {:07} {:07} {:07} {3:07}", 123, -344, 44224059, 45.32)
#assert.eq(s, "Left-padded7 numbers: 0000123 -000344 44224059 0045.32")

• Defining padding-to width using parameters, not literals: If you want the desired replacement width (the 8 in {:08} or {: ^8}) to be passed via parameter (instead of being hardcoded into the format string), you can specify parameter$ in place of the width, e.g. {:02$} to take it from the third positional parameter, or {:a>banana$} to take it from the parameter named banana - note that the chosen parameter must be an integer (desired total width):

#import "@preview/oxifmt:0.2.1": strfmt

#let s = strfmt("Padding depending on parameter: {0:02$} and {0:a>banana$}", 432, 0, 5, banana: 9)
#assert.eq(s, "Padding depending on parameter: 00432 aaaaaa432")  // widths 5 and 9

• Displaying + on positive numbers: Just add a + at the "beginning", i.e., before the #0 (if either is there), or after the custom fill and align (if it's there and not 0 - see Grammar for the exact positioning), like so:

#import "@preview/oxifmt:0.2.1": strfmt

#let s = strfmt("Some numbers: {:+} {:+08}; With fill and align: {:_<+8}; Negative (no-op): {neg:+}", 123, 456, 4444, neg: -435)
#assert.eq(s, "Some numbers: +123 +0000456; With fill and align: +4444___; Negative (no-op): -435")

• Converting numbers to bases 2, 8 and 16: Use one of the following specifier types (i.e., characters which always go at the very end of the format): b (binary), o (octal), x (lowercase hexadecimal) or X (uppercase hexadecimal). You can also add a # between + and 0 (see the exact position at the Grammar) to display a base prefix before the number (i.e. 0b for binary, 0o for octal and 0x for hexadecimal):

#import "@preview/oxifmt:0.2.1": strfmt

#let s = strfmt("Bases (10, 2, 8, 16(l), 16(U):) {0} {0:b} {0:o} {0:x} {0:X} | W/ prefixes and modifiers: {0:#b} {0:+#09o} {0:_>+#9X}", 124)
#assert.eq(s, "Bases (10, 2, 8, 16(l), 16(U):) 124 1111100 174 7c 7C | W/ prefixes and modifiers: 0b1111100 +0o000174 ____+0x7C")

• Picking float precision (right-extending with zeroes): Add, at the end of the format (just before the spec type (such as ?), if there's any), either .precision (hardcoded, e.g. .8 for 8 decimal digits) or .parameter$ (taking the precision value from the specified parameter, like with width):

#import "@preview/oxifmt:0.2.1": strfmt

#let s = strfmt("{0:.8} {0:.2$} {0:.potato$}", 1.234, 0, 2, potato: 5)
#assert.eq(s, "1.23400000 1.23 1.23400")

• Scientific notation: Use e (lowercase) or E (uppercase) as specifier types (can be combined with precision):

#import "@preview/oxifmt:0.2.1": strfmt

#let s = strfmt("{0:e} {0:E} {0:+.9e} | {1:e} | {2:.4E}", 124.2312, 50, -0.02)
#assert.eq(s, "1.242312e2 1.242312E2 +1.242312000e2 | 5e1 | -2.0000E-2")

• Customizing the decimal separator on floats: Just specify fmt-decimal-separator: "," (comma as an example):

#import "@preview/oxifmt:0.2.1": strfmt

#let s = strfmt("{0} {0:.6} {0:.5e}", 1.432, fmt-decimal-separator: ",")
#assert.eq(s, "1,432 1,432000 1,43200e0")

Grammar

Here's the grammar specification for valid format specs (in {name:spec}), which is basically Rust's format:

format_spec := [[fill]align][sign]['#']['0'][width]['.' precision]type
fill := character
align := '<' | '^' | '>'
sign := '+' | '-'
width := count
precision := count | '*'
type := '' | '?' | 'x?' | 'X?' | identifier
count := parameter | integer
parameter := argument '$'

Note, however, that precision of type .* is not supported yet and will raise an error.

Issues and Contributing

Please report any issues or send any contributions (through pull requests) to the repository at https://github.com/PgBiel/typst-oxifmt

Testing

If you wish to contribute, you may clone the repository and test this package with the following commands (from the project root folder):

git clone https://github.com/PgBiel/typst-oxifmt
cd typst-oxifmt/tests
typst c strfmt-tests.typ --root ..

The tests succeeded if you received no error messages from the last command (please ensure you're using a supported Typst version).

Changelog

v0.2.1

• Fixed formatting of UTF-8 strings. Before, strings with multi-byte UTF-8 codepoints would cause formatting inconsistencies or even crashes. (Issue #6)
• Fixed an inconsistency in negative number formatting. Now, it will always print a regular hyphen (e.g. '-2'), which is consistent with Rust's behavior; before, it would occasionally print a minus sign instead (as observed in a comment to Issue #4).
• Added compatibility with Typst 0.8.0's new type system.

v0.2.0

• The package's name is now oxifmt!
• oxifmt:0.2.0 is now available through Typst's Package Manager! You can now write #import "@preview/oxifmt:0.2.0": strfmt to use the library.
• Greatly improved the README, adding a section for common examples.
• Fixed negative numbers being formatted with two minus signs.
• Fixed custom precision of floats not working when they are exact integers.

v0.1.0

• Initial release, added strfmt.

License

Licensed under MIT or Apache-2.0, at your option.