ascend/compiler/logrelation.h

/**< 
 *  Logical Relation Construction Routines
 *  by Vicente Rico-Ramirez
 *  Version: $Revision: 1.9 $
 *  Version control file: $RCSfile: logrelation.h,v $
 *  Date last modified: $Date: 1997/07/18 12:31:43 $
 *  Last modified by: $Author: mthomas $
 *
 *  This file is part of the Ascend Language Interpreter.
 *
 *  Copyright (C) 1996 Vicente Rico-Ramirez
 *
 *  The Ascend Language Interpreter 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 of the
 *  License, or (at your option) any later version.
 *
 *  The Ascend Language Interpreter is distributed in 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 the program; if not, write to the Free Software Foundation,
 *  Inc., 675 Mass Ave, Cambridge, MA 02139 USA.  Check the file named
 *  COPYING.
 *
 */

#ifndef __LOGRELATION_H_SEEN__
#define __LOGRELATION_H_SEEN__


/**< 
 *  When #including logrelation.h, make sure these files are #included first:
 *         #include "fractions.h"
 *         #include "compiler.h"
 *         #include "dimen.h"
 *         #include "types.h"
 *         #include "logical_relation.h"
 *         #include "find.h"
 */


enum logrelation_errors {
  find_logerror,        /**< error finding an instance */
  incorrect_logstructure,
  incorrect_linst_type,     /**< contains a nonboolean instance type */
  incorrect_real_linst_type,    /**< contains a real_inst type */
  incorrect_boolean_linst_type, /**< contains a boolean instance type */
  incorrect_integer_linst_type, /**< contains an integer variable instance type*/
  incorrect_symbol_linst_type,  /**< contains a symbol instance type */
  boolean_value_undefined,  /**< boolean constant doesn't have a value yet */
  incorrect_num_largs,           /**< wrong number of arguments */
  lokay
};


extern int g_simplify_logrelations;
/**< 
 *  The default value of this variable is 0.
 *  Values imply
 *  <0: As 0 below.
 *  0:  Compile logical relations as written by user.
 *  1:  Simplify logical relations with easy reductions.
 *  >1: As one, but left open for future work if someone wants to
 *      play nifty games like applying distributive and associative rules.
 *
 *  The simplification of logical relation IS NOT implemented yet
 *
 */


extern void InitLogRelInstantiator(void);
/**< 
 *  InitLogRelInstantiator();
 *  Sets up logical relation instantiation gizmos. This must be called once
 *  before any logical relations can be built, ideally at startup time.
 *  Do not call it again unless DestroyLogRelInstantiator is called first.
 *  If insufficient memory to compile anything at all, does exit(2).
 */

extern void DestroyLogRelInstantiator(void);
/**< 
 *  DestroyLogRelInstantiator();
 *  Destroy logical relation instantiation gizmos. This must be called to
 *  clean up before shutting down ASCEND.
 *  Do attempt to instantiate anything after you call this unless you
 *  have recalled InitLogRelInstantiator.
 */

extern void ReportLogRelInstantiator(FILE*);
/**< 
 *  ReportLogRelInstantiator(f);
 *  FILE *f;
 *  Reports on the logical relation instantiator to f.
 */

/**< 
 * Some defines for Logical Relations. struct logrelation *lr;
 */
#define Infix_Log_LhsSide(lr)   ((lr)->token.lhs_term)
#define Infix_Log_RhsSide(lr)   ((lr)->token.rhs_term)
#define Postfix_Log_LhsSide(lr) ((lr)->token.lhs)
#define Postfix_Log_RhsSide(lr) ((lr)->token.rhs)


extern int CheckLogRel(CONST struct Instance *,CONST struct Expr *);
/**< 
 *  int CheckLogRel(reference,ex)
 *  const struct Instance *reference;
 *  const struct Expr *ex;
 *  Return TRUE iff the expression can be created.
 */

extern struct logrelation *CreateLogRelStructure(enum Expr_enum);
/**< 
 *  struct logrelation *CreateLogRelStructure(t);
 *  enum Epxr_enum t;
 *  Create and return a new logrelation node of type t.
 *  The node will be initialized to its defaults. It will have a reference
 *  count of 0.
 */

