generic/compiler/module.h

/*  ASCEND modelling environment
    Copyright (C) 1990, 1993, 1994 Thomas Guthrie Epperly
    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
    Ascend Module Control.

    Requires:
    #include "utilities/ascConfig.h"
    #include "compiler.h"
*//*
    by Tom Epperly
    Created: 1/10/90
    Version: $Revision: 1.11 $
    Version control file: $RCSfile: module.h,v $
    Date last modified: $Date: 1998/04/16 00:43:26 $
    Last modified by: $Author: ballan $
*/

#ifndef ASC_MODULE_H
#define ASC_MODULE_H

/** @addtogroup compiler Compiler
    @{
*/

#include <utilities/config.h>
#include <utilities/ascConfig.h>

#define  MOD_FILE_EXTS   6
#define  MOD_OLD_CODE    ".asc"
/**< Extension for old code files. */
#define  MOD_OLD_LIBRARY ".lib"
/**< Extension for old library files. */
#define  MOD_NEW_CODE    ".a4c"
/**< Extension for new code files. */
#define  MOD_NEW_LIBRARY ".a4l"
/**< Extension for new library files. */
#define  MOD_NEW_UNITS   ".a4u"
/**< Extension for new units files. */
#define  MOD_CATCHALL    ""
/**< Extension for general files. */
ASC_DLLSPEC CONST char *g_alt_ending[MOD_FILE_EXTS];
/**<
 *  This array defines the expected file extensions for
 *  parsable ascend MODEL/ATOM/unit code. Files are not
 *  limited to these, however. Interfaces that see a
 *  trailing .* where * is other than these should
 *  enquire as to the user intent: the user may have
 *  made a mistake.
 */

struct module_t;

extern int Asc_InitModules(unsigned long init_length);
/**<
 *  Create the data structures required by the modules code.  Returns
 *  nonzero if not enough memory to initialize the modules; zero for
 *  success.  Clients to not need to call this function since calls to
 *  OpenModule() or RequireModule() will initialize the data structures
 *  if needed.<br><br>
 *
 *  The initial length of the module list will be set to `init_length';
 *  since the module list will grow as needed, this number isn't too
 *  important, but a better guess will mean better performance.
 */


ASC_DLLSPEC void Asc_DestroyModules(DestroyFunc func);
/**<
 *  Deallocate all of the modules.  This should be done when all types
 *  are destroyed and just before exiting.
 *  The function argument is not optional.
 */

ASC_DLLSPEC struct module_t *Asc_OpenStringModule(CONST char *inputstring,
                                             int *status,
                                             CONST char *nameprefix);
/**<
 *  This function returns a module which behaves just as a regular
 *  file module, except that it is always there unless there is
 *  insufficient memory to make the required internal copy of the
 *  string. The scanner will use the non-input-modifying version
 *  of its functions when operating on the copy of the input string.
 *  The string module will make up its own unique name based on nameprefix.
 *  Not surprisingly, the module returned should be closed after a call
 *  to zz_lex.
 */

ASC_DLLSPEC struct module_t *Asc_OpenModule(CONST char *name, int *status);
/**<
 *  Attempt to find and open (for reading) a file whose
 *  name is based on `name'.
 *  @see Asc_RequireModule() for additional information.
 */
