Home Libraries Author Links

Abstract Data Type StmRe
[Match: Pattern Matching with Regular Expressions]

Collaboration diagram for Abstract Data Type StmRe:

Detailed Description

StmRe is an abstract data type used to represent regular expressions.

Re.

An object of abstract data type StmRe is a compiled regular expression representing a character string regular expression of the form reStr (see Regular Expression Syntax). A valid StmRe object is exclusively obtained as return value of one of the functions stmReCreate() and stmReGet(). An invalid StmRe object has value NULL. A StmRe object neither initialized by the functions stmReCreate() or stmReGet() nor having value NULL is undefined.


Files

file  StmReAdtDoc.h
 Documentation of the abstract structure data type type StmRe.

Modules

 Abstract Data Type StmReCtrl
 StmReCtrl is an abstract data type used to control regular expressions.
 Abstract Data Type StmReMtc
 StmReMtc is an abstract data type used to describe the match of a regular expression reStr.
 Abstract Data Type StmQreMtc
 StmQreMtc is an abstract data type used to describe the match of a qualified regular expression qualifRe.

StmRe Representation

An object of abstract data type StmRe is represented as a pointer to its implementation.

typedef struct StmReImpl_ StmReImpl_
 Type name of implementation structure.
typedef StmReImpl_StmRe
 Pointer to implementation.
typedef const StmReImpl_ConstStmRe
 Pointer to constant implementation.

StmRe Creation and Destruction

StmRe stmReCreate (volatile StmReCtrl reCtrl, const char *reName, const char *reStr, int(*reFct)(StmMtcFctCmd cmd, StmReMtc reMtc))
 Creation of a new StmRe object.
int stmReDestroy (StmRe re)
 Destruction of the StmRe object re.

StmRe Method Functions

StmRe stmReGet (StmReCtrl reCtrl, const char *reName)
 Return the StmRe object defined for reCtrl with name reName.
StmBool stmReTest (StmReCtrl reCtrl, const char *reName)
 Determination of a regular expression's existence.
StmBool stmReMatch (StmRe re, const char *str, void *env, void *data)
 Perform a match for a string an return its result.
StmBool stmReMatchSub (StmRe re, const char *str, int len, void *env, void *data)
 Perform a match for a substring an return its result.
int stmReGetErrno (StmRe re)
 Return the current StmRe error number.
const char * stmReGetErrorMsg (StmRe re)
 Return the current StmRe error message.
const char * stmReGetDebugMsg (StmRe re)
 Return the current StmRe debug message.
const char * stmReGetReStr (StmRe re)
 Return the defining reStr.


Typedef Documentation

typedef struct StmReImpl_ StmReImpl_

Type name of implementation structure.

Definition at line 60 of file StmReAdtDoc.h.

typedef StmReImpl_* StmRe

Pointer to implementation.

Examples:
cuglify.c, and matchtst.c.

Definition at line 63 of file StmReAdtDoc.h.

typedef const StmReImpl_* ConstStmRe

Pointer to constant implementation.

Definition at line 66 of file StmReAdtDoc.h.


Function Documentation

StmRe stmReCreate ( volatile StmReCtrl  reCtrl,
const char *  reName,
const char *  reStr,
int(*)(StmMtcFctCmd cmd, StmReMtc reMtc)  reFct 
)

Creation of a new StmRe object.

The funtion stmReCreate returns a valid StmRe object re which represents the regular expression named reName given as string reStr meeting the syntax of a reStr (see Regular Expression Syntax) in an internal compiled form and defines the regular expression for the StmReCtrl object reCtrl, if that object is valid (not NULL). If it is invalid (NULL), the regular expression is defined for an internal standard StmReCtrl object obtained by

                    stmReCtrlCreate (stderr, NULL, NULL, NULL)
By means of the construct '&'reName'&' other named regular expressions defined for re's StmReCtrl object reCtrl can refer to the StmRe object re.

An already defined regular expression named reName is redefined unless it is already used via a reference '&'reName'&' which is an error.

