diff options
Diffstat (limited to 'libsmartcols/scols-filter.5.adoc')
-rw-r--r-- | libsmartcols/scols-filter.5.adoc | 121 |
1 files changed, 121 insertions, 0 deletions
diff --git a/libsmartcols/scols-filter.5.adoc b/libsmartcols/scols-filter.5.adoc new file mode 100644 index 0000000..ec1d95c --- /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 +prefferred is always the type as specified by `param` and in case of expression with +number and float the preferred 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::[] |