generic/compiler/library.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
    Type Definition Library.

    Implements a type definition library for use by the ASCEND compiler.
    Each type encountered during parsing is converted to a TypeDescription
    and stored in the main type library maintained by this module.
    The type library will only maintain one definition for a given type
    name.  The library will complain if you try to add two types with the
    same name unless it happens when reloading a module.

    Requires:
    #include "utilities/ascConfig.h"
    #include "compiler/compiler.h"
    #include "compiler/type_desc.h"
    #include "compiler/module.h"
    #include "general/list.h"
*//*
    by Tom Epperly
    Created: 1/12/90
    Version: $Revision: 1.17 $
    Version control file: $RCSfile: library.h,v $
    Date last modified: $Date: 1998/04/16 00:43:24 $
    Last modified by: $Author: ballan $
*/

#ifndef ASC_LIBRARY_H
#define ASC_LIBRARY_H

/** addtogroup compiler Compiler
    @{
*/

#include <utilities/ascConfig.h>

/** For use in constructing hierarchies. */
struct HierarchyNode {
  struct TypeDescription *desc;   /**< The type at this node. */
  struct gl_list_t *descendents;  /**< The list of refinements of desc. */
};

extern void InitializeLibrary(void);
/**<
 *  Initializes the library.
 *  This should be called before using any other functions
 *  or globals in this module.  Call DestroyLibrary() when
 *  finished with the library.
 */

ASC_DLLSPEC void DestroyLibrary(void);
/**<
 *  Cleans up after library use.
 *  Do not use any other functions or globals in this module after
 *  using this function until InitializeLibrary() is called.
 */

ASC_DLLSPEC struct TypeDescription*FindType(symchar *name);
/**<
 *  Finds the type description associated with name.
 *  Returns NULL if unable to locate the type.
 *  Handles NULL input gracefully.
 *
 *  @param name The type name to look up.
 *  @return The type description having the specified name,
 *          or NULL if none have that name.
 */

extern struct TypeDescription *FindRelationType(void);
/**<
 *  Finds the type description associated with real relations.
 *  Returns NULL if never defined, which means someone forgot to
 *  load a system.lib equivalent.
 */

extern struct TypeDescription *FindLogRelType(void);
/**<
 *  Finds the type description associated with logical relations.
 *  Returns NULL if never defined, which means someone forgot to
 *  load a system.lib equivalent.
 */

extern struct TypeDescription *FindSetType(void);
/**<
 *  Finds the type description associated with set statements.
 *  Returns NULL if never defined, which is an extreme error.
 */

extern struct TypeDescription *FindDummyType(void);
/**<
 *  Finds the type description associated with unselected statements.
 *  Returns NULL if never defined, which is an extreme error.
 */

extern struct TypeDescription *FindWhenType(void);
/**<
 *  Finds the type description associated with WHEN statements.
 *  Returns NULL if never defined, which is an extreme error.
 */

extern struct TypeDescription *FindExternalType(void);
/**<
 *  Finds the type description associated with external statements.
 *  Returns NULL if never defined, which is an extreme error.
 */

extern int AddType(struct TypeDescription *desc);
/**<
 *  Adds a type to the library.
 *  The type is not added if it is already present in the
 *  type library.  Otherwise, the library takes ownership of
 *  desc and adds it to the library.
 *
 *  @param desc The type to add to the library.
 *  @return Returns 1 if the new type is added and kept,
 *          0 if it was already present.
 */

ASC_DLLSPEC struct gl_list_t *FindFundamentalTypes(void);
/**<
 *  Creates a gl_list_t containing pointers to the fundamental
 *  types.  Destruction of the returned list (but not it's
 *  contents) is the responsibility of the caller.
 *
 *  @return A gl_list_t of (struct TypeDescription *) to the
 *          fundamental types.
 */

ASC_DLLSPEC struct gl_list_t*Asc_TypeByModule(CONST struct module_t *module);
/**<
 *  Builds a list of type names defined in module that are already
 *  present in the main type library.  Destruction of the returned
 *  list (but not its contents) is the responsibility of the caller.
 *
 *  @param module The module to parse for defined type names.
 *  @return A gl_list_t of (symchar *) to the names of types found
 *          both in module and in the main type library.
 */

