/[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 485 - (show annotations) (download) (as text)
Tue Apr 18 04:47:11 2006 UTC (14 years, 3 months ago) by johnpye
File MIME type: text/x-chdr
File size: 17750 byte(s)
Huge cleanup of file header comments (GPL notice etc).

Changed from ASC_DLLSPEC to ASC_DLLSPEC(TYPE) -- like python

Fixed up some badly export symbols (missing 'extern')

Fixed exporting of symbols from error.h

Removed ASC_DLLSPEC from .c files-- only in .h files now (hope that's right...)

Changed the way bintoken does its exporting, to take 
advantage of ASC_BUILDING_LIBASCEND (needs testing)

I wonder if the 'extern' keywork should be a part of the ASC_DLLSPEC macro?

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

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