3rd-party/libfort
1
0
Fork 0
Code Releases Activity

[A] Added tutorial from github wiki to repository

Browse Source
This commit is contained in:
seleznevae
2020-01-30 19:11:36 +03:00
parent 77ad49daeb
commit 0430da4163
12 changed files with 1246 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

257
docs/tutorial/CPP_API/Border-styles.md Normal file
View File

@@ -0,0 +1,257 @@
**libfort** has a number of builtin border styles.
To change border style of **libfort** tables one can use `set_default_border_style`, `set_border_style` functions:
```C++
/* Change border style of all libfort tables that will be created */
bool set_default_border_style(struct ft_border_style *style);
/* Change border style of the current table */
bool set_border_style(struct ft_border_style *style);
```
Here is a simple example of creating table and setting border style:
```C++
fort::char_table table;
/* Set table border style */
table.set_border_style(FT_BASIC_STYLE);
// Fill table with data
table << fort::header
<< "Rank" << "Title" << "Year" << "Rating" << fort::endr
<< "1" << "The Shawshank Redemption" << "1994" << "9.5" << fort::endr
<< "2" << "12 Angry Men" << "1957" << "8.8" << fort::endr
<< "3" << "It's a Wonderful Life" << "1946" << "8.6" << fort::endr
<< fort::separator
<< "4" << "2001: A Space Odyssey" << "1968" << "8.5" << fort::endr
<< "5" << "Blade Runner" << "1982" << "8.1" << fort::endr
<< fort::endr;
table.column(0).set_cell_text_align(fort::text_align::center);
table.column(1).set_cell_text_align(fort::text_align::left);
std::cout << table.to_string() << std::endl;
```
Output:
```text
+------+--------------------------+------+--------+
| Rank | Title | Year | Rating |
+------+--------------------------+------+--------+
| 1 | The Shawshank Redemption | 1994 | 9.5 |
| 2 | 12 Angry Men | 1957 | 8.8 |
| 3 | It's a Wonderful Life | 1946 | 8.6 |
+------+--------------------------+------+--------+
| 4 | 2001: A Space Odyssey | 1968 | 8.5 |
| 5 | Blade Runner | 1982 | 8.1 |
+------+--------------------------+------+--------+
```
## FT_BASIC_STYLE
```text
+------+--------------------------+------+--------+
| Rank | Title | Year | Rating |
+------+--------------------------+------+--------+
| 1 | The Shawshank Redemption | 1994 | 9.5 |
| 2 | 12 Angry Men | 1957 | 8.8 |
| 3 | It's a Wonderful Life | 1946 | 8.6 |
+------+--------------------------+------+--------+
| 4 | 2001: A Space Odyssey | 1968 | 8.5 |
| 5 | Blade Runner | 1982 | 8.1 |
+------+--------------------------+------+--------+
```
## FT_BASIC2_STYLE
```text
+------+--------------------------+------+--------+
| Rank | Title | Year | Rating |
+------+--------------------------+------+--------+
| 1 | The Shawshank Redemption | 1994 | 9.5 |
+------+--------------------------+------+--------+
| 2 | 12 Angry Men | 1957 | 8.8 |
+------+--------------------------+------+--------+
| 3 | It's a Wonderful Life | 1946 | 8.6 |
+------+--------------------------+------+--------+
| 4 | 2001: A Space Odyssey | 1968 | 8.5 |
+------+--------------------------+------+--------+
| 5 | Blade Runner | 1982 | 8.1 |
+------+--------------------------+------+--------+
```
## FT_SIMPLE_STYLE
```text
Rank Title Year Rating
------ -------------------------- ------ --------
1 The Shawshank Redemption 1994 9.5
2 12 Angry Men 1957 8.8
3 It's a Wonderful Life 1946 8.6
------ -------------------------- ------ --------
4 2001: A Space Odyssey 1968 8.5
5 Blade Runner 1982 8.1
```
## FT_PLAIN_STYLE
```text
-------------------------------------------------
Rank Title Year Rating
-------------------------------------------------
1 The Shawshank Redemption 1994 9.5
2 12 Angry Men 1957 8.8
3 It's a Wonderful Life 1946 8.6
-------------------------------------------------
4 2001: A Space Odyssey 1968 8.5
5 Blade Runner 1982 8.1
```
## FT_DOT_STYLE
```text
...................................................
: Rank : Title : Year : Rating :
:......:..........................:......:........:
: 1 : The Shawshank Redemption : 1994 : 9.5 :
: 2 : 12 Angry Men : 1957 : 8.8 :
: 3 : It's a Wonderful Life : 1946 : 8.6 :
:......:..........................:......:........:
: 4 : 2001: A Space Odyssey : 1968 : 8.5 :
: 5 : Blade Runner : 1982 : 8.1 :
:......:..........................:......:........:
```
## FT_EMPTY_STYLE
```text
Rank Title Year Rating
1 The Shawshank Redemption 1994 9.5
2 12 Angry Men 1957 8.8
3 It's a Wonderful Life 1946 8.6
4 2001: A Space Odyssey 1968 8.5
5 Blade Runner 1982 8.1
```
## FT_EMPTY2_STYLE
```text
Rank Title Year Rating
1 The Shawshank Redemption 1994 9.5
2 12 Angry Men 1957 8.8
3 It's a Wonderful Life 1946 8.6
4 2001: A Space Odyssey 1968 8.5
5 Blade Runner 1982 8.1
```
## FT_SOLID_STYLE
```text
┌──────┬──────────────────────────┬──────┬────────┐
│ Rank │ Title │ Year │ Rating │
├──────┼──────────────────────────┼──────┼────────┤
│ 1 │ The Shawshank Redemption │ 1994 │ 9.5 │
│ 2 │ 12 Angry Men │ 1957 │ 8.8 │
│ 3 │ It's a Wonderful Life │ 1946 │ 8.6 │
├──────┼──────────────────────────┼──────┼────────┤
│ 4 │ 2001: A Space Odyssey │ 1968 │ 8.5 │
│ 5 │ Blade Runner │ 1982 │ 8.1 │
└──────┴──────────────────────────┴──────┴────────╯
```
## FT_SOLID_ROUND_STYLE
```text
╭──────┬──────────────────────────┬──────┬────────╮
│ Rank │ Title │ Year │ Rating │
├──────┼──────────────────────────┼──────┼────────┤
│ 1 │ The Shawshank Redemption │ 1994 │ 9.5 │
│ 2 │ 12 Angry Men │ 1957 │ 8.8 │
│ 3 │ It's a Wonderful Life │ 1946 │ 8.6 │
├──────┼──────────────────────────┼──────┼────────┤
│ 4 │ 2001: A Space Odyssey │ 1968 │ 8.5 │
│ 5 │ Blade Runner │ 1982 │ 8.1 │
╰──────┴──────────────────────────┴──────┴────────╯
```
## FT_DOUBLE_STYLE
```text
╔══════╦══════════════════════════╦══════╦════════╗
║ Rank ║ Title ║ Year ║ Rating ║
╠══════╬══════════════════════════╬══════╬════════╣
║ 1 ║ The Shawshank Redemption ║ 1994 ║ 9.5 ║
║ 2 ║ 12 Angry Men ║ 1957 ║ 8.8 ║
║ 3 ║ It's a Wonderful Life ║ 1946 ║ 8.6 ║
╠══════╬══════════════════════════╬══════╬════════╣
║ 4 ║ 2001: A Space Odyssey ║ 1968 ║ 8.5 ║
║ 5 ║ Blade Runner ║ 1982 ║ 8.1 ║
╚══════╩══════════════════════════╩══════╩════════╝
```
## FT_DOUBLE2_STYLE
```text
╔══════╤══════════════════════════╤══════╤════════╗
║ Rank │ Title │ Year │ Rating ║
╠══════╪══════════════════════════╪══════╪════════╣
║ 1 │ The Shawshank Redemption │ 1994 │ 9.5 ║
╟──────┼──────────────────────────┼──────┼────────╢
║ 2 │ 12 Angry Men │ 1957 │ 8.8 ║
╟──────┼──────────────────────────┼──────┼────────╢
║ 3 │ It's a Wonderful Life │ 1946 │ 8.6 ║
╠══════╪══════════════════════════╪══════╪════════╣
║ 4 │ 2001: A Space Odyssey │ 1968 │ 8.5 ║
╟──────┼──────────────────────────┼──────┼────────╢
║ 5 │ Blade Runner │ 1982 │ 8.1 ║
╚══════╧══════════════════════════╧══════╧════════╝
```
## FT_BOLD_STYLE
```text
┏━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━┳━━━━━━━━┓
┃ Rank ┃ Title ┃ Year ┃ Rating ┃
┣━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━╋━━━━━━╋━━━━━━━━┫
┃ 1 ┃ The Shawshank Redemption ┃ 1994 ┃ 9.5 ┃
┃ 2 ┃ 12 Angry Men ┃ 1957 ┃ 8.8 ┃
┃ 3 ┃ It's a Wonderful Life ┃ 1946 ┃ 8.6 ┃
┣━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━╋━━━━━━╋━━━━━━━━┫
┃ 4 ┃ 2001: A Space Odyssey ┃ 1968 ┃ 8.5 ┃
┃ 5 ┃ Blade Runner ┃ 1982 ┃ 8.1 ┃
┗━━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━━━┻━━━━━━┻━━━━━━━━┛
```
## FT_BOLD2_STYLE
```text
┏━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━┯━━━━━━┯━━━━━━━━┓
┃ Rank │ Title │ Year │ Rating ┃
┣━━━━━━┿━━━━━━━━━━━━━━━━━━━━━━━━━━┿━━━━━━┿━━━━━━━━┫
┃ 1 │ The Shawshank Redemption │ 1994 │ 9.5 ┃
┠──────┼──────────────────────────┼──────┼────────┨
┃ 2 │ 12 Angry Men │ 1957 │ 8.8 ┃
┠──────┼──────────────────────────┼──────┼────────┨
┃ 3 │ It's a Wonderful Life │ 1946 │ 8.6 ┃
┣━━━━━━┿━━━━━━━━━━━━━━━━━━━━━━━━━━┿━━━━━━┿━━━━━━━━┫
┃ 4 │ 2001: A Space Odyssey │ 1968 │ 8.5 ┃
┠──────┼──────────────────────────┼──────┼────────┨
┃ 5 │ Blade Runner │ 1982 │ 8.1 ┃
┗━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━┷━━━━━━━━┛
```
## FT_FRAME_STYLE
```text
▛▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▜
▌ Rank ┃ Title ┃ Year ┃ Rating ▐
▌━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━╋━━━━━━╋━━━━━━━━▐
▌ 1 ┃ The Shawshank Redemption ┃ 1994 ┃ 9.5 ▐
▌ 2 ┃ 12 Angry Men ┃ 1957 ┃ 8.8 ▐
▌ 3 ┃ It's a Wonderful Life ┃ 1946 ┃ 8.6 ▐
▌━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━╋━━━━━━╋━━━━━━━━▐
▌ 4 ┃ 2001: A Space Odyssey ┃ 1968 ┃ 8.5 ▐
▌ 5 ┃ Blade Runner ┃ 1982 ┃ 8.1 ▐
▙▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▟
```

