Commit | Line | Data |
---|---|---|
11823ed9 PR |
1 | .\" |
2 | .\" bc.1 - the *roff document processor source for the bc manual | |
3 | .\" | |
4 | .\" This file is part of bc written for MINIX. | |
5 | .\" Copyright (C) 1991, 1992 Free Software Foundation, Inc. | |
6 | .\" | |
7 | .\" This program is free software; you can redistribute it and/or modify | |
8 | .\" it under the terms of the GNU General Public License as published by | |
9 | .\" the Free Software Foundation; either version 2 of the License , or | |
10 | .\" (at your option) any later version. | |
11 | .\" | |
12 | .\" This program is distributed in the hope that it will be useful, | |
13 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of | |
14 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
15 | .\" GNU General Public License for more details. | |
16 | .\" | |
17 | .\" You should have received a copy of the GNU General Public License | |
18 | .\" along with this program; see the file COPYING. If not, write to | |
19 | .\" the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA. | |
20 | .\" | |
21 | .\" You may contact the author by: | |
22 | .\" e-mail: phil@cs.wwu.edu | |
23 | .\" us-mail: Philip A. Nelson | |
24 | .\" Computer Science Department, 9062 | |
25 | .\" Western Washington University | |
26 | .\" Bellingham, WA 98226-9062 | |
27 | .\" | |
28 | .\" | |
29 | .TH bc 1 .\" "Command Manual" v1.02 "Feb 3, 1992" | |
30 | .SH NAME | |
31 | bc - An arbitrary precision calculator language | |
32 | .SH SYNTAX | |
33 | \fBbc\fR [ \fB-lws\fR ] [ \fI file ...\fR ] | |
34 | .SH VERSION | |
35 | This man page documents GNU bc version 1.02. | |
36 | .SH DESCRIPTION | |
37 | \fBbc\fR is a language that supports arbitrary precision numbers | |
38 | with interactive execution of statements. There are some similarities | |
39 | in the syntax to the C programming language. | |
40 | A standard math library is available by command line option. | |
41 | If requested, the math library is defined before processing any files. | |
42 | \fBbc\fR starts by processing code from all the files listed | |
43 | on the command line in the order listed. After all files have been | |
44 | processed, \fBbc\fR reads from the standard input. All code is | |
45 | executed as it is read. (If a file contains a command to halt the | |
46 | processor, \fBbc\fR will never read from the standard input.) | |
47 | .PP | |
48 | This version of \fBbc\fR contains several extensions beyond | |
49 | traditional \fBbc\fR implementations and the POSIX draft standard. | |
50 | Command line options can cause these extensions to print a warning | |
51 | or to be rejected. This | |
52 | document describes the language accepted by this processor. | |
53 | Extensions will be identified as such. | |
54 | .SS OPTIONS | |
55 | .IP -l | |
56 | Define the standard math library. | |
57 | .IP -w | |
58 | Give warnings for extensions to POSIX \fBbc\fR. | |
59 | .IP -s | |
60 | Process exactly the POSIX \fBbc\fR language. | |
61 | .SS NUMBERS | |
62 | The most basic element in \fBbc\fR is the number. Numbers are | |
63 | arbitrary precision numbers. This precision is both in the integer | |
64 | part and the fractional part. All numbers are represented internally | |
65 | in decimal and all computation is done in decimal. (This version | |
66 | truncates results from divide and multiply operations.) There are two | |
67 | attributes of numbers, the length and the scale. The length is the | |
68 | total number of significant decimal digits in a number and the scale | |
69 | is the total number of decimal digits after the decimal point. For | |
70 | example: | |
71 | .nf | |
72 | .RS | |
73 | .000001 has a length of 6 and scale of 6. | |
74 | 1935.000 has a length of 7 and a scale of 3. | |
75 | .RE | |
76 | .fi | |
77 | .SS VARIABLES | |
78 | Numbers are stored in two types of variables, simple variables and | |
79 | arrays. Both simple variables and array variables are named. Names | |
80 | begin with a letter followed by any number of letters, digits and | |
81 | underscores. All letters must be lower case. (Full alpha-numeric | |
82 | names are an extension. In POSIX \fBbc\fR all names are a single | |
83 | lower case letter.) The type of variable is clear by the context | |
84 | because all array variable names will be followed by brackets ([]). | |
85 | .PP | |
86 | There are four special variables, \fBscale, ibase, obase,\fR and | |
87 | \fBlast\fR. \fBscale\fR defines how some operations use digits after the | |
88 | decimal point. The default value of \fBscale\fR is 0. \fBibase\fR | |
89 | and \fBobase\fR define the conversion base for input and output | |
90 | numbers. The default for both input and output is base 10. | |
91 | \fBlast\fR (an extension) is a variable that has the value of the last | |
92 | printed number. These will be discussed in further detail where | |
93 | appropriate. All of these variables may have values assigned to them | |
94 | as well as used in expressions. | |
95 | .SS COMMENTS | |
96 | Comments in \fBbc\fR start with the characters \fB/*\fR and end with | |
97 | the characters \fB*/\fR. Comments may start anywhere and appear as a | |
98 | single space in the input. (This causes comments to delimit other | |
99 | input items. For example, a comment can not be found in the middle of | |
100 | a variable name.) Comments include any newlines (end of line) between | |
101 | the start and the end of the comment. | |
102 | .SS EXPRESSIONS | |
103 | The numbers are manipulated by expressions and statements. Since | |
104 | the language was designed to be interactive, statements and expressions | |
105 | are executed as soon as possible. There is no "main" program. Instead, | |
106 | code is executed as it is encountered. (Functions, discussed in | |
107 | detail later, are defined when encountered.) | |
108 | .PP | |
109 | A simple expression is just a constant. \fBbc\fR converts constants | |
110 | into internal decimal numbers using the current input base, specified | |
111 | by the variable \fBibase\fR. (There is an exception in functions.) | |
112 | The legal values of \fBibase\fR are 2 through 16 (F). Assigning a | |
113 | value outside this range to \fBibase\fR will result in a value of 2 | |
114 | or 16. Input numbers may contain the characters 0-9 and A-F. (Note: | |
115 | They must be capitals. Lower case letters are variable names.) | |
116 | Single digit numbers always have the value of the digit regardless of | |
117 | the value of \fBibase\fR. (i.e. A = 10.) For multi-digit numbers, | |
118 | \fBbc\fR changes all input digits greater or equal to ibase to the | |
119 | value of \fBibase\fR-1. This makes the number \fBFFF\fR always be | |
120 | the largest 3 digit number of the input base. | |
121 | .PP | |
122 | Full expressions are similar to many other high level languages. | |
123 | Since there is only one kind of number, there are no rules for mixing | |
124 | types. Instead, there are rules on the scale of expressions. Every | |
125 | expression has a scale. This is derived from the scale of original | |
126 | numbers, the operation performed and in many cases, the value of the | |
127 | variable \fBscale\fR. Legal values of the variable \fBscale\fR are | |
128 | 0 to the maximum number representable by a C integer. | |
129 | .PP | |
130 | In the following descriptions of legal expressions, "expr" refers to a | |
131 | complete expression and "var" refers to a simple or an array variable. | |
132 | A simple variable is just a | |
133 | .RS | |
134 | \fIname\fR | |
135 | .RE | |
136 | and an array variable is specified as | |
137 | .RS | |
138 | \fIname\fR[\fIexpr\fR] | |
139 | .RE | |
140 | Unless specifically | |
141 | mentioned the scale of the result is the maximum scale of the | |
142 | expressions involved. | |
143 | .IP "- expr" | |
144 | The result is the negation of the expression. | |
145 | .IP "++ var" | |
146 | The variable is incremented by one and the new value is the result of | |
147 | the expression. | |
148 | .IP "-- var" | |
149 | The variable | |
150 | is decremented by one and the new value is the result of the | |
151 | expression. | |
152 | .IP "var ++" | |
153 | The result of the expression is the value of | |
154 | the variable and then the variable is incremented by one. | |
155 | .IP "var --" | |
156 | The result of the expression is the value of the variable and then | |
157 | the variable is decremented by one. | |
158 | .IP "expr + expr" | |
159 | The result of the expression is the sum of the two expressions. | |
160 | .IP "expr - expr" | |
161 | The result of the expression is the difference of the two expressions. | |
162 | .IP "expr * expr" | |
163 | The result of the expression is the product of the two expressions. | |
164 | .IP "expr / expr" | |
165 | The result of the expression is the quotient of the two expressions. | |
166 | The scale of the result is the value of the variable \fBscale\fR. | |
167 | .IP "expr % expr" | |
168 | The result of the expression is the "remainder" and it is computed in the | |
169 | following way. To compute a%b, first a/b is computed to \fBscale\fR | |
170 | digits. That result is used to compute a-(a/b)*b to the scale of the | |
171 | maximum of \fBscale\fR+scale(b) and scale(a). If \fBscale\fR is set | |
172 | to zero and both expressions are integers this expression is the | |
173 | integer remainder function. | |
174 | .IP "expr ^ expr" | |
175 | The result of the expression is the value of the first raised to the | |
176 | second. The second expression must be an integer. (If the second | |
177 | expression is not an integer, a warning is generated and the | |
178 | expression is truncated to get an integer value.) The scale of the | |
179 | result is \fBscale\fR if the exponent is negative. If the exponent | |
180 | is positive the scale of the result is the minimum of the scale of the | |
181 | first expression times the value of the exponent and the maximum of | |
182 | \fBscale\fR and the scale of the first expression. (e.g. scale(a^b) | |
183 | = min(scale(a)*b, max( \fBscale,\fR scale(a))).) It should be noted | |
184 | that expr^0 will always return the value of 1. | |
185 | .IP "( expr )" | |
186 | This alters the standard precedence to force the evaluation of the | |
187 | expression. | |
188 | .IP "var = expr" | |
189 | The variable is assigned the value of the expression. | |
190 | .IP "var <op>= expr" | |
191 | This is equivalent to "var = var <op> expr" with the exception that | |
192 | the "var" part is evaluated only once. This can make a difference if | |
193 | "var" is an array. | |
194 | .PP | |
195 | Relational expressions are a special kind of expression | |
196 | that always evaluate to 0 or 1, 0 if the relation is false and 1 if | |
197 | the relation is true. These may appear in any legal expression. | |
198 | (POSIX bc requires that relational expressions are used only in if, | |
199 | while, and for statements and that only one relational test may be | |
200 | done in them.) The relational operators are | |
201 | .IP "expr1 < expr2" | |
202 | The result is 1 if expr1 is strictly less than expr2. | |
203 | .IP "expr1 <= expr2" | |
204 | The result is 1 if expr1 is less than or equal to expr2. | |
205 | .IP "expr1 > expr2" | |
206 | The result is 1 if expr1 is strictly greater than expr2. | |
207 | .IP "expr1 >= expr2" | |
208 | The result is 1 if expr1 is greater than or equal to expr2. | |
209 | .IP "expr1 == expr2" | |
210 | The result is 1 if expr1 is equal to expr2. | |
211 | .IP "expr1 != expr2" | |
212 | The result is 1 if expr1 is not equal to expr2. | |
213 | .PP | |
214 | Boolean operations are also legal. (POSIX \fBbc\fR does NOT have | |
215 | boolean operations). The result of all boolean operations are 0 and 1 | |
216 | (for false and true) as in relational expressions. The boolean | |
217 | operators are: | |
218 | .IP "!expr" | |
219 | The result is 1 if expr is 0. | |
220 | .IP "expr && expr" | |
221 | The result is 1 if both expressions are non-zero. | |
222 | .IP "expr || expr" | |
223 | The result is 1 if either expression is non-zero. | |
224 | .PP | |
225 | The expression precedence is as follows: (lowest to highest) | |
226 | .nf | |
227 | .RS | |
228 | || operator, left associative | |
229 | && operator, left associative | |
230 | ! operator, nonassociative | |
231 | Relational operators, left associative | |
232 | Assignment operator, right associative | |
233 | + and - operators, left associative | |
234 | *, / and % operators, left associative | |
235 | ^ operator, right associative | |
236 | unary - operator, nonassociative | |
237 | ++ and -- operators, nonassociative | |
238 | .RE | |
239 | .fi | |
240 | .PP | |
241 | This precedence was chosen so that POSIX compliant \fBbc\fR programs | |
242 | will run correctly. This will cause the use of the relational and | |
243 | logical operators to have some unusual behavior when used with | |
244 | assignment expressions. Consider the expression: | |
245 | .RS | |
246 | a = 3 < 5 | |
247 | .RE | |
248 | .PP | |
249 | Most C programmers would assume this would assign the result of "3 < | |
250 | 5" (the value 1) to the variable "a". What this does in \fBbc\fR is | |
251 | assign the value 3 to the variable "a" and then compare 3 to 5. It is | |
252 | best to use parenthesis when using relational and logical operators | |
253 | with the assignment operators. | |
254 | .PP | |
255 | There are a few more special expressions that are provided in \fBbc\fR. | |
256 | These have to do with user defined functions and standard | |
257 | functions. They all appear as "\fIname\fB(\fIparameters\fB)\fR". | |
258 | See the section on functions for user defined functions. The standard | |
259 | functions are: | |
260 | .IP "length ( expression )" | |
261 | The value of the length function is the number of significant digits in the | |
262 | expression. | |
263 | .IP "read ( )" | |
264 | The read function (an extension) will read a number from the standard | |
265 | input, regardless of where the function occurs. Beware, this can | |
266 | cause problems with the mixing of data and program in the standard input. | |
267 | The best use for this function is in a previously written program that | |
268 | needs input from the user, but never allows program code to be input | |
269 | from the user. The value of the read function is the number read from | |
270 | the standard input using the current value of the variable | |
271 | \fBibase\fR for the conversion base. | |
272 | .IP "scale ( expression )" | |
273 | The value of the scale function is the number of digits after the decimal | |
274 | point in the expression. | |
275 | .IP "sqrt ( expression )" | |
276 | The value of the sqrt function is the square root of the expression. If | |
277 | the expression is negative, a run time error is generated. | |
278 | .SS STATEMENTS | |
279 | Statements (as in most algebraic languages) provide the sequencing of | |
280 | expression evaluation. In \fBbc\fR statements are executed "as soon | |
281 | as possible." Execution happens when a newline in encountered and | |
282 | there is one or more complete statements. Due to this immediate | |
283 | execution, newlines are very important in \fBbc\fR. In fact, both a | |
284 | semicolon and a newline are used as statement separators. An | |
285 | improperly placed newline will cause a syntax error. Because newlines | |
286 | are statement separators, it is possible to hide a newline by using | |
287 | the backslash character. The sequence "\e<nl>", where <nl> is the | |
288 | newline appears to \fBbc\fR as whitespace instead of a newline. A | |
289 | statement list is a series of statements separated by semicolons and | |
290 | newlines. The following is a list of \fBbc\fR statements and what | |
291 | they do: (Things enclosed in brackets ([]) are optional parts of the | |
292 | statement.) | |
293 | .IP "expression" | |
294 | This statement does one of two things. If the expression starts with | |
295 | "<variable> <assignment> ...", it is considered to be an assignment | |
296 | statement. If the expression is not an assignment statement, the | |
297 | expression is evaluated and printed to the output. After the number | |
298 | is printed, a newline is printed. For example, "a=1" is an assignment | |
299 | statement and "(a=1)" is an expression that has an embedded | |
300 | assignment. All numbers that are printed are printed in the base | |
301 | specified by the variable \fBobase\fR. The legal values for \fB | |
302 | obase\fR are 2 through BC_BASE_MAX. (See the section LIMITS.) For | |
303 | bases 2 through 16, the usual method of writing numbers is used. For | |
304 | bases greater than 16, \fBbc\fR uses a multi-character digit method | |
305 | of printing the numbers where each higher base digit is printed as a | |
306 | base 10 number. The multi-character digits are separated by spaces. | |
307 | Each digit contains the number of characters required to represent the | |
308 | base ten value of "obase-1". Since numbers are of arbitrary | |
309 | precision, some numbers may not be printable on a single output line. | |
310 | These long numbers will be split across lines using the "\e" as the | |
311 | last character on a line. The maximum number of characters printed | |
312 | per line is 70. Due to the interactive nature of \fBbc\fR printing | |
313 | a number cause the side effect of assigning the printed value the the | |
314 | special variable \fBlast\fR. This allows the user to recover the | |
315 | last value printed without having to retype the expression that | |
316 | printed the number. Assigning to \fBlast\fR is legal and will | |
317 | overwrite the last printed value with the assigned value. The newly | |
318 | assigned value will remain until the next number is printed or another | |
319 | value is assigned to \fBlast\fR. | |
320 | .IP "string" | |
321 | The string is printed to the output. Strings start with a double quote | |
322 | character and contain all characters until the next double quote character. | |
323 | All characters are take literally, including any newline. No newline | |
324 | character is printed after the string. | |
325 | .IP "\fBprint\fR list" | |
326 | The print statement (an extension) provides another method of output. | |
327 | The "list" is a list of strings and expressions separated by commas. | |
328 | Each string or expression is printed in the order of the list. No | |
329 | terminating newline is printed. Expressions are evaluated and their | |
330 | value is printed and assigned the the variable \fBlast\fR. Strings | |
331 | in the print statement are printed to the output and may contain | |
332 | special characters. Special characters start with the backslash | |
333 | character (\e). The special characters recognized by \fBbc\fR are | |
334 | "b" (bell), "f" (form feed), "n" (newline), "r" (carriage return), "t" | |
335 | (tab), and "\e" (backslash). Any other character following the | |
336 | backslash will be ignored. This still does not allow the double quote | |
337 | character to be part of any string. | |
338 | .IP "{ statement_list }" | |
339 | This is the compound statement. It allows multiple statements to be | |
340 | grouped together for execution. | |
341 | .IP "\fBif\fR ( expression ) \fBthen\fR statement1 [\fBelse\fR statement2]" | |
342 | The if statement evaluates the expression and executes statement1 or | |
343 | statement2 depending on the value of the expression. If the expression | |
344 | is non-zero, statement1 is executed. If statement2 is present and | |
345 | the value of the expression is 0, then statement2 is executed. (The | |
346 | else clause is an extension.) | |
347 | .IP "\fBwhile\fR ( expression ) statement" | |
348 | The while statement will execute the statement while the expression | |
349 | is non-zero. It evaluates the expression before each execution of | |
350 | the statement. Termination of the loop is caused by a zero | |
351 | expression value or the execution of a break statement. | |
352 | .IP "\fBfor\fR ( [expression1] ; [expression2] ; [expression3] ) statement" | |
353 | The for statement controls repeated execution of the statement. | |
354 | Expression1 is evaluated before the loop. Expression2 is evaluated | |
355 | before each execution of the statement. If it is non-zero, the statement | |
356 | is evaluated. If it is zero, the loop is terminated. After each | |
357 | execution of the statement, expression3 is evaluated before the reevaluation | |
358 | of expression2. If expression1 or expression3 are missing, nothing is | |
359 | evaluated at the point they would be evaluated. | |
360 | If expression2 is missing, it is the same as substituting | |
361 | the value 1 for expression2. (The optional expressions are an | |
362 | extension. POSIX \fBbc\fR requires all three expressions.) | |
363 | The following is equivalent code for the for statement: | |
364 | .nf | |
365 | .RS | |
366 | expression1; | |
367 | while (expression2) { | |
368 | statement; | |
369 | expression3; | |
370 | } | |
371 | .RE | |
372 | .fi | |
373 | .IP "\fBbreak\fR" | |
374 | This statement causes a forced exit of the most recent enclosing while | |
375 | statement or for statement. | |
376 | .IP "\fBcontinue\fR" | |
377 | The continue statement (an extension) causes the most recent enclosing | |
378 | for statement to start the next iteration. | |
379 | .IP "\fBhalt\fR" | |
380 | The halt statement (an extension) is an executed statement that causes | |
381 | the \fBbc\fR processor to quit only when it is executed. For example, | |
382 | "if (0 == 1) halt" will not cause \fBbc\fR to terminate because the halt is | |
383 | not executed. | |
384 | .IP "\fBreturn\fR" | |
385 | Return the value 0 from a function. (See the section on functions.) | |
386 | .IP "\fBreturn\fR ( expression )" | |
387 | Return the value of the expression from a function. (See the section on | |
388 | functions.) | |
389 | .SS PSEUDO STATEMENTS | |
390 | These statements are not statements in the traditional sense. They are | |
391 | not executed statements. Their function is performed at "compile" time. | |
392 | .IP "\fBlimits\fR" | |
393 | Print the local limits enforced by the local version of \fBbc\fR. This | |
394 | is an extension. | |
395 | .IP "\fBquit\fR" | |
396 | When the quit statement is read, the \fBbc\fR processor | |
397 | is terminated, regardless of where the quit statement is found. For | |
398 | example, "if (0 == 1) quit" will cause \fBbc\fR to terminate. | |
399 | .IP "\fBwarranty\fR" | |
400 | Print a longer warranty notice. This is an extension. | |
401 | .SS FUNCTIONS | |
402 | Functions provide a method of defining a computation that can be executed | |
403 | later. Functions in | |
404 | .B bc | |
405 | always compute a value and return it to the caller. Function definitions | |
406 | are "dynamic" in the sense that a function is undefined until a definition | |
407 | is encountered in the input. That definition is then used until another | |
408 | definition function for the same name is encountered. The new definition | |
409 | then replaces the older definition. A function is defined as follows: | |
410 | .nf | |
411 | .RS | |
412 | \fBdefine \fIname \fB( \fIparameters \fB) { \fInewline | |
413 | \fI auto_list statement_list \fB}\fR | |
414 | .RE | |
415 | .fi | |
416 | A function call is just an expression of the form | |
417 | "\fIname\fB(\fIparameters\fB)\fR". | |
418 | .PP | |
419 | Parameters are numbers or arrays (an extension). In the function definition, | |
420 | zero or more parameters are defined by listing their names separated by | |
421 | commas. Numbers are only call by value parameters. Arrays are only | |
422 | call by variable. Arrays are specified in the parameter definition by | |
423 | the notation "\fIname\fB[]\fR". In the function call, actual parameters | |
424 | are full expressions for number parameters. The same notation is used | |
425 | for passing arrays as for defining array parameters. The named array is | |
426 | passed by variable to the function. Since function definitions are dynamic, | |
427 | parameter numbers and types are checked when a function is called. Any | |
428 | mismatch in number or types of parameters will cause a runtime error. | |
429 | A runtime error will also occur for the call to an undefined function. | |
430 | .PP | |
78ed81a3 | 431 | The \fIauto_list\fR is an optional list of variables that are for |
11823ed9 PR |
432 | "local" use. The syntax of the auto list (if present) is "\fBauto |
433 | \fIname\fR, ... ;". (The semicolon is optional.) Each \fIname\fR is | |
434 | the name of an auto variable. Arrays may be specified by using the | |
435 | same notation as used in parameters. These variables have their | |
436 | values pushed onto a stack at the start of the function. The | |
437 | variables are then initialized to zero and used throughout the | |
438 | execution of the function. At function exit, these variables are | |
439 | popped so that the original value (at the time of the function call) | |
440 | of these variables are restored. The parameters are really auto | |
441 | variables that are initialized to a value provided in the function | |
442 | call. Auto variables are different than traditional local variables | |
443 | in the fact that if function A calls function B, B may access function | |
444 | A's auto variables by just using the same name, unless function B has | |
445 | called them auto variables. Due to the fact that auto variables and | |
446 | parameters are pushed onto a stack, \fBbc\fR supports recursive functions. | |
447 | .PP | |
448 | The function body is a list of \fBbc\fR statements. Again, statements | |
449 | are separated by semicolons or newlines. Return statements cause the | |
450 | termination of a function and the return of a value. There are two | |
451 | versions of the return statement. The first form, "\fBreturn\fR", returns | |
452 | the value 0 to the calling expression. The second form, | |
453 | "\fBreturn ( \fIexpression \fB)\fR", computes the value of the expression | |
454 | and returns that value to the calling expression. There is an implied | |
455 | "\fBreturn (0)\fR" at the end of every function. This allows a function | |
456 | to terminate and return 0 without an explicit return statement. | |
457 | .PP | |
458 | Functions also change the usage of the variable \fBibase\fR. All | |
459 | constants in the function body will be converted using the value of | |
460 | \fBibase\fR at the time of the function call. Changes of \fBibase\fR | |
461 | will be ignored during the execution of the function except for the | |
462 | standard function \fBread\fR, which will always use the current value | |
463 | of \fBibase\fR for conversion of numbers. | |
464 | .SS MATH LIBRARY | |
465 | If \fBbc\fR is invoked with the \fB-l\fR option, a math library is preloaded | |
466 | and the default scale is set to 20. The math functions will calculate their | |
467 | results to the scale set at the time of their call. | |
468 | The math library defines the following functions: | |
469 | .IP "s (\fIx\fR)" | |
470 | The sine of x in radians. | |
471 | .IP "c (\fIx\fR)" | |
472 | The cosine of x in radians. | |
473 | .IP "a (\fIx\fR)" | |
474 | The arctangent of x. | |
475 | .IP "l (\fIx\fR)" | |
476 | The natural logarithm of x. | |
477 | .IP "e (\fIx\fR)" | |
478 | The exponential function of raising e to the value x. | |
479 | .IP "j (\fIn,x\fR)" | |
480 | The bessel function of integer order n of x. | |
481 | .SS EXAMPLES | |
482 | In /bin/sh, the following will assign the value of "pi" to the shell | |
483 | variable \fBpi\fR. | |
484 | .RS | |
485 | \f(CW | |
486 | pi=$(echo "scale=10; 4*a(1)" | bc -l) | |
487 | \fR | |
488 | .RE | |
489 | .PP | |
490 | The following is the definition of the exponential function used in the | |
491 | math library. This function is written in POSIX \fBbc\fR. | |
492 | .nf | |
493 | .RS | |
494 | \f(CW | |
495 | scale = 20 | |
496 | ||
497 | /* Uses the fact that e^x = (e^(x/2))^2 | |
498 | When x is small enough, we use the series: | |
499 | e^x = 1 + x + x^2/2! + x^3/3! + ... | |
500 | */ | |
501 | ||
502 | define e(x) { | |
503 | auto a, d, e, f, i, m, v, z | |
504 | ||
505 | /* Check the sign of x. */ | |
506 | if (x<0) { | |
507 | m = 1 | |
508 | x = -x | |
509 | } | |
510 | ||
511 | /* Precondition x. */ | |
512 | z = scale; | |
513 | scale = 4 + z + .44*x; | |
514 | while (x > 1) { | |
515 | f += 1; | |
516 | x /= 2; | |
517 | } | |
518 | ||
519 | /* Initialize the variables. */ | |
520 | v = 1+x | |
521 | a = x | |
522 | d = 1 | |
523 | ||
524 | for (i=2; 1; i++) { | |
525 | e = (a *= x) / (d *= i) | |
526 | if (e == 0) { | |
527 | if (f>0) while (f--) v = v*v; | |
528 | scale = z | |
529 | if (m) return (1/v); | |
530 | return (v/1); | |
531 | } | |
532 | v += e | |
533 | } | |
534 | } | |
535 | \fR | |
536 | .RE | |
537 | .fi | |
538 | .PP | |
539 | The following is code that uses the extended features of \fBbc\fR to | |
540 | implement a simple program for calculating checkbook balances. This | |
541 | program is best kept in a file so that it can be used many times | |
542 | without having to retype it at every use. | |
543 | .nf | |
544 | .RS | |
545 | \f(CW | |
546 | scale=2 | |
547 | print "\enCheck book program!\en" | |
548 | print " Remember, deposits are negative transactions.\en" | |
549 | print " Exit by a 0 transaction.\en\en" | |
550 | ||
551 | print "Initial balance? "; bal = read() | |
552 | bal /= 1 | |
553 | print "\en" | |
554 | while (1) { | |
555 | "current balance = "; bal | |
556 | "transaction? "; trans = read() | |
557 | if (trans == 0) break; | |
558 | bal -= trans | |
559 | bal /= 1 | |
560 | } | |
561 | quit | |
562 | \fR | |
563 | .RE | |
564 | .fi | |
565 | .PP | |
566 | The following is the definition of the recursive factorial function. | |
567 | .nf | |
568 | .RS | |
569 | \f(CW | |
570 | define f (x) { | |
571 | if (x <= 1) return (1); | |
572 | return (f(x-1) * x); | |
573 | } | |
574 | \fR | |
575 | .RE | |
576 | .fi | |
577 | .SS DIFFERENCES | |
578 | This version of | |
579 | .B bc | |
580 | was implemented from the POSIX P1003.2/D11 draft and contains | |
581 | several differences and extensions relative to the draft and | |
582 | traditional implementations. | |
583 | It is not implemented in the traditional way using | |
584 | .I dc(1). | |
585 | This version is a single process which parses and runs a byte code | |
586 | translation of the program. There is an "undocumented" option (-c) | |
587 | that causes the program to output the byte code to | |
588 | the standard output instead of running it. It was mainly used for | |
589 | debugging the parser and preparing the math library. | |
590 | .PP | |
591 | A major source of differences is | |
592 | extensions, where a feature is extended to add more functionality and | |
593 | additions, where new features are added. | |
594 | The following is the list of differences and extensions. | |
595 | .IP LANG environment | |
596 | This version does not conform to the POSIX standard in the processing | |
597 | of the LANG environment variable and all environment variables starting | |
598 | with LC_. | |
599 | .IP names | |
600 | Traditional and POSIX | |
601 | .B bc | |
602 | have single letter names for functions, variables and arrays. They have | |
603 | been extended to be multi-character names that start with a letter and | |
604 | may contain letters, numbers and the underscore character. | |
605 | .IP Strings | |
606 | Strings are not allowed to contain NUL characters. POSIX says all characters | |
607 | must be included in strings. | |
608 | .IP last | |
609 | POSIX \fBbc\fR does not have a \fBlast\fR variable. Some implementations | |
610 | of \fBbc\fR use the period (.) in a similar way. | |
611 | .IP comparisons | |
612 | POSIX \fBbc\fR allows comparisons only in the if statement, the while | |
613 | statement, and the second expression of the for statement. Also, only | |
614 | one relational operation is allowed in each of those statements. | |
615 | .IP "if statement, else clause" | |
616 | POSIX \fBbc\fR does not have an else clause. | |
617 | .IP "for statement" | |
618 | POSIX \fBbc\fR requires all expressions to be present in the for statement. | |
619 | .IP "&&, ||, !" | |
620 | POSIX \fBbc\fR does not have the logical operators. | |
621 | .IP "read function" | |
622 | POSIX \fBbc\fR does not have a read function. | |
623 | .IP "print statement" | |
624 | POSIX \fBbc\fR does not have a print statement . | |
625 | .IP "continue statement" | |
626 | POSIX \fBbc\fR does not have a continue statement. | |
627 | .IP "array parameters" | |
628 | POSIX \fBbc\fR does not have array parameters. Other implementations | |
629 | of \fBbc\fR may have call by value array parameters. | |
630 | .IP "=+, =-, =*, =/, =%, =^" | |
631 | POSIX \fBbc\fR does not require these "old style" assignment operators to | |
632 | be defined. This version may allow these "old style" assignments. Use | |
633 | the limits statement to see if the installed version supports them. If | |
634 | it does support the "old style" assignment operators, the statement | |
635 | "a =- 1" will decrement \fBa\fR by 1 instead of setting \fBa\fR to the | |
636 | value -1. | |
637 | .IP "spaces in numbers" | |
638 | Other implementations of \fBbc\fR allow spaces in numbers. For example, | |
639 | "x=1 3" would assign the value 13 to the variable x. The same statement | |
640 | would cause a syntax error in this version of \fBbc\fR. | |
641 | .IP "errors and execution" | |
642 | This implementation varies from other implementations in terms of what | |
643 | code will be executed when syntax and other errors are found in the | |
644 | program. If a syntax error is found in a function definition, error | |
645 | recovery tries to find the beginning of a statement and continue to | |
646 | parse the function. Once a syntax error is found in the function, the | |
647 | function will not be callable and becomes undefined. | |
648 | Syntax errors in the interactive execution code will invalidate the | |
649 | current execution block. The execution block is terminated by an | |
650 | end of line that appears after a complete sequence of statements. | |
651 | For example, | |
652 | .nf | |
653 | .RS | |
654 | a = 1 | |
655 | b = 2 | |
656 | .RE | |
657 | .fi | |
658 | has two execution blocks and | |
659 | .nf | |
660 | .RS | |
661 | { a = 1 | |
662 | b = 2 } | |
663 | .RE | |
664 | .fi | |
665 | has one execution block. Any runtime error will terminate the execution | |
666 | of the current execution block. A runtime warning will not terminate the | |
667 | current execution block. | |
668 | .IP "Interrupts" | |
669 | During an interactive session, the SIGINT signal (usually generated by | |
670 | the control-C character from the terminal) will cause execution of the | |
671 | current execution block to be interrupted. It will display a "runtime" | |
672 | error indicating which function was interrupted. After all runtime | |
673 | structures have been cleaned up, a message will be printed to notify the | |
674 | user that \fBbc\fR is ready for more input. All previously defined functions | |
675 | remain defined and the value of all non-auto variables are the value at | |
676 | the point of interruption. All auto variables and function parameters | |
677 | are removed during the | |
678 | clean up process. During a non-interactive | |
679 | session, the SIGINT signal will terminate the entire run of \fBbc\fR. | |
680 | .SS LIMITS | |
681 | The following are the limits currently in place for this | |
682 | .B bc | |
683 | processor. Some of them may have been changed by an installation. | |
684 | Use the limits statement to see the actual values. | |
685 | .IP BC_BASE_MAX | |
686 | The maximum output base is currently set at 999. The maximum input base | |
687 | is 16. | |
688 | .IP BC_DIM_MAX | |
689 | This is currently an arbitrary limit of 65535 as distributed. Your | |
690 | installation may be different. | |
691 | .IP BC_SCALE_MAX | |
692 | The number of digits after the decimal point is limited to INT_MAX digits. | |
693 | Also, the number of digits before the decimal point is limited to INT_MAX | |
694 | digits. | |
695 | .IP BC_STRING_MAX | |
696 | The limit on the number of characters in a string is INT_MAX characters. | |
697 | .IP exponent | |
698 | The value of the exponent in the raise operation (^) is limited to LONG_MAX. | |
699 | .IP multiply | |
700 | The multiply routine may yield incorrect results if a number | |
701 | has more than LONG_MAX / 90 total digits. For 32 bit longs, this number is | |
702 | 23,860,929 digits. | |
703 | .IP "code size" | |
704 | Each function and the "main" program are limited to 10240 bytes of | |
705 | compiled byte code each. This limit (BC_MAX_SEGS) can be easily changed | |
706 | to have more than 10 segments of 1024 bytes. | |
707 | .IP "variable names" | |
708 | The current limit on the number of unique names is 32767 for each of | |
709 | simple variables, arrays and functions. | |
710 | .SH FILES | |
711 | In most installations, \fBbc\fR is completely self-contained. | |
712 | Where executable size is of importance or the C compiler does | |
713 | not deal with very long strings, \fBbc\fR will read | |
714 | the standard math library from the file /usr/local/lib/libmath.b. | |
715 | (The actual location may vary. It may be /lib/libmath.b.) | |
716 | .SH DIAGNOSTICS | |
717 | If any file on the command line can not be opened, \fBbc\fR will report | |
718 | that the file is unavailable and terminate. Also, there are compile | |
719 | and run time diagnostics that should be self-explanatory. | |
720 | .SH BUGS | |
721 | Error recovery is not very good yet. | |
722 | .SH AUTHOR | |
723 | .nf | |
724 | Philip A. Nelson | |
725 | phil@cs.wwu.edu | |
726 | .fi | |
727 | .SH ACKNOWLEDGEMENTS | |
728 | The author would like to thank Steve Sommars (sesv@iwtsf.att.com) for | |
729 | his extensive help in testing the implementation. Many great suggestions | |
730 | were given. This is a much better product due to his involvement. |