Home Libraries Author Links

Abstract Data Type StmReCtrl
[Abstract Data Type StmRe]

Collaboration diagram for Abstract Data Type StmReCtrl:

Detailed Description

StmReCtrl is an abstract data type used to control regular expressions.

ReCtrl.

An object of abstract data type StmReCtrl is a control object for compiled regular expressions of the abstract data type StmRe. A valid StmReCtrl object is exclusively obtained as return value of the function stmReCtrlCreate(). An invalid StmReCtrl object has value NULL. A StmReCtrl object neither initialized by the function stmReCtrlCreate() nor having value NULL is undefined. A valid StmReCtrl object controls the behaviour of the regular expressions defined for it by means of stmReCreate().


Files

file  StmReCtrlAdtDoc.h
 Documentation of the abstract structure data type type StmReCtrl.

Data Structures

struct  StmMtcFctCmd
 StmMtcFctCmd is a type used to control actions for regular and qualified regular expression matches. More...

StmReCtrl Error Handling

enum  StmReCtrlErrnos
 Definition of all possible StmReCtrl error numbers. More...
int stmReCtrlSetErrorEnv (StmReCtrl reCtrl, jmp_buf *penvbuf)
 Set the error environment address of the StmReCtrl object reCtrl.
int stmReCtrlGetErrno (StmReCtrl reCtrl)
 Return the current StmReCtrl error number.
const char * stmReCtrlGetErrorMsg (StmReCtrl reCtrl)
 Return the current StmReCtrl error message.
const char * stmReCtrlGetDebugMsg (StmReCtrl reCtrl)
 Return the current StmReCtrl debug message.
#define StmMtcErrors
 Definition of StmReCtrl error numbers and messages.
#define StmMtcErr(nr, txt)   nr
 Definition of the StmReCtrl error number nr for error text txt.

StmReCtrl Action Handling

enum  StmMtcFctResult {
  StmMtcFctError = -1,
  StmMtcFctOk = 0,
  StmMtcFctFail = 1,
  StmMtcFctReduce = 2
}
 Result values of regular or qualified regular expression action functions. More...
int stmQreActDef (StmReCtrl reCtrl, const char *qreactname, int(*qreFct)(StmMtcFctCmd cmd, StmQreMtc qreMtc))
 Definition of an action function for qualified regular expressions.

StmReCtrl Representation

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

typedef struct StmReCtrlImpl_ StmReCtrlImpl_
 Type name of implementation structure.
typedef StmReCtrlImpl_StmReCtrl
 Pointer to implementation.
typedef const StmReCtrlImpl_ConstStmReCtrl
 Pointer to constant implementation.

StmReCtrl Creation and Destruction

StmReCtrl stmReCtrlCreate (FILE *debug, jmp_buf *penvbuf, const char *xlatetab, const char *const *errtxt)
 Creation of a new StmReCtrl object.
void stmReCtrlDestroy (StmReCtrl reCtrl)
 Destruction of the StmReCtrl object reCtrl.


Define Documentation

#define StmMtcErrors

Value:

/*         Error number          Standard error text                        */ \
StmMtcErr (StmMtcErrOk,          "no error"),                                  \
StmMtcErr (StmMtcErrInval,       "invalid argument"),                          \
StmMtcErr (StmMtcErrNoMem,       "no more memory on heap"),                    \
StmMtcErr (StmMtcErrMblkBig,     "heap memory block too big"),                 \
StmMtcErr (StmMtcErrLong,        "syntax error: <reStr> too long"),            \
StmMtcErr (StmMtcErrPar,         "syntax error: ')' missing"),                 \
StmMtcErr (StmMtcErrSubRe,       "syntax error: '&'<reName>'&' expected"),     \
StmMtcErr (StmMtcErrQreActName,  "syntax error: ':'<actionNames>':' expected"),\
StmMtcErr (StmMtcErrShort,       "syntax error: <reStr> too short"),           \
StmMtcErr (StmMtcErrRange,       "syntax error in <range>"),                   \
StmMtcErr (StmMtcErrGroup,       "syntax error in <group>"),                   \
StmMtcErr (StmMtcErrGend,        "syntax error: ']' missing"),                 \
StmMtcErr (StmMtcErrInvalRe,     "syntax error: illegal <reStr>"),             \
StmMtcErr (StmMtcErrNoAction,    "syntax error: <qualifRe> action unnamed"),   \
StmMtcErr (StmMtcErrIllegal,     "syntax error: <char> must be masked by '%'"),\
StmMtcErr (StmMtcErrRecursion,   "syntax error: infinite recursion"),          \
StmMtcErr (StmMtcErrNoQre,       "syntax error: illegal empty <qualifRe>"),    \
StmMtcErr (StmMtcErrNoQreAct,    "<qualifRe> action not defined"),             \
StmMtcErr (StmMtcErrQreInit,     "<qualifRe> action initialization failed"),   \
StmMtcErr (StmMtcErrQreAction,   "<qualifRe> action failed"),                  \
StmMtcErr (StmMtcErrQreRollback, "<qualifRe> action rollback failed"),         \
StmMtcErr (StmMtcErrQreDeinit,   "<qualifRe> action deinitialization failed"), \
StmMtcErr (StmMtcErrNoReStr,     "<reStr> not defined"),                       \
StmMtcErr (StmMtcErrReInit,      "<reStr> action initialization failed"),      \
StmMtcErr (StmMtcErrReRollback,  "<reStr> action rollback failed"),            \
StmMtcErr (StmMtcErrReAction,    "<reStr> action failed"),                     \
StmMtcErr (StmMtcErrReDeinit,    "<reStr> action deinitialization failed"),    \
Definition of StmReCtrl error numbers and messages.