68
docs/tutorial/CPP_API/Cell-and-table-properties.md Normal file
View File

@@ -0,0 +1,68 @@
## Cell properties
By default all cells created in **libfort** tables will have the same properties.
To change cell properties one should use functions `set_cell_{property_name}`:
```C++
bool set_cell_min_width(unsigned value);
bool set_cell_text_align(enum fort::text_align value);
bool set_cell_top_padding(unsigned value);
bool set_cell_bottom_padding(unsigned value);
bool set_cell_left_padding(unsigned value);
bool set_cell_right_padding(unsigned value);
bool set_cell_empty_str_height(unsigned value);
bool set_cell_row_type(enum fort::row_type value);
bool set_cell_content_fg_color(enum fort::color value);
bool set_cell_bg_color(enum fort::color value);
bool set_cell_content_bg_color(enum fort::color value);
bool set_cell_text_style(enum fort::text_style value);
bool set_cell_content_text_style(enum fort::text_style value);
```
Properties can be set as default (for all cells in tables that will be created in the future),
for all cells of the specified table, for cells in the particular row of the specified table, for cells in the particular column of the specified table and for the particular cell of the specified table.
These examples illustrate it:
```C++
// Set top padding = 2 for all cells in all tables that will be later created
fort::table::default_props().set_cell_top_padding(2);
// Set row type for all cells in row 2
table.row(2).set_cell_row_type(fort::row_type::header);
// Set text alignment for all cells in column 1
table.column(1).set_cell_text_align(fort::text_align::center);
// Set min width of the cell(0,0)
table[0][0].set_cell_min_width(20);
```
Here is a simple complete example:
```C++
fort::char_table table;
// Fill table with data
table << fort::header
<< "Rank" << "Title" << "Year" << "Rating" << fort::endr
<< "1" << "The Shawshank Redemption" << "1994" << "9.5" << fort::endr
<< "2" << "12 Angry Men" << "1957" << "8.8" << fort::endr
<< "3" << "It's a Wonderful Life" << "1946" << "8.6" << fort::endr
<< fort::endr;
table[0][0].set_cell_min_width(20);
table.column(1).set_cell_text_align(fort::text_align::center);
table[3][3].set_cell_left_padding(15);
std::cout << table.to_string() << std::endl;
```
Output:
```
+--------------------+--------------------------+------+-------------------+
| Rank | Title | Year | Rating |
+--------------------+--------------------------+------+-------------------+
| 1 | The Shawshank Redemption | 1994 | 9.5 |
| 2 | 12 Angry Men | 1957 | 8.8 |
| 3 | It's a Wonderful Life | 1946 | 8.6 |
+--------------------+--------------------------+------+-------------------+
```

