/[ascend]/trunk/base/generic/compiler/module.h
ViewVC logotype

Contents of /trunk/base/generic/compiler/module.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 480 - (show annotations) (download) (as text)
Mon Apr 17 10:45:23 2006 UTC (13 years, 9 months ago) by johnpye
File MIME type: text/x-chdr
File size: 17947 byte(s)
Adding ASC_DLLSPEC to all functions that are being used by Python interface.
Also cleaned up some #ifdef header brackets and html-style comments inside doxygen comments.
Renamed pygtk/interface/config.in to pygtk/interface/config.h.in and made 
this active again (for ASC_BUILDING_INTERFACE) use.
Trying to catch error in ascpy.Library call with try/except, doesn't work though.
1 /*
2 * Ascend Module Control
3 * by Tom Epperly
4 * Created: 1/10/90
5 * Version: $Revision: 1.11 $
6 * Version control file: $RCSfile: module.h,v $
7 * Date last modified: $Date: 1998/04/16 00:43:26 $
8 * Last modified by: $Author: ballan $
9 *
10 * This file is part of the Ascend Language Interpreter.
11 *
12 * Copyright (C) 1990, 1993, 1994 Thomas Guthrie Epperly
13 *
14 * The Ascend Language Interpreter is free software; you can redistribute
15 * it and/or modify it under the terms of the GNU General Public License as
16 * published by the Free Software Foundation; either version 2 of the
17 * License, or (at your option) any later version.
18 *
19 * The Ascend Language Interpreter is distributed in hope that it will be
20 * useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
21 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
22 * General Public License for more details.
23 *
24 * You should have received a copy of the GNU General Public License
25 * along with the program; if not, write to the Free Software Foundation,
26 * Inc., 675 Mass Ave, Cambridge, MA 02139 USA. Check the file named
27 * COPYING.
28 */
29
30 /** @file
31 * Ascend Module Control.
32 * <pre>
33 * When #including module.h, make sure these files are #included first:
34 * #include "utilities/ascConfig.h"
35 * #include "compiler.h"
36 * </pre>
37 */
38
39 #ifndef ASC_MODULE_H
40 #define ASC_MODULE_H
41
42 #define PATHENVIRONMENTVAR "ASCENDLIBRARY"
43 /**<
44 * The name of the environment variable containing a list' of paths
45 * to search when trying to open a module. The list is in the style
46 * of the native OS: colon-separated on UNIX and semicolon separated
47 * under Windows.
48 */
49
50 #define MOD_FILE_EXTS 6
51 #define MOD_OLD_CODE ".asc"
52 /**< Extension for old code files. */
53 #define MOD_OLD_LIBRARY ".lib"
54 /**< Extension for old library files. */
55 #define MOD_NEW_CODE ".a4c"
56 /**< Extension for new code files. */
57 #define MOD_NEW_LIBRARY ".a4l"
58 /**< Extension for new library files. */
59 #define MOD_NEW_UNITS ".a4u"
60 /**< Extension for new units files. */
61 #define MOD_CATCHALL ""
62 /**< Extension for general files. */
63 extern CONST char *g_alt_ending[MOD_FILE_EXTS];
64 /**<
65 * This array defines the expected file extensions for
66 * parsable ascend MODEL/ATOM/unit code. Files are not
67 * limited to these, however. Interfaces that see a
68 * trailing .* where * is other than these should
69 * enquire as to the user intent: the user may have
70 * made a mistake.
71 */
72
73 struct module_t;
74
75 extern int Asc_InitModules(unsigned long init_length);
76 /**<
77 * Create the data structures required by the modules code. Returns
78 * nonzero if not enough memory to initialize the modules; zero for
79 * success. Clients to not need to call this function since calls to
80 * OpenModule() or RequireModule() will initialize the data structures
81 * if needed.<br><br>
82 *
83 * The initial length of the module list will be set to `init_length';
84 * since the module list will grow as needed, this number isn't too
85 * important, but a better guess will mean better performance.
86 */
87
88
89 extern void ASC_DLLSPEC Asc_DestroyModules(DestroyFunc func);
90 /**<
91 * Deallocate all of the modules. This should be done when all types
92 * are destroyed and just before exiting.
93 * The function argument is not optional.
94 */
95
96 extern struct module_t *Asc_OpenStringModule(CONST char *inputstring,
97 int *status,
98 CONST char *nameprefix);
99 /**<
100 * This function returns a module which behaves just as a regular
101 * file module, except that it is always there unless there is
102 * insufficient memory to make the required internal copy of the
103 * string. The scanner will use the non-input-modifying version
104 * of its functions when operating on the copy of the input string.
105 * The string module will make up its own unique name based on nameprefix.
106 * Not surprisingly, the module returned should be closed after a call
107 * to zz_lex.
108 */
109
110 extern struct module_t *Asc_OpenModule(CONST char *name, int *status);
111 /**<
112 * Attempt to find and open (for reading) a file whose
113 * name is based on `name'.
114 * @see Asc_RequireModule() for additional information.
115 */
116 extern struct module_t* ASC_DLLSPEC Asc_RequireModule(CONST char *name, int *status);
117 /**<
118 * Attempt to find and open (for reading) a file whose
119 * name is based on `name'.
120 *
121 * The following applies to both Asc_OpenModule() and Asc_RequireModule().
122 * `name' can either be a full path name to the file (in the native format)
123 * or a string that will be appended to each of the paths listed in the
124 * PATHENVIRONMENTVAR to try and find the file.<br><br>
125 *
126 * Past versions (pre July-97) of these functions used to append known
127 * extensions to `name' to try and find the file. That behavior is no
128 * longer supported.<br><br>
129 *
130 * The integer that `status' points to will be set to the return status
131 * of the function. If you are not concerned about the return status,
132 * pass in NULL as the second argument.<br><br>
133 *
134 * The portion of `name' after the rightmost slash (`/' on UNIX, `\' on
135 * Windows) is used as the "base-name" part of the module's
136 * name---i.e., all path information is removed. The second part of
137 * the module's name is a version number enclosed in angle brackets.
138 * Version numbers start at zero and increase. For example, the first
139 * time OpenModule("/foo/bar/baz.a4c") is called, a module with the
140 * name "baz.a4c<0>" is created. Module names are unique.<br><br>
141 *
142 * ASC_REQUIREMODULE ONLY:<br>
143 * If the base-name of the module name you specify matches an
144 * existing module's base-name or a module's alias, `status' is set
145 * to 5 and the existing module is returned. For example, if you
146 * call Asc_OpenModule("/foo/bar/baz.a4c") successfully, and then
147 * Asc_RequireModule("/food/beer/baz.a4c"), the existing module
148 * "baz.a4c<0>" is returned. The pathnames of the files are not
149 * compared, and no searching of the file system occurs. See
150 * Asc_ModuleCreateAlias() for details on aliases.<br><br>
151 *
152 * If attempting to access `name' directly fails, and searching over
153 * PATHENVIRONMENTVAR produces no valid filenames, `status' is set to
154 * -1 and NULL is returned. If a matching filename is found but the
155 * fopen() call fails, `status' is set to -2 and NULL is returned.
156 * Note that fopen() is only attempted one time; once we have a name
157 * that looks like a valid directory entry (a stat() call returns 0),
158 * we stop searching.<br><br>
159 *
160 * If a filename is found and the file is successfully opened for
161 * reading, the base-name of the module is compared against existing
162 * modules. If no match is found, a new module is created: its version
163 * number is set to zero, its times-opened counter is set to 1, the
164 * module we are currently scanning (if any---this only occurs when the
165 * user calls RequireModule) is pushed onto a stack, the scanner is
166 * told to scan the newly opened file, `status' is set to 0, and the
167 * new module is returned.<br><br>
168 *
169 * If the base-name of the filename we found matches a module alias, we
170 * treat the filename as a new module and the actions listed in the
171 * above paragraph occur, except that `status' is set to 3. See the
172 * documentation under Asc_ModuleCreateAlias() for details on aliases.<br><br>
173 *
174 * If the filename we found and an existing module have the same
175 * base-name, the pathnames and timestamps of the files are compared.
176 * If they match and the existing module is open for reading, the file
177 * is REQUIREing itself; we print an error, set `status' to 4, and
178 * return the existing module. If they match and the existing module
179 * is not open for reading, the times-opened counter on the existing
180 * module is incremented, the scanner is told to scan the newly
181 * re-opened file, `status' is set to 2, and the existing module is
182 * returned. If either the filenames or the timestamps of the files do
183 * not match, a new module is created. The new module has the same
184 * base-name as the existing module, but its version number is one
185 * greater. The times-opened flag on the new module is set to 1, the
186 * scanner is told to scan the newly opened file, `status' is set to 1,
187 * and the new module is returned. Note that a string comparison is
188 * used to compare filenames, so "./foo" and "././foo" are seen as two
189 * separate files.<br><br>
190 *
191 * If the argument `name' is NULL or has zero length, `status' is set
192 * to -4 and NULL is returned.<br><br>
193 *
194 * If any attempts to allocate memory fail, `status' is set to -3 and
195 * NULL is returned.<br><br>
196 *
197 * Summary of values put into `status':
198 * - -4 bad input: NULL or zero length name
199 * - -3 a memory error occurred: not enough memory to create module
200 * - -2 a filename was found but it could not be opened for reading
201 * - -1 a filename could not find a file for `name'
202 * - 0 a new module was successfully created
203 * - 1 a new version of an existing module was created
204 * - 2 an existing module is being returned
205 * - 3 a new module was created, overwriting a module's alias
206 * - 4 an attempt to do a recursive require was caught
207 * - 5 the module you are REQUIREing already exists
208 */
209
210
211 extern int Asc_ModuleCreateAlias(CONST struct module_t *m, CONST char *name);
212 /**<
213 * This function takes the string given in `name' and converts it
214 * to a module "base-name" by removing all path information---i.e.,
215 * only characters after the rightmost slash (`/' on UNIX, '\' on
216 * Windows) are used in the base-name. This base-name---along with
217 * the version number zero---acts as an alias for the module `m'.<br><br>
218 *
219 * The number of aliases a module may have is only limited by the
220 * computer's memory.<br><br>
221 *
222 * Clients can use the alias to retrieve the module `m'. For example,
223 * if the following sequence occurs:
224 * <pre>
225 * m = Asc_OpenModule("foo.a4c",NULL);
226 * Asc_ModuleCreateAlias(m, "bar.a4c");
227 * then
228 * m == Asc_GetModuleByName("bar.a4c<0>")
229 * == Asc_GetModuleByName("foo.a4c<0>")
230 * </pre>
231 *
232 * The typical reason to create a module-alias is to satisfy subsequent
233 * calls to Asc_RequireModule(); recall that Asc_RequireModule() checks
234 * both existing modules and module-aliases for a matching base-name
235 * before it opens the module itself. As an example, consider a case
236 * where two modules both provide basic needs (system.lib and
237 * ivpsystem.lib), but one (ivpsystem.lib) defines things differently
238 * for use by higher level modules. An intermediate module (e.g.,
239 * atoms.lib) doesn't care which version it reads, but it knows what it
240 * needs can come from system.lib, so atoms.lib will REQUIRE system.lib
241 * (the REQUIRE keyword calls Asc_RequireModule()). However, since
242 * ivpsystem.lib can act as a substitute for system.lib, it should
243 * PROVIDE system.lib (the PROVIDE keyword calls
244 * Asc_ModuleCreateAlias()) to say that ivpsystem.lib satisfies what
245 * system.lib typically provides, in effect, to say that system.lib has
246 * been provided.<br><br>
247 *
248 * The base-name of the module-alias that is created must not conflict
249 * with the base-names of any existing modules (it may conflict with
250 * existing module-aliases). If the alias's base-name conflicts with a
251 * module's base-name, an error message is printed and -2 is returned.
252 * The one exception to this rule is if an alias's base-name matches
253 * the current-module's (as returned by Asc_CurrentModule) base-name.
254 * This can occur if the file for module "foo" contains the statement
255 * ``PROVIDE "foo"''. In this case, a module-alias is not created and
256 * 1 is returned.<br><br>
257 *
258 * If the alias's base-name does not conflict with any other alias's
259 * base-name, a new module-alias is created and 0 is returned.<br><br>
260 *
261 * Attempts to create an alias with the same base-name to the same
262 * module are ignored, and 2 is returned.<br><br>
263 *
264 * If a module-alias with the same base-name exists, the filenames of
265 * `m' and the aliased module are compared. If they do not match, a
266 * warning is printed; if they match, we are rereading a file and no
267 * warning is printed. In either case, the old module-alias is
268 * destroyed, a new module-alias is created, and 3 is returned.<br><br>
269 *
270 * If `name' is NULL or has zero length, -4 is returned. `m' not be a
271 * module-alias; if it is a module-alias, an error is printed and -4 is
272 * returned.<br><br>
273 *
274 * If any attempts to allocate memory fail, -3 is returned.
275 */
276
277 extern int Asc_CloseCurrentModule(void);
278 /**<
279 * This function will close the current module, and restore the module
280 * (tell the scanner to scan the module) that REQUIREd it.<br><br>
281 *
282 * If no module REQUIREd the current module (so that this module is the
283 * last open module), return TRUE; otherwise, return FALSE.
284 */
285
286 extern int Asc_ModuleAddStatements(struct module_t *mod, struct gl_list_t *stats);
287 /**<
288 * Add statements to a Module.
289 * Returns 0 or 1 if successful, or -1 if not. The usual cause for
290 * failure is that the module is a file module and not a string
291 * module. File modules cannot have loose GLOBAL statements in them.
292 * <pre>
293 * Return: Caller should do:
294 * -1 Destroy stats and the statementlists in it.
295 * 0 Forget stats-- we now track it.
296 * 1 Destroy stats, but not the statementlists in it,
297 * as we are now tracking the statementslists.
298 * </pre>
299 */
300
301 extern CONST struct module_t* ASC_DLLSPEC Asc_GetModuleByName(CONST char *name);
302 /**<
303 * Return the module whose name is `name.' `name' should be in the
304 * style returned by Asc_ModuleName(), namely, a base-name and a
305 * version number: "foo.a4c<0>".<br><br>
306 *
307 * If `name' refers to a module-alias, the module it is an alias for is
308 * returned.<br><br>
309 *
310 * If `name' is not properly formated, print an error and return NULL.
311 * If a module with the requested name is not found, ruturn NULL.
312 */
313
314 extern struct gl_list_t* ASC_DLLSPEC Asc_ModuleList(int module_type);
315 /**<
316 * <pre>
317 * module_type 0;
318 * Returns a gl_list containing the name of each module that currently
319 * has at least one type definitions based on the module's contents.
320 *
321 * module_type 1;
322 * Returns a gl_list containing the name of each module that currently
323 * has a string definition.
324 *
325 * module_type 2;
326 * Returns a gl_list containing the name of each module that currently
327 * has statements.
328 * </pre>
329 * This function returns NULL if no modules are currently loaded or if
330 * there is not enough memory to create a new gl_list.<br><br>
331 *
332 * The caller is resposible for calling gl_destroy() when finished
333 * using the list. The names contained in the gl_list are the property
334 * of module.c and should not be touched. Since the module names are
335 * strored in the symbol table, this list will survive calls to
336 * Asc_DestroyModules().
337 */
338
339 extern void Asc_ModuleWrite(FILE *f, CONST struct module_t *m);
340 /**<
341 * Write the name, filename, open/closed-state, and time-last-modified
342 * of module `m' to the file pointer `f'. */
343
344 extern struct module_t *Asc_CurrentModuleF(void);
345 /**<
346 * Implementation function for debug version of Asc_CurrentModule().
347 * Do not call this function directly - use Asc_CurrentModule() instead.
348 */
349 #ifndef NDEBUG
350 #define Asc_CurrentModule() Asc_CurrentModuleF()
351 /**<
352 * Returns a pointer to the current module (debug mode).
353 * @see Asc_CurrentModuleF()
354 */
355 #else
356 extern struct module_t *g_current_module;
357 /**<
358 * Pointer to the current module.
359 * Do not access directly. Use Asc_CurrentModule().
360 */
361 #define Asc_CurrentModule() g_current_module
362 /**< Returns a pointer to the current module (release mode). */
363 #endif /* NDEBUG */
364
365 extern CONST char* ASC_DLLSPEC Asc_ModuleName(CONST struct module_t *m);
366 /**<
367 * Return the name of module m.
368 */
369
370 extern struct gl_list_t *Asc_ModuleStatementLists(CONST struct module_t *m);
371 /**<
372 * Returns a gl_list_t *, or NULL if none, containing pointers to
373 * struct StatementList *. The batches of statements are in order
374 * parsed. File modules will never have statements.
375 * One may, (though we don't recommend it) combine all the statements
376 * into one statementlist, resetting the content of the gl_list,
377 * to be just one pointer to the combined statement list if and only if:
378 * -- the order of the statements is not changed.
379 * -- the gl_list_t pointer returned by this function ends up containing
380 * all the statements. module.c owns the gl_list.
381 */
382
383 extern CONST char *Asc_ModuleString(CONST struct module_t *m);
384 /**<
385 * Return the string of module m, if it is an interactive
386 * string module, or NULL if it is a file module.
387 */
388
389 extern CONST char* ASC_DLLSPEC Asc_ModuleFileName(CONST struct module_t *m);
390 /**<
391 * Return the filename of module m.
392 */
393
394 extern CONST char *Asc_ModuleBestName(CONST struct module_t *m);
395 /**<
396 * Return the filename of module m, if it is a file, or the
397 * buffer name if it is a string.
398 * The string comes from a symbol table entry so, a) don't
399 * mess with it and b) can be safely stored elsewhere.
400 */
401
402
403 extern unsigned long Asc_ModuleTimesOpened(CONST struct module_t *m);
404 /**<
405 * Return the number of times that this module has been opened. This is
406 * necessary to determine when you are reloading a module.
407 */
408
409
410 extern struct tm* ASC_DLLSPEC Asc_ModuleTimeModified(CONST struct module_t *m);
411 /**<
412 * Return the time that the module was last modified. The time is
413 * coverted to the local time.
414 */
415
416 extern int Asc_ModuleStringIndex(CONST struct module_t *m);
417 /**<
418 * Return the string index (the place in the sequence of parsing
419 * strings.
420 */
421
422 #define Asc_ModulesEqual(m1,m2) ((m1)==(m2))
423 /**<
424 * This macro will evaluate to TRUE if module `m1' equals module `m2';
425 */
426
427 #endif /* ASC_MODULE_H */

john.pye@anu.edu.au
ViewVC Help
Powered by ViewVC 1.1.22