Table

Table — container for rows and columns

Functions

struct libscols_table * scols_copy_table ()
struct libscols_table * scols_new_table ()
void scols_ref_table ()
int scols_sort_table ()
int scols_sort_table_by_tree ()
int scols_table_add_column ()
int scols_table_add_line ()
int scols_table_colors_wanted ()
int scols_table_enable_ascii ()
int scols_table_enable_colors ()
int scols_table_enable_export ()
int scols_table_enable_header_repeat ()
int scols_table_enable_json ()
int scols_table_enable_maxout ()
int scols_table_enable_minout ()
int scols_table_enable_noencoding ()
int scols_table_enable_noheadings ()
int scols_table_enable_nolinesep ()
int scols_table_enable_nowrap ()
int scols_table_enable_raw ()
int scols_table_enable_shellvar ()
struct libscols_column * scols_table_get_column ()
struct libscols_column * scols_table_get_column_by_name ()
const char * scols_table_get_column_separator ()
struct libscols_line * scols_table_get_line ()
const char * scols_table_get_line_separator ()
const char * scols_table_get_name ()
size_t scols_table_get_ncols ()
size_t scols_table_get_nlines ()
FILE * scols_table_get_stream ()
struct libscols_symbols * scols_table_get_symbols ()
int scols_table_get_termforce ()
size_t scols_table_get_termheight ()
size_t scols_table_get_termwidth ()
struct libscols_cell * scols_table_get_title ()
int scols_table_is_ascii ()
int scols_table_is_empty ()
int scols_table_is_export ()
int scols_table_is_header_repeat ()
int scols_table_is_json ()
int scols_table_is_maxout ()
int scols_table_is_minout ()
int scols_table_is_noencoding ()
int scols_table_is_noheadings ()
int scols_table_is_nolinesep ()
int scols_table_is_nowrap ()
int scols_table_is_raw ()
int scols_table_is_shellvar ()
int scols_table_is_tree ()
int scols_table_move_column ()
struct libscols_column * scols_table_new_column ()
struct libscols_line * scols_table_new_line ()
int scols_table_next_column ()
int scols_table_next_line ()
int scols_table_reduce_termwidth ()
int scols_table_remove_column ()
int scols_table_remove_columns ()
int scols_table_remove_line ()
void scols_table_remove_lines ()
int scols_table_set_column_separator ()
int scols_table_set_columns_iter ()
int scols_table_set_default_symbols ()
int scols_table_set_line_separator ()
int scols_table_set_name ()
int scols_table_set_stream ()
int scols_table_set_symbols ()
int scols_table_set_termforce ()
int scols_table_set_termheight ()
int scols_table_set_termwidth ()
void scols_unref_table ()

Types and Values

Description

Table data manipulation API.

Functions

scols_copy_table ()

struct libscols_table *
scols_copy_table (struct libscols_table *tb);

Creates a new independent table copy, except struct libscols_symbols that are shared between the tables.

Parameters

tb

table

 

Returns

a newly allocated copy of tb


scols_new_table ()

struct libscols_table *
scols_new_table (void);

Returns

A newly allocated table.


scols_ref_table ()

void
scols_ref_table (struct libscols_table *tb);

Increases the refcount of tb .

Parameters

tb

a pointer to a struct libscols_table instance

 

scols_sort_table ()

int
scols_sort_table (struct libscols_table *tb,
                  struct libscols_column *cl);

Orders the table by the column. See also scols_column_set_cmpfunc(). If the tree output is enabled then children in the tree are recursively sorted too.

The column cl is saved as the default sort column to the tb and the next time is possible to call scols_sort_table(tb, NULL). The saved column is also used by scols_sort_table_by_tree().

Parameters

tb

table

 

cl

order by this column or NULL

 

Returns

0, a negative value in case of an error.


scols_sort_table_by_tree ()

int
scols_sort_table_by_tree (struct libscols_table *tb);

Reorders lines in the table by parent->child relation. Note that order of the lines in the table is independent on the tree hierarchy by default.

The children of the lines are sorted according to the default sort column if scols_sort_table() has been previously called.

