regex3.h File Reference

Manage regular expressions. More...

#include "config.h"
#include <regex.h>
#include <stdbool.h>
#include <stdint.h>
#include "queue.h"
#include <stddef.h>

Include dependency graph for regex3.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	Regex
	Cached regular expression. More...
struct	RegexNode
	List of regular expressions. More...
struct	Replace
	List of regular expressions. More...

Macros
#define	REG_WORDS   0
#define	REG_COMP(preg, regex, cflags)
	Compile a regular expression.

Functions
static regoff_t	mutt_regmatch_start (const regmatch_t *match)
	Return the start of a match.
static regoff_t	mutt_regmatch_end (const regmatch_t *match)
	Return the end of a match.
static size_t	mutt_regmatch_len (const regmatch_t *match)
	Return the length of a match.
	STAILQ_HEAD (RegexList, RegexNode)
	STAILQ_HEAD (ReplaceList, Replace)
struct Regex *	mutt_regex_compile (const char *str, uint16_t flags)
	Create an Regex from a string.
struct Regex *	mutt_regex_new (const char *str, uint32_t flags, struct Buffer *err)
	Create an Regex from a string.
void	mutt_regex_free (struct Regex **ptr)
	Free a Regex object.
int	mutt_regexlist_add (struct RegexList *rl, const char *str, uint16_t flags, struct Buffer *err)
	Compile a regex string and add it to a list.
void	mutt_regexlist_free (struct RegexList *rl)
	Free a RegexList object.
bool	mutt_regexlist_match (struct RegexList *rl, const char *str)
	Does a string match any Regex in the list?
struct RegexNode *	mutt_regexlist_new (void)
	Create a new RegexList.
int	mutt_regexlist_remove (struct RegexList *rl, const char *str)
	Remove a Regex from a list.
int	mutt_replacelist_add (struct ReplaceList *rl, const char *pat, const char *templ, struct Buffer *err)
	Add a pattern and a template to a list.
char *	mutt_replacelist_apply (struct ReplaceList *rl, const char *str)
	Apply replacements to a buffer.
void	mutt_replacelist_free (struct ReplaceList *rl)
	Free a ReplaceList object.
bool	mutt_replacelist_match (struct ReplaceList *rl, char *buf, size_t buflen, const char *str)
	Does a string match a pattern?
struct Replace *	mutt_replacelist_new (void)
	Create a new ReplaceList.
int	mutt_replacelist_remove (struct ReplaceList *rl, const char *pat)
	Remove a pattern from a list.
bool	mutt_regex_match (const struct Regex *regex, const char *str)
	Shorthand to mutt_regex_capture()
bool	mutt_regex_capture (const struct Regex *regex, const char *str, size_t num, regmatch_t matches[])
	Match a regex against a string, with provided options.

Detailed Description

Manage regular expressions.

Authors

• Richard Russon
• Pietro Cerutti

Copyright

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

Definition in file regex3.h.

Macro Definition Documentation

REG_WORDS

#define REG_WORDS   0

Definition at line 39 of file regex3.h.

REG_COMP

#define REG_COMP	(		preg,
			regex,
			cflags )

Value:

regcomp(preg, regex, REG_WORDS | REG_EXTENDED | (cflags))

Compile a regular expression.

Parameters

preg	regex_t struct to fill
regex	Regular expression string
cflags	Flags

Return values

0	Success
num	Failure, e.g. REG_BADPAT

Definition at line 50 of file regex3.h.

Function Documentation

mutt_regmatch_start()

static regoff_t mutt_regmatch_start ( const regmatch_t * match )

inlinestatic

Return the start of a match.

Parameters

match

Match

Return values

num	Start of the match

Definition at line 57 of file regex3.h.

{
  return match->rm_so;
}

Here is the caller graph for this function:

mutt_regmatch_end()

static regoff_t mutt_regmatch_end ( const regmatch_t * match )

inlinestatic

Return the end of a match.

Parameters

match

Match

Return values

num	End of the match

Definition at line 67 of file regex3.h.

{
  return match->rm_eo;
}

Here is the caller graph for this function:

mutt_regmatch_len()

static size_t mutt_regmatch_len ( const regmatch_t * match )

inlinestatic

Return the length of a match.

Parameters

match

Match

Return values

num	Length of the match

Definition at line 77 of file regex3.h.

{
  return match->rm_eo - match->rm_so;
}

Here is the caller graph for this function:

