generic/compiler/parentchild.h

/*  ASCEND modelling environment
    Copyright (C) 2006 Carnegie Mellon University
    Copyright (C) 1996 Ben Allan
    Copyright (C) 1990, 1993, 1994 Thomas Guthrie Epperly

    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 Instance Tree Link Implementation.

    General comments on parents:

      - Parents are numbered from 1 up, so zero is never a valid
        parent number

      - Parent lists are kept sorted by address.

      - The ordering of the parents list is not predictable in
        any usefull way.

      - The number of parents for a given instance can be modified
        by ARE_THE_SAME's.

      - The number of parents is NOT constant for a given type.

      - Parent lists will contain no duplications.
        (when AddParent is used correctly, that is.)

      - DummyInstances don't track parents -- they play a reference
        count game.

    General comments on children:

      - Children are number from 1 up, so zero is never a valid child
        number.

      - Children numbers will remain constant for a given type except
        for arrays which can have varying numbers of children.

      - Children numbers may or may not change will an instance is
        refined.

      - Children are always sorted in increasing order either
        alphabetically or numerically depending on the type of
        naming.

      - Children don't know what their name is.  Only a parent
        knows the names of the children below it.

      - DummyInstances have no children.

    based on instance.c

    Requires:
    #include "utilities/ascConfig.h"
    #include "instance_enum.h"
    #include "compiler.h"
*//*
    by Tom Epperly 8/16/89, Ben Allan
    Version: $Revision: 1.11 $
    Version control file: $RCSfile: parentchild.h,v $
    Date last modified: $Date: 1998/02/05 16:37:24 $
    Last modified by: $Author: ballan $
*/

#ifndef ASC_PARENTCHILD_H
#define ASC_PARENTCHILD_H

/** addtogroup compiler Compiler
    @{
*/

#include <utilities/ascConfig.h>
#include <compiler/compiler.h>
#include <compiler/instance_enum.h>
#include <compiler/instance_name.h>

/* Parent routines */

ASC_DLLSPEC unsigned long NumberParents(CONST struct Instance *i);
/**<
 *  Return the number of parents that instance i has.
 *  DummyInstances have no parents, apparently.
 */

ASC_DLLSPEC struct Instance *InstanceParent(CONST struct Instance *i, unsigned long n);
/**<
 *  Return a pointer to parent number n.  Parents are numbered from
 *  1 to NumberParents(i).  0(zero) is not a valid parent number.
 *  DummyInstances have no parents, apparently.
 */

extern unsigned long SearchForParent(CONST struct Instance *i,
                                     CONST struct Instance *p);
/**<
 *  Look in instance "i"'s parent list for parent "p".  If "p" is not
 *  found, it will return 0; otherwise, it will return the parent number of
 *  "p" in instance "i"'s parent list.
 *  DummyInstance never has parents, it thinks.
 */

extern void DeleteParent(struct Instance *i, unsigned long pos);
/**<
 *  Remove parent in pos from i's parent list.
 *  DummyInstance just reduces its reference count.
 */

ASC_DLLSPEC struct InstanceName ParentsName(CONST struct Instance *p,
                                       CONST struct Instance *c);
/**<
 *  This will returns parent "p"'s name for "c".  This assumes that
 *  "c" is actually a child of "p", and it will return a bad value if
 *  "c" is not a child of "p".  Note this is actually a combination of
 *  ChildIndex and ChildName defined below.  It is defined separately
 *  because it will be call alot.  This is not a fast routine taking time
 *  proportional to the number of children p has.
 *  DummyInstance may have several names and which you get is arbitrary
 *  because you aren't supposed to care about dummy instances.
 */

extern void AddParent(struct Instance *i, struct Instance *p);
/**<
 *  This will add parent "p" to instance "i"'s parent list.  This only
 *  creates the link from "i" to "p"; it doesn't create the link from
 *  "p" to "i" which must be done with the routines below.
 *  This doesn't <-*****
 *  check if p is already a parent of "i"; you should know that it isn't
 *  before calling this.
 *  Exception:
 *  Every reference to DummyInstance should call this, and since
 *  SearchForParent will always say that p is not a parent of dummy,
 *  things work out ok.
 */

/* Children routines */

ASC_DLLSPEC unsigned long NumberChildren(CONST struct Instance *i);
/**<
 *  Return the number of children that instance i has.
 */


ASC_DLLSPEC struct Instance*InstanceChild(CONST struct Instance *i,
                                      unsigned long n);
/**<
 *  Return a pointer to children number n.  Do not confuse the child number
 *  n with an integer index.  The two numbers may have no correlation.
 *  Child number range from 1 to NumberChildren(i).  0(zero) is not a valid
 *  child number.
 *  May exit on improper i.
 */

