124 lines
4 KiB
Text
124 lines
4 KiB
Text
//po4a: entry man manual
|
|
////
|
|
Copyright (C) 2023 Karel Zak <kzak@redhat.com>
|
|
|
|
This file may be copied under the terms of the GNU General 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]*
|
|
| [0-9]*[KMGTPEZY]
|
|
| [0-9]*[KMGTPEZY]iB
|
|
|
|
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 currently 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. The `integer` may be followed by the multiplicative suffixes KiB,
|
|
GiB, TiB, PiB, EiB, ZiB, and YiB (the "iB" is optional, e.g., "K" has the same
|
|
meaning as "KiB").
|
|
|
|
== 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::[]
|