Struct Args

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

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

pub fn to_pos(&self) -> Array

Returns the captured positional arguments as an array.

pub fn to_named(&self) -> Dict

Returns the captured named arguments as a dictionary.

Trait Implementations

impl Add for Args

type Output = Args

The resulting type after applying the + operator.

fn add(self, rhs: Args) -> <Args as Add>::Output

Performs the + operation.

impl Clone for Args

fn clone(&self) -> Args

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Args

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl FromValue for Args

fn from_value(value: Value) -> Result<Args, HintedString>

Try to cast the value into an instance of Self.

impl Hash for Args

fn hash<__H>(&self, state: &mut __H)

where __H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl IntoArgs for Args

fn into_args(self, fallback: Span) -> Args

Convert into arguments, attaching the fallback span in case Self doesn’t have a span.

impl IntoValue for Args

fn into_value(self) -> Value

Cast this type into a value.

impl NativeScope for Args

fn constructor() -> Option<&'static NativeFuncData>

The constructor function for the type, if any.

fn scope() -> Scope

Get the associated scope for the type.

impl NativeType for Args

const NAME: &'static str = "arguments"

The type’s name.

fn data() -> &'static NativeTypeData

fn ty() -> Type

Get the type for the native Rust type.

impl PartialEq for Args

fn eq(&self, other: &Args) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Reflect for Args

fn input() -> CastInfo

Describe what can be cast into this value.

fn output() -> CastInfo

Describe what this value can be cast into.

fn castable(value: &Value) -> bool

Whether the given value can be converted to T.

fn error(found: &Value) -> HintedString

Produce an error message for an unacceptable value type.

impl Repr for Args

fn repr(&self) -> EcoString

Return the debug representation of the value.