IO.ANSI.Table (IO ANSI Table v1.0.14) View Source

Writes data to stdout in a table with borders and colors. Can choose a table style to change the look of the table.

Inspired by the book Programming Elixir by Dave Thomas.

Link to this section Summary

Functions

Sends a request to the table spec server identified by option :spec_name. The server will write data from maps to stdout in a table formatted per its spec and options.

Sends a request to the table spec server identified by option :spec_name. Returns the server's table spec.

Starts a new table spec server process and supervises it. Upon request (see format/2), the server will write data from maps to stdout in a table formatted per headers and options.

Stops a table spec server process normally. It won't be restarted. The table spec server to stop is identified by option :spec_name.

Writes data from maps to stdout in a table formatted per spec and options.

Link to this section Functions

Link to this function

format(maps, options \\ [])

View Source

Specs

format([Access.container()], Keyword.t()) :: :ok

Sends a request to the table spec server identified by option :spec_name. The server will write data from maps to stdout in a table formatted per its spec and options.

Also supports:

  • keywords
  • structs implementing the Access behaviour.

Does not support:

  • nested maps, keywords or structs

See IO.ANSI.Table.Options for a list of all options in this API.

Parameters

  • maps - flat maps/keywords/structs (list)
  • options - up to 6 options (keyword)

Options

  • :async - whether to write the table asynchronously (boolean)
  • :bell - whether to ring the bell (boolean)
  • :count - number of maps to format (integer)
  • :max_width - to cap column widths (non neg integer)
  • :spec_name - to identify the table spec server (string)
  • :style - table style (atom)

Examples

alias IO.ANSI.Table

people = [
  %{name: "Mike", likes: "ski, arts", dob: "1992-04-15", bmi: 23.9},
  %{name: "Mary", likes: "travels"  , dob: "1992-04-15", bmi: 26.8},
  %{name: "Ann" , likes: "reading"  , dob: "1992-04-15", bmi: 24.7},
  %{name: "Ray" , likes: "cycling"  , dob: "1977-08-28", bmi: 19.1},
  %{name: "Bill", likes: "karate"   , dob: "1977-08-28", bmi: 18.1},
  %{name: "Joe" , likes: "boxing"   , dob: "1977-08-28", bmi: 20.8},
  %{name: "Jill", likes: "cooking"  , dob: "1976-09-28", bmi: 25.8}
]

Table.start([:name, :dob, :likes],
  header_fixes: %{~r[dob]i => "Date of Birth"},
  sort_specs: [asc: :dob],
  align_specs: [center: :dob],
  margins: [top: 2, bottom: 2, left: 2]
)

Table.format(people, style: :light)
Table.format(people, style: :light_alt)
Table.format(people, style: :light_mult)
Table.format(people, style: :cyan_alt)
Table.format(people, style: :cyan_mult)

light

light_alt

light_mult

cyan_alt

cyan_mult

Sends a request to the table spec server identified by option :spec_name. Returns the server's table spec.

See IO.ANSI.Table.Options for a list of all options in this API.

Parameters

  • options - up to 1 option (keyword)

Options

  • :spec_name - to identify the table spec server (string)
Link to this function

start(headers, options \\ [])

View Source

Specs

Starts a new table spec server process and supervises it. Upon request (see format/2), the server will write data from maps to stdout in a table formatted per headers and options.

The table columns are identified by headers (map keys). We calculate the width of each column to fit the longest element in that column, also considering the column heading. However, the :max_width option prevails.

If the :count option is positive, we format the first count maps in the list, once sorted. If negative, the last count ones.

See IO.ANSI.Table.Options for a list of all options in this API.

Parameters

  • headers - keys identifying each column (list)
  • options - up to 10 options (keyword)

Options

  • :align_specs - to align column elements (list)
  • :bell - whether to ring the bell (boolean)
  • :count - number of maps to format (integer)
  • :header_fixes - to alter the headers (map)
  • :margins - to position the table (keyword)
  • :max_width - to cap column widths (non neg integer)
  • :sort_specs - to sort the maps (list)
  • :sort_symbols - to denote sort direction (keyword)
  • :spec_name - to identify the table spec server (string)
  • :style - table style (atom)

Examples

iex> alias IO.ANSI.Table
iex> alias IO.ANSI.Table.SpecServer
iex> {:ok, pid} = Table.start([:name, :dob, :likes])
iex> pid == SpecServer.via("io_ansi_table") |> GenServer.whereis()
true

Specs

stop(Keyword.t()) :: :ok

Stops a table spec server process normally. It won't be restarted. The table spec server to stop is identified by option :spec_name.

See IO.ANSI.Table.Options for a list of all options in this API.

Parameters

  • options - up to 1 option (keyword)

Options

  • :spec_name - to identify the table spec server (string)

Examples

iex> alias IO.ANSI.Table
iex> Table.start([:name, :dob, :likes])
iex> Table.stop
:ok
Link to this function

write(maps, spec, options \\ [])

View Source

Specs

Writes data from maps to stdout in a table formatted per spec and options.

Also supports:

  • keywords
  • structs implementing the Access behaviour

Does not support:

  • nested maps, keywords or structs

See IO.ANSI.Table.Options for a list of all options in this API.

Parameters

  • spec - table spec (struct)
  • maps - flat maps/keywords/structs (list)
  • options - up to 4 options (keyword)

Options

  • :bell - whether to ring the bell (boolean)
  • :count - number of maps to format (integer)
  • :max_width - to cap column widths (non neg integer)
  • :style - table style (atom)

Examples

alias IO.ANSI.Table
alias IO.ANSI.Table.Spec

people = [
  %{name: "Mike", likes: "ski, arts", dob: "1992-04-15", bmi: 23.9},
  %{name: "Mary", likes: "travels"  , dob: "1992-04-15", bmi: 26.8},
  %{name: "Ann" , likes: "reading"  , dob: "1992-04-15", bmi: 24.7},
  %{name: "Ray" , likes: "cycling"  , dob: "1977-08-28", bmi: 19.1},
  %{name: "Bill", likes: "karate"   , dob: "1977-08-28", bmi: 18.1},
  %{name: "Joe" , likes: "boxing"   , dob: "1977-08-28", bmi: 20.8},
  %{name: "Jill", likes: "cooking"  , dob: "1976-09-28", bmi: 25.8}
]

spec = Spec.new([:name, :dob, :likes],
  header_fixes: %{~r[dob]i => "Date of Birth"},
  sort_specs: [asc: :dob],
  align_specs: [center: :dob],
  margins: [top: 2, bottom: 2, left: 2]
) |> Spec.extend()

Table.write(people, spec, style: :light)
Table.write(people, spec, style: :light_alt)
Table.write(people, spec, style: :light_mult)
Table.write(people, spec, style: :cyan_alt)
Table.write(people, spec, style: :cyan_mult)