docs: Update wireshark-filter.adoc for recent filter changes.

Commas in sets, changes to != and ~=, changes to contains and matches,
changes to implicit conversions/comparisons to unquoted values.
Also fix #15392.

1 files changed, 62 insertions, 35 deletions

diff --git a/doc/wireshark-filter.adoc b/doc/wireshark-filter.adoc
index f1fc545d2c..8271d6548d 100644
--- a/doc/wireshark-filter.adoc
+++ b/doc/wireshark-filter.adoc
@@ -41,14 +41,22 @@ field.  If you want to see all packets which contain the IP protocol, the
 filter would be "ip" (without the quotation marks). To see all packets
 that contain a Token-Ring RIF field, use "tr.rif".
 
-Think of a protocol or field in a filter as implicitly having the "exists"
-operator.
+Whenever a protocol or field appears as the argument of a function in a filter,
+an exists operator for that protocol or field implicitly appears.
+
+=== Values and operators
+
+Each field has a value, and that value can be used in operations with
+comparable values (which may be literals, other fields, or function results).
+The value of a field is not necessarily what appears in the *Wireshark*
+display or *TShark* output.  For example, a protocol is semantically
+equivalent to the sequence of bytes that it spans, not its displayed text
+in the protocol tree.
 
 === Comparison operators
 
-Fields can also be compared against values.  The comparison operators
-can be expressed either through English-like abbreviations or through
-C-like symbols:
+The comparison operators can be expressed either through English-like
+abbreviations or through C-like symbols:
 
     eq, ==    Equal
     ne, !=    Not Equal
@@ -57,18 +65,27 @@ C-like symbols:
     ge, >=    Greater than or Equal to
     le, <=    Less than or Equal to
 
+The ordering depends on the value type in the usual way (e.g., lexicographic
+for strings and arithmetic for integers.)  A field may appear more than once
+in a given frame.  In general, if any apperance of a field has a value that
+satisfies its operator, then the expression evaluates to true.  The one
+exception is the "!=" operator, which asserts that _all_ appearances of a field
+are not equal to a value, making it the logical negation of the "==" operator.footnote:[This differs from previous, deprecated behavior.  To obtain the old behavior, which was true if any appearance was not equal, use the "any_ne", "~=" operator.]
+
 === Search and match operators
 
 Additional operators exist expressed only in English, not C-like syntax:
 
     contains     Does the protocol, field or slice contain a value
-    matches, ~   Does the protocol or text string match the given
-                 case-insensitive Perl-compatible regular expression
+    matches, ~   Does the string match the given case-insensitive
+                 Perl-compatible regular expression
 
 The "contains" operator allows a filter to search for a sequence of
-characters, expressed as a string (quoted or unquoted), or bytes,
-expressed as a byte array, or for a single character, expressed as a
-C-style character constant.  For example, to search for a given HTTP
+characters, expressed as a string, or bytes, expressed as a byte array.
+The type of the left hand side of the "contains" operator must be comparable to
+that of the right hand side after any implicit or explicit conversions.
+
+For example, to search for a given HTTP
 URL in a capture, the following filter can be used:
 
     http contains "https://www.wireshark.org"
@@ -76,11 +93,12 @@ URL in a capture, the following filter can be used:
 The "contains" operator cannot be used on atomic fields,
 such as numbers or IP addresses.
 
-The "matches"  or "~" operator allows a filter to apply to a specified
-Perl-compatible regular expression (PCRE).  The "matches" operator is only
-implemented for protocols and for protocol fields with a text string
-representation. Matches are case-insensitive by default.  For example,
-to search for a given WAP WSP User-Agent, you can write:
+The "matches" or "~" operator allows a filter to apply to a specified
+Perl-compatible regular expression (PCRE).  The regular expression must
+be a double quoted string.  The left hand side of the "matches" operator
+must be a string, which can be a non-stringlike field implicitly or
+explicitly converted to a string.  Matches are case-insensitive by default.
+For example, to search for a given WAP WSP User-Agent, you can write:
 
     wsp.header.user_agent matches "cldc"
 
@@ -283,16 +301,7 @@ or
 
     frame[-4:] == 0.1.2.3
 
-A slice is always compared against either a string or a byte sequence.
-As a special case, when the slice is only 1 byte wide, you can compare
-it against a hex integer that is 0xff or less (which means it fits inside
-one byte). This is not allowed for byte sequences greater than one byte,
-because then one would need to specify the endianness of the multi-byte
-integer. Also, this is not allowed for decimal numbers, since they
-would be confused with hex numbers that are already allowed as
-byte strings. Nevertheless, single-byte hex integers can be convenient:
-
-    frame[4] == 0xff
+A slice can always be compared against either a string or a byte sequence.
 
 Slices can be combined. You can concatenate them using the comma operator:
 
@@ -307,7 +316,7 @@ A field may be checked for matches against a set of values simply with the
 membership operator. For instance, you may find traffic on common HTTP/HTTPS
 ports with the following filter:
 
-    tcp.port in {80 443 8080}
+    tcp.port in {80,443,8080}
 
 as opposed to the more verbose:
 
@@ -315,29 +324,47 @@ as opposed to the more verbose:
 
 To find HTTP requests using the HEAD or GET methods:
 
-    http.request.method in {"HEAD" "GET"}
+    http.request.method in {"HEAD", "GET"}
 
 The set of values can also contain ranges:
 
-    tcp.port in {443 4430..4434}
-    ip.addr in {10.0.0.5 .. 10.0.0.9 192.168.1.1..192.168.1.9}
+    tcp.port in {443, 4430..4434}
+    ip.addr in {10.0.0.5 .. 10.0.0.9, 192.168.1.1..192.168.1.9}
     frame.time_delta in {10 .. 10.5}
 
-=== Type conversions
+=== Implicit type conversions
 
-If a field is a text string or a byte array, it can be expressed in whichever
-way is most convenient.
+Fields which are sequences of bytes, including protocols, are implicitly
+converted to strings for comparisons against (double quoted) literal strings
+and raw strings.
 
 So, for instance, the following filters are equivalent:
 
-    http.request.method == "GET"
-    http.request.method == 47.45.54
+    tcp.payload contains "GET"
+    tcp.payload contains 47.45.54
 
-A range can also be expressed in either way:
+As noted above, a slice can also be compared in either way:
 
     frame[60:2] gt 50.51
     frame[60:2] gt "PQ"
 
+The inverse does not occur; stringlike fields are not implicitly converted to
+byte arrays.  (Some operators allow stringlike fields to be compared with
+unquoted literals, which are then treated as strings; this is deprecated in
+general and specifically disallowed by the "matches" operator.
+Literal strings should be double quoted for clarity.)
+
+A hex integer that is 0xff or less (which means it fits inside one byte)
+can be implicitly converted to a byte string.  This is not allowed for
+hex integers greater than one byte, because then one would need to specify
+the endianness of the multi-byte integer. Also, this is not allowed for
+decimal or octal numbers, since they would be confused with the hex numbers
+that make up byte string literals. Nevertheless, single-byte hex integers
+can be convenient:
+
+    frame[4] == 0xff
+    frame[1:4] contains 0x02
+
 === Bit field operations
 
 It is also possible to define tests with bit field operations. Currently the