Module stdout_formatter

This module is the entry point to format structured text.

Copyright © 2018-2019 Pivotal Software, Inc.

Authors: The RabbitMQ team.

Description

This module is the entry point to format structured text.

Which function to use

There are three "levels of formatting":
  1. format/1 returns an internal structure where the text is already formatted but not ready for display: it is mostly used internally.
  2. to_string/1 formats the given argument and returns a string ready to be displayed or stored.
  3. display/1 does the same thing as to_string/1 but displays the result on stdout directly (and returns nothing).

Examples

To automatically wrap a paragraph to fit it in 30 columns and display it:

  -include_lib("stdout_formatter/include/stdout_formatter.hrl").
 
  stdout_formatter:display(
    #paragraph{
      content = "This module is the entry point to format structured text.",
      props = #{wrap_at => 30}}).
  This module is the entry
  point to format structured
  text.

To format a table and display it:

  -include_lib("stdout_formatter/include/stdout_formatter.hrl").
 
  stdout_formatter:display(
    #table{
      rows = [["Top left", "Top right"], ["Bottom left", "Bottom right"]],
      props = #{}}).
  ┌───────────┬────────────┐
  │Top left   │Top right   │
  ├───────────┼────────────┤
  │Bottom left│Bottom right│
  └───────────┴────────────┘

Data Types

border_drawing()

border_drawing() = ansi | ascii | none

The line drawing technic.

border_style()

border_style() = thin

The style of borders.

cell()

cell() = #cell{}

A cell in a table row.

See table/0.

cell_props()

cell_props() = #{title => boolean(), inherited => map()}

Cell properties.

The properties are:

color()

color() = color_8palette() | color_256palette() | true_color()

A color name, index or value.

color_256palette()

color_256palette() = byte()

Color index in the ANSI 256-color palette.

color_8palette()

color_8palette() = black | red | green | yellow | blue | magenta | cyan | white | bright_black | bright_red | bright_green | bright_yellow | bright_blue | bright_magenta | bright_cyan | bright_white | 0..15

Color name (atom) or index in the ANSI escape sequence color palette.

content_if_reformat()

content_if_reformat() = [{unicode:chardata(), non_neg_integer()} | {color_start, string(), string()} | {color_end, string(), string()}] | derived_from_previous_sibling | false

formattable()

formattable() = paragraph() | table() | formatted_block() | term()

formatted_block()

formatted_block() = #formatted_block{}

A formatted block.

It is the result of the format/1 and format/2 functions. It contains a list of formatted_line/0.

formatted_block_props()

formatted_block_props() = #{width := non_neg_integer(), height := non_neg_integer()}

Formatted block properties.

The properties are:

formatted_line()

formatted_line() = #formatted_line{}

A formatted line.

formatted_line_props()

formatted_line_props() = #{width := non_neg_integer(), reformat_ok := content_if_reformat()}

Formatted line properties.

The properties are:

paragraph()

paragraph() = #paragraph{}

A paragraph of text to format.

The content can be a string or any Erlang term. The format string can be specified as a property (See paragraph_props/0). If it is missing, it will be guessed from the Erlang term.

paragraph_props()

paragraph_props() = #{format => string() | none | subterm, wrap_at => pos_integer() | false, bold => boolean(), fg => color() | none, bg => color() | none, inherited => map()}

Paragraph properties.

The properties are:

row()

row() = #row{}

A row in a table.

See table/0.

row_props()

row_props() = #{title => boolean(), title_repeat => pos_integer() | false, inherited => map()}

Row properties.

The properties are:

table()

table() = #table{}

A table to format.

It is made of a list of rows. Each row is either a row/0 or a list of cells. Each cell is either a cell/0 or a formattable/0.

table_props()

table_props() = #{border_drawing => border_drawing(), border_style => border_style(), inherited => map()}

Table properties.

The properties are:

true_color()

true_color() = {Red::byte(), Green::byte(), Blue::byte()}

Three-byte tuple corresponding to RGB 24-bit channel values.

Function Index

display/1Formats a term and displays it on stdout.
display/2Formats a term and displays it on stdout.
format/1 Formats a term and returns a formatted_block/0.
format/2 Formats a term and returns a formatted_block/0.
to_string/1Formats a term and returns a string.
to_string/2Formats a term and returns a string.

Function Details

display/1

display(Term::formattable()) -> ok

Term: Term to format and display.

Formats a term and displays it on stdout.

display/2

display(Formatted_block::formattable(), InheritedProps::map()) -> ok

InheritedProps: Inherited properties map.

Formats a term and displays it on stdout.

It will use the specified inherited properties.

format/1

format(Term::formattable()) -> formatted_block()

Term: Term to format.

returns: A formatted_block/0.

Formats a term and returns a formatted_block/0.

format/2

format(Table::formattable(), InheritedProps::map()) -> formatted_block()

InheritedProps: Inherited properties map.

returns: A formatted_block/0.

Formats a term and returns a formatted_block/0.

It will use the specified inherited properties.

to_string/1

to_string(Term::formattable()) -> unicode:chardata()

Term: Term to format as a string.

returns: A string of the formatted term.

Formats a term and returns a string.

to_string/2

to_string(Formatted_block::formattable(), InheritedProps::map()) -> unicode:chardata()

InheritedProps: Inherited properties map.

returns: A string of the formatted term.

Formats a term and returns a string.

It will use the specified inherited properties.


Generated by EDoc