# Table

When building a console application it may be useful to display tabular data:

    +---------------+--------------------------+------------------+
    | ISBN          | Title                    | Author           |
    +---------------+--------------------------+------------------+
    | 99921-58-10-7 | Divine Comedy            | Dante Alighieri  |
    | 9971-5-0210-0 | A Tale of Two Cities     | Charles Dickens  |
    | 960-425-059-0 | The Lord of the Rings    | J. R. R. Tolkien |
    | 80-902734-1-6 | And Then There Were None | Agatha Christie  |
    +---------------+--------------------------+------------------+

To display a table, use the `table()` method, set the headers, set the rows and then render the table:

    def handle(self):
        table = self.table()

        table.set_header_row(['ISBN', 'Title', 'Author'])
        table.set_rows([
            ['99921-58-10-7', 'Divine Comedy', 'Dante Alighieri'],
            ['9971-5-0210-0', 'A Tale of Two Cities', 'Charles Dickens'],
            ['960-425-059-0', 'The Lord of the Rings', 'J. R. R. Tolkien'],
            ['80-902734-1-6', 'And Then There Were None', 'Agatha Christie']
        ])

        table.render(self.io)

Tip

All these steps can be done in one go using the `render_table` method:

    self.render_table(
        ['ISBN', 'Title', 'Author'],
        [
            ['99921-58-10-7', 'Divine Comedy', 'Dante Alighieri'],
            ['9971-5-0210-0', 'A Tale of Two Cities', 'Charles Dickens'],
            ['960-425-059-0', 'The Lord of the Rings', 'J. R. R. Tolkien'],
            ['80-902734-1-6', 'And Then There Were None', 'Agatha Christie']
        ]
    )

You can add a table separator anywhere in the output by using `table_seprator()`, which returns a `TableSeparator`, as a row:

    table.set_rows([
        ['99921-58-10-7', 'Divine Comedy', 'Dante Alighieri'],
        ['9971-5-0210-0', 'A Tale of Two Cities', 'Charles Dickens'],
        self.table_separator(),
        ['960-425-059-0', 'The Lord of the Rings', 'J. R. R. Tolkien'],
        ['80-902734-1-6', 'And Then There Were None', 'Agatha Christie']
    ])

    +---------------+--------------------------+------------------+
    | ISBN          | Title                    | Author           |
    +---------------+--------------------------+------------------+
    | 99921-58-10-7 | Divine Comedy            | Dante Alighieri  |
    | 9971-5-0210-0 | A Tale of Two Cities     | Charles Dickens  |
    +---------------+--------------------------+------------------+
    | 960-425-059-0 | The Lord of the Rings    | J. R. R. Tolkien |
    | 80-902734-1-6 | And Then There Were None | Agatha Christie  |
    +---------------+--------------------------+------------------+

The table style can be changed to any built-in styles via `set_style()`:

    # same as calling nothing
    table.set_style('default')

    # changes the default style to compact
    table.set_style('compact')

This code results in:

    ISBN          Title                    Author
    99921-58-10-7 Divine Comedy            Dante Alighieri
    9971-5-0210-0 A Tale of Two Cities     Charles Dickens
    960-425-059-0 The Lord of the Rings    J. R. R. Tolkien
    80-902734-1-6 And Then There Were None Agatha Christie

You can also set the style to `borderless`:

    table.set_style('borderless')

which outputs:

    =============== ========================== ==================
     ISBN            Title                      Author
    =============== ========================== ==================
     99921-58-10-7   Divine Comedy              Dante Alighieri
     9971-5-0210-0   A Tale of Two Cities       Charles Dickens
     960-425-059-0   The Lord of the Rings      J. R. R. Tolkien
     80-902734-1-6   And Then There Were None   Agatha Christie
    =============== ========================== ==================

If the built-in styles do not fit your need, define your own:

    # by default, this is based on the default style
    style = self.table_style()

    # customize the style
    style.set_horizontal_border_char('<fg=magenta>|</>')
    style.set_vertical_border_char('<fg=magenta>-</>')
    style.set_crossing_char(' ')

    # use the style for this table
    table.set_style(style)

Here is a full list of things you can customize:

- `set_adding_char()`

- `set_horizontal_border_char()`

- `set_vertical_border_char()`

- `set_crossing_char()`

- `set_cell_header_format()`

- `set_cell_row_format()`

- `set_border_format()`

- `set_pad_type()`

Tip

The style can also be passed as a keyword argument to `render_table()`

    self.render_table(
        ['ISBN', 'Title', 'Author'],
        [
            ['99921-58-10-7', 'Divine Comedy', 'Dante Alighieri'],
            ['9971-5-0210-0', 'A Tale of Two Cities', 'Charles Dickens'],
            ['960-425-059-0', 'The Lord of the Rings', 'J. R. R. Tolkien'],
            ['80-902734-1-6', 'And Then There Were None', 'Agatha Christie']
        ]
        style='borderless'
    )

## Spanning Multiple Columns and Rows

To make a table cell that spans multiple columns you can use `table_cell()`, which returns a `TableCell` instance:

    table = self.table()

    table.set_headers(['ISBN', 'Title', 'Author'])
    table.set_rows([
        ['99921-58-10-7', 'Divine Comedy', 'Dante Alighieri'],
        self.table_separator(),
        [self.table_cell('This value spans 3 columns.', colspan=3)]
    ])

    table.render()

This results in:

    +---------------+---------------+-----------------+
    | ISBN          | Title         | Author          |
    +---------------+---------------+-----------------+
    | 99921-58-10-7 | Divine Comedy | Dante Alighieri |
    +---------------+---------------+-----------------+
    | This value spans 3 columns.                     |
    +---------------+---------------+-----------------+

Tip

You can create a multiple-line page title using a header cell that spans the entire table width:

    table.set_headers([
        [self.table_cell('Main table title', colspan=3)],
        ['ISBN', 'Title', 'Author']
    ])

This generate:

    +-------+-------+--------+
    | Main table title       |
    +-------+-------+--------+
    | ISBN  | Title | Author |
    +-------+-------+--------+
    | ...                    |
    +-------+-------+--------+

In a similar way you can span multiple rows:

    table = self.table()

    table.set_headers(['ISBN', 'Title', 'Author'])
    table.set_rows([
        [
            '978-0521567817',
            'De Monarchia',
            self.table_cell('Dante Alighieri\nspans multiple rows', rowspan=2)
        ]
    ])

    table.render()

This outputs:

    +----------------+---------------+---------------------+
    | ISBN           | Title         | Author              |
    +----------------+---------------+---------------------+
    | 978-0521567817 | De Monarchia  | Dante Alighieri     |
    | 978-0804169127 | Divine Comedy | spans multiple rows |
    +----------------+---------------+---------------------+

You can use the `colspan` and `rowspan` options at the same time which allows you to create any table layout you may wish.