From: Robert Kessl <kesslr@centrum.cz>
Date: Mon, 7 Jul 2014 13:50:41 +0000 (+0200)
Subject: tableprinter: update of documentation
X-Git-Tag: v6.1~3^2~113
X-Git-Url: http://mj.ucw.cz/gitweb/?a=commitdiff_plain;h=8e63ec884aea58142de802f87f011d8c83f7c048;p=libucw.git

tableprinter: update of documentation
---

diff --git a/ucw/doc/table.txt b/ucw/doc/table.txt
index b52bc688..5185cd63 100644
--- a/ucw/doc/table.txt
+++ b/ucw/doc/table.txt
@@ -39,50 +39,60 @@ string for `printf` used for this column. Moreover, various flags can
 be OR-ed to the width of the column, for example `CELL_ALIGN_LEFT` prescribes
 that the cell should be aligned to the left.
 
-  struct table recording_table = {
+To define the column order, we can create an array of struct table_col_info
+using the following macros: TBL_COL, TBL_COL_FMT, TBL_COL_TYPE. An example
+follows:
+
+  struct table_col_info column_order[] = { TBL_COL(TBL_REC_ID), TBL_COL(TBL_REC_ALBUM_NAME) };
+
+The column order is supplied in the struct table using the TBL_COL_ORDER macro.
+
+  struct table recording_table_template = {
     TBL_COLUMNS {
        [TBL_REC_ID] = TBL_COL_UINT("id", 16),
        [TBL_REC_ALBUM_NAME] = TBL_COL_STR_FMT("album-name", 20 | CELL_ALIGN_LEFT, "%s"),
        [TBL_REC_ARTIST] = TBL_COL_STR("artist", 20),
        [TBL_REC_YEAR] = TBL_COL_UINT("year", 10),
        TBL_COL_END
-    }
+    },
+    TBL_COL_ORDER(column_order)
   };
 
-Each table definition has to be initialized before use by @table_init():
 
-  table_init(&recording_table);
+Each table definition has to be created from a template before use by @table_init():
+
+  struct table *rec_table = table_init(&recording_table_template);
 
 Once it is initialized, we can use it for printing multiple tables.
 At the start of each table, we should obtain a <<fastbuf:,fastbuf>> where the output
 should be sent, store it in the table structure and call @table_start():
 
   struct fastbuf *out = bfdopen_shared(1, 4096);
-  table_start(&recording_table, out);
+  table_start(&rec_table, out);
 
 Then we can fill the rows one after another. Each row is ended by
 @table_end_row():
 
-  table_col_uint(&recording_table, TBL_REC_ID, 0);
-  table_col_str(&recording_table, TBL_REC_ALBUM_NAME, "The Wall");
-  table_col_str(&recording_table, TBL_REC_ARTIST, "Pink Floyd");
-  table_col_uint(&recording_table, TBL_REC_YEAR, 1979);
-  table_end_row(&recording_table);
+  table_col_uint(&rec_table, TBL_REC_ID, 0);
+  table_col_str(&rec_table, TBL_REC_ALBUM_NAME, "The Wall");
+  table_col_str(&rec_table, TBL_REC_ARTIST, "Pink Floyd");
+  table_col_uint(&rec_table, TBL_REC_YEAR, 1979);
+  table_end_row(&rec_table);
 
-  table_col_uint(&recording_table, TBL_REC_ID, 1);
-  table_col_str(&recording_table, TBL_REC_ALBUM_NAME, "Rio Grande Mud");
-  table_col_str(&recording_table, TBL_REC_ARTIST, "ZZ Top");
-  table_col_uint(&recording_table, TBL_REC_YEAR, 1972);
-  table_end_row(&recording_table);
+  table_col_uint(&rec_table, TBL_REC_ID, 1);
+  table_col_str(&rec_table, TBL_REC_ALBUM_NAME, "Rio Grande Mud");
+  table_col_str(&rec_table, TBL_REC_ARTIST, "ZZ Top");
+  table_col_uint(&rec_table, TBL_REC_YEAR, 1972);
+  table_end_row(&rec_table);
 
 Finally, we should close the table by calling @table_end():
 
-  table_end(&recording_table);
+  table_end(&rec_table);
 
 At this moment, the table structure is ready to be used again. When
 you do not need it any longer, you can dispose of it by @table_cleanup():
 
-  table_cleanup(&recording_table);
+  table_cleanup(&rec_table);
 
 ucw/table.h
 -----------
diff --git a/ucw/table.c b/ucw/table.c
index 1a26e5b3..cb14a89c 100644
--- a/ucw/table.c
+++ b/ucw/table.c
@@ -34,7 +34,7 @@ static struct table *table_template_copy(struct table *tbl_template)
   copy->column_count = tbl_template->column_count;
   copy->pool = mp_new(4096);
   if(tbl_template->column_order) {
-    copy->column_order = mp_alloc_zero(copy->pool, sizeof(struct table_col_info) * tbl_template->cols_to_output); //tbl_template->; // FIXME: more complicated copying
+    copy->column_order = mp_alloc_zero(copy->pool, sizeof(struct table_col_info) * tbl_template->cols_to_output);
     memcpy(copy->column_order, tbl_template->column_order, sizeof(struct table_col_info) * tbl_template->cols_to_output);
     for(uint i = 0; i < copy->cols_to_output; i++) {
       copy->column_order[i].cell_content = NULL;
diff --git a/ucw/table.h b/ucw/table.h
index 1f0f8c2e..ef7ecdc1 100644
--- a/ucw/table.h
+++ b/ucw/table.h
@@ -223,7 +223,7 @@ struct table {
   for(_idxval = _tbl->columns[_colidx].first_column, _var = _tbl->column_order + _idxval; _idxval != -1; _idxval = _tbl->column_order[_idxval].next_column, _var = _tbl->column_order + _idxval)
 
 /**
- * Initialize a table definition. The structure should already contain
+ * Creates a new table from a table template. The template should already contain
  * the definitions of columns.
  **/
 struct table *table_init(struct table *tbl_template);