Struct Content

pub struct Content { /* private fields */ }

A piece of document content.

This type is at the heart of Typst. All markup you write and most functions you call produce content values. You can create a content value by enclosing markup in square brackets. This is also how you pass content to functions.

Example

Type of *Hello!* is
#type([*Hello!*])

Content can be added with the + operator, joined together and multiplied with integers. Wherever content is expected, you can also pass a string or {none}.

Representation

Content consists of elements with fields. When constructing an element with its element function, you provide these fields as arguments and when you have a content value, you can access its fields with field access syntax.

Some fields are required: These must be provided when constructing an element and as a consequence, they are always available through field access on content of that type. Required fields are marked as such in the documentation.

Most fields are optional: Like required fields, they can be passed to the element function to configure them for a single element. However, these can also be configured with set rules to apply them to all elements within a scope. Optional fields are only available with field access syntax when they were explicitly passed to the element function, not when they result from a set rule.

Each element has a default appearance. However, you can also completely customize its appearance with a show rule. The show rule is passed the element. It can access the element’s field and produce arbitrary content from it.

In the web app, you can hover over a content variable to see exactly which elements the content is composed of and what fields they have. Alternatively, you can inspect the output of the [repr] function.

Implementations

impl Content

pub fn new<T: NativeElement>(elem: T) -> Self

Creates a new content from an element.

pub fn empty() -> Self

Creates a empty sequence content.

pub fn elem(&self) -> Element

Get the element of this content.

pub fn span(&self) -> Span

Get the span of the content.

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

Set the span of the content.

pub fn label(&self) -> Option<Label>

Get the label of the content.

pub fn labelled(self, label: Label) -> Self

Attach a label to the content.

pub fn set_label(&mut self, label: Label)

Set the label of the content.

pub fn located(self, loc: Location) -> Self

Assigns a location to the content.

This identifies the content and e.g. makes it linkable by .linked(Destination::Location(loc)).

Useful in combination with Location::variant.

pub fn set_location(&mut self, location: Location)

Set the location of the content.

pub fn is_guarded(&self, index: RecipeIndex) -> bool

Check whether a show rule recipe is disabled.

pub fn guarded(self, index: RecipeIndex) -> Self

Disable a show rule recipe.

pub fn is_prepared(&self) -> bool

Whether this content has already been prepared.

pub fn mark_prepared(&mut self)

Mark this content as prepared.

