ericonr
/
util-linux
mirror of https://github.com/ericonr/util-linux.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

libsmartcols: documentation 

Signed-off-by: Ondrej Oprala <ooprala@redhat.com>
This commit is contained in:
Ondrej Oprala 2014-03-25 15:09:09 +01:00 committed by Karel Zak
parent b72b824d06
commit 1d90bcb1a8
14 changed files with 865 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
configure.ac
View File

@ -1618,6 +1618,8 @@ libblkid/src/blkid.h
libmount/docs/Makefile
libmount/docs/version.xml
libmount/src/libmount.h
libsmartcols/docs/Makefile
libsmartcols/docs/version.xml
libsmartcols/src/libsmartcols.h
po/Makefile.in
])

6
libsmartcols/Makemodule.am
View File

@ -2,10 +2,10 @@ if BUILD_LIBSMARTCOLS
include libsmartcols/src/Makemodule.am
#if ENABLE_GTK_DOC
if ENABLE_GTK_DOC
# Docs uses separate Makefiles
#SUBDIRS += libsmartcols/docs
#endif
SUBDIRS += libsmartcols/docs
endif
pkgconfig_DATA += libsmartcols/smartcols.pc
PATHFILES += libsmartcols/smartcols.pc

18
libsmartcols/docs/.gitignore vendored Normal file
View File

