special commands '.cmd' can now also be invoked with '//GiNaC-cint.cmd'
[ginac.git] / cint / ginaccint.1
1 .TH ginaccint 1 "January, 2000" "GiNaC"
2 .SH NAME
3 GiNaC-cint \- An interactive interface for GiNaC based on the Cint C/C++ interpreter
4 .SH SYNPOSIS
5 .B ginaccint
6 [file ...]
7 .SH DESCRIPTION
8 .B ginaccint
9 is an interactive frontend for the GiNaC symbolic computation
10 framework.  It is a tool that lets you write interactive programs
11 (scripts) in C++ that directly make use of GiNaC's classes.  Thus it
12 is a more complete replacement for traditional interactive computer
13 algebra systems than \fBginsh\fP(1) is.  Programs may be composed as
14 scripts and later compiled with the native compiler and linked into
15 the system.
16 .SH USAGE
17 .SS INPUT FORMAT
18 After startup, GiNaC-cint reads and executes the files given as 
19 command line arguments. If any of these files contains a
20 .BR .quit
21 command, GiNaC-cint exits at this point.
22 Otherwise it displays a prompt signifying that it is ready to
23 accept your input. All C++ statements are valid as input, extended by
24 GiNaC's numeric or symbolic expressions.  E.g.
25 .BR fibonacci(24)/1104;
26 returns a GiNaC object of class
27 .BR "ex" ,
28 which in this case represents the numeric 42.  Symbols are declared by 
29 statements as
30 .nf 
31 GiNaC> symbol x("x"), y("y"), z;
32 .fi
33 which defines two named symbols and an anonymous one for later usage.
34 All GiNaC methods and functions are available as they would be coded
35 in C++.  It is not necessary to explicitly invoke a print command as
36 the last expression is automatically printed:
37 .nf
38 GiNaC> pow(x+y,4).expand();
39 Out2 = x^4+4*x^3*y+6*x^2*y^2+4*x*y^3+y^4
40 .fi
41 Statements are generally closed either when a closing brace 
42 .RB ( } )
43 matches the first opening brace
44 .RB ( { ) 
45 or a semicolon
46 .RB ( ; )
47 is encountered while there are no open braces. This implies that
48 an input like 
49 .nf
50 GiNaC> class A {
51      > }
52      > ;
53 .fi
54 is misinterpreted to be complete after the closing brace.
55 Instead you have to write
56 .nf
57 GiNaC> class A {
58      > };
59 .fi
60
61 .SS SPECIAL COMMANDS
62
63 Lines starting with a dot mark special GiNaC-cint commands. Instead of
64 .BR "\fB.cmd\fB"
65 you can also write
66 .BR "\fB//GiNaC-cint.cmd\fB"
67 to be compatible with programs that will be compiled later.
68 This is mostly useful for the
69 .BR "\fB.function\fB" 
70 declaration.
71
72 Lines starting with #! (for #!/path/ginaccint) are ignored.
73
74
75 .IP "\fB.cint\fR"
76 Switch to cint's interactive mode.
77
78 .IP "\fB.function\fR"
79
80 Allow a function definition in interactive mode.  GiNaC-cint must be
81 put into a special mode in order to define a function. After that any
82 function definition in valid C++ syntax may be typed in.  It becomes
83 immediatly available for usage.
84
85 .IP "\fB.help\fB"
86
87 List a short summary of available commands.
88
89 .IP "\fB.quit\fR"
90 Exit from GiNaC-cint.  Same as 
91 .BR ".bye" ,
92 .BR ".exit" ,
93 .BR ".q" ,
94 .BR "bye;" ,
95 .BR "exit; " or
96 .BR "quit;" .
97
98 .IP "\fB.read filename\fB"
99
100 Read a file from disk and execute it in GiNaC-cint
101 (recursive call is possible).
102
103 .IP "\fB.redirect [filename]\fB"
104
105 Redirect
106 .BR "\fBOut\fP\fInum\fP" 
107 output to a file (
108 .BR .redirect
109 alone redirects output to console).
110
111 .IP "\fB.restart\fB"
112
113 Restart GiNaC-cint (does not re-read command line files).       
114
115 .IP "\fB.save filename\fB"
116
117 Save the commands you have entered so far in a file.
118
119 .IP "\fB.silent\fB"
120
121 suppress
122 .BR "\fBOut\fP\fInum\fP" 
123 output (variables are still accessible).
124
125 .IP "\fB.> [filename]\fB"
126
127 same as
128 .BR "\fB.redirect [filename]\fB" .
129
130 .IP "\fBOut\fP\fInum\fP"
131 Returns the expression whose output was marked
132 .BR "\fBOut\fP\fInum\fP" 
133 as a handle.
134
135 .IP "\fBLAST\fP, \fBLLAST, \fP\fBLLLAST\fP"
136 Return the last, second last and third last expression, 
137 respectively.
138
139 .SH EXAMPLES
140 .nf
141 GiNaC> symbol x("x"), y("y"), z("z");
142 GiNaC> ex a = pow(x,2)-x-2;
143 GiNaC> ex b = pow(x+1,2);
144 GiNaC> ex s = a/b;
145 GiNaC> s.diff(x);
146 Out1 = -2*(1+x)^(-3)*(-2-x+x^2)+(-1+2*x)*(1+x)^(-2)
147 GiNaC> s.normal();
148 Out2 = (-2+x)*(1+x)^(-1)
149 GiNaC> for (int i=2; i<20; i+=2) {
150      >     cout << "B(" << i << ")==" << bernoulli(i) << endl;
151      > }
152 B(2)==1/6
153 B(4)==-1/30
154 B(6)==1/42
155 B(8)==-1/30
156 B(10)==5/66
157 B(12)==-691/2730
158 B(14)==7/6
159 B(16)==-3617/510
160 B(18)==43867/798
161 GiNaC> .function
162 next expression can be a function definition
163 GiNaC> ex EulerNumber(unsigned n)
164      > {
165      >     symbol xi;
166      >     const ex generator = pow(cosh(xi),-1);
167      >     return generator.diff(xi,n).subs(xi==0);
168      > }
169 creating file /tmp/ginac26197caa
170 GiNaC> EulerNumber(42);
171 Out3 = -10364622733519612119397957304745185976310201
172 GiNaC> ex f = expand((x*y*z-1)*(x*y*z+3));
173 GiNaC> ex g = expand((x*y*z-1)*(x*y*z-3));
174 GiNaC> cout << "The GCD of " << f << " and " << g << endl
175      >      << " is " << gcd(f, g) << endl
176      >      << " so " << f/g << endl
177      >      << " is " << normal(f/g) << endl;
178 The GCD of -3+2*x*z*y+x^2*z^2*y^2 and 3-4*x*z*y+x^2*z^2*y^2
179  is -1+x*z*y
180  so (-3+2*x*z*y+x^2*z^2*y^2)*(3-4*x*z*y+x^2*z^2*y^2)^(-1)
181  is (-3+x*z*y)^(-1)*(3+x*z*y)
182 GiNaC> .quit
183 .fi
184
185 .SH BUGS
186 Cint accepts most of K&R and ANSI C/C++ language construct but not
187 perfect.  In fact, Cint is not aimed to be a 100% ANSI/ISO compliant
188 C/C++ language processor.  It rather is a portable script language
189 environment which is close enough to the standard C++.  See the file 
190 .BR limitati.txt
191 in your Cint distribution.  Please take the time to track down any bug
192 you encounter as far as possible and contact Masaharu Goto
193 <MXJ02154@niftyserve.or.jp> for Cint-related bugs and
194 <ginac-bugs@ginac.de> for any bugs in the GiNaC engine.
195
196 Only expressions (class
197 .BR ex )
198 are typed out and available through 
199 .BR "\fBOut\fP\fInum\fP" 
200 and 
201 .BR LAST
202 after declaring them.  This accounts for some funny behaviour, like
203 .BR fibonacci(7)
204 doesn't print, but
205 .BR fibonacci(7)*1
206 does, since this is not a naked number but an expression holding
207 that number. A warning message is printed in this case only for
208 the first occurence.
209
210 .SH AUTHOR
211 .TP
212 The GiNaC Group
213 .br
214 Christian Bauer <Christian.Bauer@uni-mainz.de>
215 .br
216 Alexander Frink <Alexander.Frink@uni-mainz.de>
217 .br
218 Richard Kreckel <Richard.Kreckel@uni-mainz.de>
219 .TP
220 Agilent Technologies Japan
221 .br
222 Masaharu Goto <MXJ02154@niftyserve.or.jp>
223 .SH SEE ALSO
224 GiNaC Tutorial \- An open framework for symbolic computation within the
225 C++ programming language
226 .PP
227 CLN \- A Class Library for Numbers, Bruno Haible
228 .PP
229 \fBginsh\fP(1)
230 .SH COPYRIGHT
231 .SS GINAC COPYRIGHT
232 Copyright \(co 1999-2000 Johannes Gutenberg Universit\(:at Mainz, Germany
233
234 This program is free software; you can redistribute it and/or modify
235 it under the terms of the GNU General Public License as published by
236 the Free Software Foundation; either version 2 of the License, or
237 (at your option) any later version.
238
239 This program is distributed in the hope that it will be useful,
240 but WITHOUT ANY WARRANTY; without even the implied warranty of
241 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
242 GNU General Public License for more details.
243
244 You should have received a copy of the GNU General Public License
245 along with this program; if not, write to the Free Software
246 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
247 .SS CINT COPYRIGHT
248 Copyright \(co of Cint and associated tools are owned by Agilent
249 Technologies Japan Company and the author.  Acknowledgement to the
250 author by e-mail is recommended at installation.  Source code, binary
251 executable or library of Cint and associated tools can be used,
252 modified and distributed free of charge for any purpose provided that
253 the copyright notice appear in all copies and that both that copyright
254 notice and this permission notice appear in documentation.
255 Registration is requested, at this moment, for commercial use.  Send
256 e-mail to the author <MXJ02154@niftyserve.or.jp>.  The registration is
257 free.