ASC_DLLSPEC struct module_t*Asc_RequireModule(CONST char *name, int *status);
/**<
 *  Attempt to find and open (for reading) a file whose
 *  name is based on `name'.
 *
 *  The following applies to both Asc_OpenModule() and Asc_RequireModule().
 *  `name' can either be a full path name to the file (in the native format)
 *  or a string that will be appended to each of the paths listed in the
 *  ASC_ENV_LIBRARY to try and find the file.<br><br>
 *
 *  Past versions (pre July-97) of these functions used to append known
 *  extensions to `name' to try and find the file.  That behavior is no
 *  longer supported.<br><br>
 *
 *  The integer that `status' points to will be set to the return status
 *  of the function.  If you are not concerned about the return status,
 *  pass in NULL as the second argument.<br><br>
 *
 *  The portion of `name' after the rightmost slash (`/' on UNIX, `\' on
 *  Windows) is used as the "base-name" part of the module's
 *  name---i.e., all path information is removed.  The second part of
 *  the module's name is a version number enclosed in angle brackets.
 *  Version numbers start at zero and increase.  For example, the first
 *  time OpenModule("/foo/bar/baz.a4c") is called, a module with the
 *  name "baz.a4c<0>" is created.  Module names are unique.<br><br>
 *
 *  ASC_REQUIREMODULE ONLY:<br>
 *      If the base-name of the module name you specify matches an
 *      existing module's base-name or a module's alias, `status' is set
 *      to 5 and the existing module is returned.  For example, if you
 *      call Asc_OpenModule("/foo/bar/baz.a4c") successfully, and then
 *      Asc_RequireModule("/food/beer/baz.a4c"), the existing module
 *      "baz.a4c<0>" is returned.  The pathnames of the files are not
 *      compared, and no searching of the file system occurs.  See
 *      Asc_ModuleCreateAlias() for details on aliases.<br><br>
 *
 *  If attempting to access `name' directly fails, and searching over
 *  ASC_ENV_LIBRARY produces no valid filenames, `status' is set to
 *  -1 and NULL is returned.  If a matching filename is found but the
 *  fopen() call fails, `status' is set to -2 and NULL is returned.
 *  Note that fopen() is only attempted one time; once we have a name
 *  that looks like a valid directory entry (a stat() call returns 0),
 *  we stop searching.<br><br>
 *
 *  If a filename is found and the file is successfully opened for
 *  reading, the base-name of the module is compared against existing
 *  modules.  If no match is found, a new module is created: its version
 *  number is set to zero, its times-opened counter is set to 1, the
 *  module we are currently scanning (if any---this only occurs when the
 *  user calls RequireModule) is pushed onto a stack, the scanner is
 *  told to scan the newly opened file, `status' is set to 0, and the
 *  new module is returned.<br><br>
 *
 *  If the base-name of the filename we found matches a module alias, we
 *  treat the filename as a new module and the actions listed in the
 *  above paragraph occur, except that `status' is set to 3.  See the
 *  documentation under Asc_ModuleCreateAlias() for details on aliases.<br><br>
 *
 *  If the filename we found and an existing module have the same
 *  base-name, the pathnames and timestamps of the files are compared.
 *  If they match and the existing module is open for reading, the file
 *  is REQUIREing itself; we print an error, set `status' to 4, and
 *  return the existing module.  If they match and the existing module
 *  is not open for reading, the times-opened counter on the existing
 *  module is incremented, the scanner is told to scan the newly
 *  re-opened file, `status' is set to 2, and the existing module is
 *  returned.  If either the filenames or the timestamps of the files do
 *  not match, a new module is created.  The new module has the same
 *  base-name as the existing module, but its version number is one
 *  greater.  The times-opened flag on the new module is set to 1, the
 *  scanner is told to scan the newly opened file, `status' is set to 1,
 *  and the new module is returned.  Note that a string comparison is
 *  used to compare filenames, so "./foo" and "././foo" are seen as two
 *  separate files.<br><br>
 *
 *  If the argument `name' is NULL or has zero length, `status' is set
 *  to -4 and NULL is returned.<br><br>
 *
 *  If any attempts to allocate memory fail, `status' is set to -3 and
 *  NULL is returned.<br><br>
 *
 *  Summary of values put into `status':
 *     - -4  bad input: NULL or zero length name
 *     - -3  a memory error occurred: not enough memory to create module
 *     - -2  a filename was found but it could not be opened for reading
 *     - -1  a filename could not find a file for `name'
 *     -  0  a new module was successfully created
 *     -  1  a new version of an existing module was created
 *     -  2  an existing module is being returned
 *     -  3  a new module was created, overwriting a module's alias
 *     -  4  an attempt to do a recursive require was caught
 *     -  5  the module you are REQUIREing already exists
 */


