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