mirror of
https://github.com/zeek/zeek.git
synced 2025-10-02 14:48:21 +00:00
ded98cd373
This is based on commit 2731def9159247e6da8a3191783c89683363689c from the zeek-docs repo.
420 lines
10 KiB
ReStructuredText
420 lines
10 KiB
ReStructuredText
Operators
|
|
=========
|
|
|
|
The Zeek scripting language supports the following operators. Note that
|
|
each data type only supports a subset of these operators. For more
|
|
details, see the documentation about the :doc:`data types <types>`.
|
|
|
|
.. _relational-operators:
|
|
|
|
Relational operators
|
|
--------------------
|
|
|
|
The relational operators evaluate to type :zeek:type:`bool`.
|
|
|
|
In addition to numeric operands, the relational operators also work with
|
|
operands of type :zeek:type:`interval`, :zeek:type:`time`, :zeek:type:`string`,
|
|
:zeek:type:`port`, :zeek:type:`addr`, and :zeek:type:`set`.
|
|
|
|
.. list-table::
|
|
:header-rows: 1
|
|
|
|
* - Name
|
|
- Syntax
|
|
|
|
* - Equality
|
|
- ``a == b``
|
|
|
|
* - Inquality
|
|
- ``a != b``
|
|
|
|
* - Less than
|
|
- ``a < b``
|
|
|
|
* - Less than or equal
|
|
- ``a <= b``
|
|
|
|
* - Greater than
|
|
- ``a > b``
|
|
|
|
* - Greater than or equal
|
|
- ``a >= b``
|
|
|
|
.. _logical-operators:
|
|
|
|
Logical operators
|
|
-----------------
|
|
|
|
The logical operators require operands of type :zeek:type:`bool`, and
|
|
evaluate to type :zeek:type:`bool`.
|
|
|
|
.. list-table::
|
|
:header-rows: 1
|
|
|
|
* - Name
|
|
- Syntax
|
|
|
|
* - Logical AND
|
|
- ``a && b``
|
|
|
|
* - Logical OR
|
|
- ``a || b``
|
|
|
|
* - Logical NOT
|
|
- ``! a``
|
|
|
|
.. _arithmetic-operators:
|
|
|
|
Arithmetic operators
|
|
--------------------
|
|
|
|
.. list-table::
|
|
:header-rows: 1
|
|
|
|
* - Name
|
|
- Syntax
|
|
- Notes
|
|
|
|
* - Addition
|
|
- ``a + b``
|
|
- For :zeek:type:`string` operands, this performs string concatenation.
|
|
|
|
* - Subtraction
|
|
- ``a - b``
|
|
-
|
|
|
|
* - Multiplication
|
|
- ``a * b``
|
|
-
|
|
|
|
* - Division
|
|
- ``a / b``
|
|
- For :zeek:type:`int` or :zeek:type:`count` operands, the fractional part
|
|
of the result is dropped.
|
|
|
|
* - Modulo
|
|
- ``a % b``
|
|
- Operand types cannot be :zeek:type:`double`.
|
|
|
|
* - Unary plus
|
|
- ``+a``
|
|
-
|
|
|
|
* - Unary minus
|
|
- ``-a``
|
|
-
|
|
|
|
* - Pre-increment
|
|
- ``++a``
|
|
- Operand type cannot be :zeek:type:`double`.
|
|
|
|
* - Pre-decrement
|
|
- ``--a``
|
|
- Operand type cannot be :zeek:type:`double`.
|
|
|
|
* - Absolute value
|
|
- ``|a|``
|
|
- If operand is :zeek:type:`string`, :zeek:type:`set`, :zeek:type:`table`,
|
|
or :zeek:type:`vector`, this evaluates to number of elements.
|
|
|
|
.. _bitwise-operators:
|
|
|
|
Bitwise operators
|
|
-----------------
|
|
|
|
The bitwise operators work with operands of type :zeek:type:`count` or ``vector
|
|
of count``. The bitwise shift operators can also work with :zeek:type:`int`.
|
|
The bitwise complement operator works with :zeek:type:`count` only.
|
|
|
|
.. list-table::
|
|
:header-rows: 1
|
|
|
|
* - Name
|
|
- Syntax
|
|
|
|
* - Bitwise AND
|
|
- ``a & b``
|
|
|
|
* - Bitwise OR
|
|
- ``a | b``
|
|
|
|
* - Bitwise XOR
|
|
- ``a ^ b``
|
|
|
|
* - Bitwise left shift
|
|
- ``a << b``
|
|
|
|
* - Bitwise right shift
|
|
- ``a >> b``
|
|
|
|
* - Bitwise complement
|
|
- ``~a``
|
|
|
|
.. _set-operators:
|
|
|
|
Set operators
|
|
-------------
|
|
|
|
.. list-table::
|
|
:header-rows: 1
|
|
|
|
* - Name
|
|
- Syntax
|
|
|
|
* - Set intersection
|
|
- ``s1 & s2``
|
|
|
|
* - Set union
|
|
- ``s1 | s2``
|
|
|
|
* - Set difference
|
|
- ``s1 - s2``
|
|
|
|
.. _assignment-operators:
|
|
|
|
Assignment operators
|
|
--------------------
|
|
|
|
The assignment operators evaluate to the result of the assignment.
|
|
|
|
.. list-table::
|
|
:header-rows: 1
|
|
|
|
* - Name
|
|
- Syntax
|
|
|
|
* - Assignment
|
|
- ``a = b``
|
|
|
|
* - Addition assignment (more generally, "add to")
|
|
- ``a += b``
|
|
|
|
* - Subtraction assignment (more generally, "remove from")
|
|
- ``a -= b``
|
|
|
|
Along with simple arithmetic, the ``+=`` operator supports adding elements to
|
|
:zeek:type:`table`,
|
|
:zeek:type:`set`,
|
|
:zeek:type:`vector`, and
|
|
:zeek:type:`pattern`
|
|
values, providing the righthand operand (RHS) has the same type.
|
|
For :zeek:type:`table` and :zeek:type:`set` values,
|
|
each of the RHS elements are added to the
|
|
table or set. For :zeek:type:`vector`, the RHS elements are appended to
|
|
the end of the vector. For :zeek:type:`pattern` values, the pattern is
|
|
modified to include the RHS pattern as an alternative (regular expression ``|``
|
|
operator).
|
|
|
|
The ``-=`` operator provides analogous functionality for :zeek:type:`table`
|
|
and :zeek:type:`set` types, removing from the lefthand operand any elements
|
|
it has in common with the RHS value. (Note that for tables, only the
|
|
indices are used; if the RHS value has an index in common with the lefthand
|
|
operand's value, it's removed even if the "yield" values differ.)
|
|
|
|
For all assignment operators, you can specify a comma-separated list of
|
|
values within braces (``{`` ... ``}``). These are treated as *constructor*
|
|
arguments to create a corresponding :zeek:type:`table`, :zeek:type:`set`,
|
|
or :zeek:type:`vector` value, with the type of constructor taken from
|
|
the lefthand operand. For example:
|
|
|
|
.. code-block:: zeek
|
|
|
|
local t: table[count, string] of double;
|
|
...
|
|
t += { [3, "three"] = 3.0, [9, "nine"] = 9.0 };
|
|
|
|
will add those two elements to the table ``t``. For :zeek:type:`table`
|
|
and :zeek:type:`set` constructors, you can embed lists in the constructor
|
|
arguments to produce a cross-product expansion. For example:
|
|
|
|
.. code-block:: zeek
|
|
|
|
local t: table[count, string] of double;
|
|
...
|
|
t += { [[3, 4], ["three", "four"]] = 3.0, [9, "nine"] = 9.0 };
|
|
|
|
results in ``t`` having five elements:
|
|
|
|
.. code-block:: zeek
|
|
|
|
[3, three] = 3.0
|
|
[3, four] = 3.0
|
|
[4, three] = 3.0
|
|
[4, four] = 3.0
|
|
[9, nine] = 9.0
|
|
|
|
Finally, you can also use the ``+=`` operator to
|
|
append an element to the end of a
|
|
vector. For example, ``v += e`` is equivalent to ``v[|v|] = e``,
|
|
providing that ``e``'s type corresponds to that of one of ``v``'s elements.
|
|
|
|
.. _record-field-operators:
|
|
|
|
Record field operators
|
|
----------------------
|
|
|
|
The record field operators take a :zeek:type:`record` as the first operand,
|
|
and a field name as the second operand. For both operators, the specified
|
|
field name must be in the declaration of the record type.
|
|
|
|
.. list-table::
|
|
:header-rows: 1
|
|
|
|
* - Name
|
|
- Syntax
|
|
- Notes
|
|
|
|
* - Field access
|
|
- ``a$b``
|
|
-
|
|
|
|
* - Field value existence test
|
|
- ``a?$b``
|
|
- Evaluates to type :zeek:type:`bool`. True if the specified field has
|
|
been assigned a value, or if not.
|
|
|
|
.. _pattern-operators:
|
|
|
|
Pattern operators
|
|
-----------------
|
|
|
|
In the table below, ``p`` is a pattern, and ``s`` is a string.
|
|
|
|
.. list-table::
|
|
:header-rows: 1
|
|
|
|
* - Name
|
|
- Syntax
|
|
- Notes
|
|
|
|
* - Exact matching
|
|
- ``p == s``
|
|
- Evaluates to a boolean, indicating if the entire string exactly matches
|
|
the pattern.
|
|
|
|
* - Embedded matching
|
|
- ``p in s``
|
|
- Evaluates to a boolean, indicating if pattern is found somewhere in the
|
|
string.
|
|
|
|
* - Conjunction
|
|
- ``p1 & p2``
|
|
- Evaluates to a pattern that represents matching ``p1`` followed by
|
|
``p2``.
|
|
|
|
* - Disjunction
|
|
- ``p1 | p2``
|
|
- Evaluates to a pattern that represents matching ``p1`` or ``p2``.
|
|
|
|
Type casting
|
|
------------
|
|
|
|
The ``as`` operator performs type casting and the ``is`` operator checks if a
|
|
type cast is supported or not. For both operators, the first operand is a
|
|
value and the second operand is the name of a Zeek script type (either built-in
|
|
or user-defined).
|
|
|
|
.. list-table::
|
|
:header-rows: 1
|
|
|
|
* - Name
|
|
- Syntax
|
|
- Notes
|
|
|
|
* - Type cast
|
|
- ``v as t``
|
|
- Cast value ``v`` into type ``t``. Evaluates to the value as cast to the
|
|
specified type. If this is not a supported cast, then a runtime error
|
|
is triggered.
|
|
|
|
* - Check if a cast is supported
|
|
- ``v is t``
|
|
- Evaluates to :zeek:type:`bool`. If true, then ``v as t`` would succeed.
|
|
|
|
Only the following kinds of type casts are supported currently:
|
|
|
|
- Broker values (i.e., :zeek:see:`Broker::Data` values returned from
|
|
functions such as :zeek:id:`Broker::data`) can be cast to their
|
|
corresponding Zeek script types.
|
|
- A value of declared type :zeek:type:`any` can be cast to its actual
|
|
underlying type.
|
|
- All values can be cast to their declared types (i.e., this is a no-op).
|
|
- :zeek:type:`set` and :zeek:type:`vector` values can be converted into each
|
|
other, with the following limitations: (1) A :zeek:type:`set` being converted
|
|
into a :zeek:type:`vector` can only have a single index type. Converting a
|
|
set with multiple index types will return an error. (2) The :zeek:type:`set`
|
|
and :zeek:type:`vector` types must have the same internal type.
|
|
|
|
The function in this example tries to cast a value to a string:
|
|
|
|
.. code-block:: zeek
|
|
|
|
function example(a: any)
|
|
{
|
|
local s: string;
|
|
|
|
if ( a is string )
|
|
s = (a as string);
|
|
}
|
|
|
|
The function in this example converts a set to a vector:
|
|
|
|
.. code-block:: zeek
|
|
|
|
function example()
|
|
{
|
|
local s: set[count] = { 1, 2, 3 };
|
|
local v = s as vector of count;
|
|
}
|
|
|
|
Other operators
|
|
---------------
|
|
|
|
.. list-table::
|
|
:header-rows: 1
|
|
|
|
* - Name
|
|
- Syntax
|
|
- Notes
|
|
|
|
* - Membership test
|
|
- ``a in b``
|
|
- Evaluates to type :zeek:type:`bool`. Works with :zeek:type:`string`,
|
|
:zeek:type:`pattern`, :zeek:type:`subnet`, :zeek:type:`set`,
|
|
:zeek:type:`table`, or :zeek:type:`vector` operands. Do not confuse this
|
|
use of ``in`` with that used in a :zeek:keyword:`for`
|
|
statement.
|
|
|
|
* - Non-membership test
|
|
- ``a !in b``
|
|
- This is the logical NOT of the ``in`` operator. For example:
|
|
``a !in b`` is equivalent to ``!(a in b)``.
|
|
|
|
* - Table or vector element access
|
|
- ``a[b]``
|
|
- This operator can also be used with a :zeek:type:`set`, but only with the
|
|
:zeek:keyword:`add` or :zeek:keyword:`delete` statement.
|
|
|
|
* - Substring extraction
|
|
- ``a[b:c]``
|
|
- See the :zeek:type:`string` type for more details.
|
|
|
|
* - Create a deep copy
|
|
- ``copy(a)``
|
|
- This is relevant only for data types that are assigned by reference, such
|
|
as :zeek:type:`vector`, :zeek:type:`set`, :zeek:type:`table`, and
|
|
:zeek:type:`record`.
|
|
|
|
* - Module namespace access
|
|
- ``a::b``
|
|
- The first operand is the module name, and the second operand is an
|
|
identifier that refers to a global variable, enumeration constant, or
|
|
user-defined type that was exported from the module.
|
|
|
|
* - Conditional
|
|
- ``a ? b : c``
|
|
- The first operand must evaluate to type :zeek:type:`bool`. If true, then
|
|
the second expression is evaluated and is the result of the entire
|
|
expression. Otherwise, the third expression is evaluated and is the
|
|
result of the entire expression. The types of the second and third
|
|
operands must be compatible. Known as the ternary operator.
|