The macro StmMtcErrors defines and names the possible StmReCtrl error numbers and their associated standard error text by means of the macro StmMtcErr.

Definition at line 583 of file match.h.

#define StmMtcErr ( nr,
txt   )     nr

Definition of the StmReCtrl error number nr for error text txt.

Definition at line 617 of file match.h.


Typedef Documentation

typedef struct StmReCtrlImpl_ StmReCtrlImpl_

Type name of implementation structure.

Definition at line 60 of file StmReCtrlAdtDoc.h.

typedef StmReCtrlImpl_* StmReCtrl

Pointer to implementation.

Examples:
cuglify.c, and matchtst.c.

Definition at line 63 of file StmReCtrlAdtDoc.h.

typedef const StmReCtrlImpl_* ConstStmReCtrl

Pointer to constant implementation.

Definition at line 66 of file StmReCtrlAdtDoc.h.


Enumeration Type Documentation

enum StmReCtrlErrnos

Definition of all possible StmReCtrl error numbers.

Definition at line 623 of file match.h.

enum StmMtcFctResult

Result values of regular or qualified regular expression action functions.

Enumerator:
StmMtcFctError  System error: causes the whole matching process to fail.

StmMtcFctOk  Normal return: the regular expression shall match.

StmMtcFctFail  Force the regular expression match to fail.

StmMtcFctReduce  Cause the regular expression match to fail and to to be retried with reduced match length, if possible (only for qualified regular expression action functions).

Definition at line 698 of file match.h.


Function Documentation

StmReCtrl stmReCtrlCreate ( FILE *  debug,
jmp_buf *  penvbuf,
const char *  xlatetab,
const char *const *  errtxt 
)

Creation of a new StmReCtrl object.

The function stmReCtrlCreate returns a StmReCtrl object controlling operation and error behaviour of StmReCtrl functions called for this StmReCtrl object and of StmRe functions called for a StmRe object with this StmReCtrl object as control object (see stmReCreate()).

If stmReCtrlCreate or one of the functions just mentioned fails, an error number reflecting to the error's cause is stored in the StmReCtrl object. This error number is called its current StmReCtrl error number. Moreover, a debug message describing the error is generated and also stored in the StmReCtrl object. This debug message is called its current StmReCtrl debug message. Unless debug is NULL, this debug message is output on the stream debug.

If penvbuf is NULL, in case of failure of one of the functions mentioned above they return an error value (NULL or -1, as appropriate), else penvbuf is called the error environment address and shall point to a variable of type jmp_buf (see setjmp.h) obtained by a call to setjmp, and in case of failure a longjmp to the error target defined by penvbuf is performed.

If xlatetab is not NULL but a pointer to an array of 256 char values, before each character comparison caused by stmReMatch() or stmReMatchSub() the characters of the string to compare are transformed according to the translation table formed by this array. This can be used e.g. for case unsensitive pattern matching inclusive the handling of special foreign language characters.

A failure of one of the functions mentioned above causes stmReCtrlGetErrorMsg() and stmReGetErrorMsg() to return an error message corresponding to current StmReCtrl error number set by that failure. If errtxt is NULL, the text of this error message is associated with the current error number by means of the macro StmMtcErrors. If the text of the error messages to be returned by stmReCtrlGetErrorMsg() or stmReGetErrorMsg() shall be not the standard text, errtxt has to point to an array of dimension StmMtcErrCount of error texts to be indexed by the possible StmReCtrl error numbers.

Examples:
cuglify.c, and matchtst.c.

