How to use content given as a function argument?

Questions
1

Hi,

I’m quite new to typst and I started reading the documentation.

There is a point which is not clear for me.

There are functions which accept content as argument, while not being inside the parentheses, like from the text documentation:

text documentation example

text(blue)[
  With a function call.
]

while the function signature is

text(
...
features: arraydictionary,
body: content,
str,
) -> content

Second example from the tutorial

#let amazed(term) = box[✨ #term ✨]

is used as You are #amazed[beautiful]!

What is not clear for me

What I understand is that I can provide content to function while not being given … as a usual argument.

I wonder in which case I can make this, e.g.

#let citation(title, attribution: none, content) = {
  heading(title)
  quote(attribution: attribution, content)
}

being used as

#citation("my title")[my content]

throws me an error.

And, consider a function myshow(content1, content2), could it be used as myshow[my first content][my second content]?

Thanks for the help!

2

I tried your code and it works perfectly for me?

I also tried your second suggestion with success :slight_smile:

#let f(content1, content2) = [#content1 ; #content2 !]

#f("Hello", "world")

#f("Hello")[world]

#f[Hello][World]

In other words, all positional arguments of type content can be given via [] after the function call, they’re used in the order they’re given.

3

Ok, then this is not very clear for me.
This is very hard for me to find info about:

  • how to define the argument types,
  • how to define optional arguments,
  • how to define defaults,
  • how to document it properly.

Do you have a link? I did not find the documentation very clear for that…

4

I completely agree that this is not clear at all, right now.

Documentation

There does not seem to be official support for integrated documentation (docstring) at the moment, though tinymist does its best to interpret comments starting with /// as such: see Code Documentation - Tinymist Docs
There seems to be some agreement that once HTML output is supported, the syntax should approximately follow what’s being supported by current doc-generator project tidy.

Typing

Typst is dynamically typed so nothing about type hint (yet) though I think tinymist detects if your function starts with some assert(type(body) == content).

The documentation may indicate what types are acceptable for each argument, see tidy examples.

Arguments

By checking the arguments and function documentation, you can gather that there are exactly two kinds of arguments : required positionals and optional named arguments with a default value. Note that the named argument can be given in any position, there is no requirement for them to all be after or before the positionals.

If there is a [] argument, this will provide the value of the last non-provisioned positional argument (even if it should not be of type content, thus crashing with a type error), you can use several [] as long as the corresponding positional arguments are not already given (and content is acceptable). This is why the content argument is usually the last positional in most functions.

2 Likes
5

Small addition to an otherwise comprehensive post:

If you define a function with an argument sink, the number of trailing [] arguments can be endless.

#let my-func(..bodies) = {
  bodies.pos().join(", ", last: ", and ")
}

#my-func[a]

#my-func[a][b][c][d][e][f][g]

image

Re-reading it, I think the quoted text actually covers this case but I guess it’s worth stating it explicitly.

1 Like