1 //po4a: entry man manual
3 Copyright (C) 2023 Karel Zak <kzak@redhat.com>
5 This file may be copied under the terms of the GNU Public License.
9 :man manual: File formats and conventions
10 :man source: util-linux {release-version}
18 scols-filter - syntax for libsmartcols filter expressions
21 // Simplified https://en.wikipedia.org/wiki/Wirth_syntax_notation
22 // TRANSLATORS: don't translate the expressions syntax, please.
27 | expr && expr | expr AND expr
28 | expr || expr | expr OR expr
30 | expr == expr | expr EQ expr
31 | expr != expr | expr NE expr
32 | expr >= expr | expr GE expr
33 | expr <= expr | expr LE expr
34 | expr > expr | expr GT expr
35 | expr < expr | expr LT expr
47 float: integer.integer
49 boolean: "true" | "false" | "TRUE" | "FALSE"
51 string: "[^\n\"]*" | '[^\n\']*'
53 holder: [a-zA-Z][a-zA-Z_.%:/\-0-9]*
58 The filter expression can be used by application linked with libsmartcols to filter
59 output data. The application can use the filter before it gathers all data for the
60 output to reduce resources and improve performance. This makes scols filter more
61 effective than grep(1) on the complete output. For example
63 lsblk --output NAME,LABEL,FSTYPE --filter 'NAME=="sda1"'
65 helps lsblk(1) to not read LABELs for all block device from udevd or libblkid,
66 but read it only for device sda1.
68 The filter can be also used for columns which are not used in the output.
72 An expression consists of holders, params, and operators.
74 The currently supported `holder` type is column name only. The name has to be
75 used without quotes. Before evaluation, application map column names in the
76 given expression to the output table columns and assign column data type to the
77 holder. The default type is "string".
79 The `param` is for representing a value directly. The currenly supported data
80 types are integer, float, string and boolean.
82 An operator works with one or two operand(s). An operator has an expectation
83 about the data type(s) of its operands. Giving an unexpected data type to an
84 operator causes a syntax error. The library can cast between data types, the
85 preffered is always the type as specified by `param` and in case of expression with
86 number and float the prefered is the float.
88 Operators taking two operands are `and`, `or`, `eq`, `ne`, `le`, `lt`, `ge`, `gt`, `=~`, `!~`.
89 Alphabetically named operators have C-language
90 flavored aliases: `&&`, `||`, `==`, `!=`, `<`, `<=`, `>=`, and `>`.
92 `!` is the only operator that takes one operand. If no operator is specified then
93 expression is true if param or holder are not empty. For example `--filter NAME` will
94 return lines where column NAME is not empty.
96 `=~` and `!~` is for regular expression matching; if a string at the right side
97 matches (or not matches for `!~` a regular expression at the left side, the result
98 is true. The right side operand must be a string literal.
100 The precedences within operators is `or`, `and`, and `eq`, `ne`, `le`, `gt`, `ge`, `=~`, `!~`, `not`.
104 About `float` and `integer` typed values, the filter engine supports only
105 non-negative numbers. The `integer` is unsigned 64-bit number, and `float` is
111 mailto:kzak@redhat.com[Karel Zak]
113 Based on original implementation from mailto:yamato@redhat.com[Masatake YAMATO].
115 include::man-common/bugreports.adoc[]
117 include::man-common/footer-lib.adoc[]
120 include::man-common/translation.adoc[]