From 3a979e88da7be6240821ba8acfdd376b7f4e0f09 Mon Sep 17 00:00:00 2001 From: Laurenz Date: Mon, 11 Sep 2023 15:53:20 +0200 Subject: Docs generation for types --- docs/reference/scripting.md | 90 +++++++++++++++++++++++++-------------------- 1 file changed, 50 insertions(+), 40 deletions(-) (limited to 'docs/reference/scripting.md') diff --git a/docs/reference/scripting.md b/docs/reference/scripting.md index 72d2bb9a..29448c72 100644 --- a/docs/reference/scripting.md +++ b/docs/reference/scripting.md @@ -7,7 +7,7 @@ Typst embeds a powerful scripting language. You can automate your documents and create more sophisticated styles with code. Below is an overview over the scripting concepts. -## Expressions { #expressions } +## Expressions In Typst, markup and code are fused into one. All but the most common elements are created with _functions._ To make this as convenient as possible, Typst provides compact syntax to embed a code expression into markup: An expression is @@ -23,14 +23,13 @@ be interpreted as text, the expression can forcibly be ended with a semicolon ``` The example above shows a few of the available expressions, including -[function calls]($type/function), -[field accesses]($scripting/#fields), and +[function calls]($function), [field accesses]($scripting/#fields), and [method calls]($scripting/#methods). More kinds of expressions are discussed in the remainder of this chapter. A few kinds of expressions are not compatible with the hashtag syntax (e.g. binary operator expressions). To embed these into markup, you can use parentheses, as in `[#(1 + 2)]`. -## Blocks { #blocks } +## Blocks To structure your code and embed markup into it, Typst provides two kinds of _blocks:_ @@ -45,9 +44,9 @@ _blocks:_ - **Content block:** `{[*Hey* there!]}` \ With content blocks, you can handle markup/content as a programmatic value, - store it in variables and pass it to [functions]($type/function). Content + store it in variables and pass it to [functions]($function). Content blocks are delimited by square brackets and can contain arbitrary markup. A - content block results in a value of type [content]($type/content). An + content block results in a value of type [content]($content). An arbitrary number of content blocks can be passed as trailing arguments to functions. That is, `{list([A], [B])}` is equivalent to `{list[A][B]}`. @@ -69,7 +68,7 @@ As already demonstrated above, variables can be defined with `{let}` bindings. The variable is assigned the value of the expression that follows the `=` sign. The assignment of a value is optional, if no value is assigned, the variable will be initialized as `{none}`. The `{let}` keyword can also be used to create -a [custom named function]($type/function/#definitions). Let bindings can be +a [custom named function]($function/#defining-functions). Let bindings can be accessed for the rest of the containing block or document. ```example @@ -81,8 +80,8 @@ It explains #name. Sum is #add(2, 3). ``` -Let bindings can also be used to destructure [arrays]($type/array) and -[dictionaries]($type/dictionary). In this case, the left-hand side of the +Let bindings can also be used to destructure [arrays]($array) and +[dictionaries]($dictionary). In this case, the left-hand side of the assignment should mirror an array or dictionary. The `..` operator can be used once in the pattern to collect the remainder of the array's or dictionary's items. @@ -142,7 +141,7 @@ swap variables among other things. } ``` -## Conditionals { #conditionals } +## Conditionals With a conditional, you can display or compute different things depending on whether some condition is fulfilled. Typst supports `{if}`, `{else if}` and `{else}` expression. When the condition evaluates to `{true}`, the conditional @@ -164,7 +163,7 @@ Each branch can have a code or content block as its body. - `{if condition [..] else {..}}` - `{if condition [..] else if condition {..} else [..]}` -## Loops { #loops } +## Loops With loops, you can repeat content or compute something iteratively. Typst supports two types of loops: `{for}` and `{while}` loops. The former iterate over a specified collection whereas the latter iterate as long as a condition @@ -190,18 +189,18 @@ together into one larger array. For loops can iterate over a variety of collections: - `{for letter in "abc" {..}}` \ - Iterates over the characters of the [string]($type/string). + Iterates over the characters of the [string]($str). (Technically, iterates over the grapheme clusters of the string. Most of the time, a grapheme cluster is just a single character/codepoint. However, some constructs like flag emojis that consist of multiple codepoints are still only one cluster.) - `{for value in array {..}}` \ - Iterates over the items in the [array]($type/array). The destructuring syntax + Iterates over the items in the [array]($array). The destructuring syntax described in [Let binding]($scripting/#bindings) can also be used here. - `{for pair in dict {..}}` \ - Iterates over the key-value pairs of the [dictionary]($type/dictionary). + Iterates over the key-value pairs of the [dictionary]($dictionary). The pairs can also be destructured by using `{for (key, value) in dict {..}}`. To control the execution of the loop, Typst provides the `{break}` and @@ -225,16 +224,16 @@ The body of a loop can be a code or content block: - `{while condition {..}}` - `{while condition [..]}` -## Fields { #fields } +## Fields You can use _dot notation_ to access fields on a value. The value in question can be either: -- a [dictionary]($type/dictionary) that has the specified key, -- a [symbol]($type/symbol) that has the specified modifier, -- a [module]($type/module) containing the specified definition, -- [content]($type/content) consisting of an element that has the specified - field. The available fields match the arguments of the - [element function]($type/function/#element-functions) that were given when - the element was constructed. +- a [dictionary]($dictionary) that has the specified key, +- a [symbol]($symbol) that has the specified modifier, +- a [module]($module) containing the specified definition, +- [content]($content) consisting of an element that has the specified field. The + available fields match the arguments of the + [element function]($function/#element-functions) that were given when the + element was constructed. ```example #let dict = (greet: "Hello") @@ -246,12 +245,20 @@ can be either: #it.level ``` -## Methods { #methods } -A method is a kind of a [function]($type/function) that is tightly coupled with -a specific type. It is called on a value of its type using the same dot notation -that is also used for fields: `{value.method(..)}`. The -[type documentation]($type) lists the available methods for each of the built-in -types. You cannot define your own methods. +## Methods +A _method call_ is a convenient way to call a function that is scoped to a +value's [type]($type). For example, we can call the [`str.len`]($str.len) +function in the following two equivalent ways: + +```example +#str.len("abc") is the same as +#"abc".len() +``` + +The structure of a method call is `{value.method(..args)}` and its equivalent +full function call is `{type(value).method(value, ..args)}`. The documentation +of each type lists it's scoped functions. You cannot currently define your own +methods. ```example #let array = (1, 2, 3, 4) @@ -261,26 +268,29 @@ types. You cannot define your own methods. #("a, b, c" .split(", ") .join[ --- ]) + +#"abc".len() is the same as +#str.len("abc") ``` -Methods are the only functions in Typst that can modify the value they are -called on. In some cases, this means that a method is only called for its side -effect and its return value should be ignored (and not participate in joining). -The canonical way to discard a value is with a let binding: -`{let _ = array.remove(1)}`. +There are a few special functions that modify the value they are called on (e.g. +[`array.push`]($array.push)). These functions _must_ be called in method form. +In some cases, when the method is only called for its side effect, its return +value should be ignored (and not participate in joining). The canonical way to +discard a value is with a let binding: `{let _ = array.remove(1)}`. -## Modules { #modules } +## Modules You can split up your Typst projects into multiple files called _modules._ A module can refer to the content and definitions of another module in multiple ways: - **Including:** `{include "bar.typ"}` \ Evaluates the file at the path `bar.typ` and returns the resulting - [content]($type/content). + [content]($content). - **Import:** `{import "bar.typ"}` \ Evaluates the file at the path `bar.typ` and inserts the resulting - [module]($type/module) into the current scope as `bar` (filename without + [module]($module) into the current scope as `bar` (filename without extension). - **Import items:** `{import "bar.typ": a, b}` \ @@ -289,15 +299,15 @@ ways: bindings) and defines them in the current file. Replacing `a, b` with `*` loads all variables defined in a module. -Instead of a path, you can also use a [module value]($type/module), as shown in -the following example: +Instead of a path, you can also use a [module value]($module), as shown in the +following example: ```example #import emoji: face #face.grin ``` -## Packages { #packages } +## Packages To reuse building blocks across projects, you can also create and import Typst _packages._ A package import is specified as a triple of a namespace, a name, and a version. @@ -316,7 +326,7 @@ If you are using Typst locally, you can also create your own system-local packages. For more details on this, see the [package repository](https://github.com/typst/packages). -## Operators { #operators } +## Operators The following table lists all available unary and binary operators with effect, arity (unary, binary) and precedence level (higher binds stronger). -- cgit v1.2.3