Crate shoebill

Pretty-printer with the following notable points (which may be good or bad depending on what you want) :

(1) Uses a trait Doclike to allow insertion of different string types (and already-allocated docs) inline. IE "a".concat(format!("c"), printer).concat(d, printer) where d is some doc that was previously allocated. "a" gets allocated as a &str, and format!("c") as an owned string automatically.

(2) Allows use of borrowed or owned strings (using Cow<'_, str>) by default

(3) Allows rendering to be done with format/write macros, instead of exclusively to a target string.

(4) Includes macros allowing users to cut down on syntactic noise when composing docs.

(5) Uses an explicit allocator IndexSet for efficiency.

(6) Has explicit support for Rust Object Notation items. The motivating use case for this crate was writing debug implementations for types that have some degree of indirection (like index pointers) keeping them from using the #[derive(Debug)] macro effectively.

Taking the printer as the last argument instead of being the self item both allows for more idiomatic dot composition and plays nicer with the idea that the items of interest are Docs, and the Printer is just a thing we have to eventually tether our docs/text to.

Disclaimer: the Doc pointers use 32-bit integers as their indices. Allocating more than u32::MAX docs to a single Printer will cause a runtime error (via panic). u64 indices might be a feature in the future if anyone actually needs it.

Modules

brackets	Tools for managing bracketing during pretty-printing based.
object
ron	Types for formatting items using Rust Object Notation (the format you see when you debug format Rust items with the {:#?} formatter).

Macros

compose	Macro for allowing more pleasant composition items that implement Doclike using more familiar operators. The infix operators (which are all left-associtive, but allow for grouping w/ parentheses)
concat
concat_w
inter	Intercalate
inter_trailing	Intercalate, adding a trailing sep chracter as well.

Structs

DocPtr
Printer	The actual thing what holds the information used in composing and printing documents. The Cow strings are held in strings, and Holds CowStr elements and Doc elements in separate IndexSets.
Renderable	Renderable is a separate thing so that we can use it with format! and write! style macros. This has two lifetimes so that you can have multiple Renderable structs in one scope as long as their lifetimes don't overlap. If we ONLY had the <'p> lifetime, we wouldn't be able to do something like:
StringPtr

Enums

Doc

The inner document type. Newline gives you the option of specifying an alternate representation (as an Option) in cases where the renderer is in flat mode, where being in flat mode means you've either elected to specifically render something as flat, or you elected to group elements together (as a Group node), and all of the grouped elements will fit onto the current line without exceeding the line width specified for rendering.

StrOrDoc

A tagged union of either a Cow string, or a DocPtr. By using this type in conjuction with the Doclike trait, we get a pretty large amount of code reuse while cutting down on syntax noise since in many cases we can treat string slices, owned strings, and DocPtr items in the exact same way with the only overhead being that of dealing with the enum (IE there are no extra allocations or clones).

Traits

Doclike
HasPrinter

Type Definitions

CowStr	type alias for a Cow<'p, str>
FxIndexSet