Struct PrettyPrinter 

pub struct PrettyPrinter { /* private fields */ }

The write surface of a pretty-printed document.

See the module docs for the printing model. Obtained from Document::printer — or received, already positioned, by printing code such as a PrettyPrintable implementation. Rejections of the layout protocol (an end_group with no open group) panic, since they indicate a bug in the calling printing code.

Implementations

impl PrettyPrinter

pub fn noop() -> Self

Create a printer that discards everything printed to it.

This is how a PrintableGenerator with one shared drawing body implements its silent path: Generator::do_draw simply calls self.do_draw_and_print(tc, &mut PrettyPrinter::noop()). The contract that both paths consume identical choices then holds by construction. Guard any expensive formatting with should_print so the silent path stays cheap.

pub fn should_print(&self) -> bool

Whether printing to this printer produces output: false for the discarding printer returned by noop. Use it to skip work — formatting a value, say — whose only purpose is to be printed.

pub fn text(&mut self, s: &str)

Emit literal, unbreakable text.

Newlines in s are honored as unconditional line breaks (equivalent to hard_break, so the new line starts at the current indentation).

pub fn breakable(&mut self, sep: &str)

Emit a potential break point: renders as sep if the enclosing group fits on the current line, and as a newline plus the current indentation if the group breaks.

pub fn hard_break(&mut self)

Emit an unconditional newline followed by the current indentation.

pub fn begin_group(&mut self, indent: usize, open: &str)

Open a group: emit open, then increase the indentation applied by subsequent break points by indent (conventionally the width of open, so continuation lines align just inside the delimiter).

pub fn end_group(&mut self, close: &str)

Close the innermost group: undo the indentation its begin_group added, then emit close. Panics if no group is open.

pub fn shift_indent(&mut self, delta: isize)

Adjust the indentation applied by subsequent break points by delta.

pub fn comment(&mut self, text: &str)

Attach a comment to the line currently being written: text is rendered as // text at the end of that line, every group open at this position is forced to break — nothing else may share a line with a comment — and the comment is excluded from line-width accounting. A group forced to break by a comment also breaks before its closing delimiter, so the delimiter is not caught up in a comment on the group’s last element.

text must not contain newlines; a comment is a single-line construct.

pub fn speculate(&mut self) -> Speculation<'_>

Open a speculative region: output printed through the returned Speculation is held back until Speculation::commit emits it or Speculation::abort discards it. Dropping the Speculation without committing (e.g. on unwind) aborts it.

This is how draw-time printing survives rejection: a combinator that may retract a draw — a filter retry, a rejected collection element — prints each attempt inside a speculative region and only commits the accepted one.

Trait Implementations

impl Clone for PrettyPrinter

Cloning a printer opens a child region: a hole in the document, anchored at the printer’s current position, that the clone writes into.

Whatever the clone prints — at any later point, from any thread that owns it — appears at the anchor when the document renders, with line-breaking behaving as if it had been printed inline. This is how output crosses threads deterministically (each clone’s output lands where the clone was made, however the threads were scheduled), and how a generator whose value’s representation is only known during test execution (a Hegel-controlled random number generator, say) prints: it clones the printer at draw time and records into the clone as the value is used.

A child region dies when the document renders, or when a speculative region its anchor sat inside is aborted; a dead region’s writes are silent no-ops, so a clone that outlives its document can keep trying to record without consequence. Cloning a no-op printer yields a no-op printer, and cloning into a dead region yields a printer whose writes discard.

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 PrettyPrinter

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

Formats the value using the given formatter.