generic/compiler/notate.h

/*  ASCEND modelling environment
    Copyright (C) 1998 Carnegie Mellon University
    Copyright (C) 2006 Carnegie Mellon University

    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, 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, write to the Free Software
    Foundation, Inc., 59 Temple Place - Suite 330,
    Boston, MA 02111-1307, USA.
*//**
    @file
    This file defines and manages a little (we hope)
    database system for storing NOTES in-core in a variety
    of quickly accessible ways.

    If scale gets to be an issue, this could become a wrapper
    for a real database someday.

    This implementation is not optimized for anything -- the
    intent here is to learn if it can be done at all.
*//*
    By Ben Allan 4/98
    Last in CVS:$Revision: 1.3 $ $Date: 1998/06/16 16:38:42 $ $Author: mthomas $
*/

#ifndef ASC_NOTATE_H
#define ASC_NOTATE_H

/** addtogroup compiler Compiler
    @{
*/

#include <utilities/ascConfig.h>
#include <general/list.h>
#include "compiler.h"
#include "braced.h"

/*------------------------------------------------------------------------------
  MACROS AND DATA STRUCTURES
*/

/**
 * A wildcard pointer value for database queries.
 * It is in the zero page, odd (which is impossible for
 * a symchar) and outside the range of the NoteData enum.
 */
#define NOTESWILD ((symchar *)0x11)
#define NOTESWILDLIST ((struct gl_list_t *)0x11)
/**<
 * A wildcard list pointer value for database queries.
 * It is in the zero page, odd (which is impossible for
 * a symchar) and outside the range of the NoteData enum.
 */

/**
 * Type of the void pointer which may be stored with a note.
 * We don't want to crap up this header with half the
 * compiler's includes because interface clients shouldn't
 * know.
 */
enum NoteData {
  nd_wild,      /**< Matches any in notes queries. */
  nd_empty,     /**< Pointer meaningless, should be NULL. matches only empty. */
  nd_name,      /**< struct Name * assumed someone else's to destroy. */
  nd_vlist,     /**< struct VariableList * ours to destroy. */
  nd_module,    /**< struct module_t * not ours, obviously. */
  nd_anonymous  /**< Future expansion as needed. */
};

/* contents none of your business. our persistent record. */
struct Note;

/* wrapper for a regular expression matching engine. */
struct NoteEngine;

/** Temporary for parser use only. Some fields (lang) may not be reset by client.
 *  Do not store these anywhere permanently as they are not persistent.
 */
struct NoteTmp {
  symchar *lang;
  struct bracechar *bt;
  void *vardata;
  int line;
  struct NoteTmp *next;
};

/*------------------------------------------------------------------------------
   TEMPORARY NOTES
*/

/**
 * Create a notetmp for parsing NOTES statements. need this in order to
 * capture multiple fvarlist/bracedtext pairs for a single language key.
 */
extern struct NoteTmp *CreateNoteTmp(symchar *lang,
                                     struct bracechar *bt,
                                     void *varlist,
                                     int line);

/** Add a notetmp to a lifo (if you follow next) list. */
extern struct NoteTmp *LinkNoteTmp(struct NoteTmp *new_thing,
                                   struct NoteTmp *chain);

/**
 * Destroy a chain of struct NoteTmp following the next pointers.
 * The bt and vardata fields contained (if any) are not destroyed.
 */
extern void DestroyNoteTmpList(struct NoteTmp *head);

/*------------------------------------------------------------------------------
  REGULAR (PERSISTENT) NOTES
*/

/**
 * Initialize the notes database. Returns 0 if successful.
 * Input is the symchar by which the database will be addressed.
 * The very first call to this function should be made with
 * NULL and merely initializes internal structures without
 * creating something according to dbid. That call always
 * returns 1.
 */
ASC_DLLSPEC int InitNotesDatabase(symchar *dbid);

/**
 * Returns a gl_list containing symchar * of names (dbid)
 * of databases currently in existence.
 */
ASC_DLLSPEC struct gl_list_t *ListNotesDatabases(void);

/**
 * Destroy the database, and necessarily all tokens being held.
 * if dbid is 0x1, destroys all databases.
 */
ASC_DLLSPEC void DestroyNotesDatabase(symchar *dbid);

/**
 * Clear any notes associated with the type named out of
 * database. Useful if replacing a type.
 */
extern void DestroyNotesOnType(symchar *dbid, symchar *type_name);

/**
 * Returns a list of notes matching the keys specified.
 * NOTESWILD key values are wildcards.
 * This list returned is yours to destroy. The contents of the
 * list are struct Note * and  are Not yours to destroy.
 *
 * Examples:
 * <pre>
 * GetNotes(dbid,typename,NOTESWILD,NOTESWILD,NOTESWILD,nd_wild);
 *   returns a list of all notes on a type or any part of the type.
 *   This may contain apparent duplicates depending the Commit
 *   optimizations that are performed.
 *
 * GetNotes(dbid,typename,language,NOTESWILD,NOTESWILD,nd_empty);
 *   returns a list of all notes on a type in the given language
 *   where the data slot is empty.
 *
 * GetNotes(dbid,typename,NOTESWILD,id,NULL,nd_empty);
 *   returns a list of all notes on a type about id (including SELF)
 *   in any language where method is NULL and no data is stored.
 *
 * GetNotes(dbid,typename,language,id,NULL,nd_empty);
 *   returns a list of all notes on a type not in a method about id in language.
 *
 * GetNotes(dbid,NOTESWILD,NOTESWILD,id,NOTESWILD,nd_wild);
 *   returns a list of all notes about id in any context, any language.
 * </pre>
 */
ASC_DLLSPEC struct gl_list_t *GetNotes(symchar *dbid,
                                  symchar *type,
                                  symchar *lang,
                                  symchar *id,
                                  symchar *method,
                                  enum NoteData nd);

/**
 * Given a pointer (alleged) to a note, checks that the
 * pointer is valid and returns a gl_list containing the
 * pointer. If the list is empty, the pointer is not valid.
 * This kind of boneheaded function is necessary for handling
 * scripted interfaces that can shove in garbage.
 * GetExactNote(dbid,n);
 */
ASC_DLLSPEC struct gl_list_t *GetExactNote(symchar *dbid, struct Note *n);

/**
 * Returns the list of notes matching any combination of the
 * keys stored in the gl_lists given. So, for example,
 * if you want the notes on id in typename or any ancestor,
 * cookup up the list of ancestor type names, stick id in idlist,
 * and pass NOTESWILD,nd_wild for the other two arguments.
 */
ASC_DLLSPEC struct gl_list_t *GetNotesList(symchar *dbid,
                                      struct gl_list_t *types,
                                      struct gl_list_t *langs,
                                      struct gl_list_t *ids,
                                      struct gl_list_t *methods,
                                      struct gl_list_t *nds);

/**
 * Return id of note. id is normally a child name or SELF.
 * Might be NULL.
 */
ASC_DLLSPEC symchar *GetNoteId(struct Note *n);

/**
 * Return method of note.  Method is normally NULL unless note
 * is in scope of a method.  A note with nonNULL method might
 * also have a nonnull id.
 * Might be NULL.
 */
ASC_DLLSPEC symchar *GetNoteMethod(struct Note *n);

/**
 * Return typename of note.
 * typename is normally something in the library.
 * Might be NULL.
 */
ASC_DLLSPEC symchar *GetNoteType(struct Note *n);

/** Return language of note.  Might be NULL. */
ASC_DLLSPEC symchar *GetNoteLanguage(struct Note *n);

/**
 * Return best module name of note.
 * Might be NULL.  Name is string from a symchar.
 */
ASC_DLLSPEC CONST char *GetNoteFilename(struct Note *n);

/** Return line number of note. possibly -1. */
ASC_DLLSPEC int GetNoteLineNum(struct Note *n);

/** Return the text string of a note.  It is ours. */
ASC_DLLSPEC struct bracechar *GetNoteText(struct Note *n);

/** Return the enum NoteData. */
ASC_DLLSPEC enum NoteData GetNoteEnum(struct Note *n);

/** Return the data of a note if it matches the enum given, or NULL. */
ASC_DLLSPEC void *GetNoteData(struct Note *n, enum NoteData nd);

/**
 * Puts the list of note pointers on an internal tracking list.
 * token returned may be passed to Note functions which take a
 * token. Returns NULL on memory failure or on list nl not appearing
 * to contain notes.
 * The notes list must be from the same database.
 */
ASC_DLLSPEC void *HoldNoteData(symchar *dbid, struct gl_list_t *nl);

/**
 * Returns NULL if token given is invalid in dbid.
 */
ASC_DLLSPEC struct gl_list_t *HeldNotes(symchar *dbid, void *token);

/**
 * Removes the list of note pointers associated with token
 * from internal tracking list.
 * Calling with a 0x1 token releases all held lists and all
 * existing tokens become invalid.
 * Calling with bogus token is ok.
 */
ASC_DLLSPEC void ReleaseNoteData(symchar *dbid, void *token);

/**
 * Return the languages found in any committed note as a list of symchars.
 */
ASC_DLLSPEC struct gl_list_t *GetNotesAllLanguages(symchar *dbid);

/*
 * The 4 following calls do not work until after at least 1 call of
 * InitNotesDatabase(NULL) has been done.
 */

/** Returns the 'Loaded Libraries' symchar, which is useful for the parser. */
ASC_DLLSPEC symchar*LibraryNote(void);

/** Returns the 'All Known Files' symchar, which is useful for the parser. */
extern symchar *GlobalNote(void);

/** Returns the 'inline' symchar, which is useful for the parser. */
extern symchar *InlineNote(void);

/** Returns the 'SELF' symchar, which is useful for the parser. */
extern symchar *SelfNote(void);

/**
 * Add a note to the database.
 * Notes with vlists may be internally replicated to optimize
 * future queries.
 */
extern int CommitNote(symchar *dbid, struct Note *note);

/**
 * Create a note. Destroy the note unless you commit it to a
 * database.
 */
extern struct Note *CreateNote(symchar *type,
                               symchar *lang,
                               symchar *id,
                               symchar *method,
                               CONST char *file,
                               struct bracechar *btext,
                               int line,
                               VOIDPTR data,
                               enum NoteData nd);

/**
 * Destroys the note given, subject to reference counting.
 * Do not externally destroy a note once it has been committed to
 * the database.
 */
extern void DestroyNote(struct Note *n);

/*------------------------------------------------------------------------------
  SEARCHING FUNCTIONS (LINK TO A REGULAR EXPRESSION ENGINE)
*/

/**
 * Returns a list of notes whose text (or name list if a vlist note in future)
 * matches the pattern given according to the engine given.
 * If token is NULL, entire database is given, OTHERWISE token
 * must be a held note list.
 * Engine is the non-NULL return from a call to NotesCreateEngine.
 * The engine NEdata, about which you know more than we,
 * should be consulted for errors if the return is NULL.
 */
ASC_DLLSPEC struct gl_list_t *GetMatchingNotes(symchar *dbid,
                                          char *pattern,
                                          void *token,
                                          struct NoteEngine *engine);

/**
 * An NEInitFunc takes whatever data was specified to the engine
 * and a string to be matched and prepares the engine for one or
 * more matches against that pattern.
 * NEInitFunc should return NULL if it fails to initialize,
 * else it should return a pointer to be used in processing strings.
 * Tcl_RegExpCompile is an example of this function class.
 */
typedef void *(*NEInitFunc)(void *, /* NEdata */
                            char *  /* pattern */);

/**
 * An NECompareFunc returns -1 for error, 0 for no match, 1 for match.
 * Tcl_RegExpExec is an example of this function class.
 */
typedef int (*NECompareFunc)(void *, /* NEdata */
                             void *, /* return from NEInitFunc */
                             char *, /* substring to test for match */
                             char *  /* beginning of string containing
                                      * substring (^ matches)
                                      */
                            );

/**
 * This is a wrapper to keep things independent of anyone in particular's
 * regular expression package.
 */
ASC_DLLSPEC struct NoteEngine *NotesCreateEngine(void *NEdata,
                                   NEInitFunc NEInit,
                                   NECompareFunc NECompare);

/**
 * Destroys a previously returned engine.
 */
ASC_DLLSPEC void NotesDestroyEngine(struct NoteEngine *engine);

/* @} */

#endif /* ASC_NOTATE_H */

