View Source IO.ANSI.Table (IO ANSI Table v1.0.34)
Writes data to :stdio
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.
Summary
Functions
Sends a request to the table spec server identified by option :spec_name
.
The server will write data from maps
to :stdio
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 a list of
maps to :stdio
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 :stdio
in a table formatted per spec
and
options
.
Functions
@spec 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 :stdio
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 to6
options (keyword)
Options
:async
- whether to write the table asynchronously (boolean):bell
- whether to ring the bell (boolean):count
- number ofmaps
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)
@spec get_spec(Keyword.t()) :: IO.ANSI.Table.Spec.t()
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 to1
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> spec = Table.get_spec()
iex> {spec.headers, spec.spec_name}
{[:name, :dob, :likes], "io_ansi_table"}
iex> alias IO.ANSI.Table
iex> Table.start([:name, :dob, :likes], spec_name: "members")
iex> spec = Table.get_spec(spec_name: "members")
iex> {spec.headers, spec.spec_name}
{[:name, :dob, :likes], "members"}
@spec start([IO.ANSI.Table.Header.t(), ...], Keyword.t()) :: Supervisor.on_start_child()
Starts a new table spec server process and supervises it.
Upon request (see format/2
), the server will write data from a list of
maps to :stdio
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 to10
options (keyword)
Options
:align_specs
- to align column elements (list/keyword):bell
- whether to ring the bell (boolean):count
- number of maps to format (integer):header_fixes
- to alter theheaders
(map):margins
- to position the table (keyword):max_width
- to cap column widths (non neg integer):sort_specs
- to sort the maps (list/keyword):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], spec_name: "people")
iex> pid == SpecServer.via("people") |> GenServer.whereis()
true
@spec 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 to1
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
iex> alias IO.ANSI.Table
iex> Table.start([:name, :dob, :likes], spec_name: "stats")
iex> Table.stop(spec_name: "stats")
:ok
@spec write(IO.ANSI.Table.Spec.t(), [Access.container()], Keyword.t()) :: :ok
Writes data from maps
to :stdio
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 to4
options (keyword)
Options
:bell
- whether to ring the bell (boolean):count
- number ofmaps
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.develop()
Table.write(spec, people, style: :light)
Table.write(spec, people, style: :light_alt)
Table.write(spec, people, style: :light_mult)
Table.write(spec, people, style: :cyan_alt)
Table.write(spec, people, style: :cyan_mult)