generic/compiler/name.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
    Name external definitions.

    @todo WHAT'S IN A NAME??? That which we call a rose
    By any other name would smell as sweet.

    A name is a linked list of symchars, integers, and potentially
    unexpanded set definitions (array subscripts)
    that gives the route another instance starting at some root
    instance i.  So if you have something's name and context instance, we
    know how to find the child (grandchild, etc) with the given name.
    A name without a context (either an instance or a type definition)
    means nothing.

    Requires:
    #include "utilities/ascConfig.h"
    #include "fractions.h"
    #include "compiler.h"
    #include "dimen.h"
    #include "expr_types.h"
*//*
    by Tom Epperly
    July 31, 1989
    Last in CVS: $Revision: 1.13 $ $Date: 1998/06/16 16:36:28 $ $Author: mthomas $
*/

#ifndef ASC_NAME_H
#define ASC_NAME_H

/** addtogroup compiler Compiler
    @{
*/

#include <utilities/ascConfig.h>

#define CreateIdName(s) CreateIdNameF((s),NAMEBIT_IDTY)
/**<
    Create name with Id flag.
    @see CreateIdNameF()
*/
#define CreateSystemIdName(s) CreateIdNameF((s),NAMEBIT_IDTY|NAMEBIT_AUTO)
/**<
    Create system name with Id+Auto flags.
    @see CreateIdNameF()
*/
ASC_DLLSPEC struct Name*CreateIdNameF(symchar *s, int bits);
/**<
    Create a name node with the identifier s
    and flag bits associated with it.  Implementation
    function for CreateIdName() and CreateSystemIdName().
*/

extern struct Name *CreateSetName(struct Set *s);
/**<
    Create a name node of type set with the set s associated with it.
*/

extern struct Name *CreateEnumElementName(symchar *s);
/**<
    Create a name node of type set with the subscript s associated with it.
*/

extern struct Name *CreateIntegerElementName(long i);
/**<
    Create a name node of type set with the subscript i associated with it.
*/

extern struct Name *CreateReservedIndexName(symchar *reserved);
/**<
 * Make subscript index from the reserved identifier given, 
 * which in most uses will
 * contain an illegal character for an ascend ID reserving the
 * set index to internal compiler use only.
 */

extern void LinkNames(struct Name *cur, struct Name *next);
/**<
    Link "next" to cur so that NextName(cur) = next
*/

#ifdef NDEBUG
#define NextName(n) ((n)->next)
#else
#define NextName(n) NextNameF(n)
#endif
/**<
    Return the next attribute of n.
    @param n CONST struct Name*, Name to query.
    @return The next attribute as a struct Name*.
    @see NextNameF()
*/
extern struct Name *NextNameF(CONST struct Name *n);
/**<
    Return the next attribute of n.
    Implementation function for NextName().  Do not call this
    function directly - use NextName() instead.
*/

#ifdef NDEBUG
#define NameId(n) ((n)->bits & NAMEBIT_IDTY)
#else
#define NameId(n) NameIdF(n)
#endif
/**<
    Test whether a Name element is an identifier.
    We should have analogous functions for CHAT and ATTR, but since no
    clients yet use them, they aren't implemented.
    @param n CONST struct Name*, Name to query.
    @return An int:  NAMEBIT_IDTY if n is an identifier type Name or 0 otherwise.
    @see NameIdF()

    @note This answers for just the *first* link in the name.
        
*/

extern int NameIdF(CONST struct Name *n);
/**<
    Return NAMEBIT_IDTY if n is an identifier type Name or 0 otherwise.
    We should have analogous functions for CHAT and ATTR, but since no
    clients yet use them, they aren't implemented.
    Implementation function for NameId().  Do not call this
    function directly - use NameId() instead.
*/

#ifdef NDEBUG
#define NameAuto(n) ((n)->bits & (NAMEBIT_AUTO|NAMEBIT_IDTY))
#else
#define NameAuto(n) NameAutoF(n)
#endif
/**<
    Test whether a Name is a system generated identifier.
    @param n CONST struct Name*, Name to query.
    @return An int:  NAMEBIT_AUTO if n is an system generated identifier
            type Name, or 0 otherwise.
    @see NameAutoF()
*/