ASC_DLLSPEC struct gl_list_t *TypesThatRefineMe (symchar *name);
/**<
 *  Builds a list of type names in the main type library which refine
 *  the type having the specified name.  The returned list includes
 *  immediate refinements only, not all of the refinements in a chain
 *  such as a<-b<-c<-d.  Given a, only b is included in the list.
 *  This should be an expensive function and could be made more
 *  efficient for certain atomic types.  Destruction of the returned
 *  list (but not its contents) is the responsibility of the caller.
 *
 *  @param name The type name to check for registered refinements.
 *  @return A gl_list_t of (symchar *) to the names of types in the main
 *          type library which refine the specified type.
 */

ASC_DLLSPEC struct gl_list_t *AllTypesThatRefineMe_Flat (symchar *name);
/**<
 *  Builds a list of all type names in the main type library which
 *  refine the type having the specified name.  The returned list
 *  includes all refinements in a chain such as a<-b<-c<-d.  Given a,
 *  b, c, and d are all included in the list.  This is only slightly
 *  more expensive than TypesThatRefineMe().  For efficiency atoms
 *  and models are handled differently.  Destruction of the returned
 *  list (but not its contents) is the responsibility of the caller.
 *
 *  @param name The type name to check for registered refinements.
 *  @return A gl_list_t of (symchar *) to the names of types in the main
 *          type library which refine the specified type.
 */

ASC_DLLSPEC struct HierarchyNode *AllTypesThatRefineMe_Tree (symchar *name);
/**<
 *  Builds a tree of HierarchyNodes all types in the main type library
 *  which refine the type having the specified name.  This is similar to
 *  AllTypesThatRefineMe_Flat() except that the results are returned in
 *  a HierarchyNodes tree.  This is somewhat pricey in terms of the number
 *  of pointer comparisons.   For efficiency atoms and models are handled
 *  separately.  The first node returned is the node of the type given.
 *  If it is null, the type given was not found.  Destruction of the
 *  returned tree is the responsibility of the caller.  Use
 *  DestroyHierarchyNode() for this purpose.
 *
 *  @param name The type name to check for registered refinements.
 *  @return A tree of HierarchyNodes containing the types in the main
 *          type library which refine the specified type.
 */

ASC_DLLSPEC void DestroyHierarchyNode(struct HierarchyNode *heir);
/**<
 *  Deallocates (recursively) all the memory associated with a
 *  HierarchyNode.  Use this function to destroy the tree returned
 *  by AllTypesThatRefineMe_Tree().
 *
 *  @param heir Head of the HeirarchyNode tree to destroy.
 */

ASC_DLLSPEC int IsTypeRefined(CONST struct TypeDescription *desc);
/**<
 *  Check whether the specified type is refined by any other type in
 *  the main type library.
 *
 *  @param desc The type to check for refinements.
 *  @return Returns 1 if desc is refined, 0 otherwise.
 */

ASC_DLLSPEC struct gl_list_t *DefinitionList(void);
/**<
 *  Makes a sorted list of all registered definitions.
 *  In the case of there being two versions of a given type,
 *  the latest version is used.  This doesn't include array type
 *  definitions.  The user is responsible for destroying the
 *  returned list (but not its content).
 *
 *  @return A gl_list_t of (struct TypeDescription *) containing
 *          the sorted types.
 */

ASC_DLLSPEC unsigned int CheckFundamental(symchar *f);
/**<
 *  Checks whether string f is a fundamental type name.
 *  f must be from the symbol table (i.e. not an externally-defined
 *  character string).
 *
 *  @param f The string to check.
 *  @return Returns 1 if f is a fundamental type name, 0 if not.
 */

/* @} */

