generic/compiler/evaluate.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
    Expression Evaluation Routine

    Requires:
    #include "utilities/ascConfig.h"
    #include "list.h"
    #include "fractions.h"
    #include "compiler.h"
    #include "dimen.h"
    #include "expr_types.h"
*//*
    by Tom Epperly
    Created: 1/16/90
    Last in CVS: $Revision: 1.10 $ $Date: 1997/07/18 12:29:08 $ $Author: mthomas $
*/

#ifndef ASC_EVALUATE_H
#define ASC_EVALUATE_H

/** addtogroup compiler Compiler
    @{
*/

extern struct value_t EvaluateSet(CONST struct Set *sptr,
                                  struct value_t (*EvaluateName)());
/**<
 *  Return the value of a Set structure, which just might be a set.
 */

extern struct value_t EvaluateExpr(CONST struct Expr *expr,
                                   CONST struct Expr *stop,
                                   struct value_t (*EvaluateName)());
/**<
 *  Return the value of a name structure.
 *  In most cases stop = NULL.  stop can be used to evaluate just part of
 *  an expression.  If (stop!=NULL) the calling program, must know the
 *  the stack is correctly balanced.
 */

extern struct gl_list_t *EvaluateNamesNeeded(CONST struct Expr *expr,
                                             CONST struct Expr *stop,
                                             struct gl_list_t *list);
/**<
 *  (Analogous to EvaluateExpr, but the global EvaluatingSets is irrelevant).
 *
 *  Appends all the externally defined names found in expr to list.
 *  (Loop variables defined in the expression are ignored.)
 *  If expr is not well formed wrt loops, you may get odd results back.
 *  If the list passed in is NULL, creates a list first.
 *  The list returned may be empty, but should not be NULL.
 *  When e_var are encountered in the expression, DOES dissect the
 *  subscripts separately.<br><br>
 *
 *  Doesn't actually evaluate anything, so EvaluateName function
 *  is not required. The list will be the set of names you must have
 *  values for in order for the expression to have a chance of
 *  evaluating to a result, including for loop variables, but not
 *  dummy indices defined in the expression.
 *  No duplicate names will be added to the list, but if you send in
 *  a list with duplication already in it, we will not clean it up for you.
 */

extern struct gl_list_t *EvaluateNamesNeededShallow(CONST struct Expr *expr,
                                                    CONST struct Expr *stop,
                                                    struct gl_list_t *list);
/**<
 *  (Analogous to EvaluateExpr, but the global EvaluatingSets is irrelevant).
 *
 *  Appends all the externally defined names found in expr to list.
 *  (Loop variables defined in the expression are ignored.)
 *  If e is not well formed wrt loops, you may get odd results back.
 *  If the list passed in is NULL, creates a list first.
 *  The list returned may be empty, but should not be NULL.
 *  When e_var are encountered in the expression, DOES NOT dissect the
 *  subscripts separately.<br><br>
 *
 *  Doesn't actually evaluate anything, so no EvaluateName function
 *  is not required. The list will be the set of names you must have
 *  values for in order for the expression to have a chance of
 *  evaluating to a result, including for loop variables, but not
 *  dummy indices defined in the expression.
 *  No duplicate names will be added to the list, but if you send in
 *  a list with duplication already in it, we will not clean it up for you.
 */

extern struct gl_list_t
*EvaluateSetNamesNeeded(CONST struct Set *sptr, struct gl_list_t *list);
/**<
 *  (Analogous to EvaluateExpr, but the global EvaluatingSets is irrelevant).
 *
 *  Appends all the externally defined names found in sptr to list.
 *  (Loop variables defined in the expression are ignored.)
 *  If sptr  is not well formed wrt loops, you may get odd results back.
 *  If the list passed in is NULL, creates a list first.
 *  The list returned may be empty, but should not be NULL.
 *  DOES investigate subscripts deeply for needed names.<br><br>
 *
 *  Doesn't actually evaluate anything, so no EvaluateName function
 *  is not required. The list will be the set of names you must have
 *  values for in order for the set to have a chance of
 *  evaluating to a result, including for loop variables, but not
 *  dummy indices defined in the expression.
 *  No duplicate names will be added to the list, but if you send in
 *  a list with duplication already in it, we will not clean it up for you.
 */

