As of the release of version 10 there are some great new features built into classes and the way they work within iRules, as well as a very powerful new command to let you make use of them. Here's a little history on how things used to be (and still are in v9.x).

Prior to v10.0 the most common way to make use of a data group (class) within an iRule was with either matchclass or findclass. These were used to parse through a class file to search for a specific entry and return particular results, which worked fine. The example below shows a simple example of doing this:

class my_data_group {
  "/site1/"
  "/site2/"
}
rule myRule {
  when HTTP_REQUEST {
    if {[matchclass [HTTP::uri] starts_with $::my_data_group]}{
      log "requested URL starts with /site1/ or /site2/"
    }
  }
}

This example, and all others that make use of matchclass and findclass, continue to work the same way in v10.0. We aren't changing these just yet, so all of your iRules that make use of them will still function. There were some changes necessary though to allow for the new structures to be implemented and allow for the awesome new capabilities.

Prior to v10.0 it was possible to access the contents of a class in another way, without using matchclass or findclass, because class objects could also be treated as TCL lists.  In v10.0 and later, Data Group (class) objects can no longer be treated as TCL lists. This is becaues the class structure itself had to be changed to allow for the new commands and functionality. Our custom commands could be re-worked to function properly still, but the base TCL commands aren't built to work with the changes.

The following is an example of using a class as a TCL list from within an iRule:

when RULE_INIT {
  log "value of first element in my_data_group: [lindex $::my_data_group 0]"
  log "value of second element in my_data_group: [lindex $::my_data_group 1]"
}

Note that the TCL command 'lindex' was used to access the contents of the my_data_group class object (shown earlier).  In v10.0 calling the class name ($::my_data_group above) will just return the name of the class itself, making examples like the one above unusable. It's important to note that if you are making use of this functionality now, you will need to update your code before upgrading to v10, or your iRules will not function as expected. There are a number of commands that operate on TCL lists, which is why people have used this kind of referencing in the future.  The list of commands that people might be using in iRules to operate on class includes: foreach, join, lappend, lassign, lindex, linsert, llength, lrange, lrepeat, lreplace, lreverse, lsearch, lset, lsort, and possibly more.

To ensure that users don't lose this functionality, a new iRule command named 'class' is available to provide list-type access to data groups.  In the example above, instead of using '[lindex $::my_data_group 0]' you would now use: '[class element 0 my_data_group]'.  You can also return the  entire contents of a data group as a TCL list, and then operate on the returned list as before.  To return a data group as a list, you would use a command like this:  '[class get my_data_group]'

This change in behavior was necessary to make data groups compatible with CMP (Clustered Multi-Processing), and to add support for name-value lookups like the following example:

class images {
  "square.gif" := "<contents of image goes here>"
  "circle.gif" := "<contents of image goes here>"
}

Within an iRule you could then use the following to lookup the value of "square.gif" and place its contents in a variable named "image": set image [class lookup square.gif images].

That gets the history of how classes used to work out of the way, along with a few examples that show some of the new behavior and how to make it work for you. Now let's look at the new commands and how they work. The list is pretty long so rather than go through each command with commentary here, I'm going to drop in the entire syntax guide for the new class commands and leave discussion and commenting to the forums and wikis. Here is the new set of class commands, along with the available syntax for them:

class match [<options>] <item> <operator> <class>
  Returns 0 or 1 depending on whether <item> matches an element in <class> according to the <operator>.
  This command form is equivalent to the current iRule command:
  matchclass <item> <operator> <class>.
  Example:
    class match [HTTP::uri] ends_with image_class
    Read as: does the uri end with an element from image_class
class search [<options>] <class> <operator> <item>
  Returns 0 or 1 depending on whether an element in <class> matches <item> according to the <operator>.
  This command form is equivalent to the current iRule command: 	matchclass <class> <operator> <item>.
  Example:
    class search blocked_paths starts_with [HTTP::uri]
    Read as: does blocked_paths contain an element that starts with the uri.
  The options for both of the above forms of the class command can be:
    -index		Changes the return value to be the index of the matching class element.
    -name		Changes the return value to be the name of the matching class element.
    -value		Changes the return value to be the value of the matching class element.
    -element	Changes the return value to be a list of the name and value of the matching class element.
    -all		When used with the above options, returns a list of all matching elements, not just the first.
    --		Terminates option processing (useful if the item or '<class>' begins with a hyphen).
  The <operator> for both of the above forms can be:
    equals, starts_with, ends_with, contains
class lookup <item> <class>
  Equivalent to: class match -value <item> equals <class>.
class element [<options>] <index> <class>
  Returns a list containing the name and value of the element found at <index> in <class>.
  Note: class indexes are not guaranteed to be consistent and may change when a datagroup is modified.  
  This could happen if the event execution becomes suspended or across executions of different events.
  The <options> for this command can be:
    -name	Changes the return value to be the name of the class element at the index.
    -value	Changes the return value to be the value of the class element at the index.
    --	Terminates option processing.
class type <class>
  Returns the type of the <class>, currently only “string”, “IP”, or “value”.
class exists <class>
  Returns 1 or 0 depending on whether a class named <class> actually exists.
class size <class>
  Returns the number of elements currently found in <class>.
class names [-nocase] <class> [<pattern>]
class get [-nocase] <class> [<pattern>]
  Returns a list containing the names or a list of the name and value currently found in <class>.  
  An optional <pattern> may be specified to restrict the list to names that match the Tcl glob pattern.  
  Additionally, the switch -nocase may be specified to enable case-insensitive pattern matching.
  This command provides a way to access the class as a Tcl list similar to previously access the global 
  variable named the same as the list.

The following forms of the class command provide behavior similar to the native Tcl array command for iterating across the elements of a datagroup.

class startsearch <class>
  Returns a <search_id> to be used with each of the following commands.
  Note: the search is not guaranteed to iterate over every element and may miss elements if the datagroup is modified.  
  This could happen if the execution of the event becomes suspended or across executions of different events.
class nextelement [<options>] <class> <search_id>
  Returns a list containing the name and value of the next element in the current search.
  The <options> for this command can be:
    -index	Changes the return value to be the index of the next class element.
    -name	Changes the return value to be the name of the next class element.
    -value	Changes the return value to be the value of the next class element.
    --	Terminates option processing.
class anymore <class> <search_id>
  Returns 1 or 0 depending on whether there are more elements to iterate on in the <class>.
class donesearch <class> <search_id>
  Terminates the search.  After using this command, executing class anymore will return 0 
and executing class nextelement will cause an error.

COMMENTS