lib/termtable.h

   1 // SPDX-License-Identifier: GPL-2.0-or-later
   2 /*
   3  * ASCII table generator.
   4  * Copyright (C) 2017  Cumulus Networks
   5  * Quentin Young
   6  */
   7 #ifndef _TERMTABLE_H_
   8 #define _TERMTABLE_H_
   9
  10 #include <zebra.h>
  11
  12 #ifdef __cplusplus
  13 extern "C" {
  14 #endif
  15
  16 enum ttable_align {
  17         LEFT,
  18         RIGHT,
  19         TOP,
  20         BOTTOM,
  21 };
  22
  23 struct ttable_border {
  24         char top;
  25         char bottom;
  26         char left;
  27         char right;
  28
  29         bool top_on;
  30         bool bottom_on;
  31         bool left_on;
  32         bool right_on;
  33 };
  34
  35 /* cell style and cell */
  36 struct ttable_cellstyle {
  37         short lpad;
  38         short rpad;
  39         enum ttable_align align;
  40         struct ttable_border border;
  41 };
  42
  43 struct ttable_cell {
  44         char *text;
  45         struct ttable_cellstyle style;
  46 };
  47
  48 /* table style and table */
  49 struct ttable_style {
  50         char corner;     /* intersection */
  51         int indent;      /* left table indent */
  52         bool rownums_on; /* show row numbers; unimplemented */
  53
  54         struct ttable_border border;
  55         struct ttable_cellstyle cell;
  56 };
  57
  58 struct ttable {
  59         int nrows;                  /* number of rows */
  60         int ncols;                  /* number of cols */
  61         struct ttable_cell **table; /* table, row x col */
  62         size_t size;                /* size */
  63         struct ttable_style style;  /* style */
  64 };
  65
  66 /* some predefined styles */
  67 #define TTSTYLE_ASCII 0
  68 #define TTSTYLE_BLANK 1
  69
  70 extern const struct ttable_style ttable_styles[2];
  71
  72 /**
  73  * Creates a new table with the default style, which looks like this:
  74  *
  75  * +----------+----------+
  76  * | column 1 | column 2 |
  77  * +----------+----------+
  78  * | data...  | data!!   |
  79  * +----------+----------+
  80  * | datums   | 12345    |
  81  * +----------+----------+
  82  *
  83  * @return the created table
  84  */
  85 struct ttable *ttable_new(const struct ttable_style *tts);
  86
  87 /**
  88  * Deletes a table and releases all associated resources.
  89  *
  90  * @param tt the table to destroy
  91  */
  92 void ttable_del(struct ttable *tt);
  93
  94 /**
  95  * Inserts a new row at the given index.
  96  *
  97  * The row contents are determined by a format string. The format string has
  98  * the same form as a regular printf format string, except that columns are
  99  * delimited by '|'. For example, to make the first column of the table above,
 100  * the call is:
 101  *
 102  *   ttable_insert_row(<tt>, <n>, "%s|%s", "column 1", "column 2");
 103  *
 104  * All features of printf format strings are permissible here.
 105  *
 106  * Caveats:
 107  *  - At present you cannot insert '|' into a cell's contents.
 108  *  - If there are N columns, '|' must appear n-1 times or the row will not be
 109  *    created
 110  *
 111  * @param tt table to insert row into
 112  * @param row the row number (begins at 0)
 113  * @param format column-separated format string
 114  * @param ... arguments to format string
 115  *
 116  * @return pointer to the first cell in the created row, or NULL if not enough
 117  * columns were specified
 118  */
 119 struct ttable_cell *ttable_insert_row(struct ttable *tt, unsigned int row,
 120                                       const char *format, ...) PRINTFRR(3, 4);
 121 /**
 122  * Inserts a new row at the end of the table.
 123  *
 124  * The row contents are determined by a format string. The format string has
 125  * the same form as a regular printf format string, except that columns are
 126  * delimited by '|'. For example, to make the first column of the table above,
 127  * the call is:
 128  *
 129  *   ttable_add_row(<tt>, "%s|%s", "column 1", "column 2");
 130  *
 131  * All features of printf format strings are permissible here.
 132  *
 133  * Caveats:
 134  *  - At present you cannot insert '|' into a cell's contents.
 135  *  - If there are N columns, '|' must appear n-1 times or the row will not be
 136  *    created
 137  *
 138  * @param tt table to insert row into
 139  * @param format column-separated format string
 140  * @param ... arguments to format string
 141  *
 142  * @return pointer to the first cell in the created row, or NULL if not enough
 143  * columns were specified
 144  */
 145 struct ttable_cell *ttable_add_row(struct ttable *tt, const char *format, ...)
 146         PRINTFRR(2, 3);
 147
 148 /**
 149  * Removes a row from the table.
 150  *
 151  * @param tt table to delete row from
 152  * @param row the row number (begins at 0)
 153  */
 154 void ttable_del_row(struct ttable *tt, unsigned int row);
 155
 156 /**
 157  * Sets alignment for a range of cells.
 158  *
 159  * Available alignments are LEFT and RIGHT. Cell contents will be aligned
 160  * accordingly, while respecting padding (if any). Suppose a cell has:
 161  *
 162  * lpad = 1
 163  * rpad = 1
 164  * align = RIGHT
 165  * text = 'datums'
 166  *
 167  * The cell would look like:
 168  *
 169  *  +-------------------+
 170  *  |            datums |
 171  *  +-------------------+
 172  *
 173  * On the other hand:
 174  *
 175  * lpad = 1
 176  * rpad = 10
 177  * align = RIGHT
 178  * text = 'datums'
 179  *
 180  *  +-------------------+
 181  *  |   datums          |
 182  *  +-------------------+
 183  *
 184  * The default alignment is LEFT.
 185  *
 186  * @param tt the table to set alignment on
 187  * @param srow starting row index
 188  * @param scol starting column index
 189  * @param nrow # rows to align
 190  * @param ncol # cols to align
 191  * @param align the alignment to set
 192  */
 193 void ttable_align(struct ttable *tt, unsigned int srow, unsigned int scol,
 194                   unsigned int erow, unsigned int ecol,
 195                   enum ttable_align align);
 196
 197 /**
 198  * Sets padding for a range of cells.
 199  *
 200  * Available padding options are LEFT and RIGHT (the alignment enum is reused).
 201  * Both options may be set. Padding is treated as though it is stuck to the
 202  * walls of the cell. Suppose a cell has:
 203  *
 204  * lpad = 4
 205  * rpad = 2
 206  * align = RIGHT
 207  * text = 'datums'
 208  *
 209  * The cell padding, marked by '.', would look like:
 210  *
 211  *  +--------------+
 212  *  |    .datums.  |
 213  *  +--------------+
 214  *
 215  * If the column is wider than the cell, the cell contents are aligned in an
 216  * additional padded field according to the cell alignment.
 217  *
 218  *  +--------------------+
 219  *  | Data!!!11!~~~~~:-) |
 220  *  +--------------------+
 221  *  |    .      datums.  |
 222  *  +--------------------+
 223  *
 224  * @param tt the table to set padding on
 225  * @param srow starting row index
 226  * @param scol starting column index
 227  * @param nrow # rows to pad
 228  * @param ncol # cols to pad
 229  * @param align LEFT or RIGHT
 230  * @param pad # spaces to pad with
 231  */
 232 void ttable_pad(struct ttable *tt, unsigned int srow, unsigned int scol,
 233                 unsigned int nrow, unsigned int ncol, enum ttable_align align,
 234                 short pad);
 235
 236 /**
 237  * Restyle all cells according to table.cell.style.
 238  *
 239  * @param tt table to restyle
 240  */
 241 void ttable_restyle(struct ttable *tt);
 242
 243 /**
 244  * Turn left/right column separators on or off for specified column.
 245  *
 246  * @param tt table
 247  * @param col column index
 248  * @param align left or right separators
 249  * @param on true/false for on/off
 250  * @param sep character to use
 251  */
 252 void ttable_colseps(struct ttable *tt, unsigned int col,
 253                     enum ttable_align align, bool on, char sep);
 254
 255 /**
 256  * Turn bottom row separators on or off for specified row.
 257  *
 258  * @param tt table
 259  * @param row row index
 260  * @param align left or right separators
 261  * @param on true/false for on/off
 262  * @param sep character to use
 263  */
 264 void ttable_rowseps(struct ttable *tt, unsigned int row,
 265                     enum ttable_align align, bool on, char sep);
 266
 267 /**
 268  * Dumps a table to a heap-allocated string.
 269  *
 270  * Caller must free this string after use with
 271  *
 272  *   XFREE (MTYPE_TMP, str);
 273  *
 274  * @param tt the table to dump
 275  * @param newline the desired newline sequence to use, null terminated.
 276  * @return table in text form
 277  */
 278 char *ttable_dump(struct ttable *tt, const char *newline);
 279
 280 #ifdef __cplusplus
 281 }
 282 #endif
 283
 284 #endif /* _TERMTABLE_H */