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