libsmartcols/scols-filter.5.adoc

   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
  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.
  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::[]