@ -0,0 +1,18 @@
*-decl-list.txt
*-decl.txt
*-overrides.txt
*-undeclared.txt
*-undocumented.txt
*-unused.txt
*.args
*.bak
*.hierarchy
*.interfaces
*.prerequisites
*.signals
*.stamp
*.types
html/*
tmpl/*
version.xml
xml/*

93
libsmartcols/docs/Makefile.am Normal file
View File

@ -0,0 +1,93 @@
## Process this file with automake to produce Makefile.in
# We require automake 1.10 at least.
AUTOMAKE_OPTIONS = 1.10
# This is a blank Makefile.am for using gtk-doc.
# Copy this to your project's API docs directory and modify the variables to
# suit your project. See the GTK+ Makefiles in gtk+/docs/reference for examples
# of using the various options.
# The name of the module, e.g. 'glib'.
DOC_MODULE=libsmartcols
# Uncomment for versioned docs and specify the version of the module, e.g. '2'.
#DOC_MODULE_VERSION=2
# The top-level SGML file. You can change this if you want to.
DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.xml
# The directory containing the source code. Relative to $(srcdir).
# gtk-doc will search all .c & .h files beneath here for inline comments
# documenting the functions and macros.
# e.g. DOC_SOURCE_DIR=../../../gtk
DOC_SOURCE_DIR=../src
# Extra options to pass to gtkdoc-scangobj. Not normally needed.
SCANGOBJ_OPTIONS=
# Extra options to supply to gtkdoc-scan.
# e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED"
SCAN_OPTIONS=
# Extra options to supply to gtkdoc-mkdb.
# e.g. MKDB_OPTIONS=--sgml-mode --output-format=xml
MKDB_OPTIONS=--sgml-mode --output-format=xml --name-space mnt
# Extra options to supply to gtkdoc-mktmpl
# e.g. MKTMPL_OPTIONS=--only-section-tmpl
MKTMPL_OPTIONS=
# Extra options to supply to gtkdoc-mkhtml
MKHTML_OPTIONS=
# Extra options to supply to gtkdoc-fixref. Not normally needed.
# e.g. FIXXREF_OPTIONS=--extra-dir=../gdk-pixbuf/html --extra-dir=../gdk/html
FIXXREF_OPTIONS=
# Used for dependencies. The docs will be rebuilt if any of these change.
# e.g. HFILE_GLOB=$(top_srcdir)/gtk/*.h
# e.g. CFILE_GLOB=$(top_srcdir)/gtk/*.c
HFILE_GLOB=$(top_builddir)/libsmartcols/src/libsmartcols.h
CFILE_GLOB=$(top_srcdir)/libsmartcols/src/*.c
# Extra header to include when scanning, which are not under DOC_SOURCE_DIR
# e.g. EXTRA_HFILES=$(top_srcdir}/contrib/extra.h
EXTRA_HFILES=
# Header files to ignore when scanning. Use base file name, no paths
# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h
IGNORE_HFILES=smartcolsP.h
# Images to copy into HTML directory.
# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
HTML_IMAGES=
# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
content_files = $(builddir)/version.xml
# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
# These files must be listed here *and* in content_files
# e.g. expand_content_files=running.sgml
expand_content_files=
# CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library.
# Only needed if you are using gtkdoc-scangobj to dynamically query widget
# signals and properties.
# e.g. GTKDOC_CFLAGS=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS)
# e.g. GTKDOC_LIBS=$(top_builddir)/gtk/$(gtktargetlib)
GTKDOC_CFLAGS=
GTKDOC_LIBS=
# This includes the standard gtk-doc make rules, copied by gtkdocize.
include $(top_srcdir)/config/gtk-doc.make
# Other files to distribute
# e.g. EXTRA_DIST += version.xml.in
EXTRA_DIST += version.xml.in
# Files not to distribute
# for --rebuild-types in $(SCAN_OPTIONS), e.g. $(DOC_MODULE).types
# for --rebuild-sections in $(SCAN_OPTIONS) e.g. $(DOC_MODULE)-sections.txt
DISTCLEANFILES += version.xml

50
libsmartcols/docs/libsmartcols-docs.xml Normal file
View File

@ -0,0 +1,50 @@
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
[
<!ENTITY version SYSTEM "version.xml">
]>
<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
<bookinfo>
<title>libsmartcols Reference Manual</title>
<releaseinfo>for libsmartcols version &version;</releaseinfo>
<copyright>
<year>2014</year>
<holder>Karel Zak &lt;kzak@redhat.com&gt;</holder>
</copyright>
</bookinfo>
<part id="gtk">
<title>libsmartcols Overview</title>
<partintro>
<para>
The libsmartcols library is used for smart adaptive formatting of tabular data.
</para>
<para>
The library is part of the util-linux package since version 2.25 and is
available from ftp://ftp.kernel.org/pub/linux/utils/util-linux/.
</para>
</partintro>
</part>
<part>
<title>Data manipulation</title>
<xi:include href="xml/table.xml"/>
<xi:include href="xml/column.xml"/>
<xi:include href="xml/line.xml"/>
<xi:include href="xml/cell.xml"/>
<xi:include href="xml/symbols.xml"/>
</part>
<part>
<title>Printing</title>
<xi:include href="xml/table_print.xml"/>
</part>
<part>
<title>Misc</title>
<xi:include href="xml/iter.xml"/>
</part>
<index id="api-index-full">
<title>API Index</title>
<xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
</index>
</book>

124
libsmartcols/docs/libsmartcols-sections.txt Normal file
View File

@ -0,0 +1,124 @@
<SECTION>
<FILE>cell</FILE>
libscols_cell
scols_cell_copy_content
scols_cell_get_color
scols_cell_get_data
scols_cell_refer_data
scols_cell_set_color
scols_cell_set_data
scols_reset_cell
</SECTION>
<SECTION>
<FILE>column</FILE>
libscols_column
scols_column_get_color
scols_column_get_flags
scols_column_get_header
scols_column_get_whint
scols_column_is_no_extremes
scols_column_is_right
scols_column_is_strict_width
scols_column_is_tree
scols_column_is_trunc
scols_column_set_color
scols_column_set_flags
scols_column_set_whint
scols_copy_column
scols_new_column
scols_ref_column
scols_unref_column
</SECTION>
<SECTION>
<FILE>iter</FILE>
libscols_iter
scols_free_iter
scols_iter_get_direction
scols_new_iter
scols_reset_iter
</SECTION>
<SECTION>
<FILE>line</FILE>
libscols_line
scols_copy_line
scols_line_add_child
scols_line_alloc_cells
scols_line_free_cells
scols_line_get_cell
scols_line_get_color
scols_line_get_ncells
scols_line_get_parent
scols_line_get_userdata
scols_line_has_children
scols_line_next_child
scols_line_refer_data
scols_line_remove_child
scols_line_set_color
scols_line_set_data
scols_line_set_userdata
scols_new_line
scols_ref_line
scols_unref_line
</SECTION>
<SECTION>
<FILE>symbols</FILE>
libscols_symbols
scols_copy_symbols
scols_new_symbols
scols_ref_symbols
scols_symbols_set_branch
scols_symbols_set_right
scols_symbols_set_vertical
scols_unref_symbols
</SECTION>
<SECTION>
<FILE>table</FILE>
libscols_table
scols_copy_table
scols_new_table
scols_ref_table
scols_table_add_column
scols_table_add_line
scols_table_colors_wanted
scols_table_enable_colors
scols_table_get_column
scols_table_get_line
scols_table_get_ncols
scols_table_get_nlines
scols_table_get_stream
scols_table_is_ascii
scols_table_is_export
scols_table_is_max
scols_table_is_no_headings
scols_table_is_raw
scols_table_is_tree
scols_table_new_column
scols_table_new_line
scols_table_next_column
scols_table_next_line
scols_table_reduce_termwidth
scols_table_remove_column
scols_table_remove_columns
scols_table_remove_line
scols_table_remove_lines
scols_table_set_ascii
scols_table_set_export
scols_table_set_max
scols_table_set_no_headings
scols_table_set_raw
scols_table_set_stream
scols_table_set_symbols
scols_table_set_tree
scols_unref_table
</SECTION>
<SECTION>
<FILE>table_print</FILE>
scols_print_table
scols_print_table_to_string
</SECTION>

1
libsmartcols/docs/version.xml.in Normal file
View File

@ -0,0 +1 @@
@VERSION@

67
libsmartcols/src/cell.c
View File

@ -8,6 +8,14 @@
* GNU Lesser General Public License.
*/
/**
* SECTION: cell
* @title: Cell
* @short_description: cell API
*
* An API to access and modify per-cell data and information.
*/
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
@ -20,6 +28,15 @@
* The cell has no ref-counting, free() and new() functions. All is
* handled by libscols_line.
*/
/**
* scols_reset_cell:
* @ce: pointer to a struct libscols_cell instance
*
* Frees the cell's internal data and resets its status.
*
* Returns: 0, a negative value in case of an error.
*/
int scols_reset_cell(struct libscols_cell *ce)
{
assert(ce);
@ -34,7 +51,15 @@ int scols_reset_cell(struct libscols_cell *ce)
return 0;
}
/* stores copy of the @str to cell */
/**
* scols_cell_set_data:
* @ce: a pointer to a struct libscols_cell instance
* @str: user data
*
* Stores a copy of the @str in @ce.
*
* Returns: 0, a negative value in case of an error.
*/
int scols_cell_set_data(struct libscols_cell *ce, const char *str)
{
char *p = NULL;
@ -55,7 +80,15 @@ int scols_cell_set_data(struct libscols_cell *ce, const char *str)
return 0;
}
/* add reference to @str to cell */
/**
* scols_cell_refer_data:
* @ce: a pointer to a struct libscols_cell instance
* @str: user data
*
* Adds a reference to @str to @ce.
*
* Returns: 0, a negative value in case of an error.
*/
int scols_cell_refer_data(struct libscols_cell *ce, char *str)
{
char *p = NULL;
@ -71,12 +104,27 @@ int scols_cell_refer_data(struct libscols_cell *ce, char *str)
return 0;
}
/**
* scols_cell_get_data:
* @ce: a pointer to a struct libscols_cell instance
*
* Returns: data in @ce or NULL.
*/
const char *scols_cell_get_data(const struct libscols_cell *ce)
{
assert(ce);
return ce ? ce->data : NULL;
}
/**
* scols_cell_set_color:
* @ce: a pointer to a struct libscols_cell instance
* @color: a color string
*
* Set the color of @ce to @color.
*
* Returns: 0, a negative value in case of an error.
*/
int scols_cell_set_color(struct libscols_cell *ce, const char *color)
{
char *p = NULL;
@ -101,12 +149,27 @@ int scols_cell_set_color(struct libscols_cell *ce, const char *color)
return 0;
}
/**
* scols_cell_get_data:
* @ce: a pointer to a struct libscols_cell instance
*
* Returns: the current color of @ce.
*/
const char *scols_cell_get_color(const struct libscols_cell *ce)
{
assert(ce);
return ce ? ce->color : NULL;
}
/**
* scols_cell_copy_content:
* @dest: a pointer to a struct libscols_cell instance
* @src: a pointer to an immutable struct libscols_cell instance
*
* Copy the contents of @src into @dest.
*
* Returns: 0, a negative value in case of an error.
*/
int scols_cell_copy_content(struct libscols_cell *dest,
const struct libscols_cell *src)
{

106
libsmartcols/src/column.c
View File

@ -8,6 +8,14 @@
* GNU Lesser General Public License.
*/
/**
* SECTION: column
* @title: Column
* @short_description: column API
*
* An API to access and modify per-column data and information.
*/
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
@ -16,6 +24,13 @@
#include "smartcolsP.h"
/**
* scols_new_column:
*
* Allocates space for a new column.
*
* Returns: a pointer to a new struct libscols_cell instance, NULL in case of an ENOMEM error.
*/
struct libscols_column *scols_new_column(void)
{
struct libscols_column *cl;
@ -29,12 +44,24 @@ struct libscols_column *scols_new_column(void)
return cl;
}
/**
* scols_ref_column:
* @cl: a pointer to a struct libscols_column instance
*
* Increases the refcount of @cl.
*/
void scols_ref_column(struct libscols_column *cl)
{
if (cl)
cl->refcount++;
}
/**
* scols_unref_column:
* @cl: a pointer to a struct libscols_column instance
*
* Decreases the refcount of @cl.
*/
void scols_unref_column(struct libscols_column *cl)
{
if (cl && --cl->refcount <= 0) {
@ -45,6 +72,14 @@ void scols_unref_column(struct libscols_column *cl)
}
}
/**
* scols_copy_column:
* @cl: a pointer to a struct libscols_column instance
*
* Creates a new column and copies @cl's data over to it.
*
* Returns: a pointer to a new struct libscols_column instance.
*/
struct libscols_column *scols_copy_column(const struct libscols_column *cl)
{
struct libscols_column *ret;
@ -75,6 +110,15 @@ err:
return NULL;
}
/**
* scols_column_set_whint:
* @cl: a pointer to a struct libscols_column instance
* @whint: a width hint
*
* Sets the width hint of column @cl to @whint.
*
* Returns: 0, a negative value in case of an error.
*/
int scols_column_set_whint(struct libscols_column *cl, double whint)
{
assert(cl);
@ -86,12 +130,27 @@ int scols_column_set_whint(struct libscols_column *cl, double whint)
return 0;
}
/**
* scols_column_get_whint:
* @cl: a pointer to a struct libscols_column instance
*
* Returns: The width hint of column @cl, a negative value in case of an error.
*/
double scols_column_get_whint(struct libscols_column *cl)
{
assert(cl);
return cl ? cl->width_hint : -EINVAL;
}
/**
* scols_column_set_flags:
* @cl: a pointer to a struct libscols_column instance
* @flags: a flag mask
*
* Sets the flags of @cl to @flags.
*
* Returns: 0, a negative value in case of an error.
*/
int scols_column_set_flags(struct libscols_column *cl, int flags)
{
assert(cl);
@ -103,19 +162,36 @@ int scols_column_set_flags(struct libscols_column *cl, int flags)
return 0;
}
/**
* scols_column_get_flags:
* @cl: a pointer to a struct libscols_column instance
*
* Returns: The flag mask of @cl, a negative value in case of an error.
*/
int scols_column_get_flags(struct libscols_column *cl)
{
assert(cl);
return cl ? cl->flags : -EINVAL;
}
/**
* scols_column_get_flags:
* @cl: a pointer to a struct libscols_column instance
*
* Returns: A pointer to a struct libscols_cell instance, representing the
* header info of column @cl or NULL in case of an error.
*/
struct libscols_cell *scols_column_get_header(struct libscols_column *cl)
{
assert(cl);
return cl ? &cl->header : NULL;
}
/*
/**
* scols_column_set_color:
* @cl: a pointer to a struct libscols_column instance
* @color: a color string
*
* The default color for data cells and column header.
*
* If you want to set header specific color then use scols_column_get_header()
@ -123,6 +199,8 @@ struct libscols_cell *scols_column_get_header(struct libscols_column *cl)
*
* If you want to set data cell specific color the use scols_line_get_cell() +
* scols_cell_set_color().
*
* Returns: 0, a negative value in case of an error.
*/
int scols_column_set_color(struct libscols_column *cl, const char *color)
{
@ -148,6 +226,12 @@ int scols_column_set_color(struct libscols_column *cl, const char *color)
return 0;
}
/**
* scols_column_get_color:
* @cl: a pointer to a struct libscols_column instance
*
* Returns: The current color setting of the column @cl.
*/
const char *scols_column_get_color(struct libscols_column *cl)
{
assert(cl);
@ -156,9 +240,9 @@ const char *scols_column_get_color(struct libscols_column *cl)
/**
* scols_column_is_trunc:
* @cl: column
* @cl: a pointer to a struct libscols_column instance
*
* Get the value of trunc
* Gets the value of @cl's flag trunc.
*
* Returns: trunc flag value, negative value in case of an error.
*/
@ -171,9 +255,9 @@ int scols_column_is_trunc(struct libscols_column *cl)
}
/**
* scols_column_is_tree:
* @cl: column
* @cl: a pointer to a struct libscols_column instance
*
* Get the value of tree
* Gets the value of @cl's flag tree.
*
* Returns: tree flag value, negative value in case of an error.
*/
@ -186,9 +270,9 @@ int scols_column_is_tree(struct libscols_column *cl)
}
/**
* scols_column_is_right:
* @cl: column
* @cl: a pointer to a struct libscols_column instance
*
* Get the value of right
* Gets the value of @cl's flag right.
*
* Returns: right flag value, negative value in case of an error.
*/
@ -201,9 +285,9 @@ int scols_column_is_right(struct libscols_column *cl)
}
/**
* scols_column_is_strict_width:
* @cl: column
* @cl: a pointer to a struct libscols_column instance
*
* Get the value of strict_width
* Gets the value of @cl's flag strict_width.
*
* Returns: strict_width flag value, negative value in case of an error.
*/
@ -216,9 +300,9 @@ int scols_column_is_strict_width(struct libscols_column *cl)
}
/**
* scols_column_is_no_extremes:
* @cl: column
* @cl: a pointer to a struct libscols_column instance
*
* Get the value of no_extremes
* Gets the value of @cl's flag no_extremes.
*
* Returns: no_extremes flag value, negative value in case of an error.
*/