extern int Asc_ModuleCreateAlias(CONST struct module_t *m, CONST char *name);
/**<
 *  This function takes the string given in `name' and converts it
 *  to a module "base-name" by removing all path information---i.e.,
 *  only characters after the rightmost slash (`/' on UNIX, '\' on
 *  Windows) are used in the base-name.  This base-name---along with
 *  the version number zero---acts as an alias for the module `m'.<br><br>
 *
 *  The number of aliases a module may have is only limited by the
 *  computer's memory.<br><br>
 *
 *  Clients can use the alias to retrieve the module `m'.  For example,
 *  if the following sequence occurs:
 *  <pre>
 *      m = Asc_OpenModule("foo.a4c",NULL);
 *      Asc_ModuleCreateAlias(m, "bar.a4c");
 *  then
 *      m == Asc_GetModuleByName("bar.a4c<0>")
 *        == Asc_GetModuleByName("foo.a4c<0>")
 *  </pre>
 *
 *  The typical reason to create a module-alias is to satisfy subsequent
 *  calls to Asc_RequireModule(); recall that Asc_RequireModule() checks
 *  both existing modules and module-aliases for a matching base-name
 *  before it opens the module itself.  As an example, consider a case
 *  where two modules both provide basic needs (system.lib and
 *  ivpsystem.lib), but one (ivpsystem.lib) defines things differently
 *  for use by higher level modules.  An intermediate module (e.g.,
 *  atoms.lib) doesn't care which version it reads, but it knows what it
 *  needs can come from system.lib, so atoms.lib will REQUIRE system.lib
 *  (the REQUIRE keyword calls Asc_RequireModule()).  However, since
 *  ivpsystem.lib can act as a substitute for system.lib, it should
 *  PROVIDE system.lib (the PROVIDE keyword calls
 *  Asc_ModuleCreateAlias()) to say that ivpsystem.lib satisfies what
 *  system.lib typically provides, in effect, to say that system.lib has
 *  been provided.<br><br>
 *
 *  The base-name of the module-alias that is created must not conflict
 *  with the base-names of any existing modules (it may conflict with
 *  existing module-aliases).  If the alias's base-name conflicts with a
 *  module's base-name, an error message is printed and -2 is returned.
 *  The one exception to this rule is if an alias's base-name matches
 *  the current-module's (as returned by Asc_CurrentModule) base-name.
 *  This can occur if the file for module "foo" contains the statement
 *  ``PROVIDE "foo"''.  In this case, a module-alias is not created and
 *  1 is returned.<br><br>
 *
 *  If the alias's base-name does not conflict with any other alias's
 *  base-name, a new module-alias is created and 0 is returned.<br><br>
 *
 *  Attempts to create an alias with the same base-name to the same
 *  module are ignored, and 2 is returned.<br><br>
 *
 *  If a module-alias with the same base-name exists, the filenames of
 *  `m' and the aliased module are compared.  If they do not match, a
 *  warning is printed; if they match, we are rereading a file and no
 *  warning is printed.  In either case, the old module-alias is
 *  destroyed, a new module-alias is created, and 3 is returned.<br><br>
 *
 *  If `name' is NULL or has zero length, -4 is returned.  `m' not be a
 *  module-alias; if it is a module-alias, an error is printed and -4 is
 *  returned.<br><br>
 *
 *  If any attempts to allocate memory fail, -3 is returned.
 */

ASC_DLLSPEC int Asc_CloseCurrentModule(void);
/**<
 *  This function will close the current module, and restore the module
 *  (tell the scanner to scan the module) that REQUIREd it.<br><br>
 *
 *  If no module REQUIREd the current module (so that this module is the
 *  last open module), return TRUE; otherwise, return FALSE.
 */

extern int Asc_ModuleAddStatements(struct module_t *mod, struct gl_list_t *stats);
/**<
 * Add statements to a Module.
 * Returns 0 or 1 if successful, or -1 if not. The usual cause for
 * failure is that the module is a file module and not a string
 * module. File modules cannot have loose GLOBAL statements in them.
 *  <pre>
 * Return:  Caller should do:
 *  -1      Destroy stats and the statementlists in it.
 *   0      Forget stats-- we now track it.
 *   1      Destroy stats, but not the statementlists in it,
 *          as we are now tracking the statementslists.
 *  </pre>
 */

ASC_DLLSPEC CONST struct module_t*Asc_GetModuleByName(CONST char *name);
/**<
 *  Return the module whose name is `name.'  `name' should be in the
 *  style returned by Asc_ModuleName(), namely, a base-name and a
 *  version number: "foo.a4c<0>".<br><br>
 *
 *  If `name' refers to a module-alias, the module it is an alias for is
 *  returned.<br><br>
 *
 *  If `name' is not properly formated, print an error and return NULL.
 *  If a module with the requested name is not found, ruturn NULL.
 */