extern int NameAutoF(CONST struct Name *n);
/**<
    Return NAMEBIT_AUTO if n is an system generated identifier
    type Name, or 0 otherwise.
    Implementation function for NameAuto().  Do not call this
    function directly - use NameAuto() instead.
*/

#ifdef NDEBUG
#define NameIdPtr(n) ((n)->val.id)
#else
#define NameIdPtr(n) NameIdPtrF(n)
#endif
/**<
    Returns the id pointer for identifier type name node n.
    @param n CONST struct Name*, Name to query.
    @return The id pointer as a symchar*.
    @see NameIdPtrF()
*/
extern symchar *NameIdPtrF(CONST struct Name *n);
/**<
    Assumes that n is a identifier type name node.
    @return the id pointer.
    Implementation function for NameIdPtr().  Do not call this
    function directly - use NameIdPtr() instead.
*/

extern symchar *SimpleNameIdPtr(CONST struct Name *n);
/**<
    Return NULL if n is not an NameId or if it has a next field.  Otherwise,
    it returns the char pointer.
*/

extern unsigned int NameLength(CONST struct Name *n);
/**<
    Returns the number of links in a name.

    @note May be used in a similar manner to SimpleNameIdPtr,
        to determine if a name is a simple name

    @example
        <tt>my_var</tt> has length 1.
        <tt>my_var.your_var[1..3]</tt> has length 3.
*/

#ifdef NDEBUG
#define NameSetPtr(n) ((n)->val.s)
#else
#define NameSetPtr(n) NameSetPtrF(n)
#endif
/**<
    Returns the set pointer for set type name node n.
    @param n CONST struct Name*, Name to query.
    @return The set pointer as a CONST struct Set*.
    @see NameSetPtrF()
*/
extern CONST struct Set *NameSetPtrF(CONST struct Name *n);
/**<
    Assumes that n is a set type name node.
    Returns the set pointer.
    Implementation function for NameSetPtr().  Do not call this
    function directly - use NameSetPtr() instead.
*/

extern struct Name *CopyName(CONST struct Name *n);
/**<
    Make and return a copy of the whole name.
*/

extern struct Name *CopyAppendNameNode(CONST struct Name *n, CONST struct Name *node);
/**<
    Make a copy of n and append a copy of the node (which may be just the
    head of a longer name). The result is totally disjoint from the inputs.
*/

ASC_DLLSPEC void DestroyName(struct Name *n);
/**<
    Deallocate the whole name linked list
    Handles NULL input gracefully.
*/

extern void DestroyNamePtr(struct Name *n);
/**<
    Deallocate this name node, and don't change the next node.
    Handles NULL input gracefully.
 */

extern struct Name *JoinNames(struct Name *n1, struct Name *n2);
/**<
    Appends n2 to the end of n1.  This will return n1, unless n1 is NULL in
    which case it will return n2.
 */

extern struct Name *ReverseName(struct Name *n);
/**<
    Returns the reverse of n.
    Normally only done to unreverse the order that yacc collects
    identifiers.
*/

extern CONST struct Name *NextIdName(CONST struct Name *n);
/**<
    Returns the first NameId element in the name after the current element
    which is expected to be a NameId. If there is none, returns NULL.
 */

extern int NameCompound(CONST struct Name *n);
/**<
    Test whether name is compound (i.e. crosses a MODEL/ATOM boundary).
    If so this returns 1, OTHERWISE this returns 0.  So array names
    will return 0.

    The following return 0:
     - a
     - a[i]
     - [i][j]  -- though this isn't a proper name, generally.

    The following return 1:
     - a.b
     - a[i].b
     - [i].b

    So basically, if the name is printed with a '.' this will return 1.
*/

extern int NamesEqual(CONST struct Name *n1, CONST struct Name *n2);
/**<
    Return TRUE if and only if n1 and n2 are structurally equivalent.
*/

extern int CompareNames(CONST struct Name *n1, CONST struct Name *n2);
/**<
    Returns -1 0 1 as n1 < = > n2.
    Will need fixing when we have supported attributes.
*/

