Console report composer

include/console/report.h View source View on GitHub

Compose a report as a stream of lines, all statically allocated with no locks taken, primarily useful for panicking

Structs

report_line

struct report_line (8 fields)

Build a line into a caller supplied buffer, counting display columns

max_col bounds layout and cap bounds buffer, and partial writes are not allowed, and overflow uses ellipsis

§ char *buf

§ size_t cap

§ size_t len

bytes used

§ size_t col

display columns used

§ size_t max_col

display column bound/budget

§ size_t glyph_at

byte offset of the last visible glyph

§ bool full

budget exhausted

§ bool truncated

something was cut somewhere on this line

report_target

struct report_target (5 fields)

Where a finished line actually goes and how wide it is, either the console or the pane of a buffered region

col means a display column, a pane is the vertical panel

§ struct report_panes *panes

NULL means the console/a box

§ struct report_box *box

non-NULL = lines come out bordered

§ uint16_t width

display columns

§ uint8_t indent

§ uint8_t pane

which pane of panes

report_box

struct report_box (2 fields)

A box, such as

┌─ title ─────────────┐
│ this is my box data │
└─────────────────────┘

§ struct report_target target

§ uint16_t inner

content columns, i.e. everything but borders and padding

report_fields

struct report_fields (7 fields)

packs kv pairs, as many per row as target is wide, flushing as it fills, holding a line writer pointing into its storage

§ struct report_target target

§ uint8_t per_row

§ uint8_t in_row

§ uint8_t keyw

§ uint8_t valw

§ struct report_line line

§ char storage[REPORT_LINE_MAX]

report_panes

struct report_panes (10 fields)

Vertical panels side by side, only 2D thing here, and the only buffered one

Panes can’t stream, and lines are stored per-pane and interleaved at flush

This is statically allocated

§ uint8_t n

§ uint16_t width[REPORT_PANES_MAX]

§ const char *title[REPORT_PANES_MAX]

§ uint8_t title_sev[REPORT_PANES_MAX]

§ uint16_t nrows[REPORT_PANES_MAX]

§ uint32_t dropped[REPORT_PANES_MAX]

§ bool stacked

too narrow to sit side by side

§ bool undivided

no vertical rule

§ char text[REPORT_PANES_MAX][REPORT_PANE_ROWS][REPORT_PANE_LINE_MAX]

§ bool rule[REPORT_PANES_MAX][REPORT_PANE_ROWS]

Which rows are rules

Functions

report_line_init

void report_line_init(
    struct report_line *l,
    char *buf,
    size_t cap,
    size_t max_col
)

report_line_reset

void report_line_reset(struct report_line *l)

report_line_puts

void report_line_puts(struct report_line *l, const char *s)

report_line_printf

void report_line_printf(struct report_line *l, const char *fmt)

report_line_pad_to

void report_line_pad_to(struct report_line *l, size_t col)

Spaces out to a display column

report_line_repeat

void report_line_repeat(
    struct report_line *l,
    const char *glyph,
    size_t n
)

report_line_field

void report_line_field(
    struct report_line *l,
    const char *s,
    size_t width
)

take up exactly width display columns, and truncate if too long/pad if too short

report_line_right

void report_line_right(struct report_line *l, const char *s)

report_line_str

const char * report_line_str(const struct report_line *l)

report_line_width

size_t report_line_width(const struct report_line *l)

report_line_truncated

bool report_line_truncated(const struct report_line *l)

report_strwidth

size_t report_strwidth(const char *s)

Display columns a string would occupy

report_console

struct report_target report_console(void)

report_console_indent

struct report_target report_console_indent(uint16_t indent)

report_pane

struct report_target report_pane(
    struct report_panes *panes,
    uint32_t pane
)

report_target_indent

struct report_target report_target_indent(
    struct report_target tgt,
    uint16_t indent
)

Nesting indentation supported

report_target_width

uint16_t report_target_width(const struct report_target *tgt)

report_puts

void report_puts(struct report_target *tgt, const char *s)

Emit a line, don’t pass ‘\n’

report_printf

void report_printf(struct report_target *tgt, const char *fmt)

report_blank

void report_blank(struct report_target *tgt)

report_line_emit

void report_line_emit(
    struct report_target *tgt,
    struct report_line *l
)

report_rule

void report_rule(struct report_target *tgt, const char *title)

--- TITLE ---- , to the target’s width

report_rule_sev

void report_rule_sev(
    struct report_target *tgt,
    enum term_sev sev,
    const char *title
)

report_wrap

void report_wrap(struct report_target *tgt, const char *text)

