From: Robert Kessl <kesslr@centrum.cz>
Date: Wed, 25 Jun 2014 10:23:46 +0000 (+0200)
Subject: Merge remote-tracking branch 'origin/master'
X-Git-Tag: v6.1~22
X-Git-Url: http://mj.ucw.cz/gitweb/?a=commitdiff_plain;h=9a55005de5452fd7a970ad2b04c3407572ecc194;p=libucw.git

Merge remote-tracking branch 'origin/master'

Conflicts:
	ucw/table.h
---

9a55005de5452fd7a970ad2b04c3407572ecc194
diff --cc ucw/table.h
index 0244d759,9ce8718d..cd030b7f
--- a/ucw/table.h
+++ b/ucw/table.h
@@@ -257,49 -294,86 +294,91 @@@ void table_col_fbend(struct table *tbl)
   **/
  void table_end_row(struct table *tbl);
  
 +/**
 + * Cleans current row, When called.
 + **/
 +void table_clean_row(struct table *tbl);
 +
+ /***
+  * Configuration functions
+  * -----------------------
+  ***/
+ 
  /**
-  * Prints a string that is printf-like formated into a particular column. This function does not check the
-  * type of the column, i.e., it can be used to print double into an int column
+  * Find the index of a column with name @col_name. Returns -1 if there is no such column.
   **/
- void table_col_printf(struct table *tbl, int col, const char *fmt, ...) FORMAT_CHECK(printf, 3, 4);
+ int table_get_col_idx(struct table *tbl, const char *col_name);
  
  /**
-  * Appends a string that is printf-like formated to the last printed column. This function does not check the
-  * type of the column, i.e., it can be used to print double into an int column.
+  * Returns a comma-and-space-separated list of column names, allocated from table's internal
+  * memory pool.
   **/
- void table_append_printf(struct table *tbl, const char *fmt, ...) FORMAT_CHECK(printf, 2, 3);
+ const char *table_get_col_list(struct table *tbl);
  
  /**
-  * Find the index of a column with name @col_name and returns it. Returns -1 if the column was not found.
+  * Sets the order in which the columns are printed. The @col_order parameter is used until @table_end() or
+  * @table_cleanup() is called. The table stores only the pointer and the memory pointed to by @col_order is
+  * allocated and deallocated by the caller.
   **/
- int table_get_col_idx(struct table *tbl, const char *col_name);
+ void table_set_col_order(struct table *tbl, int *col_order, int col_order_size);
  
  /**
-  * Returns comma-and-space-separated list of column names, allocated from table's internal
-  * memory pool.
+  * Sets the order in which the columns are printed. The specification is a string with comma-separated column
+  * names. Returns NULL for success and an error message otherwise. The string is not referenced after
+  * this function returns.
   **/
- const char *table_get_col_list(struct table *tbl);
+ const char *table_set_col_order_by_name(struct table *tbl, const char *col_order);
  
  /**
-  * Opens a fastbuf stream that can be used for creating a cell content. The @sz parameter is the initial size
-  * allocated on the memory pool.
+  * Sets table formatter. See below for the list of formatters.
   **/
- struct fastbuf *table_col_fbstart(struct table *tbl, int col);
+ void table_set_formatter(struct table *tbl, struct table_formatter *fmt);
  
  /**
-  * Closes the stream that is used for printing of the last column.
+  * Set a table option. All options have a key and a value. Currently,
+  * the following keys are defined (other keys can be accepted by formatters):
+  *
+  * [options="header"]
+  * |===================================================================================================
+  * | key	| value				| meaning
+  * | `header`	| 0 or 1			| set whether a table header should be printed
+  * | `noheader`	| 'none'			| equivalent to `header`=0
+  * | `cols`	| comma-separated column list	| set order of columns
+  * | `fmt`	| `human`/`machine`/`block`	| set table formatter to one of the built-in formatters
+  * | `col-delim`| string			| set column delimiter
+  * |===================================================================================================
   **/
- void table_col_fbend(struct table *tbl);
+ const char *table_set_option_value(struct table *tbl, const char *key, const char *value);
  
  /**
-  * Sets table formatter for @tbl.
+  * Sets a table option given as 'key'`:`'value' or 'key' (with no value).
   **/
- void table_set_formatter(struct table *tbl, struct table_formatter *fmt);
+ const char *table_set_option(struct table *tbl, const char *opt);
+ 
+ /**
+  * Sets several table option in 'key'`:`'value' form, stored in a growing array.
+  * This is frequently used for options given on the command line.
+  **/
+ const char *table_set_gary_options(struct table *tbl, char **gary_table_opts);
+ 
+ /***
+  * Formatters
+  * ----------
+  *
+  * Transformation of abstract cell data to the characters in the output stream
+  * is under control of a formatter (which serves as a back-end of the table printer).
+  * There are several built-in formatters, but you can define your own.
+  *
+  * A formatter is described by a structure, which contains pointers to several
+  * call-back functions, which are called by the table printer at specific occasions.
+  
+  * The formatter can keep its internal state in the `data` field of `struct table`
+  * and allocate temporary data from the table's memory pool. Memory allocated in
+  * the `row_output` call-back is freed before the next row begins. Memory allocated
+  * between the beginning of `table_start` and the end of `table_end` is freed after
+  * `table_end`. Memory allocated by `process_option` when no table is started
+  * is kept until @table_cleanup().
+  ***/
  
  /** Definition of a formatter back-end. **/
  struct table_formatter {