extern void name_init_pool(void);
/**<
    Starts memory recycle. Do not call twice before stopping recycle.
*/

extern void name_destroy_pool(void);
/**<
    Stops memory recycle. Do not call while ANY names are outstanding.
*/

extern void name_report_pool(void);
/**<
    Write the pool report to ASCERR for the name pool.
*/

/* @} */

#endif  /* ASC_NAME_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
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	johnpye	194	Name external definitions.
22	aw0a	1
23	johnpye	194	@todo WHAT'S IN A NAME??? That which we call a rose
24			By any other name would smell as sweet.
25	aw0a	1
26	johnpye	1031	A name is a linked list of symchars, integers, and potentially
27			unexpanded set definitions (array subscripts)
28			that gives the route another instance starting at some root
29			instance i. So if you have something's name and context instance, we
30			know how to find the child (grandchild, etc) with the given name.
31			A name without a context (either an instance or a type definition)
32			means nothing.
33	johnpye	194
34	johnpye	485	Requires:
35			#include "utilities/ascConfig.h"
36			#include "fractions.h"
37			#include "compiler.h"
38			#include "dimen.h"
39	johnpye	669	#include "expr_types.h"
40	johnpye	485	//
41			by Tom Epperly
42			July 31, 1989
43	johnpye	912	Last in CVS: $Revision: 1.13 $ $Date: 1998/06/16 16:36:28 $ $Author: mthomas $
44	johnpye	194	*/
45
46			#ifndef ASC_NAME_H
47			#define ASC_NAME_H
48
49	johnpye	1066	/** addtogroup compiler Compiler
50			@{
51			*/
52
53	johnpye	485	#include <utilities/ascConfig.h>
54
55	jds	54	#define CreateIdName(s) CreateIdNameF((s),NAMEBIT_IDTY)
56	johnpye	480	/**<
57	johnpye	194	Create name with Id flag.
58			@see CreateIdNameF()
59			*/
60	aw0a	1	#define CreateSystemIdName(s) CreateIdNameF((s),NAMEBIT_IDTY\|NAMEBIT_AUTO)
61	jds	54	/**<
62	johnpye	194	Create system name with Id+Auto flags.
63			@see CreateIdNameF()
64			*/
65	johnpye	1063	ASC_DLLSPEC struct NameCreateIdNameF(symchar s, int bits);
66	jds	54	/**<
67	johnpye	194	Create a name node with the identifier s
68			and flag bits associated with it. Implementation
69			function for CreateIdName() and CreateSystemIdName().
70			*/
71	aw0a	1
72	jds	54	extern struct Name CreateSetName(struct Set s);
73	johnpye	480	/**<
74	johnpye	194	Create a name node of type set with the set s associated with it.
75			*/
76	aw0a	1
77	johnpye	1031	extern struct Name CreateEnumElementName(symchar s);
78			/**<
79			Create a name node of type set with the subscript s associated with it.
80			*/
81
82			extern struct Name *CreateIntegerElementName(long i);
83			/**<
84			Create a name node of type set with the subscript i associated with it.
85			*/
86
87	johnpye	908	extern struct Name CreateReservedIndexName(symchar reserved);
88			/**<
89			* Make subscript index from the reserved identifier given,
90			* which in most uses will
91			* contain an illegal character for an ascend ID reserving the
92			* set index to internal compiler use only.
93			*/
94
95	jds	54	extern void LinkNames(struct Name cur, struct Name next);
96	johnpye	480	/**<
97	johnpye	194	Link "next" to cur so that NextName(cur) = next
98			*/
99	aw0a	1
100			#ifdef NDEBUG
101			#define NextName(n) ((n)->next)
102			#else
103			#define NextName(n) NextNameF(n)
104			#endif
105	jds	54	/**<
106	johnpye	194	Return the next attribute of n.
107			@param n CONST struct Name*, Name to query.
108			@return The next attribute as a struct Name*.
109			@see NextNameF()
110			*/
111	jds	54	extern struct Name NextNameF(CONST struct Name n);
112			/**<
113	johnpye	480	Return the next attribute of n.
114	johnpye	194	Implementation function for NextName(). Do not call this
115			function directly - use NextName() instead.
116			*/
117	aw0a	1
118			#ifdef NDEBUG
119			#define NameId(n) ((n)->bits & NAMEBIT_IDTY)
120			#else
121			#define NameId(n) NameIdF(n)
122			#endif
123	jds	54	/**<
124	johnpye	908	Test whether a Name element is an identifier.
125	johnpye	194	We should have analogous functions for CHAT and ATTR, but since no
126			clients yet use them, they aren't implemented.
127			@param n CONST struct Name*, Name to query.
128			@return An int: NAMEBIT_IDTY if n is an identifier type Name or 0 otherwise.
129			@see NameIdF()
130
131	johnpye	908	@note This answers for just the first link in the name.
132
133	johnpye	194	*/
134
135	jds	54	extern int NameIdF(CONST struct Name *n);
136	johnpye	480	/**<
137	johnpye	194	Return NAMEBIT_IDTY if n is an identifier type Name or 0 otherwise.
138	johnpye	480	We should have analogous functions for CHAT and ATTR, but since no
139			clients yet use them, they aren't implemented.
140	johnpye	194	Implementation function for NameId(). Do not call this
141			function directly - use NameId() instead.
142			*/
143	aw0a	1
144			#ifdef NDEBUG
145			#define NameAuto(n) ((n)->bits & (NAMEBIT_AUTO\|NAMEBIT_IDTY))
146			#else
147			#define NameAuto(n) NameAutoF(n)
148			#endif
149	jds	54	/**<
150	johnpye	194	Test whether a Name is a system generated identifier.
151			@param n CONST struct Name*, Name to query.
152			@return An int: NAMEBIT_AUTO if n is an system generated identifier
153			type Name, or 0 otherwise.
154			@see NameAutoF()
155			*/
156
157	jds	54	extern int NameAutoF(CONST struct Name *n);
158			/**<
159	johnpye	194	Return NAMEBIT_AUTO if n is an system generated identifier
160	johnpye	480	type Name, or 0 otherwise.
161	johnpye	194	Implementation function for NameAuto(). Do not call this
162			function directly - use NameAuto() instead.
163			*/
164	aw0a	1
165			#ifdef NDEBUG
166			#define NameIdPtr(n) ((n)->val.id)
167			#else
168			#define NameIdPtr(n) NameIdPtrF(n)
169			#endif
170	jds	54	/**<
171	johnpye	194	Returns the id pointer for identifier type name node n.
172			@param n CONST struct Name*, Name to query.
173			@return The id pointer as a symchar*.
174			@see NameIdPtrF()
175			*/
176	jds	54	extern symchar NameIdPtrF(CONST struct Name n);
177	johnpye	480	/**<
178			Assumes that n is a identifier type name node.
179			@return the id pointer.
180	johnpye	194	Implementation function for NameIdPtr(). Do not call this
181			function directly - use NameIdPtr() instead.
182			*/
183	aw0a	1
184	jds	54	extern symchar SimpleNameIdPtr(CONST struct Name n);
185	johnpye	480	/**<
186	johnpye	194	Return NULL if n is not an NameId or if it has a next field. Otherwise,
187			it returns the char pointer.
188			*/
189	aw0a	1
190	jds	54	extern unsigned int NameLength(CONST struct Name *n);
191	johnpye	480	/**<
192			Returns the number of links in a name.
193
194	johnpye	194	@note May be used in a similar manner to SimpleNameIdPtr,
195			to determine if a name is a simple name
196	johnpye	480
197	johnpye	194	@example
198			<tt>my_var</tt> has length 1.
199			<tt>my_var.your_var[1..3]</tt> has length 3.
200			*/
201	aw0a	1
202			#ifdef NDEBUG
203			#define NameSetPtr(n) ((n)->val.s)
204			#else
205			#define NameSetPtr(n) NameSetPtrF(n)
206			#endif
207	jds	54	/**<
208	johnpye	194	Returns the set pointer for set type name node n.
209			@param n CONST struct Name*, Name to query.
210			@return The set pointer as a CONST struct Set*.
211			@see NameSetPtrF()
212			*/
213	jds	54	extern CONST struct Set NameSetPtrF(CONST struct Name n);
214	johnpye	480	/**<
215	johnpye	194	Assumes that n is a set type name node.
216			Returns the set pointer.
217			Implementation function for NameSetPtr(). Do not call this
218			function directly - use NameSetPtr() instead.
219			*/
220	aw0a	1
221	jds	54	extern struct Name CopyName(CONST struct Name n);
222	johnpye	480	/**<
223	johnpye	194	Make and return a copy of the whole name.
224			*/
225	aw0a	1
226	johnpye	1031	extern struct Name CopyAppendNameNode(CONST struct Name n, CONST struct Name *node);
227			/**<
228			Make a copy of n and append a copy of the node (which may be just the
229			head of a longer name). The result is totally disjoint from the inputs.
230			*/
231
232	johnpye	1063	ASC_DLLSPEC void DestroyName(struct Name *n);
233	johnpye	480	/**<
234	johnpye	194	Deallocate the whole name linked list
235			Handles NULL input gracefully.
236			*/
237	aw0a	1
238	jds	54	extern void DestroyNamePtr(struct Name *n);
239	johnpye	480	/**<
240	johnpye	194	Deallocate this name node, and don't change the next node.
241			Handles NULL input gracefully.
242	aw0a	1	*/
243
244	jds	54	extern struct Name JoinNames(struct Name n1, struct Name *n2);
245	johnpye	480	/**<
246	johnpye	194	Appends n2 to the end of n1. This will return n1, unless n1 is NULL in
247			which case it will return n2.
248	aw0a	1	*/
249
250	jds	54	extern struct Name ReverseName(struct Name n);
251	johnpye	480	/**<
252			Returns the reverse of n.
253	johnpye	908	Normally only done to unreverse the order that yacc collects
254			identifiers.
255	johnpye	194	*/
256	aw0a	1
257	jds	54	extern CONST struct Name NextIdName(CONST struct Name n);
258	johnpye	480	/**<
259	johnpye	194	Returns the first NameId element in the name after the current element
260			which is expected to be a NameId. If there is none, returns NULL.
261	aw0a	1	*/
262
263	jds	54	extern int NameCompound(CONST struct Name *n);
264	johnpye	480	/**<
265	johnpye	194	Test whether name is compound (i.e. crosses a MODEL/ATOM boundary).
266	johnpye	480	If so this returns 1, OTHERWISE this returns 0. So array names
267	johnpye	194	will return 0.
268	aw0a	1
269	johnpye	194	The following return 0:
270			- a
271			- a[i]
272			- [i][j] -- though this isn't a proper name, generally.
273
274			The following return 1:
275			- a.b
276			- a[i].b
277			- [i].b
278
279			So basically, if the name is printed with a '.' this will return 1.
280			*/
281
282	jds	54	extern int NamesEqual(CONST struct Name n1, CONST struct Name n2);
283	johnpye	480	/**<
284	johnpye	194	Return TRUE if and only if n1 and n2 are structurally equivalent.
285			*/
286	aw0a	1
287	jds	54	extern int CompareNames(CONST struct Name n1, CONST struct Name n2);
288	johnpye	480	/**<
289	johnpye	194	Returns -1 0 1 as n1 < = > n2.
290			Will need fixing when we have supported attributes.
291			*/
292	aw0a	1
293			extern void name_init_pool(void);
294	johnpye	480	/**<
295	johnpye	194	Starts memory recycle. Do not call twice before stopping recycle.
296			*/
297	aw0a	1
298			extern void name_destroy_pool(void);
299	johnpye	480	/**<
300	johnpye	194	Stops memory recycle. Do not call while ANY names are outstanding.
301			*/
302	aw0a	1
303			extern void name_report_pool(void);
304	johnpye	480	/**<
305	johnpye	194	Write the pool report to ASCERR for the name pool.
306			*/
307	jds	54
308	johnpye	1066	/* @} */
309
310	johnpye	194	#endif /* ASC_NAME_H */