STAILQ_HEAD() [1/2]

STAILQ_HEAD	(	RegexList	,
		RegexNode	)

STAILQ_HEAD() [2/2]

STAILQ_HEAD	(	ReplaceList	,
		Replace	)

mutt_regex_compile()

struct Regex * mutt_regex_compile	(	const char *	str,
		uint16_t	flags )

Create an Regex from a string.

Parameters

str	Regular expression
flags	Type flags, e.g. REG_ICASE

Return values

ptr	New Regex object
NULL	Error

Definition at line 58 of file regex.c.

{
  if (!str || (*str == '\0'))
    return NULL;
  struct Regex *rx = MUTT_MEM_CALLOC(1, struct Regex);
  rx->pattern = mutt_str_dup(str);
  rx->regex = MUTT_MEM_CALLOC(1, regex_t);
  if (REG_COMP(rx->regex, str, flags) != 0)
    mutt_regex_free(&rx);
 
  return rx;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_regex_new()

struct Regex * mutt_regex_new	(	const char *	str,
		uint32_t	flags,
		struct Buffer *	err )

Create an Regex from a string.

Parameters

str	Regular expression
flags	Type flags, e.g. D_REGEX_MATCH_CASE
err	Buffer for error messages

Return values

ptr	New Regex object
NULL	Error

Definition at line 79 of file regex.c.

{
  if (!str || (*str == '\0'))
    return NULL;
 
  uint16_t rflags = 0;
  struct Regex *reg = MUTT_MEM_CALLOC(1, struct Regex);
 
  reg->regex = MUTT_MEM_CALLOC(1, regex_t);
  reg->pattern = mutt_str_dup(str);
 
  /* Should we use smart case matching? */
  if (((flags & D_REGEX_MATCH_CASE) == 0) && mutt_mb_is_lower(str))
    rflags |= REG_ICASE;
 
  /* Is a prefix of '!' allowed? */
  if (((flags & D_REGEX_ALLOW_NOT) != 0) && (str[0] == '!'))
  {
    reg->pat_not = true;
    str++;
  }
 
  int rc = REG_COMP(reg->regex, str, rflags);
  if (rc != 0)
  {
    if (err)
      regerror(rc, reg->regex, err->data, err->dsize);
    mutt_regex_free(&reg);
    return NULL;
  }
 
  return reg;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_regex_free()

void mutt_regex_free

(

struct Regex **

ptr

)

Free a Regex object.

Parameters

[out]

ptr

Regex to free

Definition at line 117 of file regex.c.

{
  if (!ptr || !*ptr)
    return;
 
  struct Regex *rx = *ptr;
  FREE(&rx->pattern);
  if (rx->regex)
    regfree(rx->regex);
  FREE(&rx->regex);
  FREE(ptr);
}

Here is the caller graph for this function:

mutt_regexlist_add()

int mutt_regexlist_add	(	struct RegexList *	rl,
		const char *	str,
		uint16_t	flags,
		struct Buffer *	err )

Compile a regex string and add it to a list.

Parameters

rl	RegexList to add to
str	String to compile into a regex
flags	Flags, e.g. REG_ICASE
err	Buffer for error messages

Return values

0	Success, Regex compiled and added to the list
-1	Error, see message in 'err'

Definition at line 139 of file regex.c.

{
  if (!rl || !str || (*str == '\0'))
    return 0;
 
  struct Regex *rx = mutt_regex_compile(str, flags);
  if (!rx)
  {
    buf_printf(err, "Bad regex: %s\n", str);
    return -1;
  }
 
  /* check to make sure the item is not already on this rl */
  struct RegexNode *np = NULL;
  STAILQ_FOREACH(np, rl, entries)
  {
    if (mutt_istr_equal(rx->pattern, np->regex->pattern))
      break; /* already on the rl */
  }
 
  if (np)
  {
    mutt_regex_free(&rx);
  }
  else
  {
    np = mutt_regexlist_new();
    np->regex = rx;
    STAILQ_INSERT_TAIL(rl, np, entries);
  }
 
  return 0;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_regexlist_free()

void mutt_regexlist_free

(

struct RegexList *

rl

)

Free a RegexList object.

Parameters

rl	RegexList to free

Definition at line 178 of file regex.c.

{
  if (!rl)
    return;
 
  struct RegexNode *np = NULL, *tmp = NULL;
  STAILQ_FOREACH_SAFE(np, rl, entries, tmp)
  {
    STAILQ_REMOVE(rl, np, RegexNode, entries);
    mutt_regex_free(&np->regex);
    FREE(&np);
  }
  STAILQ_INIT(rl);
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_regexlist_match()

bool mutt_regexlist_match	(	struct RegexList *	rl,
		const char *	str )

Does a string match any Regex in the list?

Parameters

rl	RegexList to match against
str	String to compare

Return values

true	String matches one of the Regexes in the list

Definition at line 199 of file regex.c.

{
  if (!rl || !str)
    return false;
  struct RegexNode *np = NULL;
  STAILQ_FOREACH(np, rl, entries)
  {
    if (mutt_regex_match(np->regex, str))
    {
      mutt_debug(LL_DEBUG5, "%s matches %s\n", str, np->regex->pattern);
      return true;
    }
  }
 
  return false;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_regexlist_new()

struct RegexNode * mutt_regexlist_new

(

void

)

Create a new RegexList.

Return values

ptr	New RegexList object

Definition at line 220 of file regex.c.

{
  return MUTT_MEM_CALLOC(1, struct RegexNode);
}

Here is the caller graph for this function:

mutt_regexlist_remove()

int mutt_regexlist_remove	(	struct RegexList *	rl,
		const char *	str )

Remove a Regex from a list.

Parameters

rl	RegexList to alter
str	Pattern to remove from the list

Return values

0	Success, pattern was found and removed from the list
-1	Error, pattern wasn't found

If the pattern is "*", then all the Regexes are removed.

Definition at line 234 of file regex.c.

{
  if (!rl || !str)
    return -1;
 
  if (mutt_str_equal("*", str))
  {
    mutt_regexlist_free(rl); /* "unCMD *" means delete all current entries */
    return 0;
  }
 
  int rc = -1;
  struct RegexNode *np = NULL, *tmp = NULL;
  STAILQ_FOREACH_SAFE(np, rl, entries, tmp)
  {
    if (mutt_istr_equal(str, np->regex->pattern))
    {
      STAILQ_REMOVE(rl, np, RegexNode, entries);
      mutt_regex_free(&np->regex);
      FREE(&np);
      rc = 0;
    }
  }
 
  return rc;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_replacelist_add()

int mutt_replacelist_add	(	struct ReplaceList *	rl,
		const char *	pat,
		const char *	templ,
		struct Buffer *	err )

Add a pattern and a template to a list.

Parameters

rl	ReplaceList to add to
pat	Pattern to compile into a regex
templ	Template string to associate with the pattern
err	Buffer for error messages

Return values

0	Success, pattern added to the ReplaceList
-1	Error, see message in 'err'

Definition at line 270 of file regex.c.

{
  if (!rl || !pat || (*pat == '\0') || !templ)
    return 0;
 
  struct Regex *rx = mutt_regex_compile(pat, REG_ICASE);
  if (!rx)
  {
    buf_printf(err, _("Bad regex: %s"), pat);
    return -1;
  }
 
  /* check to make sure the item is not already on this rl */
  struct Replace *np = NULL;
  STAILQ_FOREACH(np, rl, entries)
  {
    if (mutt_istr_equal(rx->pattern, np->regex->pattern))
    {
      /* Already on the rl. Formerly we just skipped this case, but
       * now we're supporting removals, which means we're supporting
       * re-adds conceptually. So we probably want this to imply a
       * removal, then do an add. We can achieve the removal by freeing
       * the template, and leaving t pointed at the current item.  */
      FREE(&np->templ);
      break;
    }
  }
 
  /* If np is set, it's pointing into an extant ReplaceList* that we want to
   * update. Otherwise we want to make a new one to link at the rl's end.  */
  if (np)
  {
    mutt_regex_free(&rx);
  }
  else
  {
    np = mutt_replacelist_new();
    np->regex = rx;
    rx = NULL;
    STAILQ_INSERT_TAIL(rl, np, entries);
  }
 
  /* Now np is the Replace that we want to modify. It is prepared. */
  np->templ = mutt_str_dup(templ);
 
  /* Find highest match number in template string */
  np->nmatch = 0;
  for (const char *p = templ; *p;)
  {
    if (*p == '%')
    {
      int n = 0;
      const char *end = mutt_str_atoi(++p, &n);
      if (!end)
      {
        // this is not an error, we might have matched %R or %L in subjectrx
        mutt_debug(LL_DEBUG2, "Invalid match number in replacelist: '%s'\n", p);
      }
      if (n > np->nmatch)
      {
        np->nmatch = n;
      }
      if (end)
      {
        p = end;
      }
      else
      {
        p++;
      }
    }
    else
    {
      p++;
    }
  }
 
  if (np->nmatch > np->regex->regex->re_nsub)
  {
    if (err)
      buf_addstr(err, _("Not enough subexpressions for template"));
    mutt_replacelist_remove(rl, pat);
    return -1;
  }
 
  np->nmatch++; /* match 0 is always the whole expr */
  return 0;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_replacelist_apply()

char * mutt_replacelist_apply	(	struct ReplaceList *	rl,
		const char *	str )

Apply replacements to a buffer.

Parameters

rl	ReplaceList to apply
str	String to manipulate

Return values

ptr	New string with replacements

Note

Caller must free the returned string

Definition at line 368 of file regex.c.

{
  if (!rl || !str || (*str == '\0'))
    return NULL;
 
  static regmatch_t *pmatch = NULL;
  static size_t nmatch = 0;
  char *p = NULL;
 
  struct Buffer *src = buf_pool_get();
  struct Buffer *dst = buf_pool_get();
 
  buf_strcpy(src, str);
 
  struct Replace *np = NULL;
  STAILQ_FOREACH(np, rl, entries)
  {
    /* If this pattern needs more matches, expand pmatch. */
    if (np->nmatch > nmatch)
    {
      MUTT_MEM_REALLOC(&pmatch, np->nmatch, regmatch_t);
      nmatch = np->nmatch;
    }
 
    if (mutt_regex_capture(np->regex, buf_string(src), np->nmatch, pmatch))
    {
      mutt_debug(LL_DEBUG5, "%s matches %s\n", buf_string(src), np->regex->pattern);
 
      buf_reset(dst);
      if (np->templ)
      {
        for (p = np->templ; *p;)
        {
          if (*p == '%')
          {
            p++;
            if (*p == 'L')
            {
              p++;
              buf_addstr_n(dst, buf_string(src), pmatch[0].rm_so);
            }
            else if (*p == 'R')
            {
              p++;
              buf_addstr(dst, src->data + pmatch[0].rm_eo);
            }
            else
            {
              long n = strtoul(p, &p, 10); /* get subst number */
              if (n < np->nmatch)
              {
                buf_addstr_n(dst, src->data + pmatch[n].rm_so,
                             pmatch[n].rm_eo - pmatch[n].rm_so);
              }
              while (mutt_isdigit(*p)) /* skip subst token */
                p++;
            }
          }
          else
          {
            buf_addch(dst, *p++);
          }
        }
      }
 
      buf_strcpy(src, buf_string(dst));
      mutt_debug(LL_DEBUG5, "subst %s\n", buf_string(dst));
    }
  }
 
  char *result = buf_strdup(src);
 
  buf_pool_release(&src);
  buf_pool_release(&dst);
  return result;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_replacelist_free()

void mutt_replacelist_free

(

struct ReplaceList *

rl

)

Free a ReplaceList object.

Parameters

rl	ReplaceList to free

Definition at line 449 of file regex.c.

{
  if (!rl)
    return;
 
  struct Replace *np = NULL, *tmp = NULL;
  STAILQ_FOREACH_SAFE(np, rl, entries, tmp)
  {
    STAILQ_REMOVE(rl, np, Replace, entries);
    mutt_regex_free(&np->regex);
    FREE(&np->templ);
    FREE(&np);
  }
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_replacelist_match()

bool mutt_replacelist_match	(	struct ReplaceList *	rl,
		char *	buf,
		size_t	buflen,
		const char *	str )

Does a string match a pattern?

Parameters

rl	ReplaceList of patterns
buf	Buffer to save match
buflen	Buffer length
str	String to check

Return values

true	String matches a patterh in the ReplaceList

Match a string against the patterns defined by the 'spam' command and output the expanded format into buf when there is a match. If buflen<=0, the match is performed but the format is not expanded and no assumptions are made about the value of buf so it may be NULL.

Definition at line 477 of file regex.c.

{
  if (!rl || !buf || !str)
    return false;
 
  static regmatch_t *pmatch = NULL;
  static size_t nmatch = 0;
  int tlen = 0;
  char *p = NULL;
 
  struct Replace *np = NULL;
  STAILQ_FOREACH(np, rl, entries)
  {
    /* If this pattern needs more matches, expand pmatch. */
    if (np->nmatch > nmatch)
    {
      MUTT_MEM_REALLOC(&pmatch, np->nmatch, regmatch_t);
      nmatch = np->nmatch;
    }
 
    /* Does this pattern match? */
    if (mutt_regex_capture(np->regex, str, (size_t) np->nmatch, pmatch))
    {
      mutt_debug(LL_DEBUG5, "%s matches %s\n", str, np->regex->pattern);
      mutt_debug(LL_DEBUG5, "%d subs\n", (int) np->regex->regex->re_nsub);
 
      /* Copy template into buf, with substitutions. */
      for (p = np->templ; *p && (tlen < (buflen - 1));)
      {
        /* backreference to pattern match substring, eg. %1, %2, etc) */
        if (*p == '%')
        {
          char *e = NULL; /* used as pointer to end of integer backreference in strtol() call */
 
          p++; /* skip over % char */
          long n = strtol(p, &e, 10);
          /* Ensure that the integer conversion succeeded (e!=p) and bounds check.  The upper bound check
           * should not strictly be necessary since add_to_spam_list() finds the largest value, and
           * the static array above is always large enough based on that value. */
          if ((e != p) && (n >= 0) && (n < np->nmatch) && (pmatch[n].rm_so != -1))
          {
            /* copy as much of the substring match as will fit in the output buffer, saving space for
             * the terminating nul char */
            for (int idx = pmatch[n].rm_so;
                 (idx < pmatch[n].rm_eo) && (tlen < (buflen - 1)); idx++)
            {
              buf[tlen++] = str[idx];
            }
          }
          p = e; /* skip over the parsed integer */
        }
        else
        {
          buf[tlen++] = *p++;
        }
      }
      /* tlen should always be less than buflen except when buflen<=0
       * because the bounds checks in the above code leave room for the
       * terminal nul char.   This should avoid returning an unterminated
       * string to the caller.  When buflen<=0 we make no assumption about
       * the validity of the buf pointer. */
      if (tlen < buflen)
      {
        buf[tlen] = '\0';
        mutt_debug(LL_DEBUG5, "\"%s\"\n", buf);
      }
      return true;
    }
  }
 
  return false;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_replacelist_new()

struct Replace * mutt_replacelist_new

(

void

)

Create a new ReplaceList.

Return values

ptr	New ReplaceList

Definition at line 554 of file regex.c.

{
  return MUTT_MEM_CALLOC(1, struct Replace);
}

Here is the caller graph for this function:

mutt_replacelist_remove()

int mutt_replacelist_remove	(	struct ReplaceList *	rl,
		const char *	pat )

Remove a pattern from a list.

Parameters

rl	ReplaceList to modify
pat	Pattern to remove

Return values

num	Matching patterns removed

Definition at line 565 of file regex.c.

{
  if (!rl || !pat)
    return 0;
 
  int nremoved = 0;
  struct Replace *np = NULL, *tmp = NULL;
  STAILQ_FOREACH_SAFE(np, rl, entries, tmp)
  {
    if (mutt_str_equal(np->regex->pattern, pat))
    {
      STAILQ_REMOVE(rl, np, Replace, entries);
      mutt_regex_free(&np->regex);
      FREE(&np->templ);
      FREE(&np);
      nremoved++;
    }
  }
 
  return nremoved;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_regex_match()

bool mutt_regex_match	(	const struct Regex *	regex,
		const char *	str )

Shorthand to mutt_regex_capture()

Parameters

regex	Regex which is desired to match against
str	String to search with given regex

Return values

true	str matches
false	str does not match

Definition at line 613 of file regex.c.

{
  return mutt_regex_capture(regex, str, 0, NULL);
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_regex_capture()

bool mutt_regex_capture	(	const struct Regex *	regex,
		const char *	str,
		size_t	nmatch,
		regmatch_t	matches[] )

Match a regex against a string, with provided options.

Parameters

regex	Regex to execute
str	String to apply regex on
nmatch	Length of matches
matches	regmatch_t to hold match indices

Return values

true	str matches
false	str does not match

Definition at line 596 of file regex.c.

{
  if (!regex || !str || !regex->regex)
    return false;
 
  int rc = regexec(regex->regex, str, nmatch, matches, 0);
  return ((rc == 0) ^ regex->pat_not);
}

Here is the caller graph for this function: