src/regexp.h

   1 /*
   2  * Copyright (C) the libgit2 contributors. All rights reserved.
   3  *
   4  * This file is part of libgit2, distributed under the GNU GPL v2 with
   5  * a Linking Exception. For full terms see the included COPYING file.
   6  */
   7
   8 #ifndef INCLUDE_regexp_h__
   9 #define INCLUDE_regexp_h__
  10
  11 #include "common.h"
  12
  13 #if defined(GIT_REGEX_BUILTIN) || defined(GIT_REGEX_PCRE)
  14 # include "pcre.h"
  15 typedef pcre *git_regexp;
  16 # define GIT_REGEX_INIT NULL
  17 #elif defined(GIT_REGEX_PCRE2)
  18 # define PCRE2_CODE_UNIT_WIDTH 8
  19 # include <pcre2.h>
  20 typedef pcre2_code *git_regexp;
  21 # define GIT_REGEX_INIT NULL
  22 #elif defined(GIT_REGEX_REGCOMP) || defined(GIT_REGEX_REGCOMP_L)
  23 # include <regex.h>
  24 typedef regex_t git_regexp;
  25 # define GIT_REGEX_INIT { 0 }
  26 #else
  27 # error "No regex backend"
  28 #endif
  29
  30 /** Options supported by @git_regexp_compile. */
  31 typedef enum {
  32         /** Enable case-insensitive matching */
  33         GIT_REGEXP_ICASE = (1 << 0)
  34 } git_regexp_flags_t;
  35
  36 /** Structure containing information about regular expression matching groups */
  37 typedef struct {
  38         /** Start of the given match. -1 if the group didn't match anything */
  39         ssize_t start;
  40         /** End of the given match. -1 if the group didn't match anything */
  41         ssize_t end;
  42 } git_regmatch;
  43
  44 /**
  45  * Compile a regular expression. The compiled expression needs to
  46  * be cleaned up afterwards with `git_regexp_dispose`.
  47  *
  48  * @param r Pointer to the storage where to initialize the regular expression.
  49  * @param pattern The pattern that shall be compiled.
  50  * @param flags Flags to alter how the pattern shall be handled.
  51  *              0 for defaults, otherwise see @git_regexp_flags_t.
  52  * @return 0 on success, otherwise a negative return value.
  53  */
  54 int git_regexp_compile(git_regexp *r, const char *pattern, int flags);
  55
  56 /**
  57  * Free memory associated with the regular expression
  58  *
  59  * @param r The regular expression structure to dispose.
  60  */
  61 void git_regexp_dispose(git_regexp *r);
  62
  63 /**
  64  * Test whether a given string matches a compiled regular
  65  * expression.
  66  *
  67  * @param r Compiled regular expression.
  68  * @param string String to match against the regular expression.
  69  * @return 0 if the string matches, a negative error code
  70  *         otherwise. GIT_ENOTFOUND if no match was found,
  71  *         GIT_EINVALIDSPEC if the regular expression matching
  72  *         was invalid.
  73  */
  74 int git_regexp_match(const git_regexp *r, const char *string);
  75
  76 /**
  77  * Search for matches inside of a given string.
  78  *
  79  * Given a regular expression with capturing groups, this
  80  * function will populate provided @git_regmatch structures with
  81  * offsets for each of the given matches. Non-matching groups
  82  * will have start and end values of the respective @git_regmatch
  83  * structure set to -1.
  84  *
  85  * @param r Compiled regular expression.
  86  * @param string String to match against the regular expression.
  87  * @param nmatches Number of @git_regmatch structures provided by
  88  *                 the user.
  89  * @param matches Pointer to an array of @git_regmatch structures.
  90  * @return 0 if the string matches, a negative error code
  91  *         otherwise. GIT_ENOTFOUND if no match was found,
  92  *         GIT_EINVALIDSPEC if the regular expression matching
  93  *         was invalid.
  94  */
  95 int git_regexp_search(const git_regexp *r, const char *string, size_t nmatches, git_regmatch *matches);
  96
  97 #endif