Arithmetic Operators

Assignment Operators

Relational Operators

Logical Operators

Other Operators

For Loop

Bro uses a "foreach" style loop.

for ( c in "abc" )
    print c;

If Statement

If statements conditionally execute another statement or block of statements.

local x = "3";

for ( c in "12345" )
    {
    if ( c == x )
        {
        print "Found it.";
        # A preview of functions: fmt() does substitutions, outputs result.
        print fmt("And by 'it', I mean %s.", x);
        }
    else
        # A quick way to print multiple things on one line.
        print "I'm looking for", x, "not", c;
    }

There’s enough blueprints about the language by this point to start solving more "interesting" problems, so we’ll start practicing.

Switch Statement

Sometimes a switch statement is a more convenient way to organize code. For example, consider a switch instead of large chains of "else if" blocks, or possibly if there’s a large chain of OR’d conditions. The syntax looks like:

local x = 4;

switch ( x ) {
case 0:
    # This block only executes if x is 0.
    print "case 0";
    break;
case 1, 2, 3:
    # This block executes if any of the case labels match.
    print "case 1, 2, 3";
    break;
case 4:
    print "case 4 and ...";
    # Block ending in the "fallthrough" also execute subsequent case.
    fallthrough;
case 5:
    # This block may execute if x is 4 or 5.
    print "case 5";
    break;
default:
    # This block executed if no other case matches.
    print "default case";
    break;
}

Primitive Types

• bool - a value that’s either true (T) or false (F).

• double - a double-precision floating-point value.

• int - a signed 64-bit integer. May be automatically promoted to a double when needed.

• count - an unsigned 64-bit integer. May be automatically promoted to an int or double when needed.

• time - an absolute point in time (note the only way to create an arbitrary time value is via the double_to_time(d), with d being a variable of type double).

• interval - a relative unit of time. Known units are usec, msec, sec, min, hr, or day (any may be pluralized by adding "s" to the end). Examples: 3secs, -1min.

• port - a transport-level port number. Examples: 80/tcp, 53/udp.

• addr - an IP address. Examples: 1.2.3.4, [2001:db8::1].

• subnet - a set of IP addresses with a common prefix. Example: 192.168.0.0/16. Note that the / operator used on an address as the left operand produces a subnet mask of bit-width equal to the value of the right operand.

• enum - a user-defined type specifying a set of related values.

  type Color: enum { Red, Green, Blue, };
  

• string - character-string values.

• pattern - a regular expression using flex’s syntax. Some examples:

  print /one|two|three/ == "two";  # T
  print /one|two|three/ == "ones"; # F (exact matching)
  print /one|two|three/ in "ones"; # T (embedded matching)
  print /[123].*/ == "2 two";  # T
  print /[123].*/ == "4 four"; # F
  

Composite Types

• set - a collection of unique values. Set uses the add and delete operators to add and remove elements itself and the in operator for querying membership:

  local x: set[string] = { "one", "two", "three" };
  add x["four"];
  print "four" in x; # T
  delete x["two"];
  print "two" !in x; # T
  add x["one"]; # x is unmodified since 1 is already a member.
  for ( e in x ) print e;
  

• table - an associative collection that maps a set of unique indices to other values. Like sets, the delete operator is used to remove elements, however, adding elements is done just by assigning to an index:

  local x: table[count] of string = { [1] = "one", [3] = "three",
                                      [5] = "five" };
  x[7] = "seven";
  print 7 in x; # T
  print x[7]; # seven
  delete x[3];
  print 3 !in x; # T
  x[1] = "1"; # changed the value at index 1
  for ( key in x ) print key;
  

• vector - a collection of values with 0-based indexing.

  local x: vector of string = { "one", "two", "three" };
  print x; # [one, two, three]
  print x[1]; # two
  x[|x|] = "one";
  print x; # [one, two, three, one]
  for ( i in x ) print i;  # Iterates over indices.
  

• record - a user-defined collection of named values of

  heterogeneous types. Fields are dereferenced via the $ operator (., as used in other languages is ambiguous in Bro because of IPv4 address literals). Optional field existence is checked via the ?$ operator.

  type MyRecord: record {
      a: string;
      b: count;
      c: bool &default = T;
      d: int &optional;
  };
  
  local x = MyRecord($a = "vvvvvv", $b = 6, $c = F, $d = -13);
  if ( x?$d ) print x$d;
  x = MyRecord($a = "abc", $b = 3);
  print x$c;  # T (default value of the field)
  print x?$d; # F (optional field was not set)
  

• function

  Example of function syntax/usage:

  # Optional function declaration.
  # Takes one required string argument
  # and another optional string argument
  # and returns a string value.
  global emphasize: function(s: string, p: string &default = "*"): string;
  
  # Function implementation.
  function emphasize(s: string, p: string &default = "*"): string
      {
      return p + s + p;
      }
  
  # Function calls.
  print emphasize("yes");
  print emphasize("no", "_");
  

• event

  Events are a special flavor of functions that Bro frequently uses. They differ from functions in the following ways:

  • They may be scheduled and executed at a later time, so that their effects may not be realized directly after they are invoked.
  • They return no value — they can’t since they’re not called directly but rather scheduled for later execution.
  • Multiple bodies can be defined for the same event, each one is deemed an "event handler", and when it comes time to execute an event, all handler bodies for that event are executed in order of &priority.

  # Optional event declaration.
  global myevent: event(s: string);
  
  global n = 0;
  
  # Event handler implementation.
  # &priority attribute is optional and
  # may be used to influence the order in which
  # event handler bodies execute.
  # If omitted, &priority is implicitly 0.
  event myevent(s: string) &priority = -10
      {
      ++n;
      }
  
  # Another event handler.  &priority can be used
  # to influence the order
  # in which event handler bodies are executed.
  event myevent(s: string) &priority = 10
      {
      print "myevent", s, n;
      }
  
  # "bro_init" is a special event that's executed once when Bro starts.
  event bro_init()
      {
      print "bro_init()";
      # Schedule an event to execute as soon as possible.
      event myevent("hi");
      # Schedule an event to execute 5 seconds in
      # the future (or upon
      # Bro shutting down, whichever is sooner).
      schedule 5 sec { myevent("bye") };
      }
  
  # Another special event executed when Bro is shutting down.
  event bro_done()
      {
      print "bro_done()";
      }
  

• hook

  Hooks are yet another flavor of function. They are most like events, but with a few main differences:

  • They do execute immediately when invoked (i.e. they’re not scheduled like events).
  • It matters how the body of a hook handler terminates. If the end of the body or a return statement is reached, remaining hook handlers will be executed. If a hook handler body terminates due to a break statement being reached, no remaining hook handlers are executed.

  # Optional hook declaration.
  global myhook: hook(s: string);
  
  # Hook handler definition.
  # &priority is optional, and implicitly 0
  # if omitted.
  hook myhook(s: string) &priority = 10
      {
      print "priority 10 myhook handler", s;
      # Arguments may be modified and is visible
      # to remaining handlers.
      s = "bye";
      }
  
  hook myhook(s: string)
      {
      print "break out of myhook handling", s;
      break;
      }
  
  hook myhook(s: string) &priority = -5
      {
      print "not going to happen", s;
      }
  
  # Hook invocation.  Return value is implicitly
  # a boolean with a value of
  # true if all defined hook handlers were executed
  # (i.e. no body exited
  # as a result of a break statement).
  local ret: bool = hook myhook("hi");
  
  if ( ret )
      print "all handlers ran";