ASC_DLLSPEC struct gl_list_t*Asc_ModuleList(int module_type);
/**<
 *  <pre>
 *  module_type 0;
 *  Returns a gl_list containing the name of each module that currently
 *  has at least one type definitions based on the module's contents.
 *
 *  module_type 1;
 *  Returns a gl_list containing the name of each module that currently
 *  has a string definition.
 *
 *  module_type 2;
 *  Returns a gl_list containing the name of each module that currently
 *  has statements.
 *  </pre>
 *  This function returns NULL if no modules are currently loaded or if
 *  there is not enough memory to create a new gl_list.<br><br>
 *
 *  The caller is resposible for calling gl_destroy() when finished
 *  using the list.  The names contained in the gl_list are the property
 *  of module.c and should not be touched.  Since the module names are
 *  strored in the symbol table, this list will survive calls to
 *  Asc_DestroyModules().
 */

extern void Asc_ModuleWrite(FILE *f, CONST struct module_t *m);
/**<
 *  Write the name, filename, open/closed-state, and time-last-modified
 *  of module `m' to the file pointer `f'.  */

extern struct module_t *Asc_CurrentModuleF(void);
/**<
 *  Implementation function for debug version of Asc_CurrentModule().
 *  Do not call this function directly - use Asc_CurrentModule() instead.
 */
#ifndef NDEBUG
#define Asc_CurrentModule() Asc_CurrentModuleF()
/**<
 *  Returns a pointer to the current module (debug mode).
 *  @see Asc_CurrentModuleF()
 */
#else
extern struct module_t *g_current_module;
/**<
 *  Pointer to the current module.
 *  Do not access directly.  Use Asc_CurrentModule().
 */
#define Asc_CurrentModule() g_current_module
/**<  Returns a pointer to the current module (release mode). */
#endif /* NDEBUG */

ASC_DLLSPEC CONST char*Asc_ModuleName(CONST struct module_t *m);
/**<
 *  Return the name of module m.
 */

extern struct gl_list_t *Asc_ModuleStatementLists(CONST struct module_t *m);
/**<
 * Returns a gl_list_t *, or NULL if none, containing pointers to
 * struct StatementList *. The batches of statements are in order
 * parsed. File modules will never have statements.
 * One may, (though we don't recommend it) combine all the statements
 * into one statementlist, resetting the content of the gl_list,
 * to be just one pointer to the combined statement list if and only if:
 * -- the order of the statements is not changed.
 * -- the gl_list_t pointer returned by this function ends up containing
 *    all the statements. module.c owns the gl_list.
 */

ASC_DLLSPEC CONST char *Asc_ModuleString(CONST struct module_t *m);
/**<
 *  Return the string of module m, if it is an interactive
 *  string module, or NULL if it is a file module.
 */

ASC_DLLSPEC CONST char*Asc_ModuleFileName(CONST struct module_t *m);
/**<
 *  Return the filename of module m.
 */

ASC_DLLSPEC CONST char *Asc_ModuleBestName(CONST struct module_t *m);
/**<
 *  Return the filename of module m, if it is a file, or the
 *  buffer name if it is a string.
 *  The string comes from a symbol table entry so, a) don't
 *  mess with it and b) can be safely stored elsewhere.
 */


extern unsigned long Asc_ModuleTimesOpened(CONST struct module_t *m);
/**<
 *  Return the number of times that this module has been opened.  This is
 *  necessary to determine when you are reloading a module.
 */


ASC_DLLSPEC struct tm*Asc_ModuleTimeModified(CONST struct module_t *m);
/**<
 *  Return the time that the module was last modified.  The time is
 *  coverted to the local time.
 */

ASC_DLLSPEC int Asc_ModuleStringIndex(CONST struct module_t *m);
/**<
 *  Return the string index (the place in the sequence of parsing
 *  strings.
 */

#define Asc_ModulesEqual(m1,m2) ((m1)==(m2))
/**<
 *  This macro will evaluate to TRUE if module `m1' equals module `m2';
 */

/* @} */

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