Struct Text 

pub struct Text { /* private fields */ }

Styled text. Mirrors rich.text.Text.

Implementations

impl Text

pub fn new(plain: impl Into<String>) -> Self

Plain, unstyled text.

pub fn styled(plain: impl Into<String>, style: impl Into<StyleType>) -> Self

Text with a base style, which may be a style name resolved at render time (Text::styled("hi", "repr.number")) or a resolved Style.

pub fn justify(self, justify: Justify) -> Self

Set how lines are justified within the render width (builder form).

pub fn set_justify(&mut self, justify: Justify)

Set how lines are justified within the render width.

Justify::Default means unset here (upstream’s justify=None), deferring to the console options; use set_justify_option for an explicit justify="default".

pub fn get_justify(&self) -> Justify

This text’s own justify method (Justify::Default when unset).

pub fn set_justify_option(&mut self, justify: Option<Justify>)

Set this text’s justify, distinguishing an explicit Some(Justify::Default) (upstream’s justify="default", which a table column’s or the print call’s justify does not override) from None (upstream’s justify=None, which defers to them).

pub fn get_justify_option(&self) -> Option<Justify>

This text’s own justify, None when unset. See set_justify_option.

pub fn overflow(self, overflow: Overflow) -> Self

Set what happens to lines wider than the render width (builder form).

pub fn set_overflow(&mut self, overflow: Option<Overflow>)

Set what happens to lines wider than the render width. Pass None to defer to the console options.

pub fn get_overflow(&self) -> Option<Overflow>

This text’s own overflow method, if it set one.

pub fn no_wrap(self, no_wrap: bool) -> Self

Disable (or re-enable) wrapping for this text (builder form).

pub fn set_no_wrap(&mut self, no_wrap: Option<bool>)

Disable (or re-enable) wrapping. Pass None to defer to the console options.

pub fn get_no_wrap(&self) -> Option<bool>

This text’s own no-wrap setting, if it set one.

pub fn tab_size(self, tab_size: usize) -> Self

Set the tab stop width (builder form). Port of Text(tab_size=…).

pub fn set_tab_size(&mut self, tab_size: Option<usize>)

Set the tab stop width. Pass None to defer to the console’s tab_size. Upstream’s Text.tab_size attribute.

pub fn get_tab_size(&self) -> Option<usize>

This text’s own tab stop width, if it set one.

pub fn truncate( &mut self, max_width: usize, overflow: Option<Overflow>, pad: bool, )

Shorten this text to at most max_width cells, optionally padding it out to exactly max_width when it is shorter. Port of Text.truncate.

overflow defaults to this text’s own method, then to Overflow::Fold; Overflow::Ignore leaves the text alone entirely. Note that Fold and Crop behave identically here — folding is a property of wrapping, and a line that has already been wrapped can only be cut.

pub fn blank_copy(&self) -> Text

An empty Text carrying this one’s style, justify, overflow and no-wrap. Port of Text.blank_copy.

pub fn divide(&self, offsets: &[usize]) -> Vec<Text>

Cut this text at each byte offset in offsets, returning the pieces. Port of Text.divide.

Every piece inherits the base style, justify, overflow and no-wrap, and each span is re-based onto the pieces it covers. Spans that would come out empty are dropped, matching upstream’s new_end > new_start.

Offsets are byte offsets (as everywhere else in this port’s span arithmetic) and must fall on char boundaries.

pub fn split( &self, separator: &str, include_separator: bool, allow_blank: bool, ) -> Vec<Text>

Split on separator. Port of Text.split.

include_separator keeps the separator at the end of each piece. allow_blank keeps the trailing empty piece that a text ending in the separator would otherwise produce.

Panics

If separator is empty, which upstream asserts against.

pub fn pad(&mut self, count: usize, character: char)

Pad both sides with count copies of character. Port of Text.pad.

pub fn pad_left(&mut self, count: usize, character: char)

Pad the left with count copies of character, shifting every span to follow the text. Port of Text.pad_left.

pub fn pad_right(&mut self, count: usize, character: char)

Pad the right with count copies of character. Port of Text.pad_right. Spans are untouched, so the padding is unstyled.

pub fn right_crop(&mut self, amount: usize)

Drop the last amount bytes, clipping any span that reached into them. Port of Text.right_crop.

pub fn rstrip(&mut self)