The argument reFct is a pointer to a user supplied regular expression action function. Unless reFct is NULL, this function is called before, during and after the matching process for the regular expression re with a structure cmd of type StmMtcFctCmd used for function control as its first argument and a valid StmReMtc object reMtc describing the match of re as its second and last argument. Hence reFct is of type

                  int (*reFct) (StmMtcFctCmd cmd, StmReMtc reMtc);
A call of reFct before the matching process for re shall be indicated by a value init of cmd and shall serve the purpose of allocating and initializing the match data of re's regular expression match and of defining them for its StmReMtc object reMtc with stmReMtcSetData(). These match data shall serve as result data, as intermediate processing data and as rollback data as appropriate. By means of StmReMtc and StmQreMtc functions for the initialization of the match data of reMtc its global environment, its superior qualified regular expression match and the match of that match's superior regular expression match are available. If the matching of re is caused by a call of stmReMatch() or stmReMatchSub() with a non NULL argument data, no call of reFct before the matching process occurs, as it shall be assumed in this case that data points to data already allocated and initialized by the caller which are used as match data of reMtc then.

A call of reFct during a successful matching of re shall be indicated by a value action of cmd. In this case at first by means of stmReMtcMtermNr() the matching term number of the regular expression shall be determined. Then by means of StmReMtc and StmQreMtc functions the StmQreMtc objects of the qualifRe factors of that matching term are available. Now the task of this call of reFct is to evaluate the match data of these StmQreMtc objects and to collect them in the global environment and in the match data of re. If this evaluation and collection shall not be done, reFct shall return a StmMtcFctFail thus changing the result of the matching of re from successful to unseccessful. Else reFct shall return with StmMtcFctOk. If reFct has been called with a value action of cmd and has returned StmMtcFctOk, its effect can be undone later by calling it with a value rollback of cmd.

A call of reFct with a value rollback of cmd shall serve the purpose of undoing the effects of a previous call of reFct with a value action of cmd. This is necessary, if the matching regular expression re is part of superior qualified regular expression which does not match.

Finally a call of reFct with a value deinit of cmd shall serve the purpose of deinitializing and deallocating the match data of the regular expression match. Such a call only occurs, if the matching of re was not caused by a call of stmReMatch() or stmReMatchSub() with a non NULL argument data. When such a call does not occur, the match data pointed to by data shall remain available.

The different calls of reFct may occur combined by bitwise oring the enumerators of StmMtcFctCmd, in which case they shall be handled in the sequence described above.

In case of success reFct shall return StmMtcFctOk or StmMtcFctFail. On error reFct shall return StmMtcFctError and errno shall have a non zero value describing the error's cause.

In case of error stmReCreate() returns NULL, unless an error jump target has been defined by means of stmReCtrlCreate(). An error occurs, if reStr does not conform to the regular expression syntax reStr (see Regular Expression Syntax), if reStr or reName are NULL, or if reName is the empty string or the name of a regular expression previously defined by sdmReCreate() and already referenced. If configured by stmReCtrlCreate(), on error an error message is issued, and independently of this configuration errno is set to a non zero value describing the error's cause.

Examples:
cuglify.c, and matchtst.c.

Referenced by defsreact(), and main().

int stmReDestroy ( StmRe  re  ) 

Destruction of the StmRe object re.

The function stmReDestroy cancels the definition of the regular expression designated by a valid StmRe object re for its StmReCtrl object and deinitializes the regular expression. Thus the object re becomes undefined. If re is invalid, the function has no effect. If no regular expression with StmRe object re has been defined for its StmReCtrl object, depending on the configuration (see stmReCtrlCreate()) of the StmReCtrl object of re, an error message is issued and the function returns -1, or jumps to the error target configured. On error the variable errno is set to a non zero value reflecting the error's cause. On success 0 is returned.

Examples:
matchtst.c.

StmRe stmReGet ( StmReCtrl  reCtrl,
const char *  reName 
)

Return the StmRe object defined for reCtrl with name reName.

The function stmReGet checks, if by means of stmReCreate() a regular expression named reName has been defined for the StmReCtrl object reCtrl. If so, stmReGet returns with the valid StmRe object of this named regular expression. Else, depending on the configuration (see stmReCtrlCreate()), an error message is issued and the function returns NULL, or jumps to the error target configured. On error the variable errno is set to a non zero value reflecting the error's cause.