extern struct logrelation *CreateLogicalRelation(struct Instance *,
              struct Instance *,
              CONST struct Expr *,
              enum logrelation_errors *,
              enum find_errors *);
/**< 
 *  struct logrelation *CreateLogicalRelation(reference,lrelinst,ex,err,ferr)
 *  struct Instance *reference,*relinst;
 *  const struct Expr *ex;
 *  enum logrelation_errors *err;
 *  enum find_errors *ferr;
 *
 *  Create a logical relation from an expression, a reference instance and a
 *  relation instance.  This modifies the instance tree. The type of relinst
 *  will be set to e_bol_token.
 *
 *  The relation will not be successfully created until all variables
 *  exist and sets and constants in it are well defined.
 *
 *  reference    the instance which names are searched for in
 *  lrelinst     the logical relation instance where this
 *               relation will be placed
 *  ex           the expression to be converted.
 *  err          output any errors
 */


extern void DestroyLogRelation(struct logrelation *,struct Instance *);
/**< 
 *  void DestroyLogRelation(lrel,lrelinst)
 *  struct logrelation *lrel;
 *  struct Instance *lrelinst;
 *  Deallocate a logical relation.  This will notify all the boolean instances
 *  in the logical relation that it will no longer be pointing to them.
 *  Also, it will notify all the relations included in satisfied terms
 *  that the logical relation will no longer be pointing to them.
 *  Therefore, this routine will have an effect on the instance tree.
 */

extern void ModifyLogRelPointers(struct gl_list_t *,
     struct logrelation *,
     CONST struct Instance *,
     CONST struct Instance *);

/**< 
 *  void ModifyLogRelPointers(relorvar,lrel,old,new);
 *  struct gl_list_t *relorvar;
 *  struct logrelation *lrel;
 *  const struct Instance *old, *new;
 *  Change all references from old to new.  This doesn't do anything
 *  to the instances old and new. The gl_list can be the list of variables
 *  or the list of relations included in satisfied terms.
 */

extern void DoInOrderLogRelVisit(struct logrel_term *,struct logrelation *,
         void (*func)(struct logrel_term *,
       struct logrelation *));
/**< 
 *  void DoInOrderLogRelVisit(term,r,func);
 *  struct logrel_term *term;
 *  void (*func)(struct logrel_term *,struct logrelation *r);
 *  Will visit an infix tree and apply function func to each term.
 *  It takes the logical relation corresponding to the tree as an argument,
 *  as some of the operations on terms are dependent upon the logical
 *  relation that the term belongs to.
 *
 *  If the tree you are visiting is part of a logical relation side,
 *  your visiting function should not free any nodes it visits
 *  as these are parts of an array.
 */

extern struct logrelation *CopyLogRelByReference(CONST struct Instance *,
       struct Instance *,
       struct gl_list_t *,
       struct gl_list_t *);
/**< 
 *  Not implemented yet.
 */

extern struct logrelation *CopyLogRelToModify(CONST struct Instance *,
           struct Instance *,
           struct gl_list_t *,
           struct gl_list_t *);
/**< 
 *  struct logrelation *CopyLogRelation(src_inst,dest_inst,varlist,rellist)
 *  const struct Instance *src_inst;
 *  struct Instance *dest_inst;
 *  struct gl_list_t *varlist;
 *  struct gl_list_t *rellist;
 *
 *  Given a source and a destination logical relation instance, will copy the
 *  logrelation structure from the source instance and return it. A unique
 *  variable list is required. This variable list represents the new
 *  variables that will be marked icident upon the logical relation. Also,
 *  A unique relations list is required.
 *
 *  The tokens in the struct logrelation * returned by this function are
 *  NOT independently allocated, they are in the postfix array.
 */