Remove trailing whitespace. Port of Text.rstrip.

pub fn rstrip_end(&mut self, size: usize)

Remove only as much trailing whitespace as it takes to get down to size characters, leaving the rest. Port of Text.rstrip_end.

This is what lets a wrapped line keep the space that ended it while a line that overshot the width gives its padding back. As upstream, the length is len(self) — characters, not cells.

pub fn expand_tabs(&mut self, tab_size: usize)

pub fn join(&self, lines: &[Text]) -> Text

Join lines with this text as the separator, carrying each piece’s base style across as a covering span. Port of Text.join.

pub fn from_ansi(text: &str, style: impl Into<StyleType>) -> Text

A Text from a string containing ANSI escape codes, one decoded line per line joined by newlines, with base style. Port of Text.from_ansi (its tab_size defaults to 8; set justify, overflow and no_wrap with the builders).

pub fn detect_indentation(&self) -> usize

The indentation unit of the text: the greatest common divisor of its even line indents, or 1. Port of Text.detect_indentation.

pub fn with_indent_guides( &self, indent_size: Option<usize>, character: &str, style: impl Into<StyleType>, ) -> Text

A copy with indent guides drawn in each line’s leading spaces: every indent_size spaces (auto-detected for None) become character then padding, styled style. Port of Text.with_indent_guides (upstream’s defaults are "│" and "dim green").

pub fn highlight_words( &mut self, words: &[&str], style: impl Into<StyleType>, case_sensitive: bool, ) -> Result<usize>

Style every occurrence of any of words. Port of Text.highlight_words, returning the number of matches.

pub fn highlight_regex( &mut self, pattern: &str, style: Option<StyleType>, style_prefix: &str, ) -> Result<usize>

Style every match of pattern, returning the number of matches. Full port of Text.highlight_regex.

style, when given, styles the whole match. Each named group is then styled with {style_prefix}{name} as a style name, left for the theme to resolve at render time — which is how a highlighter colours its groups without ever seeing a console.

Groups that did not participate in the match, and zero-width ones, are skipped.

pub fn from_markup(markup_text: &str) -> Result<Text>

Build styled text from console markup. Port of Text.from_markup.

Tag names are stored on the spans and resolved when the text is rendered, so no theme is needed here.

pub fn plain(&self) -> &str

The unstyled string content.

pub fn spans(&self) -> &[Span]

The spans currently applied.

pub fn cell_len(&self) -> usize

Length in terminal cells.

pub fn is_empty(&self) -> bool

True when there is no content.

pub fn append(&mut self, text: &str, style: Option<StyleType>)

Append more text, optionally under style (a resolved Style or a style name).

pub fn append_text(self, other: &Text) -> Text

Append another Text, carrying over its base style (as a covering span) and all of its spans, shifted to their new offsets. Port of Text.append_text. Consumes self and returns it for chaining.

pub fn stylize(&mut self, style: impl Into<StyleType>, start: usize, end: usize)

Apply style to the byte range [start, end). Port of Text.stylize, including its argument order.

style may be a resolved Style or a name ("repr.number") left for the renderer to look up. Byte offsets, not char offsets; ASCII-only callers such as highlighters are unaffected by the distinction.

A range that is empty or inverted is ignored, which is what gives us upstream’s end > start skip for non-participating regex groups.

pub fn stylize_before( &mut self, style: impl Into<StyleType>, start: usize, end: usize, )

As stylize, but the span goes first, beneath every existing span. Port of Text.stylize_before.

pub fn apply_meta(&mut self, meta: Meta, start: usize, end: Option<usize>)

Apply metadata to the byte range start..end (the rest of the text when end is None). Port of Text.apply_meta: a span of Style.from_meta(meta), which an empty map (a null style) skips.

pub fn on( &mut self, meta: Option<Meta>, handlers: &[(&str, MetaValue)], ) -> &mut Self

Apply event-handler metadata to the whole text. Port of Text.on: handlers are stored as "@name" keys over meta.

pub fn push_span(&mut self, span: Span)

Append a raw span, as upstream’s text.spans.append(span) does: no clamping and no falsy-style check.

Offsets are byte offsets into plain and must fall on char boundaries (upstream’s are character offsets; convert first). A span may extend past the end of the text, as upstream allows.

pub fn spans_mut(&mut self) -> &mut Vec<Span>