Referenced by main().

void stmReCtrlDestroy ( StmReCtrl  reCtrl  ) 

Destruction of the StmReCtrl object reCtrl.

The function stmReCtrlDestroy destroys the StmReCtrl object reCtrl, if it is valid. All regular expressions and qualified regular expression actions defined for it by means of stmReCreate() and stmQreActDef() become invalid and must not be used any more. It is no error to call stmReCtrlDestroy for an invalid (value NULL) StmReCtrl object in which case no action occurs.

Examples:
cuglify.c, and matchtst.c.

Referenced by main().

int stmReCtrlSetErrorEnv ( StmReCtrl  reCtrl,
jmp_buf *  penvbuf 
)

Set the error environment address of the StmReCtrl object reCtrl.

The function stmReCtrlSetErrorEnv error environment address penvbuf (see stmReCtrlCreate()) of the StmReCtrl object reCtrl, if it is valid. If reCtrl is invalid (NULL), -1 is returned and the variable errno is set to EINVAL.

int stmReCtrlGetErrno ( StmReCtrl  reCtrl  ) 

Return the current StmReCtrl error number.

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

const char* stmReCtrlGetErrorMsg ( StmReCtrl  reCtrl  ) 

Return the current StmReCtrl error message.

The function stmReCtrlGetErrorMsg returns an error message associated with the current StmReCtrl error number (see stmReCtrlCreate()). 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 reCtrl is invalid (NULL), NULL is returned and the variable errno is set to EINVAL.

Examples:
cuglify.c, and matchtst.c.

Referenced by main().

const char* stmReCtrlGetDebugMsg ( StmReCtrl  reCtrl  ) 

Return the current StmReCtrl debug message.

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

int stmQreActDef ( StmReCtrl  reCtrl,
const char *  qreactname,
int(*)(StmMtcFctCmd cmd, StmQreMtc qreMtc)  qreFct 
)

Definition of an action function for qualified regular expressions.

The function stmQreActDef defines for a valid StmReCtrl object reCtrl a reference to the qualified regular expression action function qreFct and stores it under the name qreactname. This named qualified regular expression action is referenceable by qualifRe's (see Regular Expression Syntax) of regular expressions defined for reCtrl via the construct ':'qreactname':'. A definition of an already defined qualified regular expression action named qreactname is redefined.

The argument qreFct is a pointer to a user supplied qualified regular expression action function which is called before, during and after the matching process for the qualified regular expression qualifRe with a structure cmd of type StmMtcFctCmd used for function control as its first argument and and a valid StmQreMtc object qreMtc describing the match of qualifRe as its second and last argument. Hence qreFct is of type

                 int (*qreFct) (StmMtcFctCmd cmd, StmQreMtc qreMtc);
A call of qreFct before the matching process for qualifRe shall be indicated by a value init of cmd and shall serve the purpose of allocating and initializing the match data of qualifRe's qualified regular expression match and of defining them for its StmQreMtc object qreMtc with stmQreMtcSetData(). 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 rqeMtc its global environment, its superior regular expression match and the match of that match's superior qualified regular expression match are available.

A call of qreFct during a successful matching of qualiRe shall be indicated by a value action of cmd shall serve the purpose of evaluating the match result acessible by stmQreMtcStr(), stmQreMtcLen(), stmQreMtcData() and stmQreMtcSimpleReMtcCount(), and to collect it in the global environment and in the match data of the superior regular expression. If this evaluation and collection shall not be done, qreFct shall return a StmMtcFctFail or StmMtcFctReduce which changes the result of the matching of qualifRe from successful to unsuccessful. If qreFct returns with StmMtcFctReduce the matching of the qualified regular expression is retried with reduced match length, if possible. Else qreFct shall return StmMtcFctOk. If qreFct 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 qreFct with a value rollback of cmd shall serve the purpose of undoing the effects of a previous call of qreFct with a value action of cmd. This is necessary, if the matching qualifRe is part of a superior regular expression which does not match.

Finally a call of qreFct with a value deinit of cmd shall serve the purpose of deinitializing and deallocating the match data of the qualified regular expression match.

The different calls of qreFct 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 qreFct shall return StmMtcFctOk, StmMtcFctFail or StmMtcFctReduce. On error qreFct shall return StmMtcFctError and errno shall have a non zero value describing the error's cause.

In case of success stmQreActDef() returns 0, else -1 unless an error jump target has been defined by means of stmReCtrlCreate(). An error occurs, if reCtrl is invalid (NULL), if qreactname or qreFct is NULL, or if qreactname is the empty string. 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().


© Copyright Tom Michaelis 2002-2007

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