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

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.