12.2 Table Formatting
| import: rhombus/tabular | package: rhombus-lib |
The rhombus/tabular module extends the str namespace with str.tabular for formatting a two-dimensional table of strings.
function | |||||||||||
| |||||||||||
| |||||||||||
enumeration | |||||||||||
|
> println(str.tabular([["apple", "banana"],
["cherry", "durian"]]))
apple banana
cherrydurian
> println(str.tabular([["apple", "banana"],
["cherry", "durian"]],
~pad: [1, 0],
~cell_properties: [[#'border]]))
+--------+--------+
| apple | banana |
+--------+--------+
| cherry | durian |
+--------+--------+
The resulting string has newlines for a table that has multiple rows, but it does not end in a newline after the last row. Each cell string can itself contain newlines, in which case the corresponding cell will span multiple lines, and the resulting string will have newlines even if it formats just one row.
[["fruits", str.tabular([["apple", "banana"],
["cherry", "durian"]],
~pad: [1, 0],
~cell_properties: [[#'border]])],
["veggies", str.tabular([["eggplant"]],
~cell_properties: [[#'border]])]],
~pad: [1, 0],
~cell_properties: [[#'vcenter]]
))
+--------+--------+
| apple | banana |
fruits +--------+--------+
| cherry | durian |
+--------+--------+
+--------+
veggies |eggplant|
+--------+
A cell that is not in the first column of a row can be #'cont to indicate that the previous cell’s content continues into the next column. Table formatting ensures that spanned columns via #'cont are together wide enough for the cell content, instead of requiring just the content’s first cell to fit the entire content.
> println(str.tabular([["apple", "banana"],
["cantaloupe", #'cont]],
~pad: [1, 0],
~cell_properties: [[#'border]]))
+-------+--------+
| apple | banana |
+-------+--------+
| cantaloupe |
+-------+--------+
If pad is not a str.CellPadding, it is converted to one by treating a single as a padding for all sizes, a list of two Nats and horizontal and vertical padding, and a list of four Nat as left, top, right, and bottom padding. The normalized pad becomes the default property for all cells.
Each property (or list of propertie) in colum_properties is then combined with the properties accumulated so far for each cell in the corresponding column, where the last elemen of colum_properties (is any) is duplicated when thete are more column cells than elements of colum_properties. Combining means that properties in colum_properties can complement or supercede the padding specified as pad.
Along similar lines, each property (or list of properties) in row_properties is combined, dupliacting the last element of row_properties as needed to match the number of cell rows, complementing and superceding any properties from colum_properties.
Finally, cell_properties provides cell-specific properties, where the last lists of cell_properties is duplicated as need to match the number of cell rows, and the last element of each list in cell_properties is duplicated as need to match the cell columns. These cell-specific properties complement or supercede properties from row_properties, colum_properties, and pad.
[["apple", "banana"],
["cherry", "durian"]],
~pad: [1, 0],
~column_properties: [[#'left_border, #'right_border], #'border]
))
+--------+--------+
| apple | banana |
| +--------+
| cherry | durian |
+--------+--------+
The default alignment for a cell is #'left and #'top, and a cell has no broders by default.
enumeration | |||||
| |||||
| |||||
annotation | |||||
The str.CellProperties annotation is equivalent to str.CellProperty || List.of(str.CellProperty). The individual elements in a list of cell properties provided to str.tabular satisfy str.CellProperties, which means that each can be a single property or a list of properties to combine for a cell.
enumeration | ||||
enumeration | ||||||
Merging for border options is cumulative, combining #'left_border with an existing #'border option is the same as #'border, not a reduction in borders to just #'left_border.
Borders overlaop on the shared edge of adjacent cells. For example, if one cell has #'right_border and the cell just to its right has #'left_border, then only one border is drawn, and it’s the same if either #'right_border or #'left_border (but not both) is removed.
class | |||||||||||
|