From: Karel Zak Date: Fri, 27 Oct 2023 11:12:07 +0000 (+0200) Subject: libsmartcols: add filter API docs X-Git-Tag: v2.40-rc1~151^2~30 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=2b0a221ddbb109d41b2d4d0bf95b280f11234b41;p=thirdparty%2Futil-linux.git libsmartcols: add filter API docs Signed-off-by: Karel Zak --- diff --git a/libsmartcols/docs/libsmartcols-docs.xml b/libsmartcols/docs/libsmartcols-docs.xml index 9ded584ccf..bd55182736 100644 --- a/libsmartcols/docs/libsmartcols-docs.xml +++ b/libsmartcols/docs/libsmartcols-docs.xml @@ -35,6 +35,7 @@ available from https://www.kernel.org/pub/linux/utils/util-linux/. + Printing @@ -82,4 +83,16 @@ available from https://www.kernel.org/pub/linux/utils/util-linux/. Index of new symbols in 2.35 + + Index of new symbols in 2.38 + + + + Index of new symbols in 2.39 + + + + Index of new symbols in 2.40 + + diff --git a/libsmartcols/docs/libsmartcols-sections.txt b/libsmartcols/docs/libsmartcols-sections.txt index 78b2e65c79..5b343d01ee 100644 --- a/libsmartcols/docs/libsmartcols-sections.txt +++ b/libsmartcols/docs/libsmartcols-sections.txt @@ -22,6 +22,7 @@ scols_reset_cell column libscols_column scols_column_get_color +scols_column_get_data_type scols_column_get_flags scols_column_get_header scols_column_get_json_type @@ -32,6 +33,7 @@ scols_column_get_table scols_column_get_whint scols_column_get_width scols_column_get_wrap_data +scols_column_has_data_func scols_column_is_customwrap scols_column_is_hidden scols_column_is_noextremes @@ -42,6 +44,8 @@ scols_column_is_trunc scols_column_is_wrap scols_column_set_cmpfunc scols_column_set_color +scols_column_set_data_func +scols_column_set_data_type scols_column_set_flags scols_column_set_json_type scols_column_set_name @@ -53,6 +57,7 @@ scols_copy_column scols_new_column scols_ref_column scols_unref_column +scols_shellvar_name scols_wrapnl_chunksize scols_wrapnl_nextchunk scols_wrapzero_nextchunk @@ -67,6 +72,30 @@ scols_new_iter scols_reset_iter +
+filter +libscols_filter +libscols_counter +scols_counter_get_name +scols_counter_get_result +scols_counter_set_func +scols_counter_set_name +scols_counter_set_param +scols_dump_filter +scols_filter_assign_column +scols_filter_get_errmsg +scols_filter_new_counter +scols_filter_next_counter +scols_filter_next_holder +scols_filter_parse_string +scols_filter_set_filler_cb +scols_line_apply_filter +scols_line_is_filled +scols_new_filter +scols_ref_filter +scols_unref_filter +
+
line libscols_line diff --git a/libsmartcols/src/column.c b/libsmartcols/src/column.c index 589a4ebcb1..67f4e82cfe 100644 --- a/libsmartcols/src/column.c +++ b/libsmartcols/src/column.c @@ -318,7 +318,8 @@ const char *scols_column_get_name(struct libscols_column *cl) /** * scols_shellvar_name: * @name: raw (column) name - * @schellvar: returns normalized name + * @buf: buffer to returns normalized name + * @bufsz: size of the buffer * * Converts @name to a name compatible with shell. The buffer is reallocated if * not large enough. @@ -661,6 +662,7 @@ int scols_column_set_data_func(struct libscols_column *cl, } /** + * scols_column_has_data_func: * @cl: a pointer to a struct libscols_column instance * * See scols_column_set_data_func() for more details. diff --git a/libsmartcols/src/filter-param.c b/libsmartcols/src/filter-param.c index 446372e29f..758d1409a8 100644 --- a/libsmartcols/src/filter-param.c +++ b/libsmartcols/src/filter-param.c @@ -782,9 +782,12 @@ int filter_next_param(struct libscols_filter *fltr, * @name: holder name * @col: column * - * Assign @col to filter parametr. The parametr is addressed by @itr or by @name. + * Assign @col to filter parametr. The parametr is addressed by @itr or by + * @name. See scols_filter_next_holder(). * * Returns: 0, a negative value in case of an error. + * + * Since: 2.40 */ int scols_filter_assign_column(struct libscols_filter *fltr, struct libscols_iter *itr, @@ -824,6 +827,20 @@ int scols_filter_assign_column(struct libscols_filter *fltr, return n ? 0 : -EINVAL; } +/** + * scols_filter_next_holder: + * @fltr: filter instance + * @itr: a pointer to a struct libscols_iter instance + * @name: returns the next column name + * @type: 0 (not implemented yet) + * + * Finds the next holder used in the expression and and returns a name via + * @name. The currently supported holder type is only column name. + * + * Returns: 0, a negative value in case of an error, and 1 at the end. + * + * Since: 2.40 + */ int scols_filter_next_holder(struct libscols_filter *fltr, struct libscols_iter *itr, const char **name, diff --git a/libsmartcols/src/filter.c b/libsmartcols/src/filter.c index c68f721cbb..ad7e849ab7 100644 --- a/libsmartcols/src/filter.c +++ b/libsmartcols/src/filter.c @@ -1,3 +1,20 @@ +/* + * filter.c - functions for lines filtering + * + * Copyright (C) 2023 Karel Zak + * + * This file may be redistributed under the terms of the + * GNU Lesser General Public License. + */ + +/** + * SECTION: filter + * @title: Filters and counters + * @short_description: defines lines filter and counter + * + * An API to define and use filter and counters. + */ + #include #include #include @@ -8,6 +25,16 @@ #include "filter-parser.h" #include "filter-scanner.h" +/** + * scols_new_filter: + * @str: filter expression or NULL + * + * Allocated and optionally parses a new filter. + * + * Returns: new filter instance or NULL in case of error. + * + * Since: 2.40 + */ struct libscols_filter *scols_new_filter(const char *str) { struct libscols_filter *fltr = calloc(1, sizeof(*fltr)); @@ -28,6 +55,14 @@ struct libscols_filter *scols_new_filter(const char *str) return fltr; } +/** + * scols_ref_filter: + * @fltr: filter instance + * + * Increment filter reference counter. + * + * Since: 2.40 + */ void scols_ref_filter(struct libscols_filter *fltr) { if (fltr) @@ -66,6 +101,15 @@ static void remove_counters(struct libscols_filter *fltr) } } +/** + * scols_unref_filter: + * @fltr: filter instance + * + * Deincrements reference counter, unallocates the filter for the last + * reference. + * + * Since: 2.40 + */ void scols_unref_filter(struct libscols_filter *fltr) { if (fltr && --fltr->refcount <= 0) { @@ -130,6 +174,17 @@ void filter_dump_node(struct ul_jsonwrt *json, struct filter_node *n) extern int yyparse(void *scanner, struct libscols_filter *fltr); +/** + * scols_filter_parse_string: + * @fltr: filter instance + * @str: string with filter expression + * + * Parses filter, see scols_filter_get_errmsg() for errors. + * + * Returns: 0, a negative number in case of an error. + * + * Since: 2.40 + */ int scols_filter_parse_string(struct libscols_filter *fltr, const char *str) { yyscan_t sc; @@ -158,6 +213,18 @@ int scols_filter_parse_string(struct libscols_filter *fltr, const char *str) return rc; } +/** + * scols_dump_filter: + * @fltr: filter instance + * @out: output stream + * + * Dumps internal filter nodes in JSON format. This function is mostly designed + * for debugging purpose. The fileds in the output are subject to change. + * + * Returns: 0, a negative number in case of an error. + * + * Since: 2.40 + */ int scols_dump_filter(struct libscols_filter *fltr, FILE *out) { struct ul_jsonwrt json; @@ -173,6 +240,14 @@ int scols_dump_filter(struct libscols_filter *fltr, FILE *out) return 0; } +/** + * scols_filter_get_errmsg: + * @fltr: filter instance + * + * Returns: string with parse-error message of NULL (if no error) + * + * Since: 2.40 + */ const char *scols_filter_get_errmsg(struct libscols_filter *fltr) { return fltr ? fltr->errmsg : NULL; @@ -192,6 +267,18 @@ int filter_eval_node(struct libscols_filter *fltr, struct libscols_line *ln, return -EINVAL; } +/** + * scols_line_apply_filter: + * @ln: apply filter to the line + * @fltr: filter instance + * @status: return 1 or 0 as result of the expression + * + * Applies filter (and also counters assisiated with the filter). + * + * Returns: 0, a negative number in case of an error. + * + * Since: 2.40 + */ int scols_line_apply_filter(struct libscols_line *ln, struct libscols_filter *fltr, int *status) { @@ -229,6 +316,41 @@ int scols_line_apply_filter(struct libscols_line *ln, return rc; } +/** + * scols_filter_set_filler_cb: + * @fltr: filter instance + * @cb: application defined callback + * @userdata: pointer to private callback data + * + * The application can apply filter for empty lines to avoid filling the table + * with unnecessary data (for example if the line will be later removed from + * the table due to filter). + * + * This callback is used by filter to ask application to fill to the line data + * which are necessary to evaluate the filter expression. The callback + * arguments are filter, column number and userdata. + * + * + * + * ln = scols_table_new_line(tab, NULL); + * + * scols_filter_set_filler_cb(filter, my_filler, NULL); + * + * scols_line_apply_filter(line, filter, &status); + * if (status == 0) + * scols_table_remove_line(tab, line); + * else for (i = 0; i < ncolumns; i++) { + * if (scols_line_is_filled(line, i)) + * continue; + * my_filler(NULL, ln, i, NULL); + * } + * + * + * + * Returns: 0, a negative number in case of an error. + * + * Since: 2.40 + */ int scols_filter_set_filler_cb(struct libscols_filter *fltr, int (*cb)(struct libscols_filter *, struct libscols_line *, size_t, void *), @@ -242,6 +364,16 @@ int scols_filter_set_filler_cb(struct libscols_filter *fltr, return 0; } +/** + * scols_filter_new_counter: + * @fltr: filter instance + * + * Alocates a new counter instance into the filter. + * + * Returns: new counter or NULL in case of an error. + * + * Since: 2.40 + */ struct libscols_counter *scols_filter_new_counter(struct libscols_filter *fltr) { struct libscols_counter *ct; @@ -263,6 +395,18 @@ struct libscols_counter *scols_filter_new_counter(struct libscols_filter *fltr) return ct; } +/** + * scols_counter_set_name: + * @ct: counter instance + * @name: something for humans + * + * The name is not use by library, it's just description usable for application + * when prints results from countes. + * + * Returns: 0, a negative number in case of an error. + * + * Since: 2.40 + */ int scols_counter_set_name(struct libscols_counter *ct, const char *name) { if (!ct) @@ -270,6 +414,19 @@ int scols_counter_set_name(struct libscols_counter *ct, const char *name) return strdup_to_struct_member(ct, name, name); } +/** + * scols_counter_set_param: + * @ct: counter instance + * @name: holder (column) name + * + * Assigns a counter to the column. The name is used in the same way as names + * in the filter expression. This is usable for counter that calcuate with data + * from table cells (e.g. max, sum, etc.) + * + * Returns: 0, a negative number in case of an error. + * + * Since: 2.40 + */ int scols_counter_set_param(struct libscols_counter *ct, const char *name) { if (!ct) @@ -289,6 +446,17 @@ int scols_counter_set_param(struct libscols_counter *ct, const char *name) return 0; } +/** + * scols_counter_set_func: + * @ct: counter instance + * @func: SCOLS_COUNTER_{COUNT,MAX,MIN,SUM} + * + * Defines function to calculate data. + * + * Returns: 0, a negative number in case of an error. + * + * Since: 2.40 + */ int scols_counter_set_func(struct libscols_counter *ct, int func) { if (!ct || func < 0 || func >= __SCOLS_NCOUNTES) @@ -298,16 +466,44 @@ int scols_counter_set_func(struct libscols_counter *ct, int func) return 0; } +/** + * scols_counter_get_result: + * @ct: counter instance + * + * Returns: result from the counter + * + * Since: 2.40 + */ unsigned long long scols_counter_get_result(struct libscols_counter *ct) { return ct ? ct->result : 0; } +/** + * scols_counter_get_name: + * @ct: counter instance + * + * Returns: name of the counter. + * + * Since: 2.40 + */ const char *scols_counter_get_name(struct libscols_counter *ct) { return ct ? ct->name : NULL;; } +/** + * scols_filter_next_counter: + * @fltr: filter instance + * @itr: a pointer to a struct libscols_iter instance + * @ct: returns the next counter + * + * Finds the next counter and returns a pointer to it via @ct. + * + * Returns: 0, a negative value in case of an error, and 1 at the end. + * + * Since: 2.40 + */ int scols_filter_next_counter(struct libscols_filter *fltr, struct libscols_iter *itr, struct libscols_counter **ct) {