Parameters

tb

table

 

Returns

0, a negative value in case of an error.

Since: 2.30


scols_table_add_column ()

int
scols_table_add_column (struct libscols_table *tb,
                        struct libscols_column *cl);

Adds cl to tb 's column list. The column cannot be shared between more tables.

Parameters

tb

a pointer to a struct libscols_table instance

 

cl

a pointer to a struct libscols_column instance

 

Returns

0, a negative number in case of an error.


scols_table_add_line ()

int
scols_table_add_line (struct libscols_table *tb,
                      struct libscols_line *ln);

Note that this function calls scols_line_alloc_cells() if number of the cells in the line is too small for tb .

Parameters

tb

table

 

ln

line

 

Returns

0, a negative value in case of an error.


scols_table_colors_wanted ()

int
scols_table_colors_wanted (const struct libscols_table *tb);

Parameters

tb

table

 

Returns

1 if colors are enabled.


scols_table_enable_ascii ()

int
scols_table_enable_ascii (struct libscols_table *tb,
                          int enable);

The ASCII-only output is relevant for tree-like outputs. The library checks if the current environment is UTF8 compatible by default. This function overrides this check and force the library to use ASCII chars for the tree.

If a custom libcols_symbols are specified (see scols_table_set_symbols() then ASCII flag setting is ignored.

Parameters

tb

table

 

enable

1 or 0

 

Returns

0 on success, negative number in case of an error.


scols_table_enable_colors ()

int
scols_table_enable_colors (struct libscols_table *tb,
                           int enable);

Enable/disable colors.

Parameters

tb

table

 

enable

1 or 0

 

Returns

0 on success, negative number in case of an error.


scols_table_enable_export ()

int
scols_table_enable_export (struct libscols_table *tb,
                           int enable);

Enable/disable export output format (COLUMNAME="value" ...). The parsable output formats (export and raw) are mutually exclusive.

See also scols_table_enable_shellvar(). Note that in version 2.37 (and only in this version) scols_table_enable_shellvar() functionality has been automatically enabled for "export" format. This behavior has been reverted in version 2.38 due to backward compatibility issues. Now it's necessary to explicitly call scols_table_enable_shellvar().

Parameters

tb

table

 

enable

1 or 0

 

Returns

0 on success, negative number in case of an error.


scols_table_enable_header_repeat ()

int
scols_table_enable_header_repeat (struct libscols_table *tb,
                                  int enable);

Enable/disable header line repeat. The header line is printed only once by default. Note that the flag will be silently ignored and disabled if the output is not on terminal or output format is JSON, raw, etc.

Parameters

tb

table

 

enable

1 or 0

 

Returns

0 on success, negative number in case of an error.

Since: 2.31


scols_table_enable_json ()

int
scols_table_enable_json (struct libscols_table *tb,
                         int enable);

Enable/disable JSON output format. The parsable output formats (export, raw, JSON, ...) are mutually exclusive.

Parameters

tb

table

 

enable

1 or 0

 

Returns

0 on success, negative number in case of an error.

Since: 2.27


scols_table_enable_maxout ()

int
scols_table_enable_maxout (struct libscols_table *tb,
                           int enable);

The extra space after last column is ignored by default. The output maximization add padding for all columns.

This setting is mutually exclusive to scols_table_enable_minout().

Parameters

tb

table

 

enable

1 or 0

 

Returns

0 on success, negative number in case of an error.


scols_table_enable_minout ()

int
scols_table_enable_minout (struct libscols_table *tb,
                           int enable);

Force library to terminate line after last column with data. The extra padding is not added to the empty cells at the end of the line. The default is fill tailing empty cells except the last line cell.

This setting is mutually exclusive to scols_table_enable_maxout().

Parameters

tb

table

 

enable

1 or 0

 

Returns

0 on success, negative number in case of an error.

Since: 2.35


scols_table_enable_noencoding ()

int
scols_table_enable_noencoding (struct libscols_table *tb,
                               int enable);

The library encode non-printable and control chars by \xHEX by default.

Parameters

tb

table

 

enable

1 or 0

 

Returns

0 on success, negative number in case of an error.

Since: 2.31


scols_table_enable_noheadings ()

int
scols_table_enable_noheadings (struct libscols_table *tb,
                               int enable);

Enable/disable header line.

Parameters

tb

table

 

enable

1 or 0

 

Returns

0 on success, negative number in case of an error.


scols_table_enable_nolinesep ()

int
scols_table_enable_nolinesep (struct libscols_table *tb,
                              int enable);

Enable/disable line separator printing. This is useful if you want to re-printing the same line more than once (e.g. progress bar). Don't use it if you're not sure.

Note that for the last line in the table the separator is disabled at all. The library differentiate between table terminator and line terminator (although for standard output \n byte is used in both cases).

Parameters

tb

table

 

enable

1 or 0

 

Returns

0 on success, negative number in case of an error.


scols_table_enable_nowrap ()

int
scols_table_enable_nowrap (struct libscols_table *tb,
                           int enable);

Never continue on next line, remove last column(s) when too large, truncate last column.

Parameters

tb

table

 

enable

1 or 0

 

Returns

0 on success, negative number in case of an error.

Since: 2.28


scols_table_enable_raw ()

int
scols_table_enable_raw (struct libscols_table *tb,
                        int enable);

Enable/disable raw output format. The parsable output formats (export, raw, JSON, ...) are mutually exclusive.

Parameters

tb

table

 

enable

1 or 0

 

Returns

0 on success, negative number in case of an error.


scols_table_enable_shellvar ()

int
scols_table_enable_shellvar (struct libscols_table *tb,
                             int enable);

Force library to print column names to be compatible with shell requirements to variable names. For example "1FOO%" will be printed as "_1FOO_PCT".

Parameters

tb

table

 

enable

1 or 0

 

Returns

0 on success, negative number in case of an error.

Since: 2.38


scols_table_get_column ()

struct libscols_column *
scols_table_get_column (struct libscols_table *tb,
                        size_t n);

Parameters

tb

table

 

n

number of column (0..N)

 

Returns

pointer to column or NULL


scols_table_get_column_by_name ()

struct libscols_column *
scols_table_get_column_by_name (struct libscols_table *tb,
                                const char *name);

scols_table_get_column_separator ()

const char *
scols_table_get_column_separator (const struct libscols_table *tb);

Parameters

tb

table

 

Returns

tb column separator, NULL in case of an error


scols_table_get_line ()

struct libscols_line *
scols_table_get_line (struct libscols_table *tb,
                      size_t n);

Parameters

tb

table

 

n

column number (0..N)

 

Returns

a line or NULL


scols_table_get_line_separator ()

const char *
scols_table_get_line_separator (const struct libscols_table *tb);

Parameters

tb

table

 

Returns

tb line separator, NULL in case of an error


scols_table_get_name ()

const char *
scols_table_get_name (const struct libscols_table *tb);

Parameters

tb

a pointer to a struct libscols_table instance

 

Returns

The current name setting of the table tb

Since: 2.29


scols_table_get_ncols ()

size_t
scols_table_get_ncols (const struct libscols_table *tb);

Parameters

tb

table

 

Returns

the ncols table member.


scols_table_get_nlines ()

size_t
scols_table_get_nlines (const struct libscols_table *tb);

Parameters

tb

table

 

Returns

the nlines table member.


scols_table_get_stream ()

FILE *
scols_table_get_stream (const struct libscols_table *tb);

Gets the output stream for table tb .

Parameters

tb

table

 

Returns

stream pointer, NULL in case of an error or an unset stream.


scols_table_get_symbols ()

struct libscols_symbols *
scols_table_get_symbols (const struct libscols_table *tb);

Parameters

tb

table

 

Returns

pointer to symbols table.

Since: 2.29


scols_table_get_termforce ()

int
scols_table_get_termforce (const struct libscols_table *tb);

Parameters

tb

table

 

Returns

SCOLS_TERMFORCE_{NEVER,ALWAYS,AUTO} or a negative value in case of an error.

Since: 2.29


scols_table_get_termheight ()

size_t
scols_table_get_termheight (const struct libscols_table *tb);

Parameters

tb

table

 

Returns

terminal height (number of lines).

Since: 2.31


scols_table_get_termwidth ()

size_t
scols_table_get_termwidth (const struct libscols_table *tb);

Parameters

tb

table

 

Returns

terminal width.


scols_table_get_title ()

struct libscols_cell *
scols_table_get_title (struct libscols_table *tb);

The returned pointer is possible to modify by cell functions. Note that title output alignment on non-tty is hardcoded to 80 output chars. For the regular terminal it's based on terminal width.

Parameters

tb

a pointer to a struct libscols_table instance

 

Returns

Title of the table, or NULL in case of blank title.

Since: 2.28


scols_table_is_ascii ()

int
scols_table_is_ascii (const struct libscols_table *tb);

Parameters

tb

table

 

Returns

1 if ASCII tree is enabled.


scols_table_is_empty ()

int
scols_table_is_empty (const struct libscols_table *tb);

Parameters

tb

table

 

Returns

1 if the table is empty.


scols_table_is_export ()

int
scols_table_is_export (const struct libscols_table *tb);

Parameters

tb

table

 

Returns

1 if export output format is enabled.


scols_table_is_header_repeat ()

int
scols_table_is_header_repeat (const struct libscols_table *tb);

Parameters

tb

table

 

Returns

1 if header repeat is enabled.

Since: 2.31


scols_table_is_json ()

int
scols_table_is_json (const struct libscols_table *tb);

Parameters

tb

table

 

Returns

1 if JSON output format is enabled.

Since: 2.27


scols_table_is_maxout ()

int
scols_table_is_maxout (const struct libscols_table *tb);

Parameters

tb

table

 

Returns

1 if output maximization is enabled or 0


scols_table_is_minout ()

int
scols_table_is_minout (const struct libscols_table *tb);

Parameters

tb

table

 

Returns

1 if output minimization is enabled or 0

Since: 2.35


scols_table_is_noencoding ()

int
scols_table_is_noencoding (const struct libscols_table *tb);

Parameters

tb

a pointer to a struct libscols_table instance

 

Returns

1 if encoding is disabled.

Since: 2.31


scols_table_is_noheadings ()

int
scols_table_is_noheadings (const struct libscols_table *tb);

Parameters

tb

table

 

Returns

1 if header output is disabled.


scols_table_is_nolinesep ()

int
scols_table_is_nolinesep (const struct libscols_table *tb);

Parameters

tb

a pointer to a struct libscols_table instance

 

Returns

1 if line separator printing is disabled.

Since: 2.29


scols_table_is_nowrap ()

int
scols_table_is_nowrap (const struct libscols_table *tb);

Parameters

tb

a pointer to a struct libscols_table instance

 

Returns

1 if nowrap is enabled.

Since: 2.29


scols_table_is_raw ()

int
scols_table_is_raw (const struct libscols_table *tb);

Parameters

tb

table

 

Returns

1 if raw output format is enabled.


scols_table_is_shellvar ()

int
scols_table_is_shellvar (const struct libscols_table *tb);

Parameters

tb

table

 

Returns

1 if column names has to be compatible with shell requirements to variable names

Since: 2.38


scols_table_is_tree ()

int
scols_table_is_tree (const struct libscols_table *tb);

Parameters

tb

table

 

Returns

returns 1 tree-like output is expected.


scols_table_move_column ()

int
scols_table_move_column (struct libscols_table *tb,
                         struct libscols_column *pre,
                         struct libscols_column *cl);

Move the cl behind pre . If the pre is NULL then the col is the first column in the table.

Parameters

tb

table

 

pre

column before the column

 

cl

column to move

 

Returns

0, a negative number in case of an error.

Since: 2.30


scols_table_new_column ()

struct libscols_column *
scols_table_new_column (struct libscols_table *tb,
                        const char *name,
                        double whint,
                        int flags);

This is shortcut for

cl = scols_new_column(); scols_column_set_....(cl, ...); scols_table_add_column(tb, cl);

The column width is possible to define by:

whint : 0 < N < 1 : relative width, percent of terminal width

whint : N >= 1 : absolute width, empty column will be truncated to the column header width if no specified STRICTWIDTH flag

Note that if table has disabled "maxout" flag (disabled by default) than relative width is used as a hint only. It's possible that column will be narrow if the specified size is too large for column data.

If the width of all columns is greater than terminal width then library tries to reduce width of the individual columns. It's done in three stages:

#1 reduce columns with SCOLS_FL_TRUNC flag and with relative width if the width is greater than width defined by whint (whint * terminal_width)

#2 reduce all columns with SCOLS_FL_TRUNC flag

#3 reduce all columns with relative width

The next stage is always used if the previous stage is unsuccessful. Note that SCOLS_FL_WRAP is interpreted as SCOLS_FL_TRUNC when calculate column width (if custom wrap function is not specified), but the final text is not truncated, but wrapped to multi-line cell.

The column is necessary to address by sequential number. The first defined column has the colnum = 0. For example:

scols_table_new_column(tab, "FOO", 0.5, 0); // colnum = 0 scols_table_new_column(tab, "BAR", 0.5, 0); // colnum = 1 . . scols_line_get_cell(line, 0); // FOO column scols_line_get_cell(line, 1); // BAR column

Parameters

tb

table

 

name

column header

 

whint

column width hint (absolute width: N > 1; relative width: 0 < N < 1)

 

flags

flags integer

 

Returns

newly allocated column


scols_table_new_line ()

struct libscols_line *
scols_table_new_line (struct libscols_table *tb,
                      struct libscols_line *parent);

This is shortcut for

ln = scols_new_line(); scols_table_add_line(tb, ln); scols_line_add_child(parent, ln);

Parameters

tb

table

 

parent

parental line or NULL

 

Returns

newly allocate line


scols_table_next_column ()

int
scols_table_next_column (struct libscols_table *tb,
                         struct libscols_iter *itr,
                         struct libscols_column **cl);

Returns the next column of tb via cl .

Parameters

tb

a pointer to a struct libscols_table instance

 

itr

a pointer to a struct libscols_iter instance

 

cl

a pointer to a pointer to a struct libscols_column instance

 

Returns

0, a negative value in case of an error.


scols_table_next_line ()

int
scols_table_next_line (struct libscols_table *tb,
                       struct libscols_iter *itr,
                       struct libscols_line **ln);

Finds the next line and returns a pointer to it via ln .

Parameters

tb

a pointer to a struct libscols_table instance

 

itr

a pointer to a struct libscols_iter instance

 

ln

a pointer to a pointer to a struct libscols_line instance

 

Returns

0, a negative value in case of an error.


scols_table_reduce_termwidth ()

int
scols_table_reduce_termwidth (struct libscols_table *tb,
                              size_t reduce);

If necessary then libsmartcols use all terminal width, the reduce setting provides extra space (for example for borders in ncurses applications).

The reduce must be smaller than terminal width, otherwise it's silently ignored. The reduction is not applied when STDOUT_FILENO is not terminal.

Note that after output initialization (scols_table_print_* calls) the width will be reduced, this behavior affects subsequenced scols_table_get_termwidth() calls.

Parameters

tb

table

 

reduce

width

 

Returns

0, a negative value in case of an error.


scols_table_remove_column ()

int
scols_table_remove_column (struct libscols_table *tb,
                           struct libscols_column *cl);

Removes cl from tb .

Parameters

tb

a pointer to a struct libscols_table instance

 

cl

a pointer to a struct libscols_column instance

 

Returns

0, a negative number in case of an error.


scols_table_remove_columns ()

int
scols_table_remove_columns (struct libscols_table *tb);

Removes all of tb 's columns.

Parameters

tb

a pointer to a struct libscols_table instance

 

Returns

0, a negative number in case of an error.


scols_table_remove_line ()

int
scols_table_remove_line (struct libscols_table *tb,
                         struct libscols_line *ln);

Note that this function does not destroy the parent<->child relationship between lines. You have to call scols_line_remove_child()

Parameters

tb

table

 

ln

line

 

Returns

0, a negative value in case of an error.


scols_table_remove_lines ()

void
scols_table_remove_lines (struct libscols_table *tb);

This empties the table and also destroys all the parent<->child relationships.

Parameters

tb

table

 

scols_table_set_column_separator ()

int
scols_table_set_column_separator (struct libscols_table *tb,
                                  const char *sep);

Sets the column separator of tb to sep .

Parameters

tb

table

 

sep

separator

 

Returns

0, a negative value in case of an error.


scols_table_set_columns_iter ()

int
scols_table_set_columns_iter (struct libscols_table *tb,
                              struct libscols_iter *itr,
                              struct libscols_column *cl);

Sets iter to the position of cl in the file tb .

Parameters

tb

tab pointer

 

itr

iterator

 

cl

tab entry

 

Returns

0 on success, negative number in case of error.

Since: 2.35


scols_table_set_default_symbols ()

int
scols_table_set_default_symbols (struct libscols_table *tb);

The library check the current environment to select ASCII or UTF8 symbols. This default behavior could be controlled by scols_table_enable_ascii().

Use scols_table_set_symbols() to unset symbols or use your own setting.

Parameters

tb

table

 

Returns

0, a negative value in case of an error.

Since: 2.29


scols_table_set_line_separator ()

int
scols_table_set_line_separator (struct libscols_table *tb,
                                const char *sep);

Sets the line separator of tb to sep .

Parameters

tb

table

 

sep

separator

 

Returns

0, a negative value in case of an error.


scols_table_set_name ()

int
scols_table_set_name (struct libscols_table *tb,
                      const char *name);

The table name is used for example for JSON top level object name.

Parameters

tb

a pointer to a struct libscols_table instance

 

name

a name

 

Returns

0, a negative number in case of an error.

Since: 2.27


scols_table_set_stream ()

int
scols_table_set_stream (struct libscols_table *tb,
                        FILE *stream);

Sets the output stream for table tb .

Parameters

tb

table

 

stream

output stream

 

Returns

0, a negative number in case of an error.


scols_table_set_symbols ()

int
scols_table_set_symbols (struct libscols_table *tb,
                         struct libscols_symbols *sy);

Add a reference to sy from the table. The symbols are used by library to draw tree output. If no symbols are used for the table then library creates default temporary symbols to draw output by scols_table_set_default_symbols().

If sy is NULL then remove reference from the currently used symbols.

Parameters

tb

table

 

sy

symbols or NULL

 

Returns

0, a negative value in case of an error.


scols_table_set_termforce ()

int
scols_table_set_termforce (struct libscols_table *tb,
                           int force);

Forces library to use stdout as terminal, non-terminal or use automatic detection (default).

Parameters

tb

table

 

force

SCOLS_TERMFORCE_{NEVER,ALWAYS,AUTO}

 

Returns

0, a negative value in case of an error.

Since: 2.29


scols_table_set_termheight ()

int
scols_table_set_termheight (struct libscols_table *tb,
                            size_t height);

The library automatically detects terminal height or defaults to 24 lines if detections is unsuccessful. This function override this behaviour.

Parameters

tb

table

 

height

terminal height (number of lines)

 

Returns

0, a negative value in case of an error.

Since: 2.31


scols_table_set_termwidth ()

int
scols_table_set_termwidth (struct libscols_table *tb,
                           size_t width);

The library automatically detects terminal width or defaults to 80 chars if detections is unsuccessful. This function override this behaviour.

Parameters

tb

table

 

width

terminal width

 

Returns

0, a negative value in case of an error.

Since: 2.29


scols_unref_table ()

void
scols_unref_table (struct libscols_table *tb);

Decreases the refcount of tb . When the count falls to zero, the instance is automatically deallocated.

Parameters

tb

a pointer to a struct libscols_table instance

 

Types and Values

struct libscols_table

struct libscols_table;

A table - The most abstract object, encapsulating lines, columns, symbols and cells