ASC_DLLSPEC struct InstanceName ChildName(CONST struct Instance *i, unsigned long n);
/**<
 *  Returns the name of the n'th child of i.  Assumes that i has an
 *  n'th child.
 */

ASC_DLLSPEC CONST struct Statement *ChildDeclaration(CONST struct Instance *i,
                                                unsigned long n);
/**<
 *  Returns the declaration statement (IS_A,ALIASE,ARRAY) of the n'th child
 *  of i, if i has an n'th child. May return NULL under very odd circumstances.
 *  Does not return redeclarations (refinement) statements.
 *  i must not be NULL! The nth child may be NULL, but we don't care.
 *  (Note that as of 2/97 this function cannot return NULL because
 *  the ascend language is basetype safe semantically.)
 */

extern CONST struct TypeDescription *ChildRefines(CONST struct Instance *i,
                                                  unsigned long n);
/**<
 *  Returns the type of the n'th child of i as determined at parse time.
 *  The nth child of the instance i doesn't need to exist yet. (may be null)
 *  The nth child of the instance will be of at least this type if the
 *  child is not an array.
 *  If the child is an array, the type returned here
 *  will be the type of the array elements as determined at parse time.
 *  This function may return NULL -- this merely means that at parse
 *  time we couldn't quite untwist the naming to determine a type.<br><br>
 *
 *  Warning: Unselected parts will yield instances of type DUMMYINST
 *  instead of whatever type this returns.
 */

ASC_DLLSPEC unsigned long ChildSearch(CONST struct Instance *i,
                                 CONST struct InstanceName *name);
/**<
 *  This procedure will search instance i for a child that matches "name".
 *  It it is unsuccessful, it will return 0; otherwise, it will return the
 *  index of the child that matches.  It is assumed that all children have
 *  unique names and that there is no need to worry about more than one child
 *  matching "name".  This can be called on childless instance without
 *  error. The strings in the InstanceName must come from the symbol table.
 */

ASC_DLLSPEC struct Instance*ChildByChar(CONST struct Instance *i,
                                    symchar *str);
/**<
 *  This returns to the pointer to a child, c, of parent,p, named by str.
 *  str must be a simple name. If child not found, returns NULL.
 *  str must be from the symbol table. If AscFindSymbol(str)==NULL,
 *  then this function should not be called because NO instance
 *  can have a child with a name which is not in the symbol table.
 */

/*
 *  extern unsigned long ChildSearchRegExp(); NOT IMPLEMENTED.
 *  unsigned long ChildSearchRegExp(i,name,start)
 *  struct Instance *i;
 *  char *name;
 *  unsigned long start;
 *
 *  This is an unplanned extension to the initial implementation to add regular
 *  expression searches.  The function will search from child number "start"
 *  to the first match.  If no match is found, it will return 0; otherwise
 *  it will return the first match of the regular expression.  Examples of
 *  regular expressions are:
 *  f*  which means all strings starting with the letter f
 *  f?  which means all two character long strings starting with
 *  f
 */

ASC_DLLSPEC unsigned long ChildIndex(CONST struct Instance *i,
                                CONST struct Instance *child);
/**<
 *  This procedure searches through the child list of instance i for child.
 *  If it does not find a match, it returns 0; otherwise, it will return
 *  the child number of "child".
 */

extern void StoreChildPtr(struct Instance *i,
                          unsigned long n,
                          struct Instance *child);
/**<
 *  Store the child pointer "child" in position n of i.  This only creates
 *  the link from i to child, and not the back link which is created by
 *  add parent.  Instance "i" cannot be a fundamental atom; atoms are
 *  created in a special way.
 */

/* @} */

