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

Annotation of /trunk/base/generic/compiler/relation_io.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, 1 month ago) by jds
File MIME type: text/x-chdr
File size: 9757 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 * Relation Output Routines
3     * by Tom Epperly
4     * Created: 2/8/90
5     * Version: $Revision: 1.9 $
6     * Version control file: $RCSfile: relation_io.h,v $
7     * Date last modified: $Date: 1998/01/27 11:00:18 $
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     * Relation Output Routines.
31     * <pre>
32 aw0a 1 * When #including relation_io.h, make sure these files are #included first:
33 jds 54 * #include <stdio.h>
34     * #include "utilities/ascConfig.h"
35 aw0a 1 * #include "instance_enum.h"
36     * #include "fractions.h"
37     * #include "compiler.h"
38     * #include "dimen.h"
39     * #include "types.h"
40     * #include "relation_type.h"
41 jds 54 * #include "exprs.h"
42     * #include "relation.h"
43     * </pre>
44 aw0a 1 */
45    
46     #ifndef __RELATION_IO_H_SEEN__
47     #define __RELATION_IO_H_SEEN__
48    
49 jds 54 /**<
50     * This enum controls the format of function names and other
51     * minor operator variations in the supported languages.
52     *
53     * Add others here as desired and then update RelationWriteString.
54     */
55 aw0a 1 enum rel_lang_format {
56     relio_ascend,
57     relio_C
58     };
59    
60     typedef char * (*WRSNameFunc)(CONST struct relation *,unsigned long,void *);
61 jds 54 /**<
62     * <!-- name = func(tokenrel,varnum,userdata); -->
63     * For use with WriteRelationString() and token relations.
64 aw0a 1 * Func should return a name for varnum in tokenrel.
65     * Userdata will be that which the caller of WriteRelationString provides.
66     * We do not keep the name returned or free it -- it is the func's
67     * responsibility to track this memory.
68     */
69    
70     struct RXNameData{
71     char *prefix;
72     int *indices;
73     char *suffix;
74     };
75    
76 jds 54 extern char *RelationVarXName(CONST struct relation *r,
77     unsigned long varnum,
78     struct RXNameData *rxndata);
79     /**<
80     * <!-- ns = RelationVarXName(r,varnum,rxndata); -->
81 aw0a 1 * Returns names like x23.
82     * Returns a character string (which we own, not the caller, but it won't
83 jds 54 * change until we're called again) with the name of the
84 aw0a 1 * the variable in "Prefix%luSuffix" format. prefix and suffix are limited
85     * to 110 characters and are taken from rxndata.
86     * If indices is not NULL, then the number printed will be
87 jds 54 * (unsigned long)indices[varnum] (remember: varnums go from 1 and
88 aw0a 1 * C arrays from 0!) else number printed will be varnum.
89     * If prefix is NULL, "x" will be assumed and suffix will be assumed "".
90     * If prefix is not NULL, suffix must not be NULL.
91 jds 54 * r is ignored entirely.<br><br>
92 aw0a 1 *
93 jds 54 * This function is compatible with WriteRelationString().
94 aw0a 1 */
95    
96 jds 54 extern int NeedParen(enum Expr_enum parent, enum Expr_enum child, int rhs);
97     /**<
98     * <!-- int NeedParen(parent,child,rhs); -->
99     * <!-- enum Expr_enum parent_op; -->
100     * <!-- enum Expr_enum child_op; -->
101     * <!-- int rhs; -->
102 aw0a 1 * Given a unary or binary expression, will determine whether, the
103     * child expression needs parentheses. "rhs" tells if we are looking
104     * at the left or right side of a binary token.
105     * E.g x ^ (2/y), would need parens exactly as shown to give the
106     * correct precedence.
107     * This would be called as : NeedParen(e_power,e_divide,right);
108     * and would return nonzero.
109     */
110    
111 jds 54 extern void WriteRelation(FILE *f,
112     CONST struct Instance *relinst,
113     CONST struct Instance *ref);
114     /**<
115     * <!-- WriteRelation(f,relinst,ref); -->
116     * <!-- FILE *f; -->
117     * <!-- const struct Instance *relinst; -->
118     * <!-- const struct Instance *ref; -->
119 aw0a 1 * Write the relation in infix to the file indicated.
120     * This function comfortably handles all the relation types.
121     * Variables are written with names relative to ref.
122     */
123    
124 jds 54 extern char *WriteRelationString(CONST struct Instance *relinst,
125     CONST struct Instance *ref,
126     WRSNameFunc func,
127     void *userdata,
128     enum rel_lang_format lang,
129     int *lenptr);
130     /**<
131     * <!-- s = WriteRelationString(relinst,ref,func,userdata,lang,lenptr); -->
132     * <!-- char *f; -->
133     * <!-- const struct Instance *relinst; -->
134     * <!-- const struct Instance *ref; -->
135     * <!-- WRSNameFunc func; -->
136     * <!-- void *userdata; -->
137     * <!-- enum rel_lang_format lang; -->
138     * <!-- int *lenptr; -->
139 aw0a 1 * Write the token relation in infix to a char using the
140     * variable names as generated by func.
141     * If func is NULL, name will be written in ascend form
142     * from ref to the variable.
143 jds 54 * This function comfortably handles all the relation types,
144 aw0a 1 * but glassbox and blackbox do not use func or userdata.
145 jds 54 * lenptr contains the length of the string returned, or -1
146 aw0a 1 * if string is NULL. If lenptr is NULL, it is ignored.
147     */
148    
149 jds 54 extern void WriteRelationPostfix(FILE *f,
150     CONST struct Instance *relinst,
151     CONST struct Instance *ref);
152     /**<
153     * <!-- void WriteRelationPostfix(f,relinst,ref) -->
154     * <!-- FILE *f; -->
155     * <!-- const struct Instance *relinst; -->
156     * <!-- const struct Instance *ref; -->
157 aw0a 1 * Write the relation in postfix to the file indicated.
158     * This function at the moment is only applicable to token relations.
159     */
160    
161 jds 54 extern char *WriteRelationPostfixString(CONST struct Instance *relinst,
162     CONST struct Instance *ref);
163     /**<
164     * <!-- void WriteRelationPostfixString(relinst,ref) -->
165     * <!-- char *f; -->
166     * <!-- const struct Instance *relinst; -->
167     * <!-- const struct Instance *ref; -->
168 aw0a 1 * Write the relation in postfix to the file indicated.
169     * This function at the moment is only applicable to token relations.
170     */
171    
172 jds 54 extern void Infix_WriteRelation(FILE *f,
173     CONST struct Instance *r,
174     CONST struct Instance *ref);
175     /**<
176     * <!-- void Infix_WriteRelation(f,r,ref) -->
177     * <!-- FILE *f; -->
178     * <!-- const struct Instance *relinst; -->
179     * <!-- const struct Instance *ref; -->
180 aw0a 1 * Write the relation in infixe to the file indicated.
181     * This function uses the "new" infix representation of relations.
182     * This function at the moment is only applicable to token relations.
183     */
184    
185 jds 54 extern void WriteRelationsInTree(FILE *f, struct Instance *relinst);
186     /**<
187 aw0a 1 * Search for relations in an instance and write them to the
188     * file given in various formats.
189     */
190    
191 jds 54 extern void WriteRelationsInList(FILE *f, struct gl_list_t *l);
192     /**<
193 aw0a 1 * Search for relations in an instance list and write them to the
194     * file given in various formats.
195     */
196    
197     extern void SaveRelationVariables(FILE *fp, CONST struct relation *r);
198 jds 54 /**<
199 aw0a 1 * Given a relation will save its variable list in the ASCEND condensed
200     * format.
201     */
202    
203     extern void SaveGlassBoxRelation(FILE *fp, CONST struct Instance *relinst);
204 jds 54 /**<
205 aw0a 1 * Given a glassbox relation will save it in the ASCEND condensed
206     * format.
207     */
208    
209     extern void SaveTokenRelation(FILE *fp, CONST struct Instance *relinst);
210 jds 54 /**<
211 aw0a 1 * Given a token relation will save it in the ASCEND condensed
212     * format.
213     */
214    
215 jds 54 extern void SaveReln2GlassBox(FILE *fp,
216     CONST struct Instance *relinst,
217     char *prefix,
218     unsigned long index_);
219     /**<
220 aw0a 1 * Given a relation will save it and perform conversion to the glassbox
221     * format.
222     */
223    
224 jds 54 extern int ConversionIsValid(enum Expr_enum old, enum Expr_enum new);
225     /**<
226     * Given a relation format will return TRUE if conversion to another
227 aw0a 1 * format is valid. It assumes that new is a valid relation type.
228     */
229    
230     extern void RelationIO_init_pool(void);
231 jds 54 /**<
232     * starts memory recycle. Do not call twice before stopping recycle.
233 aw0a 1 */
234    
235     extern void RelationIO_destroy_pool(void);
236 jds 54 /**<
237     * Stops memory recycle. Do not call while ANY Expr are outstanding.
238 aw0a 1 */
239    
240     extern void RelationIO_report_pool(void);
241 jds 54 /**<
242     * Write the pool report to ASCERR for the ppe pool.
243 aw0a 1 */
244    
245 jds 54 #endif /* __RELATION_IO_H_SEEN__ */
246 aw0a 1

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