#endif /* ASC_LIBRARY_H */
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	Type Definition Library.
22
23	Implements a type definition library for use by the ASCEND compiler.
24	Each type encountered during parsing is converted to a TypeDescription
25	and stored in the main type library maintained by this module.
26	The type library will only maintain one definition for a given type
27	name. The library will complain if you try to add two types with the
28	same name unless it happens when reloading a module.
29
30	Requires:
31	#include "utilities/ascConfig.h"
32	#include "compiler/compiler.h"
33	#include "compiler/type_desc.h"
34	#include "compiler/module.h"
35	#include "general/list.h"
36	//
37	by Tom Epperly
38	Created: 1/12/90
39	Version: $Revision: 1.17 $
40	Version control file: $RCSfile: library.h,v $
41	Date last modified: $Date: 1998/04/16 00:43:24 $
42	Last modified by: $Author: ballan $
43	*/
44
45	#ifndef ASC_LIBRARY_H
46	#define ASC_LIBRARY_H
47
48	/** addtogroup compiler Compiler
49	@{
50	*/
51
52	#include <utilities/ascConfig.h>
53
54	/** For use in constructing hierarchies. */
55	struct HierarchyNode {
56	struct TypeDescription desc; /< The type at this node. /
57	struct gl_list_t descendents; /< The list of refinements of desc. /
58	};
59
60	extern void InitializeLibrary(void);
61	/**<
62	* Initializes the library.
63	* This should be called before using any other functions
64	* or globals in this module. Call DestroyLibrary() when
65	* finished with the library.
66	*/
67
68	ASC_DLLSPEC void DestroyLibrary(void);
69	/**<
70	* Cleans up after library use.
71	* Do not use any other functions or globals in this module after
72	* using this function until InitializeLibrary() is called.
73	*/
74
75	ASC_DLLSPEC struct TypeDescriptionFindType(symchar name);
76	/**<
77	* Finds the type description associated with name.
78	* Returns NULL if unable to locate the type.
79	* Handles NULL input gracefully.
80	*
81	* @param name The type name to look up.
82	* @return The type description having the specified name,
83	* or NULL if none have that name.
84	*/
85
86	extern struct TypeDescription *FindRelationType(void);
87	/**<
88	* Finds the type description associated with real relations.
89	* Returns NULL if never defined, which means someone forgot to
90	* load a system.lib equivalent.
91	*/
92
93	extern struct TypeDescription *FindLogRelType(void);
94	/**<
95	* Finds the type description associated with logical relations.
96	* Returns NULL if never defined, which means someone forgot to
97	* load a system.lib equivalent.
98	*/
99
100	extern struct TypeDescription *FindSetType(void);
101	/**<
102	* Finds the type description associated with set statements.
103	* Returns NULL if never defined, which is an extreme error.
104	*/
105
106	extern struct TypeDescription *FindDummyType(void);
107	/**<
108	* Finds the type description associated with unselected statements.
109	* Returns NULL if never defined, which is an extreme error.
110	*/
111
112	extern struct TypeDescription *FindWhenType(void);
113	/**<
114	* Finds the type description associated with WHEN statements.
115	* Returns NULL if never defined, which is an extreme error.
116	*/
117
118	extern struct TypeDescription *FindExternalType(void);
119	/**<
120	* Finds the type description associated with external statements.
121	* Returns NULL if never defined, which is an extreme error.
122	*/
123
124	extern int AddType(struct TypeDescription *desc);
125	/**<
126	* Adds a type to the library.
127	* The type is not added if it is already present in the
128	* type library. Otherwise, the library takes ownership of
129	* desc and adds it to the library.
130	*
131	* @param desc The type to add to the library.
132	* @return Returns 1 if the new type is added and kept,
133	* 0 if it was already present.
134	*/
135
136	ASC_DLLSPEC struct gl_list_t *FindFundamentalTypes(void);
137	/**<
138	* Creates a gl_list_t containing pointers to the fundamental
139	* types. Destruction of the returned list (but not it's
140	* contents) is the responsibility of the caller.
141	*
142	* @return A gl_list_t of (struct TypeDescription *) to the
143	* fundamental types.
144	*/
145
146	ASC_DLLSPEC struct gl_list_tAsc_TypeByModule(CONST struct module_t module);
147	/**<
148	* Builds a list of type names defined in module that are already
149	* present in the main type library. Destruction of the returned
150	* list (but not its contents) is the responsibility of the caller.
151	*
152	* @param module The module to parse for defined type names.
153	* @return A gl_list_t of (symchar *) to the names of types found
154	* both in module and in the main type library.
155	*/
156
157	ASC_DLLSPEC struct gl_list_t TypesThatRefineMe (symchar name);
158	/**<
159	* Builds a list of type names in the main type library which refine
160	* the type having the specified name. The returned list includes
161	* immediate refinements only, not all of the refinements in a chain
162	* such as a<-b<-c<-d. Given a, only b is included in the list.
163	* This should be an expensive function and could be made more
164	* efficient for certain atomic types. Destruction of the returned
165	* list (but not its contents) is the responsibility of the caller.
166	*
167	* @param name The type name to check for registered refinements.
168	* @return A gl_list_t of (symchar *) to the names of types in the main
169	* type library which refine the specified type.
170	*/
171
172	ASC_DLLSPEC struct gl_list_t AllTypesThatRefineMe_Flat (symchar name);
173	/**<
174	* Builds a list of all type names in the main type library which
175	* refine the type having the specified name. The returned list
176	* includes all refinements in a chain such as a<-b<-c<-d. Given a,
177	* b, c, and d are all included in the list. This is only slightly
178	* more expensive than TypesThatRefineMe(). For efficiency atoms
179	* and models are handled differently. Destruction of the returned
180	* list (but not its contents) is the responsibility of the caller.
181	*
182	* @param name The type name to check for registered refinements.
183	* @return A gl_list_t of (symchar *) to the names of types in the main
184	* type library which refine the specified type.
185	*/
186
187	ASC_DLLSPEC struct HierarchyNode AllTypesThatRefineMe_Tree (symchar name);
188	/**<
189	* Builds a tree of HierarchyNodes all types in the main type library
190	* which refine the type having the specified name. This is similar to
191	* AllTypesThatRefineMe_Flat() except that the results are returned in
192	* a HierarchyNodes tree. This is somewhat pricey in terms of the number
193	* of pointer comparisons. For efficiency atoms and models are handled
194	* separately. The first node returned is the node of the type given.
195	* If it is null, the type given was not found. Destruction of the
196	* returned tree is the responsibility of the caller. Use
197	* DestroyHierarchyNode() for this purpose.
198	*
199	* @param name The type name to check for registered refinements.
200	* @return A tree of HierarchyNodes containing the types in the main
201	* type library which refine the specified type.
202	*/
203
204	ASC_DLLSPEC void DestroyHierarchyNode(struct HierarchyNode *heir);
205	/**<
206	* Deallocates (recursively) all the memory associated with a
207	* HierarchyNode. Use this function to destroy the tree returned
208	* by AllTypesThatRefineMe_Tree().
209	*
210	* @param heir Head of the HeirarchyNode tree to destroy.
211	*/
212
213	ASC_DLLSPEC int IsTypeRefined(CONST struct TypeDescription *desc);
214	/**<
215	* Check whether the specified type is refined by any other type in
216	* the main type library.
217	*
218	* @param desc The type to check for refinements.
219	* @return Returns 1 if desc is refined, 0 otherwise.
220	*/
221
222	ASC_DLLSPEC struct gl_list_t *DefinitionList(void);
223	/**<
224	* Makes a sorted list of all registered definitions.
225	* In the case of there being two versions of a given type,
226	* the latest version is used. This doesn't include array type
227	* definitions. The user is responsible for destroying the
228	* returned list (but not its content).
229	*
230	* @return A gl_list_t of (struct TypeDescription *) containing
231	* the sorted types.
232	*/
233
234	ASC_DLLSPEC unsigned int CheckFundamental(symchar *f);
235	/**<
236	* Checks whether string f is a fundamental type name.
237	* f must be from the symbol table (i.e. not an externally-defined
238	* character string).
239	*
240	* @param f The string to check.
241	* @return Returns 1 if f is a fundamental type name, 0 if not.
242	*/
243
244	/* @} */
245
246	#endif /* ASC_LIBRARY_H */