pub fn get( &self, id: u8, styles: Option<StyleChain<'_>>, ) -> Result<Value, FieldAccessError>

Get a field by ID.

This is the preferred way to access fields. However, you can only use it if you have set the field IDs yourself or are using the field IDs generated by the #[elem] macro.

pub fn get_by_name(&self, name: &str) -> Result<Value, FieldAccessError>

Get a field by name.

If you have access to the field IDs of the element, use Self::get instead.

pub fn field(&self, id: u8) -> StrResult<Value>

Get a field by ID, returning a missing field error if it does not exist.

This is the preferred way to access fields. However, you can only use it if you have set the field IDs yourself or are using the field IDs generated by the #[elem] macro.

pub fn field_by_name(&self, name: &str) -> StrResult<Value>

Get a field by name, returning a missing field error if it does not exist.

If you have access to the field IDs of the element, use Self::field instead.

pub fn materialize(&mut self, styles: StyleChain<'_>)

Resolve all fields with the styles and save them in-place.

pub fn sequence(iter: impl IntoIterator<Item = Self>) -> Self

Create a new sequence element from multiples elements.

pub fn is<T: NativeElement>(&self) -> bool

Whether the contained element is of type T.

pub fn to_packed<T: NativeElement>(&self) -> Option<&Packed<T>>

Downcasts the element to a packed value.

pub fn to_packed_mut<T: NativeElement>(&mut self) -> Option<&mut Packed<T>>

Downcasts the element to a mutable packed value.

pub fn into_packed<T: NativeElement>(self) -> Result<Packed<T>, Self>

Downcasts the element into an owned packed value.

pub fn unpack<T: NativeElement>(self) -> Result<T, Self>

Extract the raw underlying element.

pub fn can<C>(&self) -> bool

where C: ?Sized + 'static,

Whether the contained element has the given capability.

pub fn with<C>(&self) -> Option<&C>

where C: ?Sized + 'static,

Cast to a trait object if the contained element has the given capability.

pub fn with_mut<C>(&mut self) -> Option<&mut C>

where C: ?Sized + 'static,

Cast to a mutable trait object if the contained element has the given capability.

pub fn is_empty(&self) -> bool

Whether the content is an empty sequence.

pub fn sequence_recursive_for_each<'a>(&'a self, f: &mut impl FnMut(&'a Self))

Also auto expands sequence of sequences into flat sequence

pub fn styled_with_recipe( self, engine: &mut Engine<'_>, context: Tracked<'_, Context<'_>>, recipe: Recipe, ) -> SourceResult<Self>

Style this content with a recipe, eagerly applying it if possible.

pub fn repeat(&self, count: usize) -> Self

Repeat this content count times.

pub fn styled(self, style: impl Into<Style>) -> Self

Style this content with a style entry.

pub fn styled_with_map(self, styles: Styles) -> Self

Style this content with a full style map.

pub fn style_in_place(&mut self, styles: Styles)

Style this content with a full style map in-place.

pub fn query(&self, selector: Selector) -> Vec<Content>

Queries the content tree for all elements that match the given selector.

Elements produced in show rules will not be included in the results.

pub fn query_first(&self, selector: Selector) -> Option<Content>

Queries the content tree for the first element that match the given selector.

Elements produced in show rules will not be included in the results.

pub fn plain_text(&self) -> EcoString

Extracts the plain text of this content.

impl Content

pub fn strong(self) -> Self

Strongly emphasize this content.

pub fn emph(self) -> Self

Emphasize this content.

pub fn underlined(self) -> Self

Underline this content.

pub fn linked(self, dest: Destination) -> Self

Link the content somewhere.

pub fn aligned(self, align: Alignment) -> Self

Set alignments for this content.

pub fn padded(self, padding: Sides<Rel<Length>>) -> Self

Pad this content at the sides.

pub fn moved(self, delta: Axes<Rel<Length>>) -> Self

Transform this content’s contents without affecting layout.

impl Content

pub fn func(&self) -> Element

The content’s element function. This function can be used to create the element contained in this content. It can be used in set and show rules for the element. Can be compared with global functions to check whether you have a specific kind of element.

pub fn has(&self, field: Str) -> bool

Whether the content has the specified field.

pub fn at(&self, field: Str, default: Option<Value>) -> StrResult<Value>

Access the specified field on the content. Returns the default value if the field does not exist or fails with an error if no default value was specified.

pub fn fields(&self) -> Dict

Returns the fields of this content.

#rect(
  width: 10cm,
  height: 10cm,
).fields()

pub fn location(&self) -> Option<Location>

The location of the content. This is only available on content returned by [query] or provided by a show rule, for other content it will be {none}. The resulting location can be used with counters, [state] and queries.

Trait Implementations

impl<'a> Add<&'a Content> for Content

type Output = Content

The resulting type after applying the + operator.

fn add(self, rhs: &'a Self) -> Self::Output

Performs the + operation.

impl Add for Content

type Output = Content

The resulting type after applying the + operator.

fn add(self, rhs: Self) -> Self::Output

Performs the + operation.

impl AddAssign<&Content> for Content

fn add_assign(&mut self, rhs: &Self)

Performs the += operation.

impl AddAssign for Content

fn add_assign(&mut self, rhs: Self)

Performs the += operation.

impl Clone for Content

fn clone(&self) -> Content

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Content

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

Formats the value using the given formatter.

impl Default for Content

fn default() -> Self

Returns the “default value” for a type.

impl From<Content> for GridCell

fn from(value: Content) -> Self

Converts to this type from the input type.

impl From<Content> for TableCell

fn from(value: Content) -> Self

Converts to this type from the input type.

impl<T: NativeElement> From<T> for Content

fn from(value: T) -> Self

Converts to this type from the input type.

impl FromValue for Content

fn from_value(value: Value) -> HintedStrResult<Self>

Try to cast the value into an instance of Self.

impl Hash for Content

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

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 IntoValue for Content

fn into_value(self) -> Value

Cast this type into a value.

impl NativeScope for Content

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 Content

const NAME: &'static str = "content"

The type’s name.

fn data() -> &'static NativeTypeData

fn ty() -> Type

Get the type for the native Rust type.

impl PartialEq for Content

fn eq(&self, other: &Self) -> 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 Content

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 Content

fn repr(&self) -> EcoString

Return the debug representation of the value.

impl Serialize for Content

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl Sum for Content

fn sum<I: Iterator<Item = Self>>(iter: I) -> Self

Takes an iterator and generates Self from the elements by “summing up” the items.

impl TryFrom<Content> for GridChild

type Error = HintedString

The type returned in the event of a conversion error.

fn try_from(value: Content) -> HintedStrResult<Self>

Performs the conversion.

impl TryFrom<Content> for GridItem

type Error = HintedString

The type returned in the event of a conversion error.

fn try_from(value: Content) -> HintedStrResult<Self>

Performs the conversion.

impl TryFrom<Content> for TableChild

type Error = HintedString

The type returned in the event of a conversion error.

fn try_from(value: Content) -> HintedStrResult<Self>

Performs the conversion.

impl TryFrom<Content> for TableItem

type Error = HintedString

The type returned in the event of a conversion error.

fn try_from(value: Content) -> HintedStrResult<Self>

Performs the conversion.