ActiveState::Rx::Info -- An object-oriented interface to the Regular Expression debugger.

- NAME
- SYNOPSIS
- DESCRIPTION
- API

- new(regex[, modifiers])
- `regex()`
- `modifiers()`
- `groupCount()`
- `nodeId(offset)`
- `maxLevel(nodeId)`
- `match(target)`
- `nodeTip(nodeId)`
- `nodeRange(nodeId)`
- `childNodesRange(nodeId)`
- `groupId(nodeId)`
- `matchId(nodeId)`
- `findnode(criteria)`

- AUTHOR
- COPYRIGHT

# NAME

ActiveState::Rx::Info -- An object-oriented interface to the Regular Expression debugger.

# SYNOPSIS

      use ActiveState::Rx::Info;

      my $obj = ActiveState::Rx::Info->new('(.*)(\d+)');
      print "Matched!" if ($obj->match('testing 123'));
      print "The number of groups in this regex is: $obj->groupCount\n";
      my $nid = $obj->findnode(TYPE => 'OPEN', ARGS => 1);
      print "The start of group 1 is at offset: ",
        $obj->nodeRange($nid), "\n";

This complete program prints out:

      Matched!
      The number of groups in this regex is: 2
      The start of group 1 is at offset: 0

# DESCRIPTION

ActiveState::Rx::Info is designed to provide a higher level abstraction of the regular expression debugger than does ActiveState::Rx. The modified compiler and executor are kept in ActiveState::Rx, but ActiveState::Rx::Info makes it easier to use.

# API

The following sections document the methods available from ActiveState::Rx::Info.

## new(regex[, modifiers])

Creates a ActiveState::Rx::Info object. 'regex' is the regular expression to generate information about, and 'modifiers' is an optional parameter containing perl modifiers g, i, s, m, o, and x.

## `regex()`

Returns the string form of the regular expression stored in the object.

## `modifiers()`

Returns the string form of the modifiers stored in the object.

## `groupCount()`

Returns the number of groups found in the regex. For example,

      use ActiveState::Rx::Info;
      my $gc = ActiveState::Rx::Info->new('(abc*)')->groupCount;

In this example, `$gc` will be set to 1.

## `nodeId(offset)`

Returns the 'node id' of the node found at the given offset into the regular expression string. Most API functions in ActiveState::Rx::Info operate on a node id, since that is how regular expressions are manipulated internally.

## `maxLevel(nodeId)`

Returns the maximum 'level' of the node. Level is an abstract concept -- so abstract it hasn't even been nailed down. Yet. This function currently doesn't do anything except return 0.

## `match(target)`

Attempts to apply the regular expression to the target string. Returns a list of offsets in the target string, designed to aid highlighting the parts of the string which corresponded to groups in the regular expression.

Here is an example:

      use ActiveState::Rx::Info;
      my @m = ActiveState::Rx::Info->new('(.*)(\d+)')->match('testing123');

In this example, `@m` is set to (0, 9, 0, 8, 9, 9). These numbers represent three pairs of numbers: (0, 9), (0, 8), and (9, 9). These pairs represent substrings of the target string corresponding to matches. The first pair is always the substring `$&`, or the extents of the match. The remaining pairs all refer to `$1`, `$2`, and so on. If global matching is turned on, then there will be one `$&` at the beginning, and one pair for each iteration of the match.

If no string was matched by the particular pair, they are both undef.

## `nodeTip(nodeId)`

Returns a node tip corresponding to the given regular expression node. For example:

      use ActiveState::Rx::Info;
      my $o = ActiveState::Rx::Info->new('abc*');
      print $o->nodeTip($o->nodeId(0));

will print Match 'ab'.

## `nodeRange(nodeId)`

Returns the range of the node in the regular expression string. For example:

      use ActiveState::Rx::Info;
      my $o = ActiveState::Rx::Info->new('abc*');
      print join ', ', $o->nodeRange($o->nodeId(0));

will print 0, 1.

## `childNodesRange(nodeId)`

Returns the range of any children of the given node. Some nodes do not have children; they will return an empty list.

## `groupId(nodeId)`

Returns the group number that nodeId refers to. Only supported if nodeId is either an OPEN or CLOSE node.

## `matchId(nodeId)`

Returns the nodeId of a node which ``matches'' the given node. Currently only implemented if nodeId refers to a OPEN or CLOSE node. If nodeId returns to an OPEN node, it returns the node id of the corresponding CLOSE, and vice versa.

## `findnode(criteria)`

Searches the nodes in the regular expression for a matching node. Returns the node id of the matching node structure. For example:

      use ActiveState::Rx::Info;
      my $o = ActiveState::Rx::Info->new('ab(c*)');
      my $nid = $o->findnode(TYPE => OPEN, ARGS => 1);

This example set `$nid` to the node id referring to the first OPEN node in the regular expression.

# AUTHOR

Neil Watkiss <neilw@ActiveState.com> ActiveState Corporation

# COPYRIGHT

Copyright (c) 2001, ActiveState SRL.

ActiveState::Rx::Info -- An object-oriented interface to the Regular Expression debugger.