lib/termtable.h

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