#emph[Hello] \\\n#emoji.face \\\n#"hello".len()\n![\"Preview\"](\"/en-US-v0.13.1/assets/56fcebfd54e87e06f0936777ca6c4f31.png\")
Typst embeds a powerful scripting language. You can automate your documents and\ncreate more sophisticated styles with code. Below is an overview over the\nscripting concepts.
\nIn Typst, markup and code are fused into one. All but the most common elements\nare created with functions. To make this as convenient as possible, Typst\nprovides compact syntax to embed a code expression into markup: An expression is\nintroduced with a hash (#) and normal markup parsing resumes after the\nexpression is finished. If a character would continue the expression but should\nbe interpreted as text, the expression can forcibly be ended with a semicolon\n(;).
#emph[Hello] \\\n#emoji.face \\\n#"hello".len()\nThe example above shows a few of the available expressions, including\nfunction calls, field accesses, and\nmethod calls. More kinds of expressions are\ndiscussed in the remainder of this chapter. A few kinds of expressions are not\ncompatible with the hash syntax (e.g. binary operator expressions). To embed\nthese into markup, you can use parentheses, as in #(1 + 2).
To structure your code and embed markup into it, Typst provides two kinds of\nblocks:
\nCode block: { let x = 1; x + 2 }
\nWhen writing code, you'll probably want to split up your computation into\nmultiple statements, create some intermediate variables and so on. Code blocks\nlet you write multiple expressions where one is expected. The individual\nexpressions in a code block should be separated by line breaks or semicolons.\nThe output values of the individual expressions in a code block are joined to\ndetermine the block's value. Expressions without useful output, like let\nbindings yield none, which can be joined with any value without effect.
Content block: [*Hey* there!]
\nWith content blocks, you can handle markup/content as a programmatic value,\nstore it in variables and pass it to functions. Content\nblocks are delimited by square brackets and can contain arbitrary markup. A\ncontent block results in a value of type content. An arbitrary number of\ncontent blocks can be passed as trailing arguments to functions. That is,\nlist([A], [B]) is equivalent to list[A][B].
Content and code blocks can be nested arbitrarily. In the example below,\n[hello ] is joined with the output of a + [ the ] + b yielding\n[hello from the *world*].
#{\n let a = [from]\n let b = [*world*]\n [hello ]\n a + [ the ] + b\n}\n![\"Preview\"](\"/en-US-v0.13.1/assets/f5f1a59a923ddd7899e3844457f683a1.png\")
As already demonstrated above, variables can be defined with let bindings.\nThe variable is assigned the value of the expression that follows the = sign.\nThe assignment of a value is optional, if no value is assigned, the variable\nwill be initialized as none. The let keyword can also be used to create\na custom named function. Variables can be\naccessed for the rest of the containing block (or the rest of the file if there\nis no containing block).
#let name = "Typst"\nThis is #name's documentation.\nIt explains #name.\n\n#let add(x, y) = x + y\nSum is #add(2, 3).\n![\"Preview\"](\"/en-US-v0.13.1/assets/cab2fd22fe9abd4d4b827c1bc30aee2f.png\")
Let bindings can also be used to destructure arrays and\ndictionaries. In this case, the left-hand side of the\nassignment should mirror an array or dictionary. The .. operator can be used\nonce in the pattern to collect the remainder of the array's or dictionary's\nitems.
#let (x, y) = (1, 2)\nThe coordinates are #x, #y.\n\n#let (a, .., b) = (1, 2, 3, 4)\nThe first element is #a.\nThe last element is #b.\n\n#let books = (\n Shakespeare: "Hamlet",\n Homer: "The Odyssey",\n Austen: "Persuasion",\n)\n\n#let (Austen,) = books\nAusten wrote #Austen.\n\n#let (Homer: h) = books\nHomer wrote #h.\n\n#let (Homer, ..other) = books\n#for (author, title) in other [\n #author wrote #title.\n]\n![\"Preview\"](\"/en-US-v0.13.1/assets/574a8a54d94246e011156a58bb988f10.png\")
You can use the underscore to discard elements in a destructuring pattern:
\n#let (_, y, _) = (1, 2, 3)\nThe y coordinate is #y.\n![\"Preview\"](\"/en-US-v0.13.1/assets/2d320f557a31c13c47827649626f615e.png\")
Destructuring also works in argument lists of functions ...
\n#let left = (2, 4, 5)\n#let right = (3, 2, 6)\n#left.zip(right).map(\n ((a,b)) => a + b\n)\n![\"Preview\"](\"/en-US-v0.13.1/assets/eb451d0a1cf36461e8a56ce203acf067.png\")
... and on the left-hand side of normal assignments. This can be useful to\nswap variables among other things.
\n#{\n let a = 1\n let b = 2\n (a, b) = (b, a)\n [a = #a, b = #b]\n}\n![\"Preview\"](\"/en-US-v0.13.1/assets/2c2bcc6a2509a95daa0bc4e986ee7e6d.png\")
With a conditional, you can display or compute different things depending on\nwhether some condition is fulfilled. Typst supports if, else if and\nelse expressions. When the condition evaluates to true, the conditional\nyields the value resulting from the if's body, otherwise yields the value\nresulting from the else's body.
#if 1 < 2 [\n This is shown\n] else [\n This is not.\n]\n![\"Preview\"](\"/en-US-v0.13.1/assets/9f03dfe97f385ab1a6d01127a9152c4d.png\")
Each branch can have a code or content block as its body.
\nif condition {..}if condition [..]if condition [..] else {..}if condition [..] else if condition {..} else [..]With loops, you can repeat content or compute something iteratively. Typst\nsupports two types of loops: for and while loops. The former iterate\nover a specified collection whereas the latter iterate as long as a condition\nstays fulfilled. Just like blocks, loops join the results from each iteration\ninto one value.
In the example below, the three sentences created by the for loop join together\ninto a single content value and the length-1 arrays in the while loop join\ntogether into one larger array.
\n#for c in "ABC" [\n #c is a letter.\n]\n\n#let n = 2\n#while n < 10 {\n n = (n * 2) - 1\n (n,)\n}\n![\"Preview\"](\"/en-US-v0.13.1/assets/ef87ec09b6f156465a2deb8f2ca4620b.png\")
For loops can iterate over a variety of collections:
\nfor value in array {..}
\nIterates over the items in the array. The destructuring syntax described in\nLet binding can also be used here.
for pair in dict {..}
\nIterates over the key-value pairs of the dictionary. The pairs can also be\ndestructured by using for (key, value) in dict {..}. It is more efficient\nthan for pair in dict.pairs() {..} because it doesn't create a temporary\narray of all key-value pairs.
for letter in "abc" {..}
\nIterates over the characters of the string. Technically, it iterates\nover the grapheme clusters of the string. Most of the time, a grapheme cluster\nis just a single codepoint. However, a grapheme cluster could contain multiple\ncodepoints, like a flag emoji.
for byte in bytes("😀") {..}
\nIterates over the bytes, which can be converted from a string or\nread from a file without encoding. Each byte value is an integer\nbetween 0 and 255.
To control the execution of the loop, Typst provides the break and\ncontinue statements. The former performs an early exit from the loop while\nthe latter skips ahead to the next iteration of the loop.
#for letter in "abc nope" {\n if letter == " " {\n break\n }\n\n letter\n}\n![\"Preview\"](\"/en-US-v0.13.1/assets/8ba145cb687a39c8f9146abd55f943f9.png\")
The body of a loop can be a code or content block:
\nfor .. in collection {..}for .. in collection [..]while condition {..}while condition [..]You can use dot notation to access fields on a value. For values of type\ncontent, you can also use the fields function to list\nthe fields.
The value in question can be either:
\n#let it = [= Heading]\n#it.body \\\n#it.depth \\\n#it.fields()\n\n#let dict = (greet: "Hello")\n#dict.greet \\\n#emoji.face\n\n![\"Preview\"](\"/en-US-v0.13.1/assets/e560cf75c003b55ee615a91fba54908a.png\")
A method call is a convenient way to call a function that is scoped to a\nvalue's type. For example, we can call the str.len function in\nthe following two equivalent ways:
#str.len("abc") is the same as\n#"abc".len()\n![\"Preview\"](\"/en-US-v0.13.1/assets/8fc9134962ea2ca6f8f3beaa1a77c940.png\")
The structure of a method call is value.method(..args) and its equivalent\nfull function call is type(value).method(value, ..args). The documentation\nof each type lists its scoped functions. You cannot currently define your own\nmethods.
#let values = (1, 2, 3, 4)\n#values.pop() \\\n#values.len() \\\n\n#("a, b, c"\n .split(", ")\n .join[ --- ])\n\n#"abc".len() is the same as\n#str.len("abc")\n![\"Preview\"](\"/en-US-v0.13.1/assets/69c81d74d21d4e212b8bdde97b02c949.png\")
There are a few special functions that modify the value they are called on (e.g.\narray.push). These functions must be called in method form.\nIn some cases, when the method is only called for its side effect, its return\nvalue should be ignored (and not participate in joining). The canonical way to\ndiscard a value is with a let binding: let _ = array.remove(1).
You can split up your Typst projects into multiple files called modules. A\nmodule can refer to the content and definitions of another module in multiple\nways:
\nIncluding: include "bar.typ"
\nEvaluates the file at the path bar.typ and returns the resulting content.
Import: import "bar.typ"
\nEvaluates the file at the path bar.typ and inserts the resulting module\ninto the current scope as bar (filename without extension). You can use the\nas keyword to rename the imported module: import "bar.typ" as baz. You\ncan import nested items using dot notation: import "bar.typ": baz.a.
Import items: import "bar.typ": a, b
\nEvaluates the file at the path bar.typ, extracts the values of the variables\na and b (that need to be defined in bar.typ, e.g. through let\nbindings) and defines them in the current file. Replacing a, b with *\nloads all variables defined in a module. You can use the as keyword to\nrename the individual items: import "bar.typ": a as one, b as two
Instead of a path, you can also use a module value, as shown in the\nfollowing example:
\n#import emoji: face\n#face.grin\n![\"Preview\"](\"/en-US-v0.13.1/assets/9c38d95483bccbf7479a82427087ab2a.png\")
To reuse building blocks across projects, you can also create and import Typst\npackages. A package import is specified as a triple of a namespace, a name,\nand a version.
\n#import "@preview/example:0.1.0": add\n#add(2, 7)\n![\"Preview\"](\"/en-US-v0.13.1/assets/3d994560e3517e38057aec147c441de6.png\")
The preview namespace contains packages shared by the community. You can find\nall available community packages on Typst Universe.
If you are using Typst locally, you can also create your own system-local\npackages. For more details on this, see the\npackage repository.
\nThe following table lists all available unary and binary operators with effect,\narity (unary, binary) and precedence level (higher binds stronger). Some\noperations, such as modulus, do not have a special syntax\nand can be achieved using functions from the\ncalc module.
| Operator | Effect | Arity | Precedence |
|---|---|---|---|
- | Negation | Unary | 7 |
+ | No effect (exists for symmetry) | Unary | 7 |
* | Multiplication | Binary | 6 |
/ | Division | Binary | 6 |
+ | Addition | Binary | 5 |
- | Subtraction | Binary | 5 |
== | Check equality | Binary | 4 |
!= | Check inequality | Binary | 4 |
< | Check less-than | Binary | 4 |
<= | Check less-than or equal | Binary | 4 |
> | Check greater-than | Binary | 4 |
>= | Check greater-than or equal | Binary | 4 |
in | Check if in collection | Binary | 4 |
not in | Check if not in collection | Binary | 4 |
not | Logical "not" | Unary | 3 |
and | Short-circuiting logical "and" | Binary | 3 |
or | Short-circuiting logical "or" | Binary | 2 |
= | Assignment | Binary | 1 |
+= | Add-Assignment | Binary | 1 |
-= | Subtraction-Assignment | Binary | 1 |
*= | Multiplication-Assignment | Binary | 1 |
/= | Division-Assignment | Binary | 1 |