/************************************************************\
 * Copyright (C) 2001 The Regents of the University of California.
 * (c.f. DISCLAIMER, COPYING)
 *
 * This file is part of PowerMan, a remote power management program.
 * For details, see https://github.com/chaos/powerman.
 *
 * SPDX-License-Identifier: GPL-2.0-or-later
\************************************************************/

#ifndef PM_XREGEX_H
#define PM_XREGEX_H

#include <stdbool.h>

/* A compiled regex.
 */
typedef struct xregex_struct *xregex_t;

/* A container for regexec subexpression match results.
 */
typedef struct xregex_match_struct *xregex_match_t;

/* Create/destroy a regex object.
 */
xregex_t xregex_create(void);
void xregex_destroy(xregex_t x);

/* Compile a regex defined by 's' into a regex object created with
 * xregex_create().  's' may contain the strings "\n" or "\r" in expanded
 * form and they will be converted into 0xa and 0xd respectively.
 * If 'withsub' is true, the regex will support subexpression matches.
 * Program terminates with detailed message on compilation error.
 */
void xregex_compile(xregex_t x, const char *s, bool withsub);

/* Execute a compiled regex against the provided string 's'.
 * If xm is non-NULL, place match info there.
 * Returns true on a match.
 */
bool xregex_exec(xregex_t x, const char *s, xregex_match_t xm);

/* Create/destroy/recycle a match result object.
 * The maximum number of matches is specified at creation in 'nmatch'.
 * Allow one match for main expression, and an additional match for
 * each subexpression.
 */
xregex_match_t xregex_match_create(int nmatch);
void xregex_match_destroy(xregex_match_t xm);
void xregex_match_recycle(xregex_match_t xm);

/* Retrieve a copy of the main/subexpression match specified by 'index',
 * or NULL if no match.   The caller must free result with xfree().
 * Index 0 is for the main expression, other indices are for subexpressions.
 * This function must be called only after xregex_exec().
 */
char *xregex_match_sub_strdup(xregex_match_t xm, int index);

/* Similar to xregex_match_sub_strdup(xm, 0) but includes unmatched
 * leading text.  Caller must free result with xfree().
 */
char *xregex_match_strdup(xregex_match_t xm);

/* Strlen of above.
 */
int xregex_match_strlen(xregex_match_t xm);

#endif /* PM_XREGEX_H */

/*
 * vi:tabstop=4 shiftwidth=4 expandtab
 */
