libsmartcols: add scols-filter.5 man page

Signed-off-by: Karel Zak <kzak@redhat.com>

diff --git a/libsmartcols/Makemodule.am b/libsmartcols/Makemodule.am
index 012848b2b09d4aab2689560f2fb8449748303cc3..77e87b51ce787a0efddcd7518ab41893f0ffd6d1 100644 (file)
--- a/libsmartcols/Makemodule.am
+++ b/libsmartcols/Makemodule.am
@@ -12,4 +12,7 @@ pkgconfig_DATA += libsmartcols/smartcols.pc
 PATHFILES      += libsmartcols/smartcols.pc
 EXTRA_DIST     += libsmartcols/COPYING
 
+MANPAGES += libsmartcols/scols-filter.5
+dist_noinst_DATA += libsmartcols/scols-filter.5.adoc
+
 endif # BUILD_LIBSMARTCOLS

diff --git a/libsmartcols/scols-filter.5.adoc b/libsmartcols/scols-filter.5.adoc
new file mode 100644 (file)
index 0000000..7a39c91
--- /dev/null
+++ b/libsmartcols/scols-filter.5.adoc
@@ -0,0 +1,121 @@
+//po4a: entry man manual
+////
+Copyright (C) 2023 Karel Zak <kzak@redhat.com>
+
+This file may be copied under the terms of the GNU Public License.
+////
+= scols-filter(5)
+:doctype: manpage
+:man manual: File formats and conventions
+:man source: util-linux {release-version}
+:page-layout: base
+:lib: libsmartcols
+:firstversion: 2.25
+:colon: :
+
+== NAME
+
+scols-filter - syntax for libsmartcols filter expressions
+
+== SYNTAX
+// Simplified https://en.wikipedia.org/wiki/Wirth_syntax_notation
+// TRANSLATORS: don't translate the expressions syntax, please.
+[verse]
+----
+expr: param
+      | ( expr )
+      | expr && expr | expr AND expr
+      | expr || expr | expr OR expr
+      | !expr        | NOT expr
+      | expr == expr | expr EQ expr
+      | expr != expr | expr NE expr
+      | expr >= expr | expr GE expr
+      | expr <= expr | expr LE expr
+      | expr >  expr | expr GT expr
+      | expr <  expr | expr LT expr
+      | expr =~ string 
+      | expr !~ string
+
+param: integer
+      | float
+      | string
+      | boolean
+      | holder
+
+integer: [0-9]*
+
+float: integer.integer
+
+boolean: "true" | "false" | "TRUE" | "FALSE"
+
+string: "[^\n\"]*" | '[^\n\']*'
+
+holder: [a-zA-Z][a-zA-Z_.%:/\-0-9]*
+----
+    
+== DESCRIPTION
+
+The filter expression can be used by application linked with libsmartcols to filter
+output data. The application can use the filter before it gathers all data for the
+output to reduce resources and improve performance. This makes scols filter more
+effective than grep(1) on the complete output. For example
+....
+ lsblk --output NAME,LABEL,FSTYPE --filter 'NAME=="sda1"'
+....
+helps lsblk(1) to not read LABELs for all block device from udevd or libblkid,
+but read it only for device sda1.
+
+The filter can be also used for columns which are not used in the output.
+
+== SYNTAX NOTES
+
+An expression consists of holders, params, and operators. 
+
+The currently supported `holder` type is column name only. The name has to be
+used without quotes. Before evaluation, application map column names in the
+given expression to the output table columns and assign column data type to the
+holder. The default type is "string".
+
+The `param` is for representing a value directly. The currenly supported data
+types are integer, float, string and boolean.
+
+An operator works with one or two operand(s). An operator has an expectation
+about the data type(s) of its operands. Giving an unexpected data type to an
+operator causes a syntax error. The library can cast between data types, the
+preffered is always the type as specified by `param` and in case of expression with
+number and float the prefered is the float.
+
+Operators taking two operands are `and`, `or`, `eq`, `ne`, `le`, `lt`, `ge`, `gt`, `=~`, `!~`.
+Alphabetically named operators have C-language
+flavored aliases: `&&`, `||`, `==`, `!=`, `<`, `<=`, `>=`, and `>`.
+
+`!` is the only operator that takes one operand. If no operator is specified then
+expression is true if param or holder are not empty. For example `--filter NAME` will
+return lines where column NAME is not empty.
+
+`=~` and `!~` is for regular expression matching; if a string at the right side
+matches (or not matches for `!~` a regular expression at the left side, the result
+is true. The right side operand must be a string literal.
+
+The precedences within operators is `or`, `and`, and `eq`, `ne`, `le`, `gt`, `ge`, `=~`, `!~`, `not`.
+
+== LIMITATIONS
+
+About `float` and `integer` typed values, the filter engine supports only
+non-negative numbers. The `integer` is unsigned 64-bit number, and `float` is
+long double.
+
+
+== AUTHORS
+
+mailto:kzak@redhat.com[Karel Zak]
+
+Based on original implementation from mailto:yamato@redhat.com[Masatake YAMATO].
+
+include::man-common/bugreports.adoc[]
+
+include::man-common/footer-lib.adoc[]
+
+ifdef::translation[]
+include::man-common/translation.adoc[]
+endif::[]

diff --git a/libsmartcols/src/.gitignore b/libsmartcols/src/.gitignore
index 59247e2703df05eaad519afadae04a122428a007..049310086de6be614d3ded141e7a066e7dd7edaa 100644 (file)
--- a/libsmartcols/src/.gitignore
+++ b/libsmartcols/src/.gitignore
@@ -1,3 +1,5 @@
 libsmartcols.h
 filter-parser.c
 filter-scanner.c
+filter-scanner.h
+filter-parser.h