libsmartcols/src/column.c

   1 /*
   2  * column.c - functions for table handling at the column level
   3  *
   4  * Copyright (C) 2014 Ondrej Oprala <ooprala@redhat.com>
   5  * Copyright (C) 2014 Karel Zak <kzak@redhat.com>
   6  *
   7  * This file may be redistributed under the terms of the
   8  * GNU Lesser General Public License.
   9  */
  10
  11 /**
  12  * SECTION: column
  13  * @title: Column
  14  * @short_description: defines output columns formats, headers, etc.
  15  *
  16  * An API to access and modify per-column data and information.
  17  */
  18
  19
  20 #include <stdlib.h>
  21 #include <unistd.h>
  22 #include <string.h>
  23 #include <ctype.h>
  24
  25 #include "mbsalign.h"
  26
  27 #include "smartcolsP.h"
  28
  29 /**
  30  * scols_new_column:
  31  *
  32  * Allocates space for a new column.
  33  *
  34  * Returns: a pointer to a new struct libscols_column instance, NULL in case of an ENOMEM error.
  35  */
  36 struct libscols_column *scols_new_column(void)
  37 {
  38         struct libscols_column *cl;
  39
  40         cl = calloc(1, sizeof(*cl));
  41         if (!cl)
  42                 return NULL;
  43         DBG(COL, ul_debugobj(cl, "alloc"));
  44         cl->refcount = 1;
  45         INIT_LIST_HEAD(&cl->cl_columns);
  46         return cl;
  47 }
  48
  49 /**
  50  * scols_ref_column:
  51  * @cl: a pointer to a struct libscols_column instance
  52  *
  53  * Increases the refcount of @cl.
  54  */
  55 void scols_ref_column(struct libscols_column *cl)
  56 {
  57         if (cl)
  58                 cl->refcount++;
  59 }
  60
  61 /**
  62  * scols_unref_column:
  63  * @cl: a pointer to a struct libscols_column instance
  64  *
  65  * Decreases the refcount of @cl. When the count falls to zero, the instance
  66  * is automatically deallocated.
  67  */
  68 void scols_unref_column(struct libscols_column *cl)
  69 {
  70         if (cl && --cl->refcount <= 0) {
  71                 DBG(COL, ul_debugobj(cl, "dealloc"));
  72                 list_del(&cl->cl_columns);
  73                 scols_reset_cell(&cl->header);
  74                 free(cl->color);
  75                 free(cl->safechars);
  76                 free(cl->pending_data_buf);
  77                 free(cl);
  78         }
  79 }
  80
  81 /**
  82  * scols_copy_column:
  83  * @cl: a pointer to a struct libscols_column instance
  84  *
  85  * Creates a new column and copies @cl's data over to it.
  86  *
  87  * Returns: a pointer to a new struct libscols_column instance.
  88  */
  89 struct libscols_column *scols_copy_column(const struct libscols_column *cl)
  90 {
  91         struct libscols_column *ret;
  92
  93         if (!cl)
  94                 return NULL;
  95         ret = scols_new_column();
  96         if (!ret)
  97                 return NULL;
  98
  99         DBG(COL, ul_debugobj(cl, "copy"));
 100
 101         if (scols_column_set_color(ret, cl->color))
 102                 goto err;
 103         if (scols_cell_copy_content(&ret->header, &cl->header))
 104                 goto err;
 105
 106         ret->width      = cl->width;
 107         ret->width_min  = cl->width_min;
 108         ret->width_max  = cl->width_max;
 109         ret->width_avg  = cl->width_avg;
 110         ret->width_hint = cl->width_hint;
 111         ret->flags      = cl->flags;
 112         ret->is_extreme = cl->is_extreme;
 113         ret->is_groups  = cl->is_groups;
 114
 115         return ret;
 116 err:
 117         scols_unref_column(ret);
 118         return NULL;
 119 }
 120
 121 /**
 122  * scols_column_set_whint:
 123  * @cl: a pointer to a struct libscols_column instance
 124  * @whint: a width hint
 125  *
 126  * Sets the width hint of column @cl to @whint. See scols_table_new_column().
 127  *
 128  * Returns: 0, a negative value in case of an error.
 129  */
 130 int scols_column_set_whint(struct libscols_column *cl, double whint)
 131 {
 132         if (!cl)
 133                 return -EINVAL;
 134
 135         cl->width_hint = whint;
 136         return 0;
 137 }
 138
 139 /**
 140  * scols_column_get_whint:
 141  * @cl: a pointer to a struct libscols_column instance
 142  *
 143  * Returns: The width hint of column @cl, a negative value in case of an error.
 144  */
 145 double scols_column_get_whint(const struct libscols_column *cl)
 146 {
 147         return cl->width_hint;
 148 }
 149
 150 /**
 151  * scols_column_set_flags:
 152  * @cl: a pointer to a struct libscols_column instance
 153  * @flags: a flag mask
 154  *
 155  * Sets the flags of @cl to @flags.
 156  *
 157  * Returns: 0, a negative value in case of an error.
 158  */
 159 int scols_column_set_flags(struct libscols_column *cl, int flags)
 160 {
 161         if (!cl)
 162                 return -EINVAL;
 163
 164         if (cl->table) {
 165                 if (!(cl->flags & SCOLS_FL_TREE) && (flags & SCOLS_FL_TREE))
 166                         cl->table->ntreecols++;
 167                 else if ((cl->flags & SCOLS_FL_TREE) && !(flags & SCOLS_FL_TREE))
 168                         cl->table->ntreecols--;
 169         }
 170
 171         DBG(COL, ul_debugobj(cl, "setting flags from 0%x to 0%x", cl->flags, flags));
 172         cl->flags = flags;
 173         return 0;
 174 }
 175
 176 /**
 177  * scols_column_set_json_type:
 178  * @cl: a pointer to a struct libscols_column instance
 179  * @type: SCOLS_JSON_* type
 180  *
 181  * Sets the type used for JSON formatting, the default is SCOLS_JSON_STRING.
 182  *
 183  * Returns: 0, a negative value in case of an error.
 184  *
 185  * Since: 2.33
 186  */
 187 int scols_column_set_json_type(struct libscols_column *cl, int type)
 188 {
 189         if (!cl)
 190                 return -EINVAL;
 191
 192         cl->json_type = type;
 193         return 0;
 194
 195 }
 196
 197 /**
 198  * scols_column_get_json_type:
 199  * @cl: a pointer to a struct libscols_column instance
 200  *
 201  * Note that SCOLS_JSON_BOOLEAN interprets NULL, empty strings, '0', 'N' and
 202  * 'n' as "false"; and everything else as "true".
 203  *
 204  * Returns: JSON type used for formatting or a negative value in case of an error.
 205  *
 206  * Since: 2.33
 207  */
 208 int scols_column_get_json_type(const struct libscols_column *cl)
 209 {
 210         return cl ? cl->json_type : -EINVAL;
 211 }
 212
 213
 214 /**
 215  * scols_column_get_table:
 216  * @cl: a pointer to a struct libscols_column instance
 217  *
 218  * Returns: pointer to the table where columns is used
 219  */
 220 struct libscols_table *scols_column_get_table(const struct libscols_column *cl)
 221 {
 222         return cl->table;
 223 }
 224
 225 /**
 226  * scols_column_get_flags:
 227  * @cl: a pointer to a struct libscols_column instance
 228  *
 229  * Returns: The flag mask of @cl, a negative value in case of an error.
 230  */
 231 int scols_column_get_flags(const struct libscols_column *cl)
 232 {
 233         return cl->flags;
 234 }
 235
 236 /**
 237  * scols_column_get_header:
 238  * @cl: a pointer to a struct libscols_column instance
 239  *
 240  * Returns: A pointer to a struct libscols_cell instance, representing the
 241  * header info of column @cl or NULL in case of an error.
 242  */
 243 struct libscols_cell *scols_column_get_header(struct libscols_column *cl)
 244 {
 245         return &cl->header;
 246 }
 247
 248 /**
 249  * scols_column_set_color:
 250  * @cl: a pointer to a struct libscols_column instance
 251  * @color: color name or ESC sequence
 252  *
 253  * The default color for data cells and column header.
 254  *
 255  * If you want to set header specific color then use scols_column_get_header()
 256  * and scols_cell_set_color().
 257  *
 258  * If you want to set data cell specific color the use scols_line_get_cell() +
 259  * scols_cell_set_color().
 260  *
 261  * Returns: 0, a negative value in case of an error.
 262  */
 263 int scols_column_set_color(struct libscols_column *cl, const char *color)
 264 {
 265         if (color && isalpha(*color)) {
 266                 color = color_sequence_from_colorname(color);
 267                 if (!color)
 268                         return -EINVAL;
 269         }
 270         return strdup_to_struct_member(cl, color, color);
 271 }
 272
 273 /**
 274  * scols_column_get_color:
 275  * @cl: a pointer to a struct libscols_column instance
 276  *
 277  * Returns: The current color setting of the column @cl.
 278  */
 279 const char *scols_column_get_color(const struct libscols_column *cl)
 280 {
 281         return cl->color;
 282 }
 283
 284 /**
 285  * scols_wrapnl_nextchunk:
 286  * @cl: a pointer to a struct libscols_column instance
 287  * @data: string
 288  * @userdata: callback private data
 289  *
 290  * This is built-in function for scols_column_set_wrapfunc(). This function
 291  * terminates the current chunk by \0 and returns pointer to the begin of
 292  * the next chunk. The chunks are based on \n.
 293  *
 294  * For example for data "AAA\nBBB\nCCC" the next chunk is "BBB".
 295  *
 296  * Returns: next chunk
 297  *
 298  * Since: 2.29
 299  */
 300 char *scols_wrapnl_nextchunk(const struct libscols_column *cl __attribute__((unused)),
 301                         char *data,
 302                         void *userdata __attribute__((unused)))
 303 {
 304         char *p = data ? strchr(data, '\n') : NULL;
 305
 306         if (p) {
 307                 *p = '\0';
 308                 return p + 1;
 309         }
 310         return NULL;
 311 }
 312
 313 /**
 314  * scols_wrapnl_chunksize:
 315  * @cl: a pointer to a struct libscols_column instance
 316  * @data: string
 317  * @userdata: callback private data
 318  *
 319  * Analyzes @data and returns size of the largest chunk. The chunks are based
 320  * on \n. For example for data "AAA\nBBB\nCCCC" the largest chunk size is 4.
 321  *
 322  * Note that the size has to be based on number of terminal cells rather than
 323  * bytes to support multu-byte output.
 324  *
 325  * Returns: size of the largest chunk.
 326  *
 327  * Since: 2.29
 328  */
 329 size_t scols_wrapnl_chunksize(const struct libscols_column *cl __attribute__((unused)),
 330                 const char *data,
 331                 void *userdata __attribute__((unused)))
 332 {
 333         size_t sum = 0;
 334
 335         while (data && *data) {
 336                 const char *p;
 337                 size_t sz;
 338
 339                 p = strchr(data, '\n');
 340                 if (p) {
 341                         sz = cl->table && scols_table_is_noencoding(cl->table) ?
 342                                         mbs_nwidth(data, p - data) :
 343                                         mbs_safe_nwidth(data, p - data, NULL);
 344                         p++;
 345                 } else {
 346                         sz = cl->table && scols_table_is_noencoding(cl->table) ?
 347                                         mbs_width(data) :
 348                                         mbs_safe_width(data);
 349                 }
 350                 sum = max(sum, sz);
 351                 data = p;
 352         }
 353
 354         return sum;
 355 }
 356
 357 /**
 358  * scols_column_set_cmpfunc:
 359  * @cl: column
 360  * @cmp: pointer to compare function
 361  * @data: private data for cmp function
 362  *
 363  * Returns: 0, a negative value in case of an error.
 364  */
 365 int scols_column_set_cmpfunc(struct libscols_column *cl,
 366                         int (*cmp)(struct libscols_cell *,
 367                                    struct libscols_cell *,
 368                                    void *),
 369                         void *data)
 370 {
 371         if (!cl)
 372                 return -EINVAL;
 373
 374         cl->cmpfunc = cmp;
 375         cl->cmpfunc_data = data;
 376         return 0;
 377 }
 378
 379 /**
 380  * scols_column_set_wrapfunc:
 381  * @cl: a pointer to a struct libscols_column instance
 382  * @wrap_chunksize: function to return size of the largest chink of data
 383  * @wrap_nextchunk: function to return next zero terminated data
 384  * @userdata: optional stuff for callbacks
 385  *
 386  * Extends SCOLS_FL_WRAP and allows to set custom wrap function. The default
 387  * is to wrap by column size, but you can create functions to wrap for example
 388  * after \n or after words, etc.
 389  *
 390  * Returns: 0, a negative value in case of an error.
 391  *
 392  * Since: 2.29
 393  */
 394 int scols_column_set_wrapfunc(struct libscols_column *cl,
 395                         size_t (*wrap_chunksize)(const struct libscols_column *,
 396                                                  const char *,
 397                                                  void *),
 398                         char * (*wrap_nextchunk)(const struct libscols_column *,
 399                                                  char *,
 400                                                  void *),
 401                         void *userdata)
 402 {
 403         if (!cl)
 404                 return -EINVAL;
 405
 406         cl->wrap_nextchunk = wrap_nextchunk;
 407         cl->wrap_chunksize = wrap_chunksize;
 408         cl->wrapfunc_data = userdata;
 409         return 0;
 410 }
 411
 412 /**
 413  * scols_column_set_safechars:
 414  * @cl: a pointer to a struct libscols_column instance
 415  * @safe: safe characters (e.g. "\n\t")
 416  *
 417  * Use for bytes you don't want to encode on output. This is for example
 418  * necessary if you want to use custom wrap function based on \n, in this case
 419  * you have to set "\n" as a safe char.
 420  *
 421  * Returns: 0, a negative value in case of an error.
 422  *
 423  * Since: 2.29
 424  */
 425 int scols_column_set_safechars(struct libscols_column *cl, const char *safe)
 426 {
 427         return strdup_to_struct_member(cl, safechars, safe);
 428 }
 429
 430 /**
 431  * scols_column_get_safechars:
 432  * @cl: a pointer to a struct libscols_column instance
 433  *
 434  * Returns: safe chars
 435  *
 436  * Since: 2.29
 437  */
 438 const char *scols_column_get_safechars(const struct libscols_column *cl)
 439 {
 440         return cl->safechars;
 441 }
 442
 443 /**
 444  * scols_column_get_width:
 445  * @cl: a pointer to a struct libscols_column instance
 446  *
 447  * Important note: the column width is unknown until library starts printing
 448  * (width is calculated before printing). The function is usable for example in
 449  * nextchunk() callback specified by scols_column_set_wrapfunc().
 450  *
 451  * See also scols_column_get_whint(), it returns wanted size (!= final size).
 452  *
 453  * Returns: column width
 454  *
 455  * Since: 2.29
 456  */
 457 size_t scols_column_get_width(const struct libscols_column *cl)
 458 {
 459         return cl->width;
 460 }
 461
 462 /**
 463  * scols_column_is_hidden:
 464  * @cl: a pointer to a struct libscols_column instance
 465  *
 466  * Gets the value of @cl's flag hidden.
 467  *
 468  * Returns: 0 or 1
 469  *
 470  * Since: 2.27
 471  */
 472 int scols_column_is_hidden(const struct libscols_column *cl)
 473 {
 474         return cl->flags & SCOLS_FL_HIDDEN ? 1 : 0;
 475 }
 476
 477 /**
 478  * scols_column_is_trunc:
 479  * @cl: a pointer to a struct libscols_column instance
 480  *
 481  * Gets the value of @cl's flag trunc.
 482  *
 483  * Returns: 0 or 1
 484  */
 485 int scols_column_is_trunc(const struct libscols_column *cl)
 486 {
 487         return cl->flags & SCOLS_FL_TRUNC ? 1 : 0;
 488 }
 489 /**
 490  * scols_column_is_tree:
 491  * @cl: a pointer to a struct libscols_column instance
 492  *
 493  * Gets the value of @cl's flag tree.
 494  *
 495  * Returns: 0 or 1
 496  */
 497 int scols_column_is_tree(const struct libscols_column *cl)
 498 {
 499         return cl->flags & SCOLS_FL_TREE ? 1 : 0;
 500 }
 501 /**
 502  * scols_column_is_right:
 503  * @cl: a pointer to a struct libscols_column instance
 504  *
 505  * Gets the value of @cl's flag right.
 506  *
 507  * Returns: 0 or 1
 508  */
 509 int scols_column_is_right(const struct libscols_column *cl)
 510 {
 511         return cl->flags & SCOLS_FL_RIGHT ? 1 : 0;
 512 }
 513 /**
 514  * scols_column_is_strict_width:
 515  * @cl: a pointer to a struct libscols_column instance
 516  *
 517  * Gets the value of @cl's flag strict_width.
 518  *
 519  * Returns: 0 or 1
 520  */
 521 int scols_column_is_strict_width(const struct libscols_column *cl)
 522 {
 523         return cl->flags & SCOLS_FL_STRICTWIDTH ? 1 : 0;
 524 }
 525 /**
 526  * scols_column_is_noextremes:
 527  * @cl: a pointer to a struct libscols_column instance
 528  *
 529  * Gets the value of @cl's flag no_extremes.
 530  *
 531  * Returns: 0 or 1
 532  */
 533 int scols_column_is_noextremes(const struct libscols_column *cl)
 534 {
 535         return cl->flags & SCOLS_FL_NOEXTREMES ? 1 : 0;
 536 }
 537 /**
 538  * scols_column_is_wrap:
 539  * @cl: a pointer to a struct libscols_column instance
 540  *
 541  * Gets the value of @cl's flag wrap.
 542  *
 543  * Returns: 0 or 1
 544  *
 545  * Since: 2.28
 546  */
 547 int scols_column_is_wrap(const struct libscols_column *cl)
 548 {
 549         return cl->flags & SCOLS_FL_WRAP ? 1 : 0;
 550 }
 551 /**
 552  * scols_column_is_customwrap:
 553  * @cl: a pointer to a struct libscols_column instance
 554  *
 555  * Returns: 0 or 1
 556  *
 557  * Since: 2.29
 558  */
 559 int scols_column_is_customwrap(const struct libscols_column *cl)
 560 {
 561         return (cl->flags & SCOLS_FL_WRAP)
 562                 && cl->wrap_chunksize
 563                 && cl->wrap_nextchunk ? 1 : 0;
 564 }