117
docs/tutorial/CPP_API/Filling-tables-with-data.md Normal file
View File

@@ -0,0 +1,117 @@
At each moment of time a **libfort** table has a current cell - cell to which data will be written in the next write operation.
Functions `set_cur_cell` and `operator<<(fort::endr)` can be used to change current cell:
```CPP
/* Set current cell to the cell with coordinates (row, col) */
void set_cur_cell(size_t row, size_t col)
/* Set current cell to the first cell of the next row(line) */
table << fort::endr;
```
There are a lot of functions that can be used to fill tables with data.
All write functions are grouped in pairs (**_function_**, **_function_ln_**), where **function** writes data to a group of consecutive cells, **function_ln** does the same and moves _current-cell_ pointer to the first cell of the next row(line).
### operator <<
This operator (`<<`) applied to a **libfort** table is known as insertion operator. It inserts string to the table cell. Internally **libfort** converts argument to a string using `std::stringstream`. If you want to insert argument of some custom type in a table you should overload `std::stringstream::operator<<`.
```CPP
fort::char_table table;
table << fort::header
<< "N" << "Driver" << "Time" << "Avg Speed" << fort::endr
<< "1" << "Ricciardo" << "1:25.945" << "47.362" << fort::endr
<< "2" << "Hamilton" << "1:26.373" << "35.02" << fort::endr
<< "3" << "Verstappen" << "1:26.469" << "29.78" << fort::endr;
std::cout << table.to_string() << std::endl;
```
Output:
```text
+---+------------+----------+-----------+
| N | Driver | Time | Avg Speed |
+---+------------+----------+-----------+
| 1 | Ricciardo | 1:25.945 | 222.128 |
| 2 | Hamilton | 1:26.373 | 221.027 |
| 3 | Verstappen | 1:26.469 | 220.782 |
+---+------------+----------+-----------+
```
### operator[]
This operator (`[]`) provides an ability to directly change content of a particular cell.
```CPP
fort::char_table table;
table << fort::header;
table[0][0] = "N"; table[0][1] = "Driver"; table[0][2] = "Time"; table[0][3] = "Avg Speed";
table[1][0] = "1"; table[1][1] = "Ricciardo"; table[1][2] = "1:25.945"; table[1][3] = "47.362";
table[2][0] = "2"; table[2][1] = "Hamilton"; table[2][2] = "1:26.373"; table[2][3] = "35.02";
table[3][0] = "3"; table[3][1] = "Verstappen"; table[3][2] = "1:26.469"; table[3][3] = "29.78";
std::cout << table.to_string() << std::endl;
```
Output:
```text
+---+------------+----------+-----------+
| N | Driver | Time | Avg Speed |
+---+------------+----------+-----------+
| 1 | Ricciardo | 1:25.945 | 222.128 |
| 2 | Hamilton | 1:26.373 | 221.027 |
| 3 | Verstappen | 1:26.469 | 220.782 |
+---+------------+----------+-----------+
```
### write, write_ln
`write`, `write_ln` write an arbitrary number of string arguments to the table cells.
```CPP
fort::char_table table;
table << fort::header;
table.write_ln("N", "Driver", "Time", "Avg Speed");
table.write_ln("1", "Ricciardo", "1:25.945", "47.362");
table.write_ln("2", "Hamilton", "1:26.373", "35.02");
table.write_ln("3", "Verstappen", "1:26.469", "29.78");
std::cout << table.to_string() << std::endl;
```
Output:
```text
+---+------------+----------+-----------+
| N | Driver | Time | Avg Speed |
+---+------------+----------+-----------+
| 1 | Ricciardo | 1:25.945 | 222.128 |
| 2 | Hamilton | 1:26.373 | 221.027 |
| 3 | Verstappen | 1:26.469 | 220.782 |
+---+------------+----------+-----------+
```
### range_write, range_write_ln
`range_write`, `range_write_ln` write data from a container determined by a pair of iterators.
```C++
template <typename InputIt>
bool range_write(InputIt first, InputIt last);
template <typename InputIt>
bool range_write_ln(InputIt first, InputIt last);
```
```C++
fort::char_table table;
table << fort::header;
std::vector<std::string> header = {"N", "Driver", "Time", "Avg Speed"};
std::list<std::string> line_1 = {"1", "Ricciardo", "1:25.945", "47.362"};
std::initializer_list<std::string> line_2 = {"2", "Hamilton", "1:26.373", "35.02"};
std::deque<std::string> line_3 = {"3", "Verstappen", "1:26.469", "29.78"};
table.range_write_ln(header.begin(), header.end());
table.range_write_ln(line_1.begin(), line_1.end());
table.range_write_ln(line_2.begin(), line_2.end());
table.range_write_ln(line_3.begin(), line_3.end());
std::cout << table.to_string() << std::endl;
```
Output:
```text
+---+------------+----------+-----------+
| N | Driver | Time | Avg Speed |
+---+------------+----------+-----------+
| 1 | Ricciardo | 1:25.945 | 222.128 |
| 2 | Hamilton | 1:26.373 | 221.027 |
| 3 | Verstappen | 1:26.469 | 220.782 |
+---+------------+----------+-----------+
```

30
docs/tutorial/CPP_API/Table-life-cycle.md Normal file
View File

@@ -0,0 +1,30 @@
The common **libfort table** life cycle:
- create a table (with default constructor, copy constructor or move constructor);
- fill it with data (`operator <<`, `operator[]`, `write_ln` ...);
- modify basic table appearance;
- convert table to string representation (`to_string`) and print it.
All resources allocated during table lifetime will be automatically freed in destructor.
Example:
```CPP
fort::char_table table;
table << fort::header
<< "N" << "Driver" << "Time" << "Avg Speed" << fort::endr
<< "1" << "Ricciardo" << "1:25.945" << "47.362" << fort::endr
<< "2" << "Hamilton" << "1:26.373" << "35.02" << fort::endr
<< "3" << "Verstappen" << "1:26.469" << "29.78" << fort::endr;
std::cout << table.to_string() << std::endl;
```
Output:
```
+---+------------+----------+-----------+
| N | Driver | Time | Avg Speed |
+---+------------+----------+-----------+
| 1 | Ricciardo | 1:25.945 | 47.362 |
| 2 | Hamilton | 1:26.373 | 35.02 |
| 3 | Verstappen | 1:26.469 | 29.78 |
+---+------------+----------+-----------+
```