Overview

Module stdout_formatter

• Description
• Data Types
• Function Index
• Function Details

Description

This module is the entry point to format structured text.

Which function to use

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.

• ansi: borders are drawn with ANSI escape sequences.
• ascii: borders are drawn with US-ASCII characters.
• none: no border drawn.

border_style()

border_style() = thin

The style of borders.

cell()

cell() = #cell{}

A cell in a table row.

cell_props()

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

Cell properties.

• title: true if the cells is a title (i.e. content is bold).

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.

formatted_block_props()

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

Formatted block properties.

• width: Number of columns of the widest line.
• height: Number of lines.

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.

• width: Number of columns of the line.
• reformat_ok: Content used to reformat the line if relevant, e.g. to rewrap a paragraph.

padding()

padding() = padding_value() | {padding_value(), padding_value()} | {padding_value(), padding_value(), padding_value(), padding_value()}

The number of columns/lines of horizontal/vertical padding.

padding_value()

padding_value() = non_neg_integer()

paragraph()

paragraph() = #paragraph{}

A paragraph of text to format.

paragraph_props()

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

Paragraph properties.

• format: the format string to present the content.
• wrap_at: the number of columns after which the lines are wrapped.
• bold: true if the content must be dispalyed as bold characters.
• fg: the color to use as foreground.
• bg: the color to use as background.

row()

row() = #row{}

A row in a table.

row_props()

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

Row properties.

• title: true if cells are all title cells.
• title_repeat: whether to repeat the title rows and how often. [NOT IMPLEMENTED]

table()

table() = #table{}

A table to format.

table_props()

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

Table properties.

• border_drawing: the type of line drawing to use.
• border_style: the style of borders.

true_color()

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

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

Function Index

Function Details

display/1

Formats a term and displays it on stdout.

display/2

Formats 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/1

Formats a term and returns a string.

to_string/2

Formats a term and returns a string.

Overview

Generated by EDoc