StmBool stmReTest ( StmReCtrl  reCtrl,
const char *  reName 
)

Determination of a regular expression's existence.

The function stmReTest returns StmTrue, if for the StmReCtrl object reCtrl a regular expression named reName has been defined by means of stmReCreate(), else StmFalse.

StmBool stmReMatch ( StmRe  re,
const char *  str,
void *  env,
void *  data 
)

Perform a match for a string an return its result.

The function stmReMatch returns StmTrue, if the regular expression of the StmRe object re is matched by the '\0' terminated string str, else StmFalse. Unless an error jump target has been configured with stmReCtrlCreate(), StmFalse is also returned, if re is invalid (NULL), if str is NULL, or data is non NULL and no regular expression action function for re has been defined by stmReCreate(). With env a pointer to a global environment may be provided. That global environment is available for all regular expression functions defined by stmReCreate() and for qualified regular expression actions defined by stmQreActDef() for re's StmReCtrl object by means of stmReMtcEnv() and stmQreMtcEnv(). If data is not NULL, a regular expression action function shall have been associated to re by stmReCreate(), and data shall point to match data of re provided and initialized by the caller. These match data are available to the regular expression's action function by means of stmReMtcData() and to the caller after return.

Examples:
cuglify.c, and matchtst.c.

Referenced by main().

StmBool stmReMatchSub ( StmRe  re,
const char *  str,
int  len,
void *  env,
void *  data 
)

Perform a match for a substring an return its result.

The function stmReMatchSub returns StmTrue, if the regular expression of the StmRe object re is matched by the string str of length len, else StmFalse. Unless an error jump target has been configured with stmReCtrlCreate(), StmFalse is also returned, if re is invalid (NULL), if str is NULL, or data is non NULL and no regular expression action function for re has been defined by stmReCreate(). With env a pointer to a global environment may be provided. That global environment is available for all regular expression functions defined by stmReCreate() and for qualified regular expression actions defined by stmQreActDef() for re's StmReCtrl object by means of stmReMtcEnv() and stmQreMtcEnv(). If data is not NULL, a regular expression action function shall have been associated to re by stmReCreate(), and data shall point to match data of re provided and initialized by the caller. These match data are available to the regular expression's action function by means of stmReMtcData() and to the caller after return.

int stmReGetErrno ( StmRe  re  ) 

Return the current StmRe error number.

The function stmReGetErrno returns the current StmReCtrl error number (see stmReCtrlCreate()) stored in the control object of re (see stmReCreate()) as enumerator of the enumeration StmReCtrlErrnos. If re is invalid (NULL), -1 is returned and the variable errno is set to EINVAL.

const char* stmReGetErrorMsg ( StmRe  re  ) 

Return the current StmRe error message.

The function stmReGetErrorMsg returns an error message associated with the current StmReCtrl error number (see stmReCtrlCreate()) stored in the control object of re (see stmReCreate()). Depending on the configuration set by the errtxt parameter of stmReCtrlCreate() in this message the name of the function having caused the error is followed by the standard error text (see StmMtcErrors) or an individual error text. If re is invalid (NULL), NULL is returned and the variable errno is set to EINVAL.

const char* stmReGetDebugMsg ( StmRe  re  ) 

Return the current StmRe debug message.

The function stmReGetDebugMsg returns the current StmReCtrl debug message (see stmReCtrlCreate()) stored in the control object of re (see stmReCreate()) as a dynamic string (see dvec.h). If re is invalid (NULL), NULL is returned and the variable errno is set to EINVAL.

const char* stmReGetReStr ( StmRe  re  ) 

Return the defining reStr.

The function stmReGetReStr returns the reStr (see Regular Expression Syntax) which defines re (see stmReCreate()). If re is invalid (NULL), NULL is returned and the variable errno is set to EINVAL.


© Copyright Tom Michaelis 2002-2007

Distributed under the SysToMath Software License (See the accompanying file license.txt or a copy at www.SysToMath.com).