#endif  /* ASC_PARENTCHILD_H */
1	johnpye	485	/* ASCEND modelling environment
2	johnpye	952	Copyright (C) 2006 Carnegie Mellon University
3	johnpye	485	Copyright (C) 1996 Ben Allan
4			Copyright (C) 1990, 1993, 1994 Thomas Guthrie Epperly
5	aw0a	1
6	johnpye	485	This program is free software; you can redistribute it and/or modify
7			it under the terms of the GNU General Public License as published by
8			the Free Software Foundation; either version 2, or (at your option)
9			any later version.
10	aw0a	1
11	johnpye	485	This program is distributed in the hope that it will be useful,
12			but WITHOUT ANY WARRANTY; without even the implied warranty of
13			MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14			GNU General Public License for more details.
15
16			You should have received a copy of the GNU General Public License
17			along with this program; if not, write to the Free Software
18			Foundation, Inc., 59 Temple Place - Suite 330,
19			Boston, MA 02111-1307, USA.
20			//*
21			@file
22			Ascend Instance Tree Link Implementation.
23
24			General comments on parents:
25
26			- Parents are numbered from 1 up, so zero is never a valid
27			parent number
28
29			- Parent lists are kept sorted by address.
30
31			- The ordering of the parents list is not predictable in
32			any usefull way.
33
34			- The number of parents for a given instance can be modified
35			by ARE_THE_SAME's.
36
37			- The number of parents is NOT constant for a given type.
38
39			- Parent lists will contain no duplications.
40			(when AddParent is used correctly, that is.)
41
42			- DummyInstances don't track parents -- they play a reference
43			count game.
44
45			General comments on children:
46
47			- Children are number from 1 up, so zero is never a valid child
48			number.
49
50			- Children numbers will remain constant for a given type except
51			for arrays which can have varying numbers of children.
52
53			- Children numbers may or may not change will an instance is
54			refined.
55
56			- Children are always sorted in increasing order either
57			alphabetically or numerically depending on the type of
58			naming.
59
60			- Children don't know what their name is. Only a parent
61			knows the names of the children below it.
62
63			- DummyInstances have no children.
64
65			based on instance.c
66
67			Requires:
68			#include "utilities/ascConfig.h"
69			#include "instance_enum.h"
70			#include "compiler.h"
71			//
72	johnpye	952	by Tom Epperly 8/16/89, Ben Allan
73	johnpye	485	Version: $Revision: 1.11 $
74			Version control file: $RCSfile: parentchild.h,v $
75			Date last modified: $Date: 1998/02/05 16:37:24 $
76			Last modified by: $Author: ballan $
77			*/
78
79	johnpye	67	#ifndef ASC_PARENTCHILD_H
80			#define ASC_PARENTCHILD_H
81	jds	54
82	johnpye	1066	/** addtogroup compiler Compiler
83			@{
84			*/
85
86	johnpye	485	#include <utilities/ascConfig.h>
87	johnpye	502	#include <compiler/compiler.h>
88	johnpye	811	#include <compiler/instance_enum.h>
89	johnpye	502	#include <compiler/instance_name.h>
90	johnpye	485
91	jds	54	/* Parent routines */
92
93	johnpye	1063	ASC_DLLSPEC unsigned long NumberParents(CONST struct Instance *i);
94	jds	54	/**<
95	aw0a	1	* Return the number of parents that instance i has.
96			* DummyInstances have no parents, apparently.
97			*/
98
99	johnpye	1063	ASC_DLLSPEC struct Instance InstanceParent(CONST struct Instance i, unsigned long n);
100	jds	54	/**<
101	aw0a	1	* Return a pointer to parent number n. Parents are numbered from
102			* 1 to NumberParents(i). 0(zero) is not a valid parent number.
103			* DummyInstances have no parents, apparently.
104			*/
105
106	jds	54	extern unsigned long SearchForParent(CONST struct Instance *i,
107			CONST struct Instance *p);
108			/**<
109	aw0a	1	* Look in instance "i"'s parent list for parent "p". If "p" is not
110			* found, it will return 0; otherwise, it will return the parent number of
111			* "p" in instance "i"'s parent list.
112			* DummyInstance never has parents, it thinks.
113			*/
114
115	jds	54	extern void DeleteParent(struct Instance *i, unsigned long pos);
116			/**<
117	aw0a	1	* Remove parent in pos from i's parent list.
118			* DummyInstance just reduces its reference count.
119			*/
120
121	johnpye	1063	ASC_DLLSPEC struct InstanceName ParentsName(CONST struct Instance *p,
122	jds	54	CONST struct Instance *c);
123			/**<
124	aw0a	1	* This will returns parent "p"'s name for "c". This assumes that
125			* "c" is actually a child of "p", and it will return a bad value if
126			* "c" is not a child of "p". Note this is actually a combination of
127			* ChildIndex and ChildName defined below. It is defined separately
128			* because it will be call alot. This is not a fast routine taking time
129			* proportional to the number of children p has.
130			* DummyInstance may have several names and which you get is arbitrary
131			* because you aren't supposed to care about dummy instances.
132			*/
133
134	jds	54	extern void AddParent(struct Instance i, struct Instance p);
135			/**<
136	aw0a	1	* This will add parent "p" to instance "i"'s parent list. This only
137			* creates the link from "i" to "p"; it doesn't create the link from
138			* "p" to "i" which must be done with the routines below.
139			* This doesn't <-*****
140			* check if p is already a parent of "i"; you should know that it isn't
141			* before calling this.
142			* Exception:
143			* Every reference to DummyInstance should call this, and since
144			* SearchForParent will always say that p is not a parent of dummy,
145			* things work out ok.
146			*/
147
148	jds	54	/* Children routines */
149	aw0a	1
150	johnpye	1063	ASC_DLLSPEC unsigned long NumberChildren(CONST struct Instance *i);
151	jds	54	/**<
152	aw0a	1	* Return the number of children that instance i has.
153			*/
154
155
156	johnpye	1063	ASC_DLLSPEC struct InstanceInstanceChild(CONST struct Instance i,
157	jds	54	unsigned long n);
158			/**<
159	aw0a	1	* Return a pointer to children number n. Do not confuse the child number
160			* n with an integer index. The two numbers may have no correlation.
161			* Child number range from 1 to NumberChildren(i). 0(zero) is not a valid
162			* child number.
163			* May exit on improper i.
164			*/
165
166	johnpye	1063	ASC_DLLSPEC struct InstanceName ChildName(CONST struct Instance *i, unsigned long n);
167	jds	54	/**<
168	aw0a	1	* Returns the name of the n'th child of i. Assumes that i has an
169			* n'th child.
170			*/
171
172	johnpye	1063	ASC_DLLSPEC CONST struct Statement ChildDeclaration(CONST struct Instance i,
173	jds	54	unsigned long n);
174			/**<
175	aw0a	1	* Returns the declaration statement (IS_A,ALIASE,ARRAY) of the n'th child
176			* of i, if i has an n'th child. May return NULL under very odd circumstances.
177			* Does not return redeclarations (refinement) statements.
178	jds	54	* i must not be NULL! The nth child may be NULL, but we don't care.
179	aw0a	1	* (Note that as of 2/97 this function cannot return NULL because
180	jds	54	* the ascend language is basetype safe semantically.)
181	aw0a	1	*/
182
183	jds	54	extern CONST struct TypeDescription ChildRefines(CONST struct Instance i,
184			unsigned long n);
185			/**<
186	aw0a	1	* Returns the type of the n'th child of i as determined at parse time.
187			* The nth child of the instance i doesn't need to exist yet. (may be null)
188			* The nth child of the instance will be of at least this type if the
189			* child is not an array.
190			* If the child is an array, the type returned here
191			* will be the type of the array elements as determined at parse time.
192			* This function may return NULL -- this merely means that at parse
193	jds	54	* time we couldn't quite untwist the naming to determine a type.<br><br>
194	aw0a	1	*
195			* Warning: Unselected parts will yield instances of type DUMMYINST
196			* instead of whatever type this returns.
197			*/
198
199	johnpye	1063	ASC_DLLSPEC unsigned long ChildSearch(CONST struct Instance *i,
200	jds	54	CONST struct InstanceName *name);
201			/**<
202	aw0a	1	* This procedure will search instance i for a child that matches "name".
203			* It it is unsuccessful, it will return 0; otherwise, it will return the
204			* index of the child that matches. It is assumed that all children have
205			* unique names and that there is no need to worry about more than one child
206			* matching "name". This can be called on childless instance without
207			* error. The strings in the InstanceName must come from the symbol table.
208			*/
209
210	johnpye	1063	ASC_DLLSPEC struct InstanceChildByChar(CONST struct Instance i,
211	jds	54	symchar *str);
212			/**<
213	aw0a	1	* This returns to the pointer to a child, c, of parent,p, named by str.
214			* str must be a simple name. If child not found, returns NULL.
215			* str must be from the symbol table. If AscFindSymbol(str)==NULL,
216			* then this function should not be called because NO instance
217			* can have a child with a name which is not in the symbol table.
218			*/
219
220	jds	54	/*
221	aw0a	1	* extern unsigned long ChildSearchRegExp(); NOT IMPLEMENTED.
222			* unsigned long ChildSearchRegExp(i,name,start)
223			* struct Instance *i;
224			* char *name;
225			* unsigned long start;
226			*
227			* This is an unplanned extension to the initial implementation to add regular
228			* expression searches. The function will search from child number "start"
229			* to the first match. If no match is found, it will return 0; otherwise
230			* it will return the first match of the regular expression. Examples of
231			* regular expressions are:
232			* f* which means all strings starting with the letter f
233			* f? which means all two character long strings starting with
234			* f
235			*/
236
237	johnpye	1063	ASC_DLLSPEC unsigned long ChildIndex(CONST struct Instance *i,
238	jds	54	CONST struct Instance *child);
239			/**<
240	aw0a	1	* This procedure searches through the child list of instance i for child.
241			* If it does not find a match, it returns 0; otherwise, it will return
242			* the child number of "child".
243			*/
244
245	jds	54	extern void StoreChildPtr(struct Instance *i,
246			unsigned long n,
247			struct Instance *child);
248			/**<
249	aw0a	1	* Store the child pointer "child" in position n of i. This only creates
250			* the link from i to child, and not the back link which is created by
251			* add parent. Instance "i" cannot be a fundamental atom; atoms are
252			* created in a special way.
253			*/
254
255	johnpye	1066	/* @} */
256
257	johnpye	67	#endif /* ASC_PARENTCHILD_H */