From 442efa9b3ff211c692b6967a944b3d9371ad1bb7 Mon Sep 17 00:00:00 2001 From: Werner Koch Date: Sat, 2 Jul 2016 16:18:50 +0200 Subject: [PATCH] doc: Describe filter expressions. * doc/gpg.texi: Remove some superfluous .E. (FILTER EXPRESSIONS): New. Signed-off-by: Werner Koch --- common/recsel.c | 6 +-- doc/gpg.texi | 127 +++++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 124 insertions(+), 9 deletions(-) diff --git a/common/recsel.c b/common/recsel.c index b35574fb6..5dc685fe9 100644 --- a/common/recsel.c +++ b/common/recsel.c @@ -133,7 +133,7 @@ find_next_lc (char *string) } -/* Parse an expression. The expression symtax is: +/* Parse an expression. The expression syntax is: * * [] {{} PROPNAME VALUE []} * @@ -161,8 +161,8 @@ find_next_lc (char *string) * >= The numerical value of the field must be GE than the value. * -n True if value is not empty (no VALUE parameter allowed). * -z True if value is empty (no VALUE parameter allowed). - * -t Alias for "NAME != 0" (no VALUE parameter allowed). - * -f Alias for "NAME == 0" (no VALUE parameter allowed). + * -t Alias for "PROPNAME != 0" (no VALUE parameter allowed). + * -f Alias for "PROPNAME == 0" (no VALUE parameter allowed). * * Values for must be space separated and any of: * diff --git a/doc/gpg.texi b/doc/gpg.texi index 7118e0d1c..7dff333d5 100644 --- a/doc/gpg.texi +++ b/doc/gpg.texi @@ -570,7 +570,7 @@ Use the source, Luke :-). The output format is still subject to change. @item --enarmor -@item --dearmor +@itemx --dearmor @opindex enarmor @opindex dearmor Pack or unpack an arbitrary input into/from an OpenPGP ASCII armor. @@ -2239,9 +2239,9 @@ The available filter types are: @end table -The syntax for the expression is defined in the appendix (FIXME). The -property names for the expressions depend on the actual filter type -and are indicated in the following table. +For the syntax of the expression see the chapter "FILTER EXPRESSIONS". +The property names for the expressions depend on the actual filter +type and are indicated in the following table. The available properties are: @@ -3238,7 +3238,6 @@ current home directory (@pxref{option --homedir}). @end table -@c man:.RE Note that on larger installations, it is useful to put predefined files into the directory @file{@value{SYSCONFSKELDIR}} so that newly created users start up with a working configuration. @@ -3313,7 +3312,6 @@ files; They all live in in the current home directory (@pxref{option @end table -@c man:.RE Operation is further controlled by a few environment variables: @table @asis @@ -3406,6 +3404,123 @@ user for the filename. @include specify-user-id.texi @end ifset +@mansect filter expressions +@chapheading FILTER EXPRESSIONS + +The options @option{--import-filter} and @option{--export-filter} use +expressions with this syntax (square brackets indicate an optional +part and curly braces a repetition, white space between the elements +are allowed): + +@c man:.RS +@example + [lc] @{[@{flag@}] PROPNAME op VALUE [lc]@} +@end example +@c man:.RE + +The name of a property (@var{PROPNAME}) may only consist of letters, +digits and underscores. The description for the filter type +describes which properties are defined. If an undefined property is +used it evaluates to the empty string. Unless otherwise noted, the +@var{VALUE} must always be given and may not be the empty string. No +quoting is defined for the value, thus the value may not contain the +strings @code{&&} or @code{||}, which are used as logical connection +operators. The flag @code{--} can be used to remove this restriction. + +Numerical values are computed as long int; standard C notation +applies. @var{lc} is the logical connection operator; either +@code{&&} for a conjunction or @code{||} for a disjunction. A +conjunction is assumed at the begin of an expression. Conjunctions +have higher precedence than disjunctions. If @var{VALUE} starts with +one of the characters used in any @var{op} a space after the +@var{op} is required. + +@noindent +The supported operators (@var{op}) are: + +@table @asis + + @item =~ + Substring must match. + + @item !~ + Substring must not match. + + @item = + The full string must match. + + @item <> + The full string must not match. + + @item == + The numerical value must match. + + @item != + The numerical value must not match. + + @item <= + The numerical value of the field must be LE than the value. + + @item < + The numerical value of the field must be LT than the value. + + @item >= + The numerical value of the field must be GT than the value. + + @item >= + The numerical value of the field must be GE than the value. + + @item -n + True if value is not empty (no value allowed). + + @item -z + True if value is empty (no value allowed). + + @item -t + Alias for "PROPNAME != 0" (no value allowed). + + @item -f + Alias for "PROPNAME == 0" (no value allowed). + +@end table + +@noindent +Values for @var{flag} must be space separated. The supported flags +are: + +@table @asis + @item -- + @var{VALUE} spans to the end of the expression. + @item -c + The string match in this part is done case-sensitive. +@end table + +The filter options concatenate several specifications for a filter of +the same type. For example the four options in this example: + +@c man:.RS +@example + --import-option keep-uid="uid =~ Alfa" + --import-option keep-uid="&& uid !~ Test" + --import-option keep-uid="|| uid =~ Alpha" + --import-option keep-uid="uid !~ Test" +@end example +@c man:.RE + +@noindent +which is equivalent to + +@c man:.RS +@example + --import-option \ + keep-uid="uid =~ Alfa" && uid !~ Test" || uid =~ Alpha" && "uid !~ Test" +@end example +@c man:.RE + +imports only the user ids of a key containing the strings "Alfa" +or "Alpha" but not the string "test". + + @mansect return value @chapheading RETURN VALUE