Text::DelimMatch - Perl extension to find regexp delimited strings with proper nesting

  use Text::DelimMatch;

  $mc = new Text::DelimMatch, $startdelim, $enddelim;

  $mc->quote('"');
  $mc->escape("\\");
  $mc->double_escape('"');
  $mc->case_sensitive(1);

  ($prefix, $match, $remainder) = $mc->match($string);
  ($prefix, $nextmatch, $remainder) = $mc->match();

  $middle = $mc->strip_delim($match); # returns $match w/o start and end delim

These routines allow you to match delimited substrings in a buffer. The delimiters can be specified with any regular expression and the start and end delimiters need not be the same. If the delimited text is properly nested, entire nested groups are returned.

In addition, you may specify quoting and escaping characters that contribute to the recognition of start and end delimiters.

For example, if you specify the start and end delimiters as '\(' and '\)', respectively, and the double quote character as a quoting character, and the backslash as an escaping character, then the delimited substring in this buffer is (ma(t)c\)h):

  'prefix text "(quoted text)" \(escaped \" text) (ma(t)c\)h) postfix text'

In order to support this rather complex interface, the matching context is encapsulated in an object. The object, Text::DelimMatch, has the following public methods: Creates a new object. All of the arguments are optional, and can be set with other methods, but they must be passed in the specified order: start delimiter, end delimiter, escape characters, double escape characters, and a set of quote characters. In an array context, returns ($pre, CW$match, CW$post) where CW$pre is the text preceding the first match, CW$match is the matched text (including the delimiters), and CW$post is the rest of the text in the buffer. In a scalar context, returns CW$match. If CW$string is not provided on subsequent calls, the CW$post from the previous match is used, unless keep is false. If keep is false, the match always fails. Returns CW$string with the start and end delimiters removed. Set the start and end delimiters. Only one set of delimiters can be in use at any one time. Returns the delimters in use before this call. Specifies the start and end quote characters. Multiple quote character pairs are supported, so this function is additive. To clear the current settings, pass no arguments, e.g., CW$mc->quote(). If only CW$start is passed, CW$end is assumed to be the same. In matching, quotes occur in pairs. In other words, if (,) and (',') are both specified as quote pairs and a string beginning with is found, it is ended only by another , not by '. Returns the quote hash in use before this call. Specifies a set of escaping characters. This can only be a string of characters. CW$esc can be a regexp set or a simple string. If it is a simple string, it will be translated into the regexp set [ quotemeta($esc) ]. Returns the escape characters in use before this call. Specifies a set of double-escaping characters, i.e., characters that are considered escaped if they occur in pairs. For example, in some languages,

  'Don''t you see?'

pre_matched

Returns the prefix text from the last match if keep is true. Sets an error and returns an empty string if keep is false.

matched

Returns the matched text from the last match if keep is true. Sets an error and returns an empty string if keep is false.

post_matched

Returns the postfix text from the last match if keep is true. Sets an error and returns an empty string if keep is false. Sets debug to CW$bool or true if CW$bool is not specified. If debug is true, informative and progress messages are printed to STDOUT by some methods. Returns the debugging setting in use before this call.

dump

For debugging, prints all of the instance variables for a particular object. For debugging. Some classes of delimited strings can be located with much faster algorithms than can be used in the most general case. If slow is true, the slower, general algorithm is always used.

For simplicity, and backward compatibility with the previous (limited release) incarnation of this module, the following functions are also available directly: If CW$three is true, returns ($pre, CW$match, CW$post) in an array context otherwise returns ($pre$match, CW$post). In a scalar context, returns $pre$match. If CW$three is true, returns ($pre, CW$match, CW$post) in an array context otherwise returns ($pre$match, CW$post). In a scalar context, returns CW$post.

  $mc = new Text::DelimMatch '"';
  $mc->('pre "match" post') == '"match"';

  $mc->delim("\\(", "\\)");
  $mc->('pre (match) post')   == ('pre ', '(match)', ' post');
  $mc->('pre (ma(t)ch) post') == ('pre ', '(ma(t)ch)', ' post');

  $mc->quote('"');
  $mc->escape("\\");
  $mc->('pre (ma")"tch) post') == ('pre ', '(ma")"tch)', ' post');
  $mc->('pre (ma(t)c\)h\") post') == ('pre ', '(ma(t)c\)h\")', ' post');

See also test.pl in the distribution.

Norman Walsh, ndw@nwalsh.com

Copyright (C) 1997-2002 Norman Walsh. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

THIS PACKAGE IS PROVIDED AS IS AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.

perl(1).