]>
Commit | Line | Data |
---|---|---|
da12f191 KZ |
1 | //po4a: entry man manual |
2 | //// | |
3 | Copyright (C) 2023 Karel Zak <kzak@redhat.com> | |
4 | ||
5 | This file may be copied under the terms of the GNU Public License. | |
6 | //// | |
7 | = scols-filter(5) | |
8 | :doctype: manpage | |
9 | :man manual: File formats and conventions | |
10 | :man source: util-linux {release-version} | |
11 | :page-layout: base | |
12 | :lib: libsmartcols | |
13 | :firstversion: 2.25 | |
14 | :colon: : | |
15 | ||
16 | == NAME | |
17 | ||
18 | scols-filter - syntax for libsmartcols filter expressions | |
19 | ||
20 | == SYNTAX | |
21 | // Simplified https://en.wikipedia.org/wiki/Wirth_syntax_notation | |
22 | // TRANSLATORS: don't translate the expressions syntax, please. | |
23 | [verse] | |
24 | ---- | |
25 | expr: param | |
26 | | ( expr ) | |
27 | | expr && expr | expr AND expr | |
28 | | expr || expr | expr OR expr | |
29 | | !expr | NOT 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 | |
36 | | expr =~ string | |
37 | | expr !~ string | |
38 | ||
39 | param: integer | |
40 | | float | |
41 | | string | |
42 | | boolean | |
43 | | holder | |
44 | ||
45 | integer: [0-9]* | |
46 | ||
47 | float: integer.integer | |
48 | ||
49 | boolean: "true" | "false" | "TRUE" | "FALSE" | |
50 | ||
51 | string: "[^\n\"]*" | '[^\n\']*' | |
52 | ||
53 | holder: [a-zA-Z][a-zA-Z_.%:/\-0-9]* | |
54 | ---- | |
55 | ||
56 | == DESCRIPTION | |
57 | ||
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 | |
62 | .... | |
63 | lsblk --output NAME,LABEL,FSTYPE --filter 'NAME=="sda1"' | |
64 | .... | |
65 | helps lsblk(1) to not read LABELs for all block device from udevd or libblkid, | |
66 | but read it only for device sda1. | |
67 | ||
68 | The filter can be also used for columns which are not used in the output. | |
69 | ||
70 | == SYNTAX NOTES | |
71 | ||
72 | An expression consists of holders, params, and operators. | |
73 | ||
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". | |
78 | ||
79 | The `param` is for representing a value directly. The currenly supported data | |
80 | types are integer, float, string and boolean. | |
81 | ||
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 | |
885ad817 MY |
85 | prefferred is always the type as specified by `param` and in case of expression with |
86 | number and float the preferred is the float. | |
da12f191 KZ |
87 | |
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 `>`. | |
91 | ||
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. | |
95 | ||
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. | |
99 | ||
100 | The precedences within operators is `or`, `and`, and `eq`, `ne`, `le`, `gt`, `ge`, `=~`, `!~`, `not`. | |
101 | ||
102 | == LIMITATIONS | |
103 | ||
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 | |
106 | long double. | |
107 | ||
108 | ||
109 | == AUTHORS | |
110 | ||
111 | mailto:kzak@redhat.com[Karel Zak] | |
112 | ||
113 | Based on original implementation from mailto:yamato@redhat.com[Masatake YAMATO]. | |
114 | ||
115 | include::man-common/bugreports.adoc[] | |
116 | ||
117 | include::man-common/footer-lib.adoc[] | |
118 | ||
119 | ifdef::translation[] | |
120 | include::man-common/translation.adoc[] | |
121 | endif::[] |