extern struct gl_list_t
*EvaluateSetNamesNeededShallow(CONST struct Set *sptr, struct gl_list_t *list);
/**<
 *  (Analogous to EvaluateExpr, but the global EvaluatingSets is irrelevant).
 *
 *  Appends all the externally defined names found in sptr to list.
 *  (Loop variables defined in the expression are ignored.)
 *  If sptr  is not well formed wrt loops, you may get odd results back.
 *  If the list passed in is NULL, creates a list first.
 *  The list returned may be empty, but should not be NULL.
 *  DOES NOT investigate subscripts deeply for needed names.<br><br>
 *
 *  Doesn't actually evaluate anything, so no EvaluateName function
 *  is not required. The list will be the set of names you must have
 *  values for in order for the set to have a chance of
 *  evaluating to a result, including for loop variables, but not
 *  dummy indices defined in the expression.
 *  No duplicate names will be added to the list, but if you send in
 *  a list with duplication already in it, we will not clean it up for you.
 */

extern void ClearRecycleStack(void);
/**<
 *  Call this function after shutting down the compiler.
 *
 *  The stack seldom gets beyond 2 deep, but we recycle the memory for
 *  it anyway because malloc and free are expensive and we use the
 *  stack millions of times.
 *  The recycler is initialized to empty by the ANSI C assumption,
 *  so there is no init function. This function can be used as a ReInit
 *  if so desired, but there is no need for it.
 *  There is an option inside evaluate.c that causes this function to
 *  report how many recycled stack elements it deallocates.
 */

/* @} */

