DelimMatch(3pm)

💖 DelimMatch — the Text::DelimMatch page, but make it cute 💖

okay bestie, welcome to User Contributed Perl Documentation, and today's main character is DelimMatch(3pm). yes it's a perl thing. yes it's iconic. let's go 🦋

---

✨ NAME ✨

Text::DelimMatch — a Perl extension that finds regexp-delimited strings, and it does the nesting properly 💅

---

🎀 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

like. look at it. it's giving object-oriented but make it effortless 💜

---

🌸 DESCRIPTION 🌸

So basically, these routines let you match delimited substrings inside a buffer. The delimiters can be any regular expression, and the start and end delimiters do not have to be the same thing. and if the delimited text is properly nested? entire nested groups come back to you. as a treat 🫶

Bonus round: you can also specify quoting and escaping characters, and those lil guys actually count toward recognizing start and end delimiters.

fr fr example time. say you set the start and end delimiters to '\(' and '\)', 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'

To support this whole ~complex interface~ the matching context is encapsulated in an object. That object, Text::DelimMatch, has these public methods:

new $start, $end, $escape, $dblesc, $qs1, $qe1, ... $qsn, $qen

Makes a brand new object, slay. Every argument is optional and you can set them later with other methods — but if you pass them here they have to come in this exact order: start delimiter, end delimiter, escape characters, double escape characters, and then a set of quote characters. no skipping the line bestie ✋

match $string

In an array context it returns ($pre, $match, $post), where $pre is the text before the first match, $match is the matched text (delimiters included, no cap), and $post is the rest of the text in the buffer. In a scalar context it just returns $match.

If you don't hand over a $string on later calls, it reuses the $post from the previous match — unless keep is false. And if keep is false? the match always fails. periodt 💀

strip_delim $string

Returns $string with the start and end delimiters taken off. clean. minimal. aesthetic ✨

delim $start, $end

Sets the start and end delimiters. Only one set of delimiters can be in use at any one time, so pick a lane.

Returns the delimiters that were 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 — it stacks. To clear whatever's currently set, pass no arguments, e.g. $mc->quote().

If you only pass $start, then $end is assumed to be the same thing.

When matching, quotes occur in pairs. in other words: if (", ") and (', ') are both specified as quote pairs and a string starting with " is found, it is ended only by another ", not by '. they don't mix, bestie.

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's a simple string, it gets 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 count as escaped if they show up in pairs. For example, in some languages,

'Don''t you see?'

defines a string containing a single apostrophe. the way that works is so cool actually 😭

$esc can only be a string of characters. $esc can be a regexp set or a simple string. If it's a simple string, it gets 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 isn't specified.

Returns the case sensitivity in use before this call.

keep $bool

Sets keep to $bool, or true if $bool isn't specified.

Keep — which is true by default — says whether or not the matching context object keeps a local copy of the buffer used in matching. Keeping a local copy lets you match repeatedly on the same buffer, but it 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 isn't specified.

Returndelim — also true by default — says whether or not the start and end delimiters come back attached to 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 get detected and an error condition is raised. And once an error condition is raised, all matching fails until the error is cleared. so dramatic. so real.

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

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 isn't 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. it's giving "let me see your diary" 🙈

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. sometimes you just gotta take the scenic route 🌈

---

For simplicity, and for 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');

also, see test.pl in the distribution. iykyk 🧚

---

👑 AUTHOR 👑

Norman Walsh, ndw@nwalsh.com — icon behavior, honestly.

---

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

no promises bestie. it is what it is. 💀

---

🌟 SEE ALSO 🌟

• perl(1).

---

and that's the whole page, babe — brought to you by perl v5.36.0, dated 2022-10-13, the little footer that could 💖 mwah, go nest some delimiters 🎀🦋✨