1	/* ASCEND modelling environment
2	Copyright (C) 1998 Carnegie Mellon University
3	Copyright (C) 2006 Carnegie Mellon University
4
5	This program is free software; you can redistribute it and/or modify
6	it under the terms of the GNU General Public License as published by
7	the Free Software Foundation; either version 2, or (at your option)
8	any later version.
9
10	This program is distributed in the hope that it will be useful,
11	but WITHOUT ANY WARRANTY; without even the implied warranty of
12	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13	GNU General Public License for more details.
14
15	You should have received a copy of the GNU General Public License
16	along with this program; if not, write to the Free Software
17	Foundation, Inc., 59 Temple Place - Suite 330,
18	Boston, MA 02111-1307, USA.
19	//*
20	@file
21	This file defines and manages a little (we hope)
22	database system for storing NOTES in-core in a variety
23	of quickly accessible ways.
24
25	If scale gets to be an issue, this could become a wrapper
26	for a real database someday.
27
28	This implementation is not optimized for anything -- the
29	intent here is to learn if it can be done at all.
30	//
31	By Ben Allan 4/98
32	Last in CVS:$Revision: 1.3 $ $Date: 1998/06/16 16:38:42 $ $Author: mthomas $
33	*/
34
35	#ifndef ASC_NOTATE_H
36	#define ASC_NOTATE_H
37
38	/** addtogroup compiler Compiler
39	@{
40	*/
41
42	#include <utilities/ascConfig.h>
43	#include <general/list.h>
44	#include "compiler.h"
45	#include "braced.h"
46
47	/*------------------------------------------------------------------------------
48	MACROS AND DATA STRUCTURES
49	*/
50
51	/**
52	* A wildcard pointer value for database queries.
53	* It is in the zero page, odd (which is impossible for
54	* a symchar) and outside the range of the NoteData enum.
55	*/
56	#define NOTESWILD ((symchar *)0x11)
57	#define NOTESWILDLIST ((struct gl_list_t *)0x11)
58	/**<
59	* A wildcard list pointer value for database queries.
60	* It is in the zero page, odd (which is impossible for
61	* a symchar) and outside the range of the NoteData enum.
62	*/
63
64	/**
65	* Type of the void pointer which may be stored with a note.
66	* We don't want to crap up this header with half the
67	* compiler's includes because interface clients shouldn't
68	* know.
69	*/
70	enum NoteData {
71	nd_wild, /*< Matches any in notes queries. /
72	nd_empty, /*< Pointer meaningless, should be NULL. matches only empty. /
73	nd_name, /*< struct Name assumed someone else's to destroy. */
74	nd_vlist, /*< struct VariableList ours to destroy. */
75	nd_module, /*< struct module_t not ours, obviously. */
76	nd_anonymous /*< Future expansion as needed. /
77	};
78
79	/* contents none of your business. our persistent record. */
80	struct Note;
81
82	/* wrapper for a regular expression matching engine. */
83	struct NoteEngine;
84
85	/** Temporary for parser use only. Some fields (lang) may not be reset by client.
86	* Do not store these anywhere permanently as they are not persistent.
87	*/
88	struct NoteTmp {
89	symchar *lang;
90	struct bracechar *bt;
91	void *vardata;
92	int line;
93	struct NoteTmp *next;
94	};
95
96	/*------------------------------------------------------------------------------
97	TEMPORARY NOTES
98	*/
99
100	/**
101	* Create a notetmp for parsing NOTES statements. need this in order to
102	* capture multiple fvarlist/bracedtext pairs for a single language key.
103	*/
104	extern struct NoteTmp CreateNoteTmp(symchar lang,
105	struct bracechar *bt,
106	void *varlist,
107	int line);
108
109	/** Add a notetmp to a lifo (if you follow next) list. */
110	extern struct NoteTmp LinkNoteTmp(struct NoteTmp new_thing,
111	struct NoteTmp *chain);
112
113	/**
114	* Destroy a chain of struct NoteTmp following the next pointers.
115	* The bt and vardata fields contained (if any) are not destroyed.
116	*/
117	extern void DestroyNoteTmpList(struct NoteTmp *head);
118
119	/*------------------------------------------------------------------------------
120	REGULAR (PERSISTENT) NOTES
121	*/
122
123	/**
124	* Initialize the notes database. Returns 0 if successful.
125	* Input is the symchar by which the database will be addressed.
126	* The very first call to this function should be made with
127	* NULL and merely initializes internal structures without
128	* creating something according to dbid. That call always
129	* returns 1.
130	*/
131	ASC_DLLSPEC int InitNotesDatabase(symchar *dbid);
132
133	/**
134	* Returns a gl_list containing symchar * of names (dbid)
135	* of databases currently in existence.
136	*/
137	ASC_DLLSPEC struct gl_list_t *ListNotesDatabases(void);
138
139	/**
140	* Destroy the database, and necessarily all tokens being held.
141	* if dbid is 0x1, destroys all databases.
142	*/
143	ASC_DLLSPEC void DestroyNotesDatabase(symchar *dbid);
144
145	/**
146	* Clear any notes associated with the type named out of
147	* database. Useful if replacing a type.
148	*/
149	extern void DestroyNotesOnType(symchar dbid, symchar type_name);
150
151	/**
152	* Returns a list of notes matching the keys specified.
153	* NOTESWILD key values are wildcards.
154	* This list returned is yours to destroy. The contents of the
155	* list are struct Note * and are Not yours to destroy.
156	*
157	* Examples:
158	* <pre>
159	* GetNotes(dbid,typename,NOTESWILD,NOTESWILD,NOTESWILD,nd_wild);
160	* returns a list of all notes on a type or any part of the type.
161	* This may contain apparent duplicates depending the Commit
162	* optimizations that are performed.
163	*
164	* GetNotes(dbid,typename,language,NOTESWILD,NOTESWILD,nd_empty);
165	* returns a list of all notes on a type in the given language
166	* where the data slot is empty.
167	*
168	* GetNotes(dbid,typename,NOTESWILD,id,NULL,nd_empty);
169	* returns a list of all notes on a type about id (including SELF)
170	* in any language where method is NULL and no data is stored.
171	*
172	* GetNotes(dbid,typename,language,id,NULL,nd_empty);
173	* returns a list of all notes on a type not in a method about id in language.
174	*
175	* GetNotes(dbid,NOTESWILD,NOTESWILD,id,NOTESWILD,nd_wild);
176	* returns a list of all notes about id in any context, any language.
177	* </pre>
178	*/
179	ASC_DLLSPEC struct gl_list_t GetNotes(symchar dbid,
180	symchar *type,
181	symchar *lang,
182	symchar *id,
183	symchar *method,
184	enum NoteData nd);
185
186	/**
187	* Given a pointer (alleged) to a note, checks that the
188	* pointer is valid and returns a gl_list containing the
189	* pointer. If the list is empty, the pointer is not valid.
190	* This kind of boneheaded function is necessary for handling
191	* scripted interfaces that can shove in garbage.
192	* GetExactNote(dbid,n);
193	*/
194	ASC_DLLSPEC struct gl_list_t GetExactNote(symchar dbid, struct Note *n);
195
196	/**
197	* Returns the list of notes matching any combination of the
198	* keys stored in the gl_lists given. So, for example,
199	* if you want the notes on id in typename or any ancestor,
200	* cookup up the list of ancestor type names, stick id in idlist,
201	* and pass NOTESWILD,nd_wild for the other two arguments.
202	*/
203	ASC_DLLSPEC struct gl_list_t GetNotesList(symchar dbid,
204	struct gl_list_t *types,
205	struct gl_list_t *langs,
206	struct gl_list_t *ids,
207	struct gl_list_t *methods,
208	struct gl_list_t *nds);
209
210	/**
211	* Return id of note. id is normally a child name or SELF.
212	* Might be NULL.
213	*/
214	ASC_DLLSPEC symchar GetNoteId(struct Note n);
215
216	/**
217	* Return method of note. Method is normally NULL unless note
218	* is in scope of a method. A note with nonNULL method might
219	* also have a nonnull id.
220	* Might be NULL.
221	*/
222	ASC_DLLSPEC symchar GetNoteMethod(struct Note n);
223
224	/**
225	* Return typename of note.
226	* typename is normally something in the library.
227	* Might be NULL.
228	*/
229	ASC_DLLSPEC symchar GetNoteType(struct Note n);
230
231	/** Return language of note. Might be NULL. */
232	ASC_DLLSPEC symchar GetNoteLanguage(struct Note n);
233
234	/**
235	* Return best module name of note.
236	* Might be NULL. Name is string from a symchar.
237	*/
238	ASC_DLLSPEC CONST char GetNoteFilename(struct Note n);
239
240	/** Return line number of note. possibly -1. */
241	ASC_DLLSPEC int GetNoteLineNum(struct Note *n);
242
243	/** Return the text string of a note. It is ours. */
244	ASC_DLLSPEC struct bracechar GetNoteText(struct Note n);
245
246	/** Return the enum NoteData. */
247	ASC_DLLSPEC enum NoteData GetNoteEnum(struct Note *n);
248
249	/** Return the data of a note if it matches the enum given, or NULL. */
250	ASC_DLLSPEC void GetNoteData(struct Note n, enum NoteData nd);
251
252	/**
253	* Puts the list of note pointers on an internal tracking list.
254	* token returned may be passed to Note functions which take a
255	* token. Returns NULL on memory failure or on list nl not appearing
256	* to contain notes.
257	* The notes list must be from the same database.
258	*/
259	ASC_DLLSPEC void HoldNoteData(symchar dbid, struct gl_list_t *nl);
260
261	/**
262	* Returns NULL if token given is invalid in dbid.
263	*/
264	ASC_DLLSPEC struct gl_list_t HeldNotes(symchar dbid, void *token);
265
266	/**
267	* Removes the list of note pointers associated with token
268	* from internal tracking list.
269	* Calling with a 0x1 token releases all held lists and all
270	* existing tokens become invalid.
271	* Calling with bogus token is ok.
272	*/
273	ASC_DLLSPEC void ReleaseNoteData(symchar dbid, void token);
274
275	/**
276	* Return the languages found in any committed note as a list of symchars.
277	*/
278	ASC_DLLSPEC struct gl_list_t GetNotesAllLanguages(symchar dbid);
279
280	/*
281	* The 4 following calls do not work until after at least 1 call of
282	* InitNotesDatabase(NULL) has been done.
283	*/
284
285	/** Returns the 'Loaded Libraries' symchar, which is useful for the parser. */
286	ASC_DLLSPEC symchar*LibraryNote(void);
287
288	/** Returns the 'All Known Files' symchar, which is useful for the parser. */
289	extern symchar *GlobalNote(void);
290
291	/** Returns the 'inline' symchar, which is useful for the parser. */
292	extern symchar *InlineNote(void);
293
294	/** Returns the 'SELF' symchar, which is useful for the parser. */
295	extern symchar *SelfNote(void);
296
297	/**
298	* Add a note to the database.
299	* Notes with vlists may be internally replicated to optimize
300	* future queries.
301	*/
302	extern int CommitNote(symchar dbid, struct Note note);
303
304	/**
305	* Create a note. Destroy the note unless you commit it to a
306	* database.
307	*/
308	extern struct Note CreateNote(symchar type,
309	symchar *lang,
310	symchar *id,
311	symchar *method,
312	CONST char *file,
313	struct bracechar *btext,
314	int line,
315	VOIDPTR data,
316	enum NoteData nd);
317
318	/**
319	* Destroys the note given, subject to reference counting.
320	* Do not externally destroy a note once it has been committed to
321	* the database.
322	*/
323	extern void DestroyNote(struct Note *n);
324
325	/*------------------------------------------------------------------------------
326	SEARCHING FUNCTIONS (LINK TO A REGULAR EXPRESSION ENGINE)
327	*/
328
329	/**
330	* Returns a list of notes whose text (or name list if a vlist note in future)
331	* matches the pattern given according to the engine given.
332	* If token is NULL, entire database is given, OTHERWISE token
333	* must be a held note list.
334	* Engine is the non-NULL return from a call to NotesCreateEngine.
335	* The engine NEdata, about which you know more than we,
336	* should be consulted for errors if the return is NULL.
337	*/
338	ASC_DLLSPEC struct gl_list_t GetMatchingNotes(symchar dbid,
339	char *pattern,
340	void *token,
341	struct NoteEngine *engine);
342
343	/**
344	* An NEInitFunc takes whatever data was specified to the engine
345	* and a string to be matched and prepares the engine for one or
346	* more matches against that pattern.
347	* NEInitFunc should return NULL if it fails to initialize,
348	* else it should return a pointer to be used in processing strings.
349	* Tcl_RegExpCompile is an example of this function class.
350	*/
351	typedef void (NEInitFunc)(void , / NEdata */
352	char * /* pattern */);
353
354	/**
355	* An NECompareFunc returns -1 for error, 0 for no match, 1 for match.
356	* Tcl_RegExpExec is an example of this function class.
357	*/
358	typedef int (NECompareFunc)(void , /* NEdata */
359	void , / return from NEInitFunc */
360	char , / substring to test for match */
361	char * /* beginning of string containing
362	* substring (^ matches)
363	*/
364	);
365
366	/**
367	* This is a wrapper to keep things independent of anyone in particular's
368	* regular expression package.
369	*/
370	ASC_DLLSPEC struct NoteEngine NotesCreateEngine(void NEdata,
371	NEInitFunc NEInit,
372	NECompareFunc NECompare);
373
374	/**
375	* Destroys a previously returned engine.
376	*/
377	ASC_DLLSPEC void NotesDestroyEngine(struct NoteEngine *engine);
378
379	/* @} */
380
381	#endif /* ASC_NOTATE_H */
382