|
1 | 1 | Table |
2 | 2 | =============================================================================== |
3 | 3 |
|
4 | | -A `Table` in Mech is a set of records, where each record corresponds to a row and each column has a name and kind. Tables provide structured, columnar data that is flexible and human-readable. |
| 4 | +A table in Mech is a set of records, where each record corresponds to a row and each column has a name and kind. Tables provide structured, columnar data that is flexible and human-readable. |
5 | 5 |
|
6 | 6 | 1. Syntax |
7 | 7 | ------------------------------------------------------------------------------- |
8 | 8 |
|
9 | | -Tables are defined using curly braces `{}` with named columns and a vertical bar `|` to separate column headers from data rows. |
| 9 | +(1.1) Basic Syntax |
10 | 10 |
|
11 | | -```mech |
12 | | -| x<f32> y<u8> | |
13 | | -| 1.2 9 | |
14 | | -| 1.3 8 | |
15 | | -``` |
| 11 | +Tables are defined using the pipe `|` character. Each column is defined with a name and a kind, which describes the type of data it holds. |
16 | 12 |
|
17 | | -This creates a table with two columns, `x` of kind `f32` and `y` of kind `u8`. |
| 13 | +``` |
| 14 | +| x<f32> y<bool> | |
| 15 | +| 1.2 true | |
| 16 | +| 1.3 false | |
| 17 | +``` |
18 | 18 |
|
19 | | -You can write tables inline using semicolons to separate rows: |
| 19 | +This creates a table with two columns, `x` of kind `f32` and `y` of kind `bool`: |
20 | 20 |
|
21 | | -```mech |
22 | | -| x<f32> y<u8> |{ 1.2 9; 1.3 8 } |
| 21 | +```mech:disabled |
| 22 | +| x<f32> y<bool> | |
| 23 | +| 1.2 true | |
| 24 | +| 1.3 false | |
23 | 25 | ``` |
24 | 26 |
|
25 | | -2. Heterogeneous Columns |
26 | | - |
27 | | ---- |
| 27 | +(1.2) Inline Syntax |
28 | 28 |
|
29 | | -The kind `_` indicates that a column may contain heterogeneous data: |
| 29 | +You can write tables inline as well: |
30 | 30 |
|
31 | | -```mech |
32 | | -| x<_> y<_> | |
33 | | -| 1.2 true| |
34 | | -| "Hi" 8 | |
| 31 | +``` |
| 32 | +| x<f32> y<bool> | 1.2 true | 1.3 false | |
35 | 33 | ``` |
36 | 34 |
|
37 | | -Each cell in the column may hold a different type of value. |
| 35 | +(1.3) Fancy Syntax |
38 | 36 |
|
39 | | -3. Partial Rows |
| 37 | +The Mech REPL formats matrix output using fancy box drawing characters for better readability. |
40 | 38 |
|
41 | | ---- |
| 39 | +``` |
| 40 | +╭────────┬─────────╮ |
| 41 | +│ x<f32> │ y<bool> │ |
| 42 | +├────────┼─────────┤ |
| 43 | +│ 1.2 │ true │ |
| 44 | +│ 1.3 │ false │ |
| 45 | +╰────────┴─────────╯ |
| 46 | +``` |
42 | 47 |
|
43 | | -You can omit values in certain rows using `_` to indicate a missing value: |
| 48 | +Mech can parse data formatted this way, allowing you to copy or pipe REPL output directly into a Mech program that expects a table. The above example evaluates to: |
44 | 49 |
|
45 | | -```mech |
46 | | -| x<u8> y<string> z<[u8]:3> | |
47 | | -| _ "a" [1;2;3] | |
48 | | -| 4 "b" _ | |
49 | | -| 7 _ [7;8;9] | |
| 50 | +```mech:disabled |
| 51 | +╭────────┬─────────╮ |
| 52 | +│ x<u64> │ y<bool> │ |
| 53 | +├────────┼─────────┤ |
| 54 | +│ 1.2 │ true │ |
| 55 | +│ 1.3 │ false │ |
| 56 | +╰────────┴─────────╯ |
50 | 57 | ``` |
51 | 58 |
|
52 | | -4. Fancy Formatting |
| 59 | +Fancy tables can be formatted in a variety of ways: |
53 | 60 |
|
54 | | ---- |
| 61 | +``` |
| 62 | +╭────────┬────────╮ |
| 63 | +│ x<u64> │ y<f32> │ |
| 64 | +├────────┼────────┤ |
| 65 | +│ 1 │ 2 │ |
| 66 | +├────────┼────────┤ |
| 67 | +│ 3 │ 4 │ |
| 68 | +╰────────┴────────╯ |
| 69 | +``` |
55 | 70 |
|
56 | | -Tables can be displayed using a box-drawn format in the REPL for improved readability: |
| 71 | +This one has no horizontal lines between rows, making it more compact: |
57 | 72 |
|
58 | 73 | ``` |
59 | | -╭────────────────────────────────╮ |
60 | | -│ x<u8> y<string> z<[u8]:1,3> │ |
61 | | -├───────┬──────────┬─────────────┤ |
62 | | -│ _ │ "a" │ [1,2,3,4] │ |
63 | | -├───────┼──────────┼─────────────┤ |
64 | | -│ 4 │ "b" │ _ │ |
65 | | -├───────┼──────────┼─────────────┤ |
66 | | -│ 7 │ _ │ [5,6,7,8] │ |
67 | | -╰───────┴──────────┴─────────────╯ |
| 74 | +╭────────┬────────╮ |
| 75 | +│ x<u64> │ y<f32> │ |
| 76 | +│ 1 │ 2 │ |
| 77 | +│ 3 │ 4 │ |
| 78 | +╰────────┴────────╯ |
68 | 79 | ``` |
69 | 80 |
|
| 81 | +2. Kind |
| 82 | +-------------------------------------------------------------------------------- |
| 83 | + |
| 84 | +A table's kind describes the names and kinds of the columns, as well as the number of rows in the table. For example: |
| 85 | + |
| 86 | + <|x<u8> y<f32>|:3> |
| 87 | + |
| 88 | +This represents a table with two columns, `x` of kind `u8` and `y` of kind `f32`, and 3 rows. |
| 89 | + |
| 90 | +3. Construction |
| 91 | +------------------------------------------------------------------------------- |
| 92 | + |
| 93 | +Tables can be constructed of vectors, matrices, or records. |
| 94 | + |
| 95 | +(3.1) From vectors |
| 96 | + |
| 97 | +(3.2) From a matrix |
| 98 | + |
| 99 | +(3.3) From records |
| 100 | + |
| 101 | +4. Accessing Elements |
| 102 | +------------------------------------------------------------------------------- |
| 103 | + |
| 104 | +Consider the table: |
| 105 | + |
| 106 | +a:=| x<f32> y<bool> | |
| 107 | + | 1.2 true | |
| 108 | + | 1.3 false | |
| 109 | + |
| 110 | +(4.1) Access a Column |
| 111 | + |
| 112 | +Use dot indexing to access columns. For example {{a.x;}}. The kind of the result is a column vector with elements of the column's kind. For instance, column `x` has kind `f32`, so the result of accessing that column is a column vector of kind `[f32]`, with the same number of rows as the table: |
| 113 | + |
| 114 | +```mech |
| 115 | +a.x -- Select column `x`, which has kind `[f32]` |
70 | 116 | ``` |
71 | | -╭────────────────────────────────╮ |
72 | | -│ x<u8> y<string> z<[u8]:1,3> │ |
73 | | -├───────┬──────────┬─────────────┤ |
74 | | -│ _ │ "a" │ [1,2,3,4] │ |
75 | | -│ 4 │ "b" │ _ │ |
76 | | -│ 7 │ _ │ [5,6,7,8] │ |
77 | | -╰───────┴──────────┴─────────────╯ |
| 117 | + |
| 118 | +(4.2) Access Elements |
| 119 | + |
| 120 | +You can access an individual element in a table column by specifying the row index on the selected column: |
| 121 | + |
| 122 | +```mech |
| 123 | +a.x[1] -- Select the first element of column `x`, which has kind `f32` |
78 | 124 | ``` |
79 | 125 |
|
80 | | -5. Kind |
| 126 | +Table columns are just vectors, so they support the same indexing operations as vectors. |
81 | 127 |
|
82 | | ---- |
| 128 | +(4.3) Access a Record |
83 | 129 |
|
84 | | -A table's kind describes the types and structure of its columns and dimensions. For example: |
| 130 | +You can access a record in a table by specifying the row index on the table itself: |
85 | 131 |
|
86 | 132 | ```mech |
87 | | -<{u8,string,[u8]:3}:3,3> |
| 133 | +a{1} -- Select the first record in the table, which has kind `record` |
88 | 134 | ``` |
89 | 135 |
|
90 | | -This represents a table with three columns of kinds `u8`, `string`, and `[u8]:3`, and three rows. |
| 136 | +5. Heterogeneous Columns |
| 137 | +------------------------------------------------------------------------------- |
91 | 138 |
|
92 | | -6. Notes |
| 139 | +The kind `*` indicates that a column may contain heterogeneous data: |
93 | 140 |
|
94 | | ---- |
| 141 | +```mech:disabled |
| 142 | +| x<*> y<*> | |
| 143 | +| 1.2 true| |
| 144 | +| "Hi" 8 | |
| 145 | +``` |
95 | 146 |
|
96 | | -* Tables are more expressive than matrices and can store structured data. |
97 | | -* They support mixed kinds per column and partial rows. |
98 | | -* Tables are generally slower than matrices due to their flexibility. |
| 147 | +Each cell in the column may hold a different type of value. |
| 148 | + |
| 149 | +(5.1) Partial Columns |
| 150 | + |
| 151 | +You can omit values in the table using using `_` to indicate a missing value. In this case, the kind of the column must be annotated with an `option` kind, indicated by a `?` suffix: |
| 152 | + |
| 153 | +```mech:disabled |
| 154 | +| x<u8?> y<string?> z<[u8]:1,3?> | |
| 155 | +| _ "a" [1 2 3] | |
| 156 | +| 4 "b" _ | |
| 157 | +| 7 _ [7 8 9] | |
| 158 | +``` |
0 commit comments