41
libsmartcols/src/libsmartcols.h.in
View File

@ -19,11 +19,46 @@ extern "C" {
#define LIBSMARTCOLS_VERSION "@LIBSMARTCOLS_VERSION@"
/**
* libscols_iter:
*
* Generic iterator
*/
struct libscols_iter;
/**
* libscols_symbols:
*
* Symbol groups for printing tree hierarchies
*/
struct libscols_symbols;
/**
* libscols_cell:
*
* A cell - the smallest library object
*/
struct libscols_cell;
/**
* libscols_line:
*
* A line - an array of cells
*/
struct libscols_line;
/**
* libscols_table:
*
* A table - The most abstract object, encapsulating lines, columns, symbols and cells
*/
struct libscols_table;
/**
* libscols_column:
*
* A column - defines the number of columns and column names
*/
struct libscols_column;
/* iter.c */
@ -33,10 +68,10 @@ enum {
SCOLS_ITER_BACKWARD
};
/*
* Column flags
*/
enum {
/*
* Column flags
*/
SCOLS_FL_TRUNC = (1 << 15), /* truncate fields data if necessary */
SCOLS_FL_TREE = (1 << 16), /* use tree "ascii art" */
SCOLS_FL_RIGHT = (1 << 17), /* align to the right */

148
libsmartcols/src/line.c
View File

@ -8,6 +8,14 @@
* GNU Lesser General Public License.
*/
/**
* SECTION: line
* @title: Line
* @short_description: line API
*
* An API to access and modify per-line data and information.
*/
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
@ -16,11 +24,15 @@
#include "smartcolsP.h"
/*
/**
* scols_new_line:
*
* Note that the line is allocated without cells, the cells will be allocated
* later when you add the line to the table. If you want to use the line
* without table then you have to explicitly allocate the cells by
* scols_line_alloc_cells().
*
* Returns: a pointer to a new struct libscols_line instance.
*/
struct libscols_line *scols_new_line(void)
{
@ -36,12 +48,24 @@ struct libscols_line *scols_new_line(void)
return ln;
}
/**
* scols_ref_line:
* @ln: a pointer to a struct libscols_line instance
*
* Increases the refcount of @ln.
*/
void scols_ref_line(struct libscols_line *ln)
{
if (ln)
ln->refcount++;
}
/**
* scols_unref_line:
* @ln: a pointer to a struct libscols_line instance
*
* Decreases the refcount of @ln.
*/
void scols_unref_line(struct libscols_line *ln)
{
@ -56,6 +80,12 @@ void scols_unref_line(struct libscols_line *ln)
}
}
/**
* scols_line_free_cells:
* @ln: a pointer to a struct libscols_line instance
*
* Frees the allocated cells referenced to by @ln.
*/
void scols_line_free_cells(struct libscols_line *ln)
{
size_t i;
@ -71,7 +101,15 @@ void scols_line_free_cells(struct libscols_line *ln)
ln->cells = NULL;
}
/**
* scols_line_alloc_cells:
* @ln: a pointer to a struct libscols_line instance
* @n: the number of elements
*
* Allocates space for @n cells.
*
* Returns: 0, a negative value in case of an error.
*/
int scols_line_alloc_cells(struct libscols_line *ln, size_t n)
{
struct libscols_cell *ce;
@ -101,6 +139,15 @@ int scols_line_alloc_cells(struct libscols_line *ln, size_t n)
return 0;
}
/**
* scols_line_set_userdata:
* @ln: a pointer to a struct libscols_line instance
* @data: user data
*
* Binds @data to @ln.
*
* Returns: 0, a negative value in case of an error.
*/
int scols_line_set_userdata(struct libscols_line *ln, void *data)
{
assert(ln);
@ -110,12 +157,27 @@ int scols_line_set_userdata(struct libscols_line *ln, void *data)
return 0;
}
/**
* scols_line_get_userdata:
* @ln: a pointer to a struct libscols_line instance
*
* Returns: 0, a negative value in case of an error.
*/
void *scols_line_get_userdata(struct libscols_line *ln)
{
assert(ln);
return ln ? ln->userdata : NULL;
}
/**
* scols_line_remove_child:
* @ln: a pointer to a struct libscols_line instance
* @child: a pointer to a struct libscols_line instance
*
* Removes @child as a child of @ln.
*
* Returns: 0, a negative value in case of an error.
*/
int scols_line_remove_child(struct libscols_line *ln, struct libscols_line *child)
{
assert(ln);
@ -131,6 +193,15 @@ int scols_line_remove_child(struct libscols_line *ln, struct libscols_line *chil
return 0;
}
/**
* scols_line_add_child:
* @ln: a pointer to a struct libscols_line instance
* @child: a pointer to a struct libscols_line instance
*
* Sets @child as a child of @ln.
*
* Returns: 0, a negative value in case of an error.
*/
int scols_line_add_child(struct libscols_line *ln, struct libscols_line *child)
{
assert(ln);
@ -154,18 +225,40 @@ int scols_line_add_child(struct libscols_line *ln, struct libscols_line *child)
return 0;
}
/**
* scols_line_get_parent:
* @ln: a pointer to a struct libscols_line instance
*
* Returns: a pointer to @ln's parent, NULL in case it has no parent or if there was an error.
*/
struct libscols_line *scols_line_get_parent(struct libscols_line *ln)
{
assert(ln);
return ln ? ln->parent : NULL;
}
/**
* scols_line_has_children:
* @ln: a pointer to a struct libscols_line instance
*
* Returns: 1 if @ln has any children, otherwise 0.
*/
int scols_line_has_children(struct libscols_line *ln)
{
assert(ln);
return ln ? !list_empty(&ln->ln_branch) : 0;
}
/**
* scols_line_next_child:
* @ln: a pointer to a struct libscols_line instance
* @itr: a pointer to a struct libscols_iter instance
* @chld: a pointer to a pointer to a struct libscols_line instance
*
* Finds the next child and returns a pointer to it via @chld.
*
* Returns: 0, a negative value in case of an error.
*/
int scols_line_next_child(struct libscols_line *ln,
struct libscols_iter *itr,
struct libscols_line **chld)
@ -186,8 +279,12 @@ int scols_line_next_child(struct libscols_line *ln,
return rc;
}
/*
* The default line color, used when cell color unspecified.
/**
* scols_line_set_color:
* @ln: a pointer to a struct libscols_line instance
* @color: a color string
*
* Returns: 0, a negative value in case of an error.
*/
int scols_line_set_color(struct libscols_line *ln, const char *color)
{
@ -213,18 +310,37 @@ int scols_line_set_color(struct libscols_line *ln, const char *color)
return 0;
}
/**
* scols_line_get_color:
* @ln: a pointer to a struct libscols_line instance
*
* Returns: @ln's color string, NULL in case of an error.
*/
const char *scols_line_get_color(struct libscols_line *ln)
{
assert(ln);
return ln ? ln->color : NULL;
}
/**
* scols_line_get_ncells:
* @ln: a pointer to a struct libscols_line instance
*
* Returns: @ln's number of cells
*/
size_t scols_line_get_ncells(struct libscols_line *ln)
{
assert(ln);
return ln ? ln->ncells : 0;
}
/**
* scols_line_get_cell:
* @ln: a pointer to a struct libscols_line instance
* @n: cell number to retrieve
*
* Returns: the @n-th cell in @ln, NULL in case of an error.
*/
struct libscols_cell *scols_line_get_cell(struct libscols_line *ln,
size_t n)
{
@ -235,7 +351,14 @@ struct libscols_cell *scols_line_get_cell(struct libscols_line *ln,
return &ln->cells[n];
}
/* just shortcut */
/**
* scols_line_set_data:
* @ln: a pointer to a struct libscols_cell instance
* @n: number of the cell, whose data is to be set
* @data: actual data to set
*
* Returns: 0, a negative value in case of an error.
*/
int scols_line_set_data(struct libscols_line *ln, size_t n, const char *data)
{
struct libscols_cell *ce = scols_line_get_cell(ln, n);
@ -245,7 +368,14 @@ int scols_line_set_data(struct libscols_line *ln, size_t n, const char *data)
return scols_cell_set_data(ce, data);
}
/* just shortcut */
/**
* scols_line_set_data:
* @ln: a pointer to a struct libscols_cell instance
* @n: number of the cell which will refer to @data
* @data: actual data to refer to
*
* Returns: 0, a negative value in case of an error.
*/
int scols_line_refer_data(struct libscols_line *ln, size_t n, char *data)
{
struct libscols_cell *ce = scols_line_get_cell(ln, n);
@ -255,6 +385,12 @@ int scols_line_refer_data(struct libscols_line *ln, size_t n, char *data)
return scols_cell_refer_data(ce, data);
}
/**
* scols_copy_line:
* @ln: a pointer to a struct libscols_cell instance
*
* Returns: A newly allocated copy of @ln, NULL in case of an error.
*/
struct libscols_line *scols_copy_line(struct libscols_line *ln)
{
struct libscols_line *ret;

56
libsmartcols/src/symbols.c
View File

@ -6,6 +6,15 @@
* This file may be redistributed under the terms of the
* GNU Lesser General Public License.
*/
/**
* SECTION: symbols
* @title: Symbols
* @short_description: symbols API
*
* An API to access and modify data and information per symbol/symbol group.
*/
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
@ -13,6 +22,11 @@
#include "smartcolsP.h"
/**
* scols_new_symbols:
*
* Returns: a pointer to a newly allocated struct libscols_symbols instance.
*/
struct libscols_symbols *scols_new_symbols(void)
{
struct libscols_symbols *sy = calloc(1, sizeof(struct libscols_symbols));
@ -23,13 +37,24 @@ struct libscols_symbols *scols_new_symbols(void)
return sy;
}
/**
* scols_ref_symbols:
* @sy: a pointer to a struct libscols_symbols instance
*
* Increases the refcount of @sy.
*/
void scols_ref_symbols(struct libscols_symbols *sy)
{
if (sy)
sy->refcount++;
}
/**
* scols_unref_symbols:
* @sy: a pointer to a struct libscols_symbols instance
*
* Decreases the refcount of @sy.
*/
void scols_unref_symbols(struct libscols_symbols *sy)
{
if (sy && --sy->refcount <= 0) {
@ -40,7 +65,13 @@ void scols_unref_symbols(struct libscols_symbols *sy)
}
}
/**
* scols_symbols_set_branch:
* @sb: a pointer to a struct libscols_symbols instance
* @str: a string which will represent the branch part of a tree output
*
* Returns: 0, a negative value in case of an error.
*/
int scols_symbols_set_branch(struct libscols_symbols *sb, const char *str)
{
char *p = NULL;
@ -59,6 +90,13 @@ int scols_symbols_set_branch(struct libscols_symbols *sb, const char *str)
return 0;
}
/**
* scols_symbols_set_vertical:
* @sb: a pointer to a struct libscols_symbols instance
* @str: a string which will represent the vertical part of a tree output
*
* Returns: 0, a negative value in case of an error.
*/
int scols_symbols_set_vertical(struct libscols_symbols *sb, const char *str)
{
char *p = NULL;
@ -77,6 +115,13 @@ int scols_symbols_set_vertical(struct libscols_symbols *sb, const char *str)
return 0;
}
/**
* scols_symbols_set_right:
* @sb: a pointer to a struct libscols_symbols instance
* @str: a string which will represent the right part of a tree output
*
* Returns: 0, a negative value in case of an error.
*/
int scols_symbols_set_right(struct libscols_symbols *sb, const char *str)
{
char *p = NULL;
@ -95,7 +140,12 @@ int scols_symbols_set_right(struct libscols_symbols *sb, const char *str)
return 0;
}
/**
* scols_copy_symbols:
* @sb: a pointer to a struct libscols_symbols instance
*
* Returns: a newly allocated copy of the @sb symbol group or NULL in caes of an error.
*/
struct libscols_symbols *scols_copy_symbols(const struct libscols_symbols *sb)
{
struct libscols_symbols *ret;

193
libsmartcols/src/table.c
View File

@ -7,6 +7,15 @@
* This file may be redistributed under the terms of the
* GNU Lesser General Public License.
*/
/**
* SECTION: table
* @title: Table
* @short_description: table API
*
* Table manipulation API.
*/
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
@ -29,12 +38,13 @@
list_entry_is_last(&(_cl)->cl_columns, &(_tb)->tb_columns)
/*
/**
* scols_new_table:
* @syms: tree symbols or NULL for default
*
* Note that this function add a new reference to @syms
* Note that this function add a new reference to @syms.
*
* Returns: newly allocated table
* Returns: A newly allocated table.
*/
struct libscols_table *scols_new_table(struct libscols_symbols *syms)
{
@ -57,12 +67,24 @@ struct libscols_table *scols_new_table(struct libscols_symbols *syms)
return NULL;
}
/**
* scols_ref_table:
* @tb: a pointer to a struct libscols_table instance
*
* Increases the refcount of @tb.
*/
void scols_ref_table(struct libscols_table *tb)
{
if (tb)
tb->refcount++;
}
/**
* scols_unref_table:
* @tb: a pointer to a struct libscols_table instance
*
* Decreases the refcount of @tb.
*/
void scols_unref_table(struct libscols_table *tb)
{
if (tb && (--tb->refcount <= 0)) {
@ -73,6 +95,16 @@ void scols_unref_table(struct libscols_table *tb)
}
}
/**
* scols_table_add_column:
* @tb: a pointer to a struct libscols_table instance
* @cl: a pointer to a struct libscols_column instance
* @flags: a flag mask integer
*
* Adds @cl to @tb's column list, setting the appropriate flags to @flags.
*
* Returns: 0, a negative number in case of an error.
*/
int scols_table_add_column(struct libscols_table *tb, struct libscols_column *cl, int flags)
{
assert(tb);
@ -97,6 +129,15 @@ int scols_table_add_column(struct libscols_table *tb, struct libscols_column *cl
return 0;
}
/**
* scols_table_remove_column:
* @tb: a pointer to a struct libscols_table instance
* @cl: a pointer to a struct libscols_column instance
*
* Removes @cl from @tb.
*
* Returns: 0, a negative number in case of an error.
*/
int scols_table_remove_column(struct libscols_table *tb,
struct libscols_column *cl)
{
@ -112,6 +153,14 @@ int scols_table_remove_column(struct libscols_table *tb,
return 0;
}
/**
* scols_table_remove_columns:
* @tb: a pointer to a struct libscols_table instance
*
* Removes all of @tb's columns.
*
* Returns: 0, a negative number in case of an error.
*/
int scols_table_remove_columns(struct libscols_table *tb)
{
assert(tb);
@ -128,10 +177,12 @@ int scols_table_remove_columns(struct libscols_table *tb)
}
/*
/**
* scols_table_new_column:
* @tb: table
* @name: column header
* @whint: column width hint (absolute width: N > 1; relative width: N < 1)
* @flags: flags integer
*
* This is shortcut for
*
@ -148,7 +199,7 @@ int scols_table_remove_columns(struct libscols_table *tb)
*
* @whint = 1..N
*
* The column is necessary to address (for example for scols_line_set_cell_data()) by
* The column is necessary to address by
* sequential number. The first defined column has the colnum = 0. For example:
*
* scols_table_new_column(tab, "FOO", 0.5, 0); // colnum = 0
@ -195,6 +246,16 @@ err:
return NULL;
}
/**
* scols_table_next_column:
* @tb: a pointer to a struct libscols_table instance
* @itr: a pointer to a struct libscols_iter instance
* @cl: a pointer to a pointer to a struct libscols_column instance
*
* Returns the next column of @tb via @cl.
*
* Returns: 0, a negative value in case of an error.
*/
int scols_table_next_column(struct libscols_table *tb,
struct libscols_iter *itr,
struct libscols_column **cl)
@ -216,10 +277,11 @@ int scols_table_next_column(struct libscols_table *tb,
}
/*
/**
* scols_table_get_ncols:
* @tb: table
*
* Returns: ncols integer
* Returns: the ncols table member, a negative number in case of an error.
*/
int scols_table_get_ncols(struct libscols_table *tb)
{
@ -228,9 +290,10 @@ int scols_table_get_ncols(struct libscols_table *tb)
}
/*
* scols_table_get_nlines:
* @tb: table
*
* Returns: nlines integer
* Returns: the nlines table member, a negative number in case of an error.
*/
int scols_table_get_nlines(struct libscols_table *tb)
{
@ -238,6 +301,15 @@ int scols_table_get_nlines(struct libscols_table *tb)
return tb ? tb->nlines : -EINVAL;
}
/**
* scols_table_set_stream:
* @tb: table
* @stream: output stream
*
* Sets the output stream for table @tb.
*
* Returns: 0, a negative number in case of an error.
*/
int scols_table_set_stream(struct libscols_table *tb, FILE *stream)
{
assert(tb);
@ -248,12 +320,29 @@ int scols_table_set_stream(struct libscols_table *tb, FILE *stream)
return 0;
}
/**
* scols_table_get_stream:
* @tb: table
*
* Gets the output stream for table @tb.
*
* Returns: stream pointer, NULL in case of an error or an unset stream.
*/
FILE *scols_table_get_stream(struct libscols_table *tb)
{
assert(tb);
return tb ? tb->out: NULL;
}
/**
* scols_table_reduce_termwidth:
* @tb: table
* @reduce: width
*
* Reduce the output width to @reduce.
*
* Returns: 0, a negative value in case of an error.
*/
int scols_table_reduce_termwidth(struct libscols_table *tb, size_t reduce)
{
assert(tb);
@ -264,9 +353,10 @@ int scols_table_reduce_termwidth(struct libscols_table *tb, size_t reduce)
return 0;
}
/*
/**
* scols_table_get_column:
* @tb: table
* @: number of column (0..N)
* @n: number of column (0..N)
*
* Returns: pointer to column or NULL
*/
@ -290,9 +380,15 @@ struct libscols_column *scols_table_get_column(struct libscols_table *tb,
return NULL;
}
/*
* Note that this functiion calls scols_line_alloc_cells() if number
/**
* scols_table_add_line:
* @tb: table
* @ln: line
*
* Note that this function calls scols_line_alloc_cells() if number
* of the cells in the line is too small for @tb.
*
* Returns: 0, a negative value in case of an error.
*/
int scols_table_add_line(struct libscols_table *tb, struct libscols_line *ln)
{
@ -315,8 +411,15 @@ int scols_table_add_line(struct libscols_table *tb, struct libscols_line *ln)
return 0;
}
/* Note that this function does not destroy parent->child relation between lines.
/**
* scols_table_remove_line:
* @tb: table
* @ln: line
*
* Note that this function does not destroy the parent<->child relationship between lines.
* You have to call scols_line_remove_child()
*
* Returns: 0, a negative value in case of an error.
*/
int scols_table_remove_line(struct libscols_table *tb,
struct libscols_line *ln)
@ -333,7 +436,12 @@ int scols_table_remove_line(struct libscols_table *tb,
return 0;
}
/* This make the table empty and also destroy all parent<->child relations */
/**
* scols_table_remove_lines:
* @tb: table
*
* This empties the table and also destroys all the parent<->child relationships.
*/
void scols_table_remove_lines(struct libscols_table *tb)
{
assert(tb);
@ -349,6 +457,16 @@ void scols_table_remove_lines(struct libscols_table *tb)
}
}
/**
* scols_table_next_line:
* @tb: a pointer to a struct libscols_table instance
* @itr: a pointer to a struct libscols_iter instance
* @ln: a pointer to a pointer to a struct libscols_line instance
*
* Finds the next line and returns a pointer to it via @ln.
*
* Returns: 0, a negative value in case of an error.
*/
int scols_table_next_line(struct libscols_table *tb,
struct libscols_iter *itr,
struct libscols_line **ln)
@ -369,13 +487,14 @@ int scols_table_next_line(struct libscols_table *tb,
return rc;
}
/*
/**
* scols_table_new_line:
* @tb: table
* @parent: parental line or NULL
*
* This is shortcut for
*
* ln = scols_new_linen();
* ln = scols_new_line();
* scols_line_set_....(cl, ...);
* scols_table_add_line(tb, ln);
@ -408,7 +527,19 @@ err:
return NULL;
}
/**
* scols_table_get_line:
* @tb: table
* @n: column number (0..N)
*
* This is a shortcut for
*
* ln = scols_new_line();
* scols_line_set_....(cl, ...);
* scols_table_add_line(tb, ln);
*
* Returns: a newly allocate line
*/
struct libscols_line *scols_table_get_line(struct libscols_table *tb,
size_t n)
{
@ -429,9 +560,14 @@ struct libscols_line *scols_table_get_line(struct libscols_table *tb,
return NULL;
}
/*
/**
* scols_copy_table:
* @tb: table
*
* Creates a new independent table copy, except struct libscols_symbols that
* are shared between the tables.
*
* Returns: a newly allocated copy of @tb
*/
struct libscols_table *scols_copy_table(struct libscols_table *tb)
{
@ -481,6 +617,13 @@ err:
return NULL;
}
/**
* scols_table_set_symbols:
* @tb: table
* @sy: symbols
*
* Returns: 0, a negative value in case of an error.
*/
int scols_table_set_symbols(struct libscols_table *tb,
struct libscols_symbols *sy)
{
@ -639,7 +782,7 @@ int scols_table_set_tree(struct libscols_table *tb, int enable)
* scols_table_colors_wanted:
* @tb: table
*
* Get the value of colors_wanted
* Gets the value of the colors_wanted flag.
*
* Returns: colors_wanted flag value, negative value in case of an error.
*/
@ -654,7 +797,7 @@ int scols_table_colors_wanted(struct libscols_table *tb)
* scols_table_is_raw:
* @tb: table
*
* Get the value of raw
* Gets the value of the raw flag.
*
* Returns: raw flag value, negative value in case of an error.
*/
@ -669,7 +812,7 @@ int scols_table_is_raw(struct libscols_table *tb)
* scols_table_is_ascii:
* @tb: table
*
* Get the value of ascii
* Gets the value of the ascii flag.
*
* Returns: ascii flag value, negative value in case of an error.
*/
@ -684,7 +827,7 @@ int scols_table_is_ascii(struct libscols_table *tb)
* scols_table_is_no_headings:
* @tb: table
*
* Get the value of no_headings
* Gets the value of the no_headings flag.
*
* Returns: no_headings flag value, negative value in case of an error.
*/
@ -699,7 +842,7 @@ int scols_table_is_no_headings(struct libscols_table *tb)
* scols_table_is_export:
* @tb: table
*
* Get the value of export
* Gets the value of the export flag.
*
* Returns: export flag value, negative value in case of an error.
*/
@ -714,7 +857,7 @@ int scols_table_is_export(struct libscols_table *tb)
* scols_table_is_max:
* @tb: table
*
* Get the value of max
* Gets the value of the max flag.
*
* Returns: max flag value, negative value in case of an error.
*/
@ -729,7 +872,7 @@ int scols_table_is_max(struct libscols_table *tb)
* scols_table_is_tree:
* @tb: table
*
* Get the value of tree
* Gets the value of the tree flag.
*
* Returns: tree flag value, negative value in case of an error.
*/

14
libsmartcols/src/table_print.c
View File

@ -535,9 +535,12 @@ static size_t strlen_line(struct libscols_line *ln)
}
/*
* scols_print_table:
* @tb: table
*
* Prints the table to the output stream.
*
* Returns: 0, a negative value in case of an error.
*/
int scols_print_table(struct libscols_table *tb)
{
@ -582,6 +585,15 @@ int scols_print_table(struct libscols_table *tb)
return 0;
}
/*
* scols_print_table_to_string:
* @tb: table
* @data: pointer to the beginning of a memory area to print to
*
* Prints the table to @data.
*
* Returns: 0, a negative value in case of an error.
*/
int scols_print_table_to_string(struct libscols_table *tb, char **data)
{
#ifdef HAVE_OPEN_MEMSTREAM
@ -591,7 +603,7 @@ int scols_print_table_to_string(struct libscols_table *tb, char **data)
if (!tb)
return -EINVAL;
/* create a streem for output */
/* create a stream for output */
stream = open_memstream(data, &sz);
if (!stream)
return -ENOMEM;