#endif /**< __LOGRELATION_H_SEEN__ */
1	/**<
2	* Logical Relation Construction Routines
3	* by Vicente Rico-Ramirez
4	* Version: $Revision: 1.9 $
5	* Version control file: $RCSfile: logrelation.h,v $
6	* Date last modified: $Date: 1997/07/18 12:31:43 $
7	* Last modified by: $Author: mthomas $
8	*
9	* This file is part of the Ascend Language Interpreter.
10	*
11	* Copyright (C) 1996 Vicente Rico-Ramirez
12	*
13	* The Ascend Language Interpreter is free software; you can redistribute
14	* it and/or modify it under the terms of the GNU General Public License as
15	* published by the Free Software Foundation; either version 2 of the
16	* License, or (at your option) any later version.
17	*
18	* The Ascend Language Interpreter is distributed in hope that it will be
19	* useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
20	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
21	* General Public License for more details.
22	*
23	* You should have received a copy of the GNU General Public License
24	* along with the program; if not, write to the Free Software Foundation,
25	* Inc., 675 Mass Ave, Cambridge, MA 02139 USA. Check the file named
26	* COPYING.
27	*
28	*/
29
30	#ifndef __LOGRELATION_H_SEEN__
31	#define __LOGRELATION_H_SEEN__
32
33
34	/**<
35	* When #including logrelation.h, make sure these files are #included first:
36	* #include "fractions.h"
37	* #include "compiler.h"
38	* #include "dimen.h"
39	* #include "types.h"
40	* #include "logical_relation.h"
41	* #include "find.h"
42	*/
43
44
45	enum logrelation_errors {
46	find_logerror, /*< error finding an instance /
47	incorrect_logstructure,
48	incorrect_linst_type, /*< contains a nonboolean instance type /
49	incorrect_real_linst_type, /*< contains a real_inst type /
50	incorrect_boolean_linst_type, /*< contains a boolean instance type /
51	incorrect_integer_linst_type, /*< contains an integer variable instance type/
52	incorrect_symbol_linst_type, /*< contains a symbol instance type /
53	boolean_value_undefined, /*< boolean constant doesn't have a value yet /
54	incorrect_num_largs, /*< wrong number of arguments /
55	lokay
56	};
57
58
59	extern int g_simplify_logrelations;
60	/**<
61	* The default value of this variable is 0.
62	* Values imply
63	* <0: As 0 below.
64	* 0: Compile logical relations as written by user.
65	* 1: Simplify logical relations with easy reductions.
66	* >1: As one, but left open for future work if someone wants to
67	* play nifty games like applying distributive and associative rules.
68	*
69	* The simplification of logical relation IS NOT implemented yet
70	*
71	*/
72
73
74	extern void InitLogRelInstantiator(void);
75	/**<
76	* InitLogRelInstantiator();
77	* Sets up logical relation instantiation gizmos. This must be called once
78	* before any logical relations can be built, ideally at startup time.
79	* Do not call it again unless DestroyLogRelInstantiator is called first.
80	* If insufficient memory to compile anything at all, does exit(2).
81	*/
82
83	extern void DestroyLogRelInstantiator(void);
84	/**<
85	* DestroyLogRelInstantiator();
86	* Destroy logical relation instantiation gizmos. This must be called to
87	* clean up before shutting down ASCEND.
88	* Do attempt to instantiate anything after you call this unless you
89	* have recalled InitLogRelInstantiator.
90	*/
91
92	extern void ReportLogRelInstantiator(FILE*);
93	/**<
94	* ReportLogRelInstantiator(f);
95	* FILE *f;
96	* Reports on the logical relation instantiator to f.
97	*/
98
99	/**<
100	* Some defines for Logical Relations. struct logrelation *lr;
101	*/
102	#define Infix_Log_LhsSide(lr) ((lr)->token.lhs_term)
103	#define Infix_Log_RhsSide(lr) ((lr)->token.rhs_term)
104	#define Postfix_Log_LhsSide(lr) ((lr)->token.lhs)
105	#define Postfix_Log_RhsSide(lr) ((lr)->token.rhs)
106
107
108	extern int CheckLogRel(CONST struct Instance ,CONST struct Expr );
109	/**<
110	* int CheckLogRel(reference,ex)
111	* const struct Instance *reference;
112	* const struct Expr *ex;
113	* Return TRUE iff the expression can be created.
114	*/
115
116	extern struct logrelation *CreateLogRelStructure(enum Expr_enum);
117	/**<
118	* struct logrelation *CreateLogRelStructure(t);
119	* enum Epxr_enum t;
120	* Create and return a new logrelation node of type t.
121	* The node will be initialized to its defaults. It will have a reference
122	* count of 0.
123	*/
124
125	extern struct logrelation CreateLogicalRelation(struct Instance ,
126	struct Instance *,
127	CONST struct Expr *,
128	enum logrelation_errors *,
129	enum find_errors *);
130	/**<
131	* struct logrelation *CreateLogicalRelation(reference,lrelinst,ex,err,ferr)
132	* struct Instance reference,relinst;
133	* const struct Expr *ex;
134	* enum logrelation_errors *err;
135	* enum find_errors *ferr;
136	*
137	* Create a logical relation from an expression, a reference instance and a
138	* relation instance. This modifies the instance tree. The type of relinst
139	* will be set to e_bol_token.
140	*
141	* The relation will not be successfully created until all variables
142	* exist and sets and constants in it are well defined.
143	*
144	* reference the instance which names are searched for in
145	* lrelinst the logical relation instance where this
146	* relation will be placed
147	* ex the expression to be converted.
148	* err output any errors
149	*/
150
151
152	extern void DestroyLogRelation(struct logrelation ,struct Instance );
153	/**<
154	* void DestroyLogRelation(lrel,lrelinst)
155	* struct logrelation *lrel;
156	* struct Instance *lrelinst;
157	* Deallocate a logical relation. This will notify all the boolean instances
158	* in the logical relation that it will no longer be pointing to them.
159	* Also, it will notify all the relations included in satisfied terms
160	* that the logical relation will no longer be pointing to them.
161	* Therefore, this routine will have an effect on the instance tree.
162	*/
163
164	extern void ModifyLogRelPointers(struct gl_list_t *,
165	struct logrelation *,
166	CONST struct Instance *,
167	CONST struct Instance *);
168
169	/**<
170	* void ModifyLogRelPointers(relorvar,lrel,old,new);
171	* struct gl_list_t *relorvar;
172	* struct logrelation *lrel;
173	* const struct Instance old, new;
174	* Change all references from old to new. This doesn't do anything
175	* to the instances old and new. The gl_list can be the list of variables
176	* or the list of relations included in satisfied terms.
177	*/
178
179	extern void DoInOrderLogRelVisit(struct logrel_term ,struct logrelation ,
180	void (func)(struct logrel_term ,
181	struct logrelation *));
182	/**<
183	* void DoInOrderLogRelVisit(term,r,func);
184	* struct logrel_term *term;
185	* void (func)(struct logrel_term ,struct logrelation *r);
186	* Will visit an infix tree and apply function func to each term.
187	* It takes the logical relation corresponding to the tree as an argument,
188	* as some of the operations on terms are dependent upon the logical
189	* relation that the term belongs to.
190	*
191	* If the tree you are visiting is part of a logical relation side,
192	* your visiting function should not free any nodes it visits
193	* as these are parts of an array.
194	*/
195
196	extern struct logrelation CopyLogRelByReference(CONST struct Instance ,
197	struct Instance *,
198	struct gl_list_t *,
199	struct gl_list_t *);
200	/**<
201	* Not implemented yet.
202	*/
203
204	extern struct logrelation CopyLogRelToModify(CONST struct Instance ,
205	struct Instance *,
206	struct gl_list_t *,
207	struct gl_list_t *);
208	/**<
209	* struct logrelation *CopyLogRelation(src_inst,dest_inst,varlist,rellist)
210	* const struct Instance *src_inst;
211	* struct Instance *dest_inst;
212	* struct gl_list_t *varlist;
213	* struct gl_list_t *rellist;
214	*
215	* Given a source and a destination logical relation instance, will copy the
216	* logrelation structure from the source instance and return it. A unique
217	* variable list is required. This variable list represents the new
218	* variables that will be marked icident upon the logical relation. Also,
219	* A unique relations list is required.
220	*
221	* The tokens in the struct logrelation * returned by this function are
222	* NOT independently allocated, they are in the postfix array.
223	*/
224
225	#endif /*< __LOGRELATION_H_SEEN__ /