Club Amiga de Montreal

home *** CD-ROM | disk | FTP | other *** search

/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 521.lha / ICalc_v1.0 / icalc.doc.pp / icalc.doc

Wrap

Text File | 1991-06-10 | 19.5 KB | 661 lines

3micalc 0m1mversion 10m.1m0 0mA complex-number expression parser by Martin W.Scott User Guide icalc User Guide icalc 1mIntroduction 0m3micalc 0mis a terminal-based calculator; the 1mi 0mstands for 1mimaginary0m, denoting the fact that the calculator works with complex numbers (and the name is also a little pun). There are many calculator programs for the Amiga, but to my knowledge, none with this ability. There are other fairly powerful features which are also rare in similar programs. 1mComplex Numbers 0mEven if you don't know what a complex number is, 3micalc 0mis still useful. It was designed to be used for real calculations too, and although the behavior of certain functions is different, this is generally not a problem. 1mExpressions 0m3micalc 0maccepts expressions in the usual form for computer expressions, i.e. multiplication must be explicitly shown by '*', and function arguments enclosed within parentheses. The exception to this is the method of inputing imaginary parts of complex numbers. If you want to enter the number 3 + 4i, you can type either 3 + 4i or 3 + 4*i but 3mnot 0m3 + i4 since this would give an ambiguous grammar - is it i*4 or the variable "i4"? In almost all circumstances, the algebraic "4i" is preferred, but there is one exception, exponentation "^". If you want 3*i^3, you must type 3*i^3 and not 3i^3 The former gives the correct result, -3i, whilst the latter gives -27i. This is because the grammar sees "3i" as a number in its own right, and not an implicit multiplication. See the appendices for the complete list of commands, operators, constants and builtin functions that 3micalc 0msupports. Expressions are separated by newlines or icalc -2- version 1.0 icalc User Guide icalc semi-colons ';'. Comments are introduced by '#'; the rest of the input line is ignored. 1mSample Expressions 0mx=1-i # an assignment statement assigns to variable x the value 1-i. # and now, two statements separated by a semi-colon sqr(x); x*sqr(x); displays the values -2i and -2-2i. 2*sin(x)*cos(x) - sin(2*x) displays the value 4.4408920985e-16 + 4.4408920985e-16i. The answer should be 0, and indeed is very close to that. The inaccuracy results because each term has a value as close to the actual value as the computer's internal representation of numbers can hold. This behaviour is common to most programs. 1mStarting icalc 0mCLI Usage The synopsis for icalc is icalc [file-list] where file-list is a list of input files. 3micalc 0mwill read (process) the files in the list and exit. Thus, if you wish to also use the program interactively, you should specify one of the files as a dash "-"; this is taken to mean "use standard input". You can obviously redirect output to a file if you wish (and redirect input from a file, but this is generally unnecessary). For example, if you wanted to use definitions contained in a file called "trig.ic", and then type some expressions in at the terminal, you would use icalc trig.ic - to start the program. I recommend you use a stack size of about 20K when running 3micalc. 0mIf no file-list is given, 3micalc 0mstarts an interactive session. Workbench Usage To start 3micalc 0mfrom the Workbench, simply double-click its icon. You may also pass arguments (definition/command files) to 3micalc 0min the usual Workbench manner (shift-select etc.). 3micalc 0msession. You can specify the window to be opened by modifying the WINDOW tooltype (click once on the icalc -3- version 1.0 icalc User Guide icalc 3micalc 0micon, and select "Info" from the Workbench menu). You may also set the default tool of a definition file's project icon to be 3micalc. 0mThen simply double clicking that icon will launch 3micalc 0mand read the definition file. Remember, however, to set the project icon's stack to 20000, or you will get a stack overflow error. Exiting icalc To end an interactive session of 3micalc 0m(from either CLI or Workbench) use the commands "quit" or "exit". You can also type ^\ (press the control key and '\' simultaneously). 1mVariables 0mVariables in 3micalc 0mcan be named arbitrarily, as long as no name conflicts with a pre-defined symbol name, such as sin or PI. The standard conventions apply: the first character must be a letter, followed by a string of letters and digits. Case is significant. Variables are introduced by using them; If a variable is used before it has been initialized (i.e. has had a value assigned to it), 3micalc 0mwill warn the user and use the value zero. Assignments can appear anywhere in an expression, and are in fact expressions in their own right (as in C). So, you can do things like apple = banana = apricot = 34 to assign the value 34 to these variables. Since assignments are expressions, their value being the assignment value, you can also do apple = sqr(banana = 12) which assigns the value 12 to "banana", and 144 to "apple". You can of course assign new values to existing variables. 1mConstants and ans 0m3micalc 0mcomes with several predefined constants, e.g. PI, GAMMA etc. You cannot assign a new value to a constant. There is a special constant, "ans", which isn't really a constant at all, but is made so to prevent assignments to it. "ans" contains the value of the previously evaluated expression, and so is useful when splitting a calculation up into smaller chunks. 1 + 2 + 3 6 ans * 12 72 You can also use it for recursive formulas. For example, icalc -4- version 1.0 icalc User Guide icalc the logistic equation xnext = rx(1-x) for parameter r = 3.5, initial x = 0.4 could be iterated as follows: r = 3.5; 0.4 # initialize r and ans 3.5 0.4 r*ans*(1-ans) 0.84 r*ans*(1-ans) 0.4704 r*ans*(1-ans) 0.87193344 r*ans*(1-ans) 0.390829306734 and so on. Of course, you needn't use "ans" here; you could just use assignments to "x", but it illustrates the point. If you're going to do things like this (and even if you're not) I suggest you use NEWCON:, Conman, or something along those lines, it makes life 3mmuch 0measier. There is a neater way to do this sort of stuff using the "repeat" command which is explained later. 1mBuiltin Functions 0m3micalc 0mcomes with many builtin functions, for example sin, cos, sqrt, exp, ln etc. There are some special functions for complex numbers too, namely Im, Re, arg, norm. They all take real or complex arguments, which can be any expression. For example, asin(sin(1)) returns the value 1 as expected. But ... asin(sin(1-i)) returns 1.484116283319 - 0.831157682449i; this is because the inverse of sin is a many-valued function. asin returns a value in the PVR (principal value range) as do all many-valued functions in 3micalc. 0mThe PVR is defined (for this program anyway) as the interval [-PI,PI). When working with complex numbers, you should always bear in mind that almost all the trigonometric functions are many-valued, because they are defined in terms of the exponential and logarithmic functions. Another thing to bear in mind if you intend working with reals is that things like ln(-1) return a value, 3.14159265359i (PI*i) in this case. icalc -5- version 1.0 icalc User Guide icalc 1mUser0m-1mdefined Functions 0mA browse through the list of builtin functions may show a number of surprising omissions, including gaga(z) = sin(sqrt(z)). Well, not to worry, 3micalc 0mlets you define your own, and they can then be used just like any other function. You define functions in the following manner: func <name> ( <parameter> ) = <expr> so to define gaga(z), use func gaga(z) = sin(sqrt(z)) Note that z is 3mlocal 0mto the function, not a global variable. Thus, if z is defined as a variable, it is unaltered when you call gaga. There is a sample file called "trig.icalc" in this distribution defining every trig function you care to mention, and a few other functions too. At the moment, functions are restricted to being single-parameter. I will add multi-parameter functions soon. Also, as with most programming languages, don't write circular definitions; 3micalc 0mdoes not detect them, and you will swiftly run out of stack. Recursive functions fall into this category, as there is no way to specify terminal cases - see the Improvements section below. 1mCommands 0m3micalc 0mhas a few commands to make life easier. quit exit not surprisingly, these commands terminate 3micalc. 0msilent tells 3micalc 0mnot to display the results of expressions, or inform you that a function has been defined. It is useful for initialization files containing lots of definitions. verbose This is the inverse function of "silent"; it turns back on the display of results, etc. prec <num-digits> allows you to modify the way results are displayed; values are printed with <num-digits> decimal places, if possible. The default is 12. For C programmers: numbers are printed using fprintf with "%.*lg" format string; the asterisk is replaced with the (integer) value of the internal precision variable, set by this command. help reminds you what other commands are available. icalc -6- version 1.0 icalc User Guide icalc vars lists all currently defined variables and their values. consts lists all predefined constants and their values. builtins lists all built-in functions available. functions lists all defined user-functions. 1mThe repeat Construct 0mThis is a timesaving facility with a number of uses. The structure of a repeat command is repeat <number> <expr> where number is the number of times to evaluate the expression expr. The usefulness of this construct is best illustrated by example: say you wanted to sum the expression 1/n² from 1 to 100; you could do sum = n = 0 0 silent; repeat 100 sum = sum+1/sqr(n=n+1); verbose;n;sum 100 1.634983900185 Now you may want to sum to 200, to get a beter idea of the limit (your analysis course has told you it converges). Just retype the last line (or press the up-arrow if using NEWCON: etc.) silent; repeat 100 sum = sum+1/sqr(n=n+1); verbose;n;sum 200 1.639946546015 and you could repeat this process indefinitely. Note the use of the silent-verbose pair around the repeat statement. This speeds things up quite a bit, and saves your eyes too. Of course, if you're interested in each stage, you can omit them. Another example: compound interest 5% p.a., initial capital $1000. c = 1000 1000 repeat 20 c = c*1.05 1050 1102.5 1157.625 : : 2653.297705144415 icalc -7- version 1.0 icalc User Guide icalc 1mBugs 0mWhat bugs? Well, I'm sure there must be the odd one or two, but I haven't noticed. Should you find any, please let me know and I'll try to fix them. If there's something you hate about 3micalc 0mand would like changed, again drop me a line. 1mImprovements 0mThere's a lot of scope for extension/improvement to 3micalc. 0mHere's my list: o allow modification of the PVR. Should be fairly easy, but is there much point? o make 3micalc 0mmore like a little language, by adding if-then-else, while etc. This requires some sort of comparison method; equality is easy, but since there is no ordering of complex numbers, how to imlement >, >= etc? I have some ideas, but if you would like to see these extensions, let me know, along with your opinion on the best comparison method. o load/save environment, i.e. dump all vars to a file for reloading later. o print actual function definitions when listing user-defined functions. o get rid of small errors creeping in (like the example in the Sample expressions section). o etc... 1mCompiling 0m3micalc 0mwas written using Lattice C (version 5.10a) but should compile with no problems with Manx C. I used the version of bison on Fish #136; if you're using a later version or Yacc, you may need to change the makefile. The code is meant to be portable, so Amiga-specific code (currently only the Workbench interface) is #ifdef'd. Also, to implement the WINDOW tooltype, I've used a slightly modified version of Lattice's _main function; since I'm probably not permitted to distribute the modified source, I've included just the compiled module, myumain.o. 1mCredits 0mThanks to the GNU team for bison (it makes these things so much easier to write and modify) and to William Loftus for the Amiga port. icalc -8- version 1.0 icalc User Guide icalc Thanks also to Steve Koren for Sksh, and Mike Meyer et al for Mg3; together they make a great development environment. This is my first bison-based project, and I learnt a lot from "The Unix Programming Environment" by Brian Kernighan and Rob Pike. Their "hoc" calculator was a model for this (although there are major differences too). 1mThe Bottom Line 0mAlthough contributions are not required, they would be most welcome (I'm a poor student). Don't let that inhibit you from sending bug reports, praise, suggestions, etc. I'd get most pleasure from hearing if anyone actually uses this bloody program! Send mail to: Martin W. Scott, 23 Drum Brae North, Edinburgh, EH4 8AT SCOTLAND. Thanks for reading this far. The appendices follow. icalc -9- version 1.0 icalc User Guide icalc 1mAppendix 1 0m- 1mOperators 0m(1min order order of precedence0m) = assignment + addition - subtraction, unary minus * multiplication / division ^ exponentation ' conjugate: z' = conjugate of z 1mAppendix 2 0m- 1mConstants 0mPI 4*atan(1) E exp(1) GAMMA Euler's constant, 0.57721566... DEG Number of degrees in one radian PHI Golden ratio 1.61803398... LOG10 ln(10) LOG2 ln(2) 1mAppendix 3 0m- 1mBuiltin functions 0msin trigonometric functions cos tan asin inverse trigonometric functions acos atan sinh hyperbolic trigonometric functions cosh tanh exp exponential function ln natural logarithm sqr square sqrt square root conj conjugate (see also ' operator) abs absolute value norm not really norm; if z=x+iy, norm(z) = x²+y² arg principal argument Re real part of complex number Im imaginary part of complex number icalc -10- version 1.0