stdout_formatter: Format paragraphs and tables for a human-readable text output

stdout_formatter is a pure Erlang application which allows an application to format paragraphs and tables as text, usually to display it on a terminal. It only depends on standard Erlang/OTP applications; no external dependency is required. It doesn't use native code either (neither port drivers nor NIFs).

stdout_formatter can be used inside Elixir projects, like any other Erlang library. You can find an example later in this README.

stdout_formatter is distributed under the terms of both the Apache License v2 and Mozilla Public Licence v1.1; see LICENSE.

Integrate to your project

stdout_formatter uses Rebar 3 as its build system so it can be integrated to many common build systems.

Rebar

stdout_formatter is available as a Hex.pm package. Thus you can simply list it as a package dependency in your rebar.config:

{deps, [stdout_formatter]}.

Erlang.mk

Erlang.mk knows about stdout_formatter. You just need to add stdout_formatter as a dependency in your Makefile:

DEPS = stdout_formatter
dep_stdout_formatter = git https://github.com/rabbitmq/stdout_formatter.git v0.1.0

Mix

You can use stdout_formatter in your Elixir project. stdout_formatter is available as a Hex.pm package. Thus you can simply list its name in your mix.exs:

def project do
  [
    deps: [{:stdout_formatter, "~> 0.1.0"}]
  ]
end

Getting started

Format and display a paragraph of text

In this example, we want to format a long paragraph of text to fit it in an 80-columns terminal and display it directly.

-include_lib("stdout_formatter/include/stdout_formatter.hrl").

Text = "Lorem ipsum dolor (...) est laborum.",

stdout_formatter:display(
  #paragraph{
    content = Text
    props = #{wrap_at => 72}}).

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea
commodo consequat. Duis aute irure dolor in reprehenderit in voluptate
velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint
occaecat cupidatat non proident, sunt in culpa qui officia deserunt
mollit anim id est laborum.

Format and display a simple table

In this example, we want to format a table and display it directly.

-include_lib("stdout_formatter/include/stdout_formatter.hrl").

Data = [
         ["Top left", "Top right"],
         ["Bottom left", "Bottom right"]
       ],

stdout_formatter:display(
  #table{
    rows = Data}).

┌───────────┬────────────┐
│Top left   │Top right   │
├───────────┼────────────┤
│Bottom left│Bottom right│
└───────────┴────────────┘

Format and display a complex table with paragraphs inside

In this example, we mix the previous examples to put a paragraph inside a table and we start to use colors.

-include_lib("stdout_formatter/include/stdout_formatter.hrl").

Text = "Lorem ipsum dolor (...) est laborum.",

Data = [
         #row{
           cells = [
             "Initial data",
             "Result"],
           props = #{title => true}},
         #row{
           cells = [
             "The famous Lorem Ipsum sample",
             #paragraph{
               content = Text,
               props = #{wrap_at => 40}}]}
       ],

stdout_formatter:display(
  #table{
    rows = Data}).

┌─────────────────────────────┬───────────────────────────────────────┐
│Initial data                 │Result                                 │
├─────────────────────────────┼───────────────────────────────────────┤
│The famous Lorem Ipsum sample│Lorem ipsum dolor sit amet, consectetur│
│                             │adipiscing elit, sed do eiusmod tempor │
│                             │incididunt ut labore et dolore magna   │
│                             │aliqua. Ut enim ad minim veniam, quis  │
│                             │nostrud exercitation ullamco laboris   │
│                             │nisi ut aliquip ex ea commodo          │
│                             │consequat. Duis aute irure dolor in    │
│                             │reprehenderit in voluptate velit esse  │
│                             │cillum dolore eu fugiat nulla pariatur.│
│                             │Excepteur sint occaecat cupidatat non  │
│                             │proident, sunt in culpa qui officia    │
│                             │deserunt mollit anim id est laborum.   │
└─────────────────────────────┴───────────────────────────────────────┘

In the example above, what does not appear is the fact the the first row is using bold text.