The spans, mutably. Upstream’s Text.spans is a public, mutable list; the same byte-offset rules as push_span apply.

pub fn set_spans(&mut self, spans: Vec<Span>)

Replace every span. Port of the Text.spans setter.

pub fn base_style(&self) -> &StyleType

The whole-text base style, resolved or named. Port of the Text.style attribute.

pub fn set_base_style(&mut self, style: impl Into<StyleType>)

Set the whole-text base style, resolved or named.

pub fn render(&self, theme: &Theme, base_style: &Style) -> Vec<Segment>

Flatten into non-overlapping segments (newlines become Segment::line), combining base_style, this text’s base style, and every covering span. Does not wrap. Port of the core of Text.render.

Named span styles are resolved against theme.

pub fn measurement(&self) -> (usize, usize)

The (minimum, maximum) cell width of this text: maximum is the widest hard line, minimum the widest word. Port of Text.__rich_measure__.

pub fn render_lines( &self, theme: &Theme, base_style: &Style, width: Option<usize>, ) -> Vec<Vec<Segment>>

Render into visual lines, wrapping each hard line to width cells when Some, and justifying per this text’s own justify.

pub fn render_lines_justified( &self, theme: &Theme, base_style: &Style, width: Option<usize>, justify: Justify, ) -> Vec<Vec<Segment>>

Like render_lines but with an explicit justify (used by the console to apply options.justify).

pub fn render_lines_wrapped( &self, theme: &Theme, base_style: &Style, width: Option<usize>, justify: Justify, overflow: Overflow, no_wrap: bool, ) -> Vec<Vec<Segment>>

The full wrap-justify-truncate pipeline, with every knob resolved by the caller. Port of Text.wrap.

Lines are split on \n, wrapped to width (folding over-long words only when overflow is Overflow::Fold), justified, and finally truncated to width. Overflow::Ignore skips wrapping and truncation both, so lines may come back wider than width.

Tabs expand to this text’s own tab_size, else DEFAULT_TAB_SIZE; render_lines_wrapped_tabs takes the width explicitly (upstream’s wrap(tab_size=…)).

pub fn console_tab_size(&self, console: &Console) -> usize

The tab stop width Text.__rich_console__ wraps with on console: this text’s own, else the console’s, and 8 for zero (tab_size or 8).

pub fn render_lines_wrapped_tabs( &self, theme: &Theme, base_style: &Style, width: Option<usize>, justify: Justify, overflow: Overflow, no_wrap: bool, tab_size: usize, ) -> Vec<Vec<Segment>>

render_lines_wrapped with an explicit tab stop width. Port of Text.wrap(…, tab_size=…).

pub fn render_joined_wrapped( &self, theme: &Theme, base_style: &Style, width: usize, justify: Justify, overflow: Overflow, no_wrap: bool, ) -> Vec<Segment>

As render_lines_wrapped, flattened into a single segment stream with Segment::line between visual lines.

pub fn render_joined_wrapped_tabs( &self, theme: &Theme, base_style: &Style, width: usize, justify: Justify, overflow: Overflow, no_wrap: bool, tab_size: usize, ) -> Vec<Segment>

render_joined_wrapped with an explicit tab stop width (see console_tab_size).

Trait Implementations

impl Clone for Text

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Text

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

Formats the value using the given formatter.

impl Default for Text

fn default() -> Self

Returns the “default value” for a type.

impl From<Text> for Cell

fn from(text: Text) -> Self

Converts to this type from the input type.

impl Renderable for Text

fn rich_render( &self, console: &Console, options: &ConsoleOptions, ) -> Vec<Segment>

fn measure(&self, _console: &Console, options: &ConsoleOptions) -> Measurement

The (minimum, maximum) cell width this renderable wants. The default assumes the renderable fills the available width (e.g. Panel, Table); Text overrides it with its content width so the top-level print path can shrink to fit. Port of __rich_measure__ / Measurement.get.

fn fit_to_measurement(&self) -> bool

Whether a top-level Console::print shrinks this renderable to its measured width. Upstream renders every top-level renderable at the full console width, so the default is false; an extension may opt in.

fn vertical(&self) -> Option<VerticalAlign>

The vertical alignment a Table cell holding this renderable uses in place of its column’s. Upstream reads getattr(renderable, "vertical", None); Align sets it.