rich_micro/
lib.rs

1//! Micro assets for rs-rich (#565): emoji-sized inline images and
2//! animations, written `Deploying :micro:rocket:`.
3//!
4//! Not a port of anything upstream: an rs-rich addition, outside core. Core
5//! is unchanged: `:micro:name:` is not an emoji code, so it passes through
6//! core untouched, and every seam here goes through core's public API (style
7//! metadata, [`Renderable`](rich::Renderable)) or rs-rich-ext's.
8//!
9//! - [`MicroAsset`]: a name, a kind, a size in cells (2×1 by default, up
10//!   to 4×2: 1 to 4 columns, 1 or 2 rows), images, mandatory alt text, an
11//!   emoji or text fallback, and where it came from.
12//! - [`package`]: `.richmicro` packages and packs, read under hard
13//!   [`Limits`].
14//! - [`MicroRegistry`]: built-in < user < trusted project < inline, with
15//!   aliases, collisions and [`explain`](MicroRegistry::explain).
16//! - [`markup`]: `:micro:name:` in markup and text, and in Markdown
17//!   ([`PreparedMarkdown`]); [`MicroExt`] and [`MicroAssetRef`] in code.
18//! - [`render`]: the placeholder representation, and the [`MicroRenderer`]
19//!   seam that terminal graphics plug into.
20//! - [`rows`]: assets two rows high (a 2×2 icon, a 3×2 animation):
21//!   [`MicroRows`] reserves the row below the line each one sits on, in
22//!   wrapped text, table cells and panels.
23//! - [`graphics`]: drawing on a terminal: [`select`] picks Kitty, iTerm2,
24//!   Sixel, half-blocks or the text fallback, and [`MicroGraphics`] draws
25//!   with it, in printed output and through the graphics side channel of
26//!   `rich-ext`'s live regions and the interactive painter.
27//! - [`cache`]: decoded images fitted to their cells, cached in memory and
28//!   on disk.
29//! - [`pipeline`]: any picture or animation to an asset's images: fitted,
30//!   adjusted, sharpened, with its transparency decided; [`create`] writes
31//!   the package.
32//! - [`builtin`]: the built-in library (status, dev and fun sets), drawn for
33//!   this project; [`MicroRegistry::builtin`] loads it.
34//!
35//! ```
36//! use rich::Console;
37//! use rich_micro::{render_markup, FallbackPreference, Layer, MicroAsset, MicroRegistry};
38//!
39//! let mut registry = MicroRegistry::new();
40//! registry.add(Layer::Inline, MicroAsset::new("ship", "rocket")?.with_emoji("🚀")?)?;
41//! let console = Console::builder().width(40).build();
42//! let (text, diagnostics) =
43//!     render_markup(&console, "Deploying :micro:ship: :fire:", &registry, FallbackPreference::Emoji);
44//! assert_eq!(text.plain(), "Deploying 🚀 🔥");
45//! assert!(diagnostics.is_empty());
46//! # Ok::<(), rich_micro::MicroError>(())
47//! ```
48
49// A builder method that returns `Self` is `#[must_use]`: dropping its
50// result drops the value (CONTRIBUTING.md, "API conventions").
51#![warn(clippy::return_self_not_must_use)]
52
53pub mod api;
54pub mod builtin;
55pub mod cache;
56pub mod create;
57pub mod error;
58pub mod graphics;
59pub mod image;
60pub mod markup;
61pub mod model;
62pub mod name;
63pub mod package;
64pub mod pipeline;
65pub mod registry;
66pub mod render;
67pub mod rows;
68
69pub use api::{MicroAssetRef, MicroExt, MicroPlugin};
70pub use cache::{ImageCache, Prepared};
71pub use error::MicroError;
72pub use graphics::{MicroGraphics, MicroMode, Selection, select};
73pub use markup::{
74    Diagnostic, DiagnosticKind, MarkdownView, MicroTransform, PreparedMarkdown, PreparedMarkup,
75    expand, markup_text, render_markup,
76};
77pub use model::{
78    AssetKind, CellSize, Fallback, ImageFormat, ImageInfo, ImageRef, Layer, MicroAsset, Origin,
79    PackageLocation, Variants,
80};
81pub use name::is_valid_name;
82pub use package::{Limits, Pack};
83pub use registry::{Collision, LoadReport, MicroRegistry, MicroRoots, Rejected};
84pub use render::{
85    FallbackPreference, FallbackRenderer, MICRO_META_KEY, MicroMeta, MicroRenderer, MicroView,
86    PAD_CELL, Placement, fallback_cells, fallback_row, placeholder,
87};
88/// The size of a terminal cell in pixels, as the cache and pipeline take it.
89pub use rich_art::graphics::CellPixels;
90pub use rows::{MicroRows, reserve_rows};
rich_micro/lib.rs

rich_micro/
lib.rs
