/[ascend]/trunk/base/generic/compiler/proc.h
ViewVC logotype

Annotation of /trunk/base/generic/compiler/proc.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 54 - (hide annotations) (download) (as text)
Tue Aug 2 11:20:09 2005 UTC (14 years, 5 months ago) by jds
File MIME type: text/x-chdr
File size: 10625 byte(s)
Manual rework of doxygen comments in all headers.
- Added @file comment to all headers.
- Added parameter names to all function declarations in headers.
- Corrected comment referencing where necessary.
- Split some comments which documented blocks of declarations.
- Converted notes about required work into @todo comments so doxygen can generate a todo list.
Minor bug fixes.
1 jds 54 /*
2 aw0a 1 * Procedure Data Structure
3     * by Tom Epperly
4     * Created: 1/10/90
5     * Version: $Revision: 1.13 $
6     * Version control file: $RCSfile: proc.h,v $
7     * Date last modified: $Date: 1998/04/11 01:31:54 $
8     * Last modified by: $Author: ballan $
9     *
10     * This file is part of the Ascend Language Interpreter.
11     *
12     * Copyright (C) 1990, 1993, 1994 Thomas Guthrie Epperly
13     *
14     * The Ascend Language Interpreter is free software; you can redistribute
15     * it and/or modify it under the terms of the GNU General Public License as
16     * published by the Free Software Foundation; either version 2 of the
17     * License, or (at your option) any later version.
18     *
19     * The Ascend Language Interpreter is distributed in hope that it will be
20     * useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
21     * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
22     * General Public License for more details.
23     *
24     * You should have received a copy of the GNU General Public License along
25     * with the program; if not, write to the Free Software Foundation, Inc., 675
26     * Mass Ave, Cambridge, MA 02139 USA. Check the file named COPYING.
27     */
28    
29 jds 54 /** @file
30     * Procedure Data Structure.
31     * <pre>
32 aw0a 1 * When #including proc.h, make sure these files are #included first:
33 jds 54 * #include "utilities/ascConfig.h"
34 aw0a 1 * #include "compiler.h"
35 jds 54 * #include"list.h"
36     * #include"slist.h"
37     * </pre>
38 aw0a 1 */
39    
40     #ifndef __PROC_H_SEEN__
41     #define __PROC_H_SEEN__
42    
43     struct InitProcedure {
44 jds 54 symchar *name; /**< procedure's name */
45     struct StatementList *slist; /**< statement list */
46     long int parse_id; /**< parse id of type desc with which this is defined
47     0 if method is not yet associated */
48 aw0a 1 };
49    
50 jds 54 extern struct InitProcedure *CreateProcedure(symchar *name,
51     struct StatementList *stats);
52     /**<
53     * <!-- struct InitProcedure *CreateProcedure(name,stats) -->
54     * <!-- symchar *name; -->
55     * <!-- struct StatementList *stats; -->
56 aw0a 1 * Create a procedure data structure with name and stats.
57     */
58    
59 jds 54 extern struct InitProcedure *CopyProcedure(struct InitProcedure *p);
60     /**<
61     * <!-- struct InitProcedure *CopyProcedure(p) -->
62     * <!-- struct InitProcedure *p; -->
63 aw0a 1 * Make a copy of procedure p, but this copy should not be modified.
64     * If you want to change the structure, use CopyProcToModify. Use
65     * DestroyProcedure when you are done with it.
66     */
67    
68 jds 54 extern struct InitProcedure *CopyProcToModify(struct InitProcedure *p);
69     /**<
70     * <!-- struct InitProcedure *CopyProcToModify(p) -->
71     * <!-- struct InitProcedure *p; -->
72 aw0a 1 * Make a copy, but this copy can be changed.
73     */
74    
75 jds 54 extern struct gl_list_t *MergeProcedureLists(struct gl_list_t *old,
76     struct gl_list_t *new);
77     /**<
78     * <!-- plr = MergeProcedureLists(old,new); -->
79     * <!-- struct gl_list_t *plr, *old, *new; -->
80 aw0a 1 * Merges the lists of (struct InitProcedure *) given into a third list,
81     * plr.
82     * new, if it exists, is destroyed because we move the contents to plr.
83     * old is assumed to belong to someone else and is left alone.
84 jds 54 * old or new may be NULL.
85     * The result is sorted with CmpProcs.<br><br>
86 aw0a 1 *
87 jds 54 * This is where method inheritance rules occur. We keep all the
88     * methods from the new in result, then we search for any method in
89     * the old list which does not have an identically named
90     * counterpart in the result list and add it to the result.
91     * Methods in the old result which have be redefined in the new
92     * list given are thereby ignored and overridden.
93 aw0a 1 */
94    
95     extern struct gl_list_t *GetUniversalProcedureList(void);
96 jds 54 /**<
97 aw0a 1 * Returns the list of methods defined for all MODELs
98     * unless they redefine the methods themselves.
99     */
100    
101 jds 54 extern void SetUniversalProcedureList(struct gl_list_t *l);
102 ben.allan 33 /**<
103 aw0a 1 * Sets the list of procedures defined for all MODELs.
104     * If a UPL already exists, it will be destroyed unless it
105     * is the same. If the same, it is resorted.
106     */
107    
108 jds 54 extern void DestroyProcedure(struct InitProcedure *p);
109 ben.allan 33 /**<
110 jds 54 * <!-- void DestroyProcedure(p) -->
111     * <!-- struct InitProcedure *p; -->
112 aw0a 1 * Destroy this reference to p. This won't necessary destroy all the parts
113     * of p.
114     */
115    
116 jds 54 extern void DestroyProcedureList(struct gl_list_t *pl);
117 ben.allan 33 /**<
118 jds 54 * <!-- void DestroyProcedureList(pl) -->
119     * <!-- struct gl_list_t *pl contain pointers to -->
120     * <!-- struct InitProcedure *p -->
121 aw0a 1 * Destroy this reference to p. This won't necessary destroy all the parts
122     * of each p unless the parts have no other references. The gl_list is
123     * destroyed as are all the p in it.
124     * Handles NULL input gracefully.
125     */
126    
127 jds 54 extern int CompareProcedureLists(struct gl_list_t *pl1,
128     struct gl_list_t *pl2 ,
129     unsigned long int *n);
130     /**<
131     * <!-- CompareProcedureLists(pl1,pl2,&n) -->
132     * <!-- struct gl_list_t *pl1, *pl2 contain pointers to -->
133     * <!-- struct InitProcedure *p. -->
134     * <!-- unsigned long n; -->
135 aw0a 1 * Returns 0 if pl1,pl2 semantically equivalent, 1 if not.
136     * If return is 1, n contains the index of the first different
137     * procedure.
138 jds 54 */
139 aw0a 1
140     #ifdef NDEBUG
141     #define ProcName(p) ((p)->name)
142     #else
143     #define ProcName(p) ProcNameF(p)
144     #endif
145 jds 54 /**<
146 aw0a 1 * Return the name part of a procedure structure.
147 jds 54 * @param p CONST struct InitProcedure*, procedure to query.
148     * @return name as a symchar*.
149     * @see ProcNameF()
150 aw0a 1 */
151 jds 54 extern symchar *ProcNameF(CONST struct InitProcedure *p);
152     /**<
153     * <!-- macro ProcName(p) -->
154     * <!-- symchar *ProcNameF(p) -->
155     * <!-- const struct InitProcedure *p; -->
156     * <!-- Return the name part of a procedure structure. -->
157     * Implementation function for ProcName(). Do not call this
158     * function directly - use ProcName() instead.
159     */
160 aw0a 1
161     #ifdef NDEBUG
162     #define ProcStatementList(p) ((p)->slist)
163     #else
164     #define ProcStatementList(p) ProcStatementListF(p)
165     #endif
166 jds 54 /**<
167 aw0a 1 * Return the statement list part of the procedure structure.
168 jds 54 * @param p CONST struct InitProcedure*, procedure to query.
169     * @return Statement list as a struct StatementList*.
170     * @see ProcStatementListF()
171 aw0a 1 */
172 jds 54 extern struct StatementList *ProcStatementListF(CONST struct InitProcedure *p);
173     /**<
174     * <!-- struct StatementList *ProcStatementListF(p) -->
175     * <!-- const struct InitProcedure *p; -->
176     * <!-- Return the statement list part of the procedure structure. -->
177     * Implementation function for ProcStatementList(). Do not call this
178     * function directly - use ProcStatementList() instead.
179     */
180 aw0a 1
181     #ifdef NDEBUG
182     #define GetProcParseId(p) ((p)->parse_id)
183     #else
184     #define GetProcParseId(p) GetProcParseIdF(p)
185     #endif
186 jds 54 /**<
187     * Return the parse id of the type which originally defined this
188 aw0a 1 * procedure. This may be a copy of that procedure and not the
189     * original, but this is of no significance.
190 jds 54 * @param p CONST struct InitProcedure*, procedure to query.
191     * @return Id as a long.
192     * @see GetProcParseIdF()
193 aw0a 1 */
194 jds 54 extern long GetProcParseIdF(CONST struct InitProcedure *p);
195     /**<
196     * <!-- id = GetProcParseIdF(p); -->
197     * <!-- const struct InitProcedure *p; -->
198     * <!-- long id; -->
199     * <!-- Return the parse id of the type which originally defined this-->
200     * <!-- procedure. This may be a copy of that procedure and not the -->
201     * <!-- original, but this is of no significance. -->
202     * Implementation function for GetProcParseId(). Do not call this
203     * function directly - use GetProcParseId() instead.
204     */
205 aw0a 1
206     #ifdef NDEBUG
207     #define SetProcParseId(p,id) ((p)->parse_id = (id))
208     #else
209     #define SetProcParseId(p,id) SetProcParseIdF((p),(id))
210     #endif
211 jds 54 /**<
212 aw0a 1 * Sets the parse id of the procedure. The wisdom of this move
213     * is not investigated. The rules should be:
214     * Procs normally get id's at the type desc creation step once
215     * parseid is known. When a proc is inherited (by copy) the copy
216     * retains the id of the original. If a method is added after the
217     * type's creation, it should get that types id. If a method is replaced
218     * in a type, all the refiners of that type which contain an
219     * inherited copy of the method also get replaced and this id
220     * helps us figure out which method was inherited efficiently.
221 jds 54 * @param p CONST struct InitProcedure*, procedure to query.
222     * @param id long, new parse id.
223     * @return No return value.
224     * @see SetProcParseIdF()
225 aw0a 1 */
226 jds 54 extern void SetProcParseIdF(struct InitProcedure *p, long id);
227     /**<
228     * <!-- SetProcParseIdF(p,id); -->
229     * <!-- const struct InitProcedure *p; -->
230     * <!-- long id. -->
231     * <!-- Sets the parse id of the procedure. The wisdom of this move -->
232     * <!-- is not investigated. The rules should be: -->
233     * <!-- Procs normally get id's at the type desc creation step once -->
234     * <!-- parseid is known. When a proc is inherited (by copy) the copy -->
235     * <!-- retains the id of the original. If a method is added after the -->
236     * <!-- type's creation, it should get that types id. If a method is replaced -->
237     * <!-- in a type, all the refiners of that type which contain an -->
238     * <!-- inherited copy of the method also get replaced and this id -->
239     * <!-- helps us figure out which method was inherited efficiently. -->
240     * Implementation function for SetProcParseId(). Do not call this
241     * function directly - use SetProcParseId() instead.
242     */
243 aw0a 1
244 jds 54 extern int CmpProcs(CONST struct InitProcedure *p1, CONST struct InitProcedure *p2);
245     /**<
246     * <!-- int CmpProcs(p1,p2) -->
247     * <!-- const struct InitProcedure *p1,*p2; -->
248 aw0a 1 * Compare the two procedures to provide an ordering for them.
249     * Simply alphabetizing.
250     */
251 jds 54
252     #endif /* __PROC_H_SEEN__ */
253    

john.pye@anu.edu.au
ViewVC Help
Powered by ViewVC 1.1.22