Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
DelimMatch(3)	      User Contributed Perl Documentation	 DelimMatch(3)

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

SYNOPSIS
	 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

DESCRIPTION
       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:

       new $start, $end, $escape, $dblesc, $qs1, $qe1, ... $qsn, $qen
	   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.

       match $string
	   In an array context,	returns	($pre, $match, $post) where $pre is
	   the text preceding the first	match, $match is the matched text
	   (including the delimiters), and $post is the	rest of	the text in
	   the buffer.	In a scalar context, returns $match.

	   If $string is not provided on subsequent calls, the $post from the
	   previous match is used, unless keep is false.  If keep is false,
	   the match always fails.

       strip_delim $string
	   Returns $string with	the start and end delimiters removed.

       delim $start, $end
	   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.

       quote $startq, $endq
	   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.,	$mc->quote().

	   If only $start is passed, $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.

       escape $esc
	   Specifies a set of escaping characters.  This can only be a string
	   of characters.  $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.

       double_escape $esc
	   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?'

	   defines a string containing a single	apostrophe.

	   $esc	can only be a string of	characters.  $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 double-escaping characters in use before	this call.

       case_sensitive $bool
	   Sets	case sensitivity to $bool or true if $bool is not specified.

	   Returns the case sensitivity	in use before this call.

       keep $bool
	   Sets	keep to	$bool or true if $bool is not specified.

	   Keep, which is true by default, specifies whether or	not the
	   matching context object keeps a local copy of the buffer used in
	   matching.  Keeping a	local copy allows repeated matching on the
	   same	buffer,	but might be a bad idea	if the buffer is a terabyte
	   long. ;-)

	   Returns the keep setting in use before this call.

       returndelim $bool
	   Sets	returndelim to $bool or	true if	$bool is not specified.

	   Returndelim,	which is true by default, specifies whether or not the
	   start and end delimiters are	returned with the matching string.

	   Returns the returndelim setting in use before this call.

       error $seterr
	   Returns the last error that occured.	 If $seterr is passed, the
	   error is set	to that	value.	Some common kinds of bad input are
	   detected and	an error condition is raised.  If an error condition
	   is raised, all matching fails until the error is cleared.

	   The most common error is a bad regular expression, for example
	   specifing the start delimiter as "("	instead	of "\\(".  Remember,
	   these are regexps!

       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.

       debug $bool
	   Sets	debug to $bool or true if $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.

       slow $bool
	   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:

       nested_match ($string, $start, $end, $three)
	   If $three is	true, returns ($pre, $match, $post) in an array
	   context otherwise returns ("$pre$match", $post).  In	a scalar
	   context, returns "$pre$match".

       skip_nested_match ($string, $start, $end, $three)
	   If $three is	true, returns ($pre, $match, $post) in an array
	   context otherwise returns ("$pre$match", $post).  In	a scalar
	   context, returns $post.

EXAMPLES
	 $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.

AUTHOR
       Norman Walsh, ndw@nwalsh.com

COPYRIGHT
       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.

WARRANTY
       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.

SEE ALSO
       perl(1).

perl v5.24.1			  2002-10-02			 DelimMatch(3)

NAME | SYNOPSIS | DESCRIPTION | EXAMPLES | AUTHOR | COPYRIGHT | WARRANTY | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Text::DelimMatch&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help