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