Struct Syntax 

pub struct Syntax { /* private fields */ }

A block of syntax-highlighted source code. Mirrors rich.syntax.Syntax.

The highlighting engine is the one given to highlighter, else the console’s default (ConsoleCodeHighlighting), else syntect with the syntax feature. A build with only the code feature has no engine of its own, so a Syntax with neither renders as plain code in the same layout:

use rich::{Console, Syntax};

let console = Console::builder().width(12).color_system(None).build();
let out = console.render_to_string(&Syntax::new("SELECT 1", "sql").padding(1));
assert!(out.contains(" SELECT 1"));

Implementations

impl Syntax

pub fn word_wrap(self, wrap: bool) -> Self

Wrap lines wider than the render width instead of cropping them.

Off by default, matching upstream’s Syntax(word_wrap=False): a long line is cut at the width. Upstream’s CLI turns this on, which is why rich --syntax does too — cropping a source file silently loses code.

pub fn new(code: impl Into<String>, language: impl Into<String>) -> Self

Highlight code as language (a name or file extension, e.g. "rust" or "rs"). Pass an empty/unknown language to render as plain text.

pub fn highlighter(self, highlighter: Arc<dyn CodeHighlighter>) -> Self

Highlight with highlighter instead of the console’s default or the built-in engine (SyntectHighlighter with the syntax feature, plain code without it). Theme names are the highlighter’s own.

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

How far a tab advances the column, in characters. Upstream’s Syntax(tab_size=…), default 4.

Tabs are expanded to spaces before highlighting (upstream’s code.expandtabs(self.tab_size)), so this is the only tab handling in play — the rendered code contains no U+0009 at all.

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

Strip the leading whitespace common to every line before highlighting (upstream dedent, default off), as textwrap.dedent does.

pub fn from_path(path: impl AsRef<Path>, lexer: Option<&str>) -> Result<Self>

A Syntax for the file at path, read as UTF-8, highlighted as lexer, or as guess_lexer guesses from the path. Port of Syntax.from_path (its other options are this type’s builders; only UTF-8 is read, where upstream takes an encoding).

pub fn guess_lexer(path: impl AsRef<Path>) -> String

The lexer for a path: its extension, lower-cased, or its file name when it has none (Makefile), else "default". Port of Syntax.guess_lexer, whose answer is a Pygments alias; here it is the name the code highlighter looks the grammar up by.

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

Surround the code with padding cells of background on every side.

Upstream’s Markdown renders a fenced block as Syntax(..., padding=1), which is what gives a code block its blank inset row above and below and its one-column gutter. Without it the code sat flush against the surrounding text and every document containing a fence diverged.

pub fn padding_sides(self, padding: (usize, usize, usize, usize)) -> Self

Padding on each side, (top, right, bottom, left), in the code background (upstream padding as a tuple).

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

Number the lines in a gutter (upstream line_numbers, default off).

pub fn start_line(self, start_line: i64) -> Self

The number of the first line (upstream start_line, default 1). Any integer, as upstream’s: zero and negative numbers are drawn as they are.

pub fn line_range(self, start: Option<i64>, end: Option<i64>) -> Self

Render only lines start..=end (1-based; None leaves that end open). Upstream line_range, with its Python semantics: a start of 0 or less is the first line, and a negative end counts back from the last line (lines[start - 1:end]) after the highlighter has stopped at the first line it reached.

pub fn highlight_lines(self, lines: impl IntoIterator<Item = i64>) -> Self

Mark these line numbers with a pointer in the gutter (upstream highlight_lines; shown with line_numbers).

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

A fixed width for the code, excluding line numbers (upstream code_width; default all the available width).

pub fn background_color(self, color: impl Into<String>) -> Self

Override the theme’s background colour (upstream background_color).

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

Draw indent guides (upstream indent_guides, default off; not on an ASCII-only console).

pub fn stylize_range( &mut self, style: impl Into<StyleType>, start: SyntaxPosition, end: SyntaxPosition, style_before: bool, ) -> &mut Self

Style a range of the code, from start to end ((line, column), 1-based lines, 0-based columns), on top of the highlighting — or beneath it with style_before. Port of Syntax.stylize_range.

pub fn theme(self, theme: impl Into<String>) -> Self

Choose the highlighting theme, by the highlighter’s name for it. The default highlighter offers syntect’s themes plus upstream’s ansi_dark and ansi_light. Unknown names fall back to the highlighter’s default theme.

impl Syntax

pub fn highlight(&self) -> Text

Highlight the code into a Text rather than a padded block. Port of Syntax.highlight: the theme background is the text’s base style and every token carries its own style. Tabs are expanded first, as _process_code does. Used by Markdown(inline_code_lexer=…).

pub fn highlight_for(&self, console: &Console) -> Text

highlight with console’s default code highlighter (see ConsoleCodeHighlighting) when this Syntax has none of its own. Not in upstream.

pub fn highlight_range( &self, line_range: Option<(Option<i64>, Option<i64>)>, console: Option<&Console>, ) -> Text

Port of Syntax.highlight(code, line_range) over this Syntax’s code: the highlighted Text in the base style (the theme’s background and background_color), with upstream’s justify, tab_size and no_wrap. With a line_range, lines before it are left unstyled and lines after it dropped. console supplies a default code highlighter, as in highlight_for.

Trait Implementations

impl Renderable for Syntax

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

Port of Syntax.__rich_measure__. Like upstream it measures the raw source, where a tab counts as zero cells.

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

Port of Syntax.__rich_console__: the lines, inside Padding in the code’s base style when there is any padding.

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.

fn print_end_line(&self, _options: &ConsoleOptions) -> bool

Whether a top-level print ends this renderable’s last line. This port’s renderables separate lines, where upstream’s end each line with "\n", so a print adds the final line break. A renderable whose upstream output stops without one (Screen, LiveRender, a Rule whose end has no newline) returns false, and the next output continues its last line. options are the print’s options.