Word wrap to tgt’s width, emitting however many lines it takes

Break at spaces, honor newlines, count display columns

report_wrap_printf

void report_wrap_printf(struct report_target *tgt, const char *fmt)

report_box_open

void report_box_open(
    struct report_box *b,
    struct report_target target,
    const char *title,
    uint16_t inner
)

inner == 0 fills target, size with report_strwidth(), when the box should hug rather than span the terminal, content wraps

report_box_printf

void report_box_printf(struct report_box *b, const char *fmt)

This wraps, different from all the other _printf functions here

report_box_body

struct report_target report_box_body(struct report_box *b)

A target whose lines get bordered, so anything that draws to a target works in a box, its width is the box’s inner width

report_box_close

void report_box_close(struct report_box *b)

report_section_begin

bool report_section_begin(const char *name)

Gives a header to a region we’re inside of it, with faults being recorded to avoid nested panics breaking the report

report_section_begin_at

bool report_section_begin_at(
    struct report_target *tgt,
    const char *name
)

report_section_claim

bool report_section_claim(const char *name)

No heading emitted, for callers that already have drawn one

report_section_claim_at

bool report_section_claim_at(
    struct report_target *tgt,
    const char *name
)

report_section_end

void report_section_end(void)

report_section_current

const char * report_section_current(void)

report_fields_begin

void report_fields_begin(
    struct report_fields *g,
    struct report_target target,
    uint32_t keyw,
    uint32_t valw
)

report_field

void report_field(
    struct report_fields *g,
    const char *key,
    const char *fmt
)

report_field_full

void report_field_full(
    struct report_fields *g,
    const char *key,
    const char *fmt
)

End row and take the full line, for values carrying annotations too long

report_fields_end

void report_fields_end(struct report_fields *g)

report_panes_begin

void report_panes_begin(
    struct report_panes *panes,
    uint32_t n,
    const uint8_t *weights
)

weights == NULL is even split

report_panes_undivided

void report_panes_undivided(struct report_panes *panes)

Remove the vertical rule between panes, leaving only the gap

report_panes_title

void report_panes_title(
    struct report_panes *panes,
    uint32_t pane,
    enum term_sev sev,
    const char *title
)

Heading for a pane, drawn as a segment of the pane’s opening rule

report_panes_top

void report_panes_top(struct report_panes *panes)

Framing rules with dividers:

-- text -----+--- more ------
...
-- data -----+---------------

The opening rule is segmented, and closing rule can double as a title

report_panes_bottom

void report_panes_bottom(
    struct report_panes *panes,
    enum term_sev sev,
    const char *title
)

report_panes_carry

void report_panes_carry(struct report_panes *panes)

Hand this region’s divider positions to next opening rule, so one rule can close the region above and open one below, such as

-----------+------

— text ---+------

Call after flushing and before begin() changes widths, consumed by the next report_panes_top()

report_panes_flush

void report_panes_flush(struct report_panes *panes)

Below REPORT_PANE_MIN_WIDTH, the panes stack vertically

report_pane_rows

uint16_t report_pane_rows(
    const struct report_panes *panes,
    uint32_t pane
)

report_panes_rows_max

uint16_t report_panes_rows_max(const struct report_panes *panes)

report_panes_panic

struct report_panes * report_panes_panic(void)

Reserved for panic paths, so callers don’t need to own the storage, regions get used one at a time with begin() resetting it

report_enter_panic

void report_enter_panic(void)

Enter panic report path, so writes are lock free and the screen is given back, used in panic handler and tracks nested panics

Macros

REPORT_LINE_MAX

#define REPORT_LINE_MAX 1024

Bytes for a composed line. Full width rules of box drawing glyphs cost three bytes a column, so we use this to bound terminal width

REPORT_LINE

#define REPORT_LINE(name, width)

Expansion

#define REPORT_LINE(name, width) \
    char name##_storage[REPORT_LINE_MAX]; \
    struct report_line name; \
    report_line_init(&name, name##_storage, sizeof(name##_storage), (width))

REPORT_FIELD_GAP

#define REPORT_FIELD_GAP 2

REPORT_PANES_MAX

#define REPORT_PANES_MAX UINT32_C(3)

Storage is MAX * LINES * BYTES

REPORT_PANE_ROWS

#define REPORT_PANE_ROWS 96

Max rows for a pane

Bytes stored per line

REPORT_PANE_LINE_MAX

#define REPORT_PANE_LINE_MAX 384

REPORT_PANE_MIN_WIDTH

#define REPORT_PANE_MIN_WIDTH 24

REPORT_PANE_GAP

#define REPORT_PANE_GAP 3