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 [or seems to JP to be] a linked list of symchars, integers
    or so on that gives the complete global context for a variable or
    a relation. So if you have something's name, it tells you how to
    find it in the instance hierarchy. Is that right?

    Actually I'm not sure if linked-up Names actually make discrete lists
    or maybe form a tree structure?

    @TODO Clarify what is a name of type 'set'.
    @TODO These things need to be pooled to save space and time. baa 3/96

    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

#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 *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.
*/

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