Merge remote-tracking branch 'origin/topic/dnthayer/ticket1947'

* origin/topic/dnthayer/ticket1947:
  Fix some typos and formatting in NEWS
  Add pattern operators to the documentation of operators
  Fix minor typos in broker reference documentation
  Fix a broken link and some typos in broker documentation
  Fix reST formatting in documentation of "count" type
  Add documentation for some new Bro features

doc/script-reference/operators.rst

@@ -85,6 +85,25 @@ Arithmetic operators
 |                              |             | of elements.                  |
 +------------------------------+-------------+-------------------------------+
 
+Bitwise operators
+-----------------
+
+The bitwise operators work with operands of type :bro:type:`count` or
+``vector of count``, but the bitwise complement operator works with ``count``
+only.
+
++------------------------------+-------------+
+| Name                         | Syntax      |
++==============================+=============+
+| Bitwise AND                  | *a* & *b*   |
++------------------------------+-------------+
+| Bitwise OR                   | *a* | *b*   |
++------------------------------+-------------+
+| Bitwise XOR                  | *a* ^ *b*   |
++------------------------------+-------------+
+| Bitwise complement           | ~ *a*       |
++------------------------------+-------------+
+
 
 Assignment operators
 --------------------
@@ -122,6 +141,73 @@ field name must be in the declaration of the record type.
 +------------------------------+-------------+-------------------------------+
 
 
+Pattern operators
+-----------------
+
+In the table below, *p* is a pattern, and *s* is a string.
+
++------------------------------+-------------+-------------------------------+
+| 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 Bro script type (either built-in
+or user-defined).
+
++------------------------------+-------------+-------------------------------+
+| Name                         | Syntax      | Notes                         |
++==============================+=============+===============================+
+| Type cast                    | *v* as *t*  | Cast value "v" into type "t". |
+|                              |             | Evaluates to the value casted |
+|                              |             | 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 boolean. If true,|
+|                              |             | then "v as t" would succeed.  |
++------------------------------+-------------+-------------------------------+
+
+Only the following kinds of type casts are supported currently:
+
+- Broker values (i.e., :bro:see:`Broker::Data` values returned from
+  functions such as :bro:id:`Broker::data`) can be casted to their
+  corresponding Bro script types.
+- A value of declared type "any" can be casted to its actual underlying type.
+- All values can be casted to their declared types (i.e., this is a no-op).
+
+The function in this example tries to cast a value to a string::
+
+    function example(a: any)
+        {
+        local s: string;
+
+        if ( a is string )
+            s = (a as string);
+        }
+
+
 Other operators
 ---------------
 

doc/script-reference/statements.rst

@@ -571,6 +571,42 @@ Here are the statements that the Bro scripting language supports.
     do not indicate the presence of a `compound statement`_), and that no
     semicolon is needed at the end of a "switch" statement.
 
+    There is an alternative form of the switch statement that supports
+    switching by type rather than value.  This form of the switch statement
+    uses type-based versions of "case":
+
+    - "case type t: ...": Take branch if the value of the switch expression
+      could be casted to type t (where "t" is the name of a Bro script type,
+      either built-in or user-defined).
+
+    - "case type t as x: ...": Same as above, but the casted value is
+      available through ID "x".
+
+    Multiple types can be listed per branch, separated by commas (the "type"
+    keyword must be repeated for each type in the list).
+
+    Example::
+
+        function example(v: any)
+            {
+            switch (v) {
+            case type count as c:
+                    print "It's a count", c;
+                    break;
+
+            case type bool, type addr:
+                    print "It's a bool or address";
+                    break;
+            }
+            }
+
+    Note that a single switch statement switches either by type or by value,
+    but not both.
+
+    Also note that the type-based switch statement will trigger a runtime
+    error if any cast in any "case" is an unsupported cast (see the
+    documentation of the type casting operator "as").
+
 
 .. bro:keyword:: when
 

doc/script-reference/types.rst

@@ -92,7 +92,7 @@ Here is a more detailed description of each type:
     "int".
 
     In addition, "count" types support bitwise operations.  You can use
-    ``&``, ``|``, and ``^`` for bitwise ``and'', ``or'', and ``xor''.  You
+    ``&``, ``|``, and ``^`` for bitwise ``and``, ``or``, and ``xor``.  You
     can also use ``~`` for bitwise (one's) complement.
 
 .. bro:type:: double