Struct Args

pub struct Args {
    pub span: Span,
    pub items: EcoVec<Arg>,
}

Expand description

Captured arguments to a function.

§Argument Sinks

Like built-in functions, custom functions can also take a variable number of arguments. You can specify an argument sink which collects all excess arguments as ..sink. The resulting sink value is of the arguments type. It exposes methods to access the positional and named arguments.

#let format(title, ..authors) = {
  let by = authors
    .pos()
    .join(", ", last: " and ")

  [*#title* \ _Written by #by;_]
}

#format("ArtosFlow", "Jane", "Joe")

§Spreading

Inversely to an argument sink, you can spread arguments, arrays and dictionaries into a function call with the ..spread operator:

#let array = (2, 3, 5)
#calc.min(..array)
#let dict = (fill: blue)
#text(..dict)[Hello]

Fields§

§span: Span

The callsite span for the function. This is not the span of the argument list itself, but of the whole function call.

§items: EcoVec<Arg>

The positional and named arguments.

Implementations§

§

impl Args

pub fn new<T>(span: Span, values: impl IntoIterator<Item = T>) -> Args
where T: IntoValue,

Create positional arguments from a span and values.

pub fn spanned(self, span: Span) -> Args

Attach a span to these arguments if they don’t already have one.

pub fn remaining(&self) -> usize

Returns the number of remaining positional arguments.

pub fn insert(&mut self, index: usize, span: Span, value: Value)

Insert a positional argument at a specific index.

pub fn push(&mut self, span: Span, value: Value)

Push a positional argument.

pub fn eat<T>(&mut self) -> Result<Option<T>, EcoVec<SourceDiagnostic>>
where T: FromValue<Spanned<Value>>,

Consume and cast the first positional argument if there is one.

pub fn consume( &mut self, n: usize, ) -> Result<Vec<Arg>, EcoVec<SourceDiagnostic>>

Consume n positional arguments if possible.

pub fn expect<T>(&mut self, what: &str) -> Result<T, EcoVec<SourceDiagnostic>>
where T: FromValue<Spanned<Value>>,

Consume and cast the first positional argument.

Returns a missing argument: {what} error if no positional argument is left.

pub fn find<T>(&mut self) -> Result<Option<T>, EcoVec<SourceDiagnostic>>
where T: FromValue<Spanned<Value>>,

Find and consume the first castable positional argument.

pub fn all<T>(&mut self) -> Result<Vec<T>, EcoVec<SourceDiagnostic>>
where T: FromValue<Spanned<Value>>,

Find and consume all castable positional arguments.

pub fn named<T>( &mut self, name: &str, ) -> Result<Option<T>, EcoVec<SourceDiagnostic>>
where T: FromValue<Spanned<Value>>,

Cast and remove the value for the given named argument, returning an error if the conversion fails.

pub fn named_or_find<T>( &mut self, name: &str, ) -> Result<Option<T>, EcoVec<SourceDiagnostic>>
where T: FromValue<Spanned<Value>>,

Same as named, but with fallback to find.

pub fn take(&mut self) -> Args

Take out all arguments into a new instance.

pub fn finish(self) -> Result<(), EcoVec<SourceDiagnostic>>

Return an “unexpected argument” error if there is any remaining argument.

§

impl Args

pub fn construct(args: &mut Args) -> Args

Construct spreadable arguments in place.

This function behaves like {let args(..sink) = sink}.

#let args = arguments(stroke: red, inset: 1em, [Body])
#box(..args)

pub fn at( &self, key: ArgumentKey, default: Option<Value>, ) -> Result<Value, EcoString>

Returns the positional argument at the specified index, or the named argument with the specified name.

If the key is an integer, this is equivalent to first calling pos and then [array.at]. If it is a string, this is equivalent to first calling named and then [dictionary.at].