#endif /* ASC_EVALUATE_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	Expression Evaluation Routine
22
23	Requires:
24	#include "utilities/ascConfig.h"
25	#include "list.h"
26	#include "fractions.h"
27	#include "compiler.h"
28	#include "dimen.h"
29	#include "expr_types.h"
30	//
31	by Tom Epperly
32	Created: 1/16/90
33	Last in CVS: $Revision: 1.10 $ $Date: 1997/07/18 12:29:08 $ $Author: mthomas $
34	*/
35
36	#ifndef ASC_EVALUATE_H
37	#define ASC_EVALUATE_H
38
39	/** addtogroup compiler Compiler
40	@{
41	*/
42
43	extern struct value_t EvaluateSet(CONST struct Set *sptr,
44	struct value_t (*EvaluateName)());
45	/**<
46	* Return the value of a Set structure, which just might be a set.
47	*/
48
49	extern struct value_t EvaluateExpr(CONST struct Expr *expr,
50	CONST struct Expr *stop,
51	struct value_t (*EvaluateName)());
52	/**<
53	* Return the value of a name structure.
54	* In most cases stop = NULL. stop can be used to evaluate just part of
55	* an expression. If (stop!=NULL) the calling program, must know the
56	* the stack is correctly balanced.
57	*/
58
59	extern struct gl_list_t EvaluateNamesNeeded(CONST struct Expr expr,
60	CONST struct Expr *stop,
61	struct gl_list_t *list);
62	/**<
63	* (Analogous to EvaluateExpr, but the global EvaluatingSets is irrelevant).
64	*
65	* Appends all the externally defined names found in expr to list.
66	* (Loop variables defined in the expression are ignored.)
67	* If expr is not well formed wrt loops, you may get odd results back.
68	* If the list passed in is NULL, creates a list first.
69	* The list returned may be empty, but should not be NULL.
70	* When e_var are encountered in the expression, DOES dissect the
71	* subscripts separately.<br><br>
72	*
73	* Doesn't actually evaluate anything, so EvaluateName function
74	* is not required. The list will be the set of names you must have
75	* values for in order for the expression to have a chance of
76	* evaluating to a result, including for loop variables, but not
77	* dummy indices defined in the expression.
78	* No duplicate names will be added to the list, but if you send in
79	* a list with duplication already in it, we will not clean it up for you.
80	*/
81
82	extern struct gl_list_t EvaluateNamesNeededShallow(CONST struct Expr expr,
83	CONST struct Expr *stop,
84	struct gl_list_t *list);
85	/**<
86	* (Analogous to EvaluateExpr, but the global EvaluatingSets is irrelevant).
87	*
88	* Appends all the externally defined names found in expr to list.
89	* (Loop variables defined in the expression are ignored.)
90	* If e is not well formed wrt loops, you may get odd results back.
91	* If the list passed in is NULL, creates a list first.
92	* The list returned may be empty, but should not be NULL.
93	* When e_var are encountered in the expression, DOES NOT dissect the
94	* subscripts separately.<br><br>
95	*
96	* Doesn't actually evaluate anything, so no EvaluateName function
97	* is not required. The list will be the set of names you must have
98	* values for in order for the expression to have a chance of
99	* evaluating to a result, including for loop variables, but not
100	* dummy indices defined in the expression.
101	* No duplicate names will be added to the list, but if you send in
102	* a list with duplication already in it, we will not clean it up for you.
103	*/
104
105	extern struct gl_list_t
106	EvaluateSetNamesNeeded(CONST struct Set sptr, struct gl_list_t *list);
107	/**<
108	* (Analogous to EvaluateExpr, but the global EvaluatingSets is irrelevant).
109	*
110	* Appends all the externally defined names found in sptr to list.
111	* (Loop variables defined in the expression are ignored.)
112	* If sptr is not well formed wrt loops, you may get odd results back.
113	* If the list passed in is NULL, creates a list first.
114	* The list returned may be empty, but should not be NULL.
115	* DOES investigate subscripts deeply for needed names.<br><br>
116	*
117	* Doesn't actually evaluate anything, so no EvaluateName function
118	* is not required. The list will be the set of names you must have
119	* values for in order for the set to have a chance of
120	* evaluating to a result, including for loop variables, but not
121	* dummy indices defined in the expression.
122	* No duplicate names will be added to the list, but if you send in
123	* a list with duplication already in it, we will not clean it up for you.
124	*/
125
126	extern struct gl_list_t
127	EvaluateSetNamesNeededShallow(CONST struct Set sptr, struct gl_list_t *list);
128	/**<
129	* (Analogous to EvaluateExpr, but the global EvaluatingSets is irrelevant).
130	*
131	* Appends all the externally defined names found in sptr to list.
132	* (Loop variables defined in the expression are ignored.)
133	* If sptr is not well formed wrt loops, you may get odd results back.
134	* If the list passed in is NULL, creates a list first.
135	* The list returned may be empty, but should not be NULL.
136	* DOES NOT investigate subscripts deeply for needed names.<br><br>
137	*
138	* Doesn't actually evaluate anything, so no EvaluateName function
139	* is not required. The list will be the set of names you must have
140	* values for in order for the set to have a chance of
141	* evaluating to a result, including for loop variables, but not
142	* dummy indices defined in the expression.
143	* No duplicate names will be added to the list, but if you send in
144	* a list with duplication already in it, we will not clean it up for you.
145	*/
146
147	extern void ClearRecycleStack(void);
148	/**<
149	* Call this function after shutting down the compiler.
150	*
151	* The stack seldom gets beyond 2 deep, but we recycle the memory for
152	* it anyway because malloc and free are expensive and we use the
153	* stack millions of times.
154	* The recycler is initialized to empty by the ANSI C assumption,
155	* so there is no init function. This function can be used as a ReInit
156	* if so desired, but there is no need for it.
157	* There is an option inside evaluate.c that causes this function to
158	* report how many recycled stack elements it deallocates.
159	*/
160
161	/* @} */
162
163	#endif /* ASC_EVALUATE_H */
164