Commit | Line | Data |
---|---|---|

984263bc MD |
1 | .\" |

2 | .\" bc.1 - the *roff document processor source for the bc manual | |

3 | .\" | |

4 | .\" This file is part of GNU bc. | |

5 | .\" Copyright (C) 1991-1994, 1997, 2000 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, Inc. | |

20 | .\" 59 Temple Place, Suite 330 | |

21 | .\" Boston, MA 02111 USA | |

22 | .\" | |

23 | .\" You may contact the author by: | |

24 | .\" e-mail: philnelson@acm.org | |

25 | .\" us-mail: Philip A. Nelson | |

26 | .\" Computer Science Department, 9062 | |

27 | .\" Western Washington University | |

28 | .\" Bellingham, WA 98226-9062 | |

29 | .\" | |

30 | .\" $FreeBSD: src/contrib/bc/doc/bc.1,v 1.4.6.2 2002/07/29 07:41:24 ru Exp $ | |

1de703da | 31 | .\" $DragonFly: src/contrib/bc/doc/Attic/bc.1,v 1.2 2003/06/17 04:23:58 dillon Exp $ |

984263bc MD |
32 | .\" |

33 | .TH bc 1 .\" "Command Manual" v1.06 "Sept 12, 2000" | |

34 | .SH NAME | |

35 | bc - An arbitrary precision calculator language | |

36 | .SH SYNTAX | |

37 | \fBbc\fR [ \fB-hlwsqv\fR ] [long-options] [ \fI file ...\fR ] | |

38 | .SH VERSION | |

39 | This man page documents GNU bc version 1.06. | |

40 | .SH DESCRIPTION | |

41 | \fBbc\fR is a language that supports arbitrary precision numbers | |

42 | with interactive execution of statements. There are some similarities | |

43 | in the syntax to the C programming language. | |

44 | A standard math library is available by command line option. | |

45 | If requested, the math library is defined before processing any files. | |

46 | \fBbc\fR starts by processing code from all the files listed | |

47 | on the command line in the order listed. After all files have been | |

48 | processed, \fBbc\fR reads from the standard input. All code is | |

49 | executed as it is read. (If a file contains a command to halt the | |

50 | processor, \fBbc\fR will never read from the standard input.) | |

51 | .PP | |

52 | This version of \fBbc\fR contains several extensions beyond | |

53 | traditional \fBbc\fR implementations and the POSIX draft standard. | |

54 | Command line options can cause these extensions to print a warning | |

55 | or to be rejected. This | |

56 | document describes the language accepted by this processor. | |

57 | Extensions will be identified as such. | |

58 | .SS OPTIONS | |

59 | .IP "-h, --help" | |

60 | Print the usage and exit. | |

61 | .IP "-i, --interactive" | |

62 | Force interactive mode. | |

63 | .IP "-l, --mathlib" | |

64 | Define the standard math library. | |

65 | .IP "-w, --warn" | |

66 | Give warnings for extensions to POSIX \fBbc\fR. | |

67 | .IP "-s, --standard" | |

68 | Process exactly the POSIX \fBbc\fR language. | |

69 | .IP "-q, --quiet" | |

70 | Do not print the normal GNU bc welcome. | |

71 | .IP "-v, --version" | |

72 | Print the version number and copyright and quit. | |

73 | .SS NUMBERS | |

74 | The most basic element in \fBbc\fR is the number. Numbers are | |

75 | arbitrary precision numbers. This precision is both in the integer | |

76 | part and the fractional part. All numbers are represented internally | |

77 | in decimal and all computation is done in decimal. (This version | |

78 | truncates results from divide and multiply operations.) There are two | |

79 | attributes of numbers, the length and the scale. The length is the | |

80 | total number of significant decimal digits in a number and the scale | |

81 | is the total number of decimal digits after the decimal point. For | |

82 | example: | |

83 | .nf | |

84 | .RS | |

85 | .000001 has a length of 6 and scale of 6. | |

86 | 1935.000 has a length of 7 and a scale of 3. | |

87 | .RE | |

88 | .fi | |

89 | .SS VARIABLES | |

90 | Numbers are stored in two types of variables, simple variables and | |

91 | arrays. Both simple variables and array variables are named. Names | |

92 | begin with a letter followed by any number of letters, digits and | |

93 | underscores. All letters must be lower case. (Full alpha-numeric | |

94 | names are an extension. In POSIX \fBbc\fR all names are a single | |

95 | lower case letter.) The type of variable is clear by the context | |

96 | because all array variable names will be followed by brackets ([]). | |

97 | .PP | |

98 | There are four special variables, \fBscale, ibase, obase,\fR and | |

99 | \fBlast\fR. \fBscale\fR defines how some operations use digits after the | |

100 | decimal point. The default value of \fBscale\fR is 0. \fBibase\fR | |

101 | and \fBobase\fR define the conversion base for input and output | |

102 | numbers. The default for both input and output is base 10. | |

103 | \fBlast\fR (an extension) is a variable that has the value of the last | |

104 | printed number. These will be discussed in further detail where | |

105 | appropriate. All of these variables may have values assigned to them | |

106 | as well as used in expressions. | |

107 | .SS COMMENTS | |

108 | Comments in \fBbc\fR start with the characters \fB/*\fR and end with | |

109 | the characters \fB*/\fR. Comments may start anywhere and appear as a | |

110 | single space in the input. (This causes comments to delimit other | |

111 | input items. For example, a comment can not be found in the middle of | |

112 | a variable name.) Comments include any newlines (end of line) between | |

113 | the start and the end of the comment. | |

114 | .PP | |

115 | To support the use of scripts for \fBbc\fR, a single line comment has been | |

116 | added as an extension. A single line comment starts at a \fB#\fR | |

117 | character and continues to the next end of the line. The end of line | |

118 | character is not part of the comment and is processed normally. | |

119 | .SS EXPRESSIONS | |

120 | The numbers are manipulated by expressions and statements. Since | |

121 | the language was designed to be interactive, statements and expressions | |

122 | are executed as soon as possible. There is no "main" program. Instead, | |

123 | code is executed as it is encountered. (Functions, discussed in | |

124 | detail later, are defined when encountered.) | |

125 | .PP | |

126 | A simple expression is just a constant. \fBbc\fR converts constants | |

127 | into internal decimal numbers using the current input base, specified | |

128 | by the variable \fBibase\fR. (There is an exception in functions.) | |

129 | The legal values of \fBibase\fR are 2 through 16. Assigning a | |

130 | value outside this range to \fBibase\fR will result in a value of 2 | |

131 | or 16. Input numbers may contain the characters 0-9 and A-F. (Note: | |

132 | They must be capitals. Lower case letters are variable names.) | |

133 | Single digit numbers always have the value of the digit regardless of | |

134 | the value of \fBibase\fR. (i.e. A = 10.) For multi-digit numbers, | |

135 | \fBbc\fR changes all input digits greater or equal to ibase to the | |

136 | value of \fBibase\fR-1. This makes the number \fBFFF\fR always be | |

137 | the largest 3 digit number of the input base. | |

138 | .PP | |

139 | Full expressions are similar to many other high level languages. | |

140 | Since there is only one kind of number, there are no rules for mixing | |

141 | types. Instead, there are rules on the scale of expressions. Every | |

142 | expression has a scale. This is derived from the scale of original | |

143 | numbers, the operation performed and in many cases, the value of the | |

144 | variable \fBscale\fR. Legal values of the variable \fBscale\fR are | |

145 | 0 to the maximum number representable by a C integer. | |

146 | .PP | |

147 | In the following descriptions of legal expressions, "expr" refers to a | |

148 | complete expression and "var" refers to a simple or an array variable. | |

149 | A simple variable is just a | |

150 | .RS | |

151 | \fIname\fR | |

152 | .RE | |

153 | and an array variable is specified as | |

154 | .RS | |

155 | \fIname\fR[\fIexpr\fR] | |

156 | .RE | |

157 | Unless specifically | |

158 | mentioned the scale of the result is the maximum scale of the | |

159 | expressions involved. | |

160 | .IP "- expr" | |

161 | The result is the negation of the expression. | |

162 | .IP "++ var" | |

163 | The variable is incremented by one and the new value is the result of | |

164 | the expression. | |

165 | .IP "-- var" | |

166 | The variable | |

167 | is decremented by one and the new value is the result of the | |

168 | expression. | |

169 | .IP "var ++" | |

170 | The result of the expression is the value of | |

171 | the variable and then the variable is incremented by one. | |

172 | .IP "var --" | |

173 | The result of the expression is the value of the variable and then | |

174 | the variable is decremented by one. | |

175 | .IP "expr + expr" | |

176 | The result of the expression is the sum of the two expressions. | |

177 | .IP "expr - expr" | |

178 | The result of the expression is the difference of the two expressions. | |

179 | .IP "expr * expr" | |

180 | The result of the expression is the product of the two expressions. | |

181 | .IP "expr / expr" | |

182 | The result of the expression is the quotient of the two expressions. | |

183 | The scale of the result is the value of the variable \fBscale\fR. | |

184 | .IP "expr % expr" | |

185 | The result of the expression is the "remainder" and it is computed in the | |

186 | following way. To compute a%b, first a/b is computed to \fBscale\fR | |

187 | digits. That result is used to compute a-(a/b)*b to the scale of the | |

188 | maximum of \fBscale\fR+scale(b) and scale(a). If \fBscale\fR is set | |

189 | to zero and both expressions are integers this expression is the | |

190 | integer remainder function. | |

191 | .IP "expr ^ expr" | |

192 | The result of the expression is the value of the first raised to the | |

193 | second. The second expression must be an integer. (If the second | |

194 | expression is not an integer, a warning is generated and the | |

195 | expression is truncated to get an integer value.) The scale of the | |

196 | result is \fBscale\fR if the exponent is negative. If the exponent | |

197 | is positive the scale of the result is the minimum of the scale of the | |

198 | first expression times the value of the exponent and the maximum of | |

199 | \fBscale\fR and the scale of the first expression. (e.g. scale(a^b) | |

200 | = min(scale(a)*b, max( \fBscale,\fR scale(a))).) It should be noted | |

201 | that expr^0 will always return the value of 1. | |

202 | .IP "( expr )" | |

203 | This alters the standard precedence to force the evaluation of the | |

204 | expression. | |

205 | .IP "var = expr" | |

206 | The variable is assigned the value of the expression. | |

207 | .IP "var <op>= expr" | |

208 | This is equivalent to "var = var <op> expr" with the exception that | |

209 | the "var" part is evaluated only once. This can make a difference if | |

210 | "var" is an array. | |

211 | .PP | |

212 | Relational expressions are a special kind of expression | |

213 | that always evaluate to 0 or 1, 0 if the relation is false and 1 if | |

214 | the relation is true. These may appear in any legal expression. | |

215 | (POSIX bc requires that relational expressions are used only in if, | |

216 | while, and for statements and that only one relational test may be | |

217 | done in them.) The relational operators are | |

218 | .IP "expr1 < expr2" | |

219 | The result is 1 if expr1 is strictly less than expr2. | |

220 | .IP "expr1 <= expr2" | |

221 | The result is 1 if expr1 is less than or equal to expr2. | |

222 | .IP "expr1 > expr2" | |

223 | The result is 1 if expr1 is strictly greater than expr2. | |

224 | .IP "expr1 >= expr2" | |

225 | The result is 1 if expr1 is greater than or equal to expr2. | |

226 | .IP "expr1 == expr2" | |

227 | The result is 1 if expr1 is equal to expr2. | |

228 | .IP "expr1 != expr2" | |

229 | The result is 1 if expr1 is not equal to expr2. | |

230 | .PP | |

231 | Boolean operations are also legal. (POSIX \fBbc\fR does NOT have | |

232 | boolean operations). The result of all boolean operations are 0 and 1 | |

233 | (for false and true) as in relational expressions. The boolean | |

234 | operators are: | |

235 | .IP "!expr" | |

236 | The result is 1 if expr is 0. | |

237 | .IP "expr && expr" | |

238 | The result is 1 if both expressions are non-zero. | |

239 | .IP "expr || expr" | |

240 | The result is 1 if either expression is non-zero. | |

241 | .PP | |

242 | The expression precedence is as follows: (lowest to highest) | |

243 | .nf | |

244 | .RS | |

245 | || operator, left associative | |

246 | && operator, left associative | |

247 | ! operator, nonassociative | |

248 | Relational operators, left associative | |

249 | Assignment operator, right associative | |

250 | + and - operators, left associative | |

251 | *, / and % operators, left associative | |

252 | ^ operator, right associative | |

253 | unary - operator, nonassociative | |

254 | ++ and -- operators, nonassociative | |

255 | .RE | |

256 | .fi | |

257 | .PP | |

258 | This precedence was chosen so that POSIX compliant \fBbc\fR programs | |

259 | will run correctly. This will cause the use of the relational and | |

260 | logical operators to have some unusual behavior when used with | |

261 | assignment expressions. Consider the expression: | |

262 | .RS | |

263 | a = 3 < 5 | |

264 | .RE | |

265 | .PP | |

266 | Most C programmers would assume this would assign the result of "3 < | |

267 | 5" (the value 1) to the variable "a". What this does in \fBbc\fR is | |

268 | assign the value 3 to the variable "a" and then compare 3 to 5. It is | |

269 | best to use parenthesis when using relational and logical operators | |

270 | with the assignment operators. | |

271 | .PP | |

272 | There are a few more special expressions that are provided in \fBbc\fR. | |

273 | These have to do with user defined functions and standard | |

274 | functions. They all appear as "\fIname\fB(\fIparameters\fB)\fR". | |

275 | See the section on functions for user defined functions. The standard | |

276 | functions are: | |

277 | .IP "length ( expression )" | |

278 | The value of the length function is the number of significant digits in the | |

279 | expression. | |

280 | .IP "read ( )" | |

281 | The read function (an extension) will read a number from the standard | |

282 | input, regardless of where the function occurs. Beware, this can | |

283 | cause problems with the mixing of data and program in the standard input. | |

284 | The best use for this function is in a previously written program that | |

285 | needs input from the user, but never allows program code to be input | |

286 | from the user. The value of the read function is the number read from | |

287 | the standard input using the current value of the variable | |

288 | \fBibase\fR for the conversion base. | |

289 | .IP "scale ( expression )" | |

290 | The value of the scale function is the number of digits after the decimal | |

291 | point in the expression. | |

292 | .IP "sqrt ( expression )" | |

293 | The value of the sqrt function is the square root of the expression. If | |

294 | the expression is negative, a run time error is generated. | |

295 | .SS STATEMENTS | |

296 | Statements (as in most algebraic languages) provide the sequencing of | |

297 | expression evaluation. In \fBbc\fR statements are executed "as soon | |

298 | as possible." Execution happens when a newline in encountered and | |

299 | there is one or more complete statements. Due to this immediate | |

300 | execution, newlines are very important in \fBbc\fR. In fact, both a | |

301 | semicolon and a newline are used as statement separators. An | |

302 | improperly placed newline will cause a syntax error. Because newlines | |

303 | are statement separators, it is possible to hide a newline by using | |

304 | the backslash character. The sequence "\e<nl>", where <nl> is the | |

305 | newline appears to \fBbc\fR as whitespace instead of a newline. A | |

306 | statement list is a series of statements separated by semicolons and | |

307 | newlines. The following is a list of \fBbc\fR statements and what | |

308 | they do: (Things enclosed in brackets ([]) are optional parts of the | |

309 | statement.) | |

310 | .IP "expression" | |

311 | This statement does one of two things. If the expression starts with | |

312 | "<variable> <assignment> ...", it is considered to be an assignment | |

313 | statement. If the expression is not an assignment statement, the | |

314 | expression is evaluated and printed to the output. After the number | |

315 | is printed, a newline is printed. For example, "a=1" is an assignment | |

316 | statement and "(a=1)" is an expression that has an embedded | |

317 | assignment. All numbers that are printed are printed in the base | |

318 | specified by the variable \fBobase\fR. The legal values for \fB | |

319 | obase\fR are 2 through BC_BASE_MAX. (See the section LIMITS.) For | |

320 | bases 2 through 16, the usual method of writing numbers is used. For | |

321 | bases greater than 16, \fBbc\fR uses a multi-character digit method | |

322 | of printing the numbers where each higher base digit is printed as a | |

323 | base 10 number. The multi-character digits are separated by spaces. | |

324 | Each digit contains the number of characters required to represent the | |

325 | base ten value of "obase-1". Since numbers are of arbitrary | |

326 | precision, some numbers may not be printable on a single output line. | |

327 | These long numbers will be split across lines using the "\e" as the | |

328 | last character on a line. The maximum number of characters printed | |

329 | per line is 70. Due to the interactive nature of \fBbc\fR, printing | |

330 | a number causes the side effect of assigning the printed value to the | |

331 | special variable \fBlast\fR. This allows the user to recover the | |

332 | last value printed without having to retype the expression that | |

333 | printed the number. Assigning to \fBlast\fR is legal and will | |

334 | overwrite the last printed value with the assigned value. The newly | |

335 | assigned value will remain until the next number is printed or another | |

336 | value is assigned to \fBlast\fR. (Some installations may allow the | |

337 | use of a single period (.) which is not part of a number as a short | |

338 | hand notation for for \fBlast\fR.) | |

339 | .IP "string" | |

340 | The string is printed to the output. Strings start with a double quote | |

341 | character and contain all characters until the next double quote character. | |

342 | All characters are take literally, including any newline. No newline | |

343 | character is printed after the string. | |

344 | .IP "\fBprint\fR list" | |

345 | The print statement (an extension) provides another method of output. | |

346 | The "list" is a list of strings and expressions separated by commas. | |

347 | Each string or expression is printed in the order of the list. No | |

348 | terminating newline is printed. Expressions are evaluated and their | |

349 | value is printed and assigned to the variable \fBlast\fR. Strings | |

350 | in the print statement are printed to the output and may contain | |

351 | special characters. Special characters start with the backslash | |

352 | character (\e). The special characters recognized by \fBbc\fR are | |

353 | "a" (alert or bell), "b" (backspace), "f" (form feed), "n" (newline), | |

354 | "r" (carriage return), "q" (double quote), "t" (tab), and "\e" (backslash). | |

355 | Any other character following the backslash will be ignored. | |

356 | .IP "{ statement_list }" | |

357 | This is the compound statement. It allows multiple statements to be | |

358 | grouped together for execution. | |

359 | .IP "\fBif\fR ( expression ) statement1 [\fBelse\fR statement2]" | |

360 | The if statement evaluates the expression and executes statement1 or | |

361 | statement2 depending on the value of the expression. If the expression | |

362 | is non-zero, statement1 is executed. If statement2 is present and | |

363 | the value of the expression is 0, then statement2 is executed. (The | |

364 | else clause is an extension.) | |

365 | .IP "\fBwhile\fR ( expression ) statement" | |

366 | The while statement will execute the statement while the expression | |

367 | is non-zero. It evaluates the expression before each execution of | |

368 | the statement. Termination of the loop is caused by a zero | |

369 | expression value or the execution of a break statement. | |

370 | .IP "\fBfor\fR ( [expression1] ; [expression2] ; [expression3] ) statement" | |

371 | The for statement controls repeated execution of the statement. | |

372 | Expression1 is evaluated before the loop. Expression2 is evaluated | |

373 | before each execution of the statement. If it is non-zero, the statement | |

374 | is evaluated. If it is zero, the loop is terminated. After each | |

375 | execution of the statement, expression3 is evaluated before the reevaluation | |

376 | of expression2. If expression1 or expression3 are missing, nothing is | |

377 | evaluated at the point they would be evaluated. | |

378 | If expression2 is missing, it is the same as substituting | |

379 | the value 1 for expression2. (The optional expressions are an | |

380 | extension. POSIX \fBbc\fR requires all three expressions.) | |

381 | The following is equivalent code for the for statement: | |

382 | .nf | |

383 | .RS | |

384 | expression1; | |

385 | while (expression2) { | |

386 | statement; | |

387 | expression3; | |

388 | } | |

389 | .RE | |

390 | .fi | |

391 | .IP "\fBbreak\fR" | |

392 | This statement causes a forced exit of the most recent enclosing while | |

393 | statement or for statement. | |

394 | .IP "\fBcontinue\fR" | |

395 | The continue statement (an extension) causes the most recent enclosing | |

396 | for statement to start the next iteration. | |

397 | .IP "\fBhalt\fR" | |

398 | The halt statement (an extension) is an executed statement that causes | |

399 | the \fBbc\fR processor to quit only when it is executed. For example, | |

400 | "if (0 == 1) halt" will not cause \fBbc\fR to terminate because the halt is | |

401 | not executed. | |

402 | .IP "\fBreturn\fR" | |

403 | Return the value 0 from a function. (See the section on functions.) | |

404 | .IP "\fBreturn\fR ( expression )" | |

405 | Return the value of the expression from a function. (See the section on | |

406 | functions.) As an extension, the parenthesis are not required. | |

407 | .SS PSEUDO STATEMENTS | |

408 | These statements are not statements in the traditional sense. They are | |

409 | not executed statements. Their function is performed at "compile" time. | |

410 | .IP "\fBlimits\fR" | |

411 | Print the local limits enforced by the local version of \fBbc\fR. This | |

412 | is an extension. | |

413 | .IP "\fBquit\fR" | |

414 | When the quit statement is read, the \fBbc\fR processor | |

415 | is terminated, regardless of where the quit statement is found. For | |

416 | example, "if (0 == 1) quit" will cause \fBbc\fR to terminate. | |

417 | .IP "\fBwarranty\fR" | |

418 | Print a longer warranty notice. This is an extension. | |

419 | .SS FUNCTIONS | |

420 | Functions provide a method of defining a computation that can be executed | |

421 | later. Functions in | |

422 | .B bc | |

423 | always compute a value and return it to the caller. Function definitions | |

424 | are "dynamic" in the sense that a function is undefined until a definition | |

425 | is encountered in the input. That definition is then used until another | |

426 | definition function for the same name is encountered. The new definition | |

427 | then replaces the older definition. A function is defined as follows: | |

428 | .nf | |

429 | .RS | |

430 | \fBdefine \fIname \fB( \fIparameters \fB) { \fInewline | |

431 | \fI auto_list statement_list \fB}\fR | |

432 | .RE | |

433 | .fi | |

434 | A function call is just an expression of the form | |

435 | "\fIname\fB(\fIparameters\fB)\fR". | |

436 | .PP | |

437 | Parameters are numbers or arrays (an extension). In the function definition, | |

438 | zero or more parameters are defined by listing their names separated by | |

439 | commas. Numbers are only call by value parameters. Arrays are only | |

440 | call by variable. Arrays are specified in the parameter definition by | |

441 | the notation "\fIname\fB[]\fR". In the function call, actual parameters | |

442 | are full expressions for number parameters. The same notation is used | |

443 | for passing arrays as for defining array parameters. The named array is | |

444 | passed by variable to the function. Since function definitions are dynamic, | |

445 | parameter numbers and types are checked when a function is called. Any | |

446 | mismatch in number or types of parameters will cause a runtime error. | |

447 | A runtime error will also occur for the call to an undefined function. | |

448 | .PP | |

449 | The \fIauto_list\fR is an optional list of variables that are for | |

450 | "local" use. The syntax of the auto list (if present) is "\fBauto | |

451 | \fIname\fR, ... ;". (The semicolon is optional.) Each \fIname\fR is | |

452 | the name of an auto variable. Arrays may be specified by using the | |

453 | same notation as used in parameters. These variables have their | |

454 | values pushed onto a stack at the start of the function. The | |

455 | variables are then initialized to zero and used throughout the | |

456 | execution of the function. At function exit, these variables are | |

457 | popped so that the original value (at the time of the function call) | |

458 | of these variables are restored. The parameters are really auto | |

459 | variables that are initialized to a value provided in the function | |

460 | call. Auto variables are different than traditional local variables | |

461 | because if function A calls function B, B may access function | |

462 | A's auto variables by just using the same name, unless function B has | |

463 | called them auto variables. Due to the fact that auto variables and | |

464 | parameters are pushed onto a stack, \fBbc\fR supports recursive functions. | |

465 | .PP | |

466 | The function body is a list of \fBbc\fR statements. Again, statements | |

467 | are separated by semicolons or newlines. Return statements cause the | |

468 | termination of a function and the return of a value. There are two | |

469 | versions of the return statement. The first form, "\fBreturn\fR", returns | |

470 | the value 0 to the calling expression. The second form, | |

471 | "\fBreturn ( \fIexpression \fB)\fR", computes the value of the expression | |

472 | and returns that value to the calling expression. There is an implied | |

473 | "\fBreturn (0)\fR" at the end of every function. This allows a function | |

474 | to terminate and return 0 without an explicit return statement. | |

475 | .PP | |

476 | Functions also change the usage of the variable \fBibase\fR. All | |

477 | constants in the function body will be converted using the value of | |

478 | \fBibase\fR at the time of the function call. Changes of \fBibase\fR | |

479 | will be ignored during the execution of the function except for the | |

480 | standard function \fBread\fR, which will always use the current value | |

481 | of \fBibase\fR for conversion of numbers. | |

482 | .PP | |

483 | As an extension, the format of the definition has been slightly relaxed. | |

484 | The standard requires the opening brace be on the same line as the | |

485 | \fBdefine\fR keyword and all other parts must be on following lines. | |

486 | This version of \fBbc\fR will allow any number of newlines before and | |

487 | after the opening brace of the function. For example, the following | |

488 | definitions are legal. | |

489 | .nf | |

490 | .RS | |

491 | \f(CW | |

492 | define d (n) { return (2*n); } | |

493 | define d (n) | |

494 | { return (2*n); } | |

495 | \fR | |

496 | .RE | |

497 | .fi | |

498 | .SS MATH LIBRARY | |

499 | If \fBbc\fR is invoked with the \fB-l\fR option, a math library is preloaded | |

500 | and the default scale is set to 20. The math functions will calculate their | |

501 | results to the scale set at the time of their call. | |

502 | The math library defines the following functions: | |

503 | .IP "s (\fIx\fR)" | |

504 | The sine of x, x is in radians. | |

505 | .IP "c (\fIx\fR)" | |

506 | The cosine of x, x is in radians. | |

507 | .IP "a (\fIx\fR)" | |

508 | The arctangent of x, arctangent returns radians. | |

509 | .IP "l (\fIx\fR)" | |

510 | The natural logarithm of x. | |

511 | .IP "e (\fIx\fR)" | |

512 | The exponential function of raising e to the value x. | |

513 | .IP "j (\fIn,x\fR)" | |

514 | The bessel function of integer order n of x. | |

515 | .SS EXAMPLES | |

516 | In /bin/sh, the following will assign the value of "pi" to the shell | |

517 | variable \fBpi\fR. | |

518 | .RS | |

519 | \f(CW | |

520 | pi=$(echo "scale=10; 4*a(1)" | bc -l) | |

521 | \fR | |

522 | .RE | |

523 | .PP | |

524 | The following is the definition of the exponential function used in the | |

525 | math library. This function is written in POSIX \fBbc\fR. | |

526 | .nf | |

527 | .RS | |

528 | \f(CW | |

529 | scale = 20 | |

530 | ||

531 | /* Uses the fact that e^x = (e^(x/2))^2 | |

532 | When x is small enough, we use the series: | |

533 | e^x = 1 + x + x^2/2! + x^3/3! + ... | |

534 | */ | |

535 | ||

536 | define e(x) { | |

537 | auto a, d, e, f, i, m, v, z | |

538 | ||

539 | /* Check the sign of x. */ | |

540 | if (x<0) { | |

541 | m = 1 | |

542 | x = -x | |

543 | } | |

544 | ||

545 | /* Precondition x. */ | |

546 | z = scale; | |

547 | scale = 4 + z + .44*x; | |

548 | while (x > 1) { | |

549 | f += 1; | |

550 | x /= 2; | |

551 | } | |

552 | ||

553 | /* Initialize the variables. */ | |

554 | v = 1+x | |

555 | a = x | |

556 | d = 1 | |

557 | ||

558 | for (i=2; 1; i++) { | |

559 | e = (a *= x) / (d *= i) | |

560 | if (e == 0) { | |

561 | if (f>0) while (f--) v = v*v; | |

562 | scale = z | |

563 | if (m) return (1/v); | |

564 | return (v/1); | |

565 | } | |

566 | v += e | |

567 | } | |

568 | } | |

569 | \fR | |

570 | .RE | |

571 | .fi | |

572 | .PP | |

573 | The following is code that uses the extended features of \fBbc\fR to | |

574 | implement a simple program for calculating checkbook balances. This | |

575 | program is best kept in a file so that it can be used many times | |

576 | without having to retype it at every use. | |

577 | .nf | |

578 | .RS | |

579 | \f(CW | |

580 | scale=2 | |

581 | print "\enCheck book program!\en" | |

582 | print " Remember, deposits are negative transactions.\en" | |

583 | print " Exit by a 0 transaction.\en\en" | |

584 | ||

585 | print "Initial balance? "; bal = read() | |

586 | bal /= 1 | |

587 | print "\en" | |

588 | while (1) { | |

589 | "current balance = "; bal | |

590 | "transaction? "; trans = read() | |

591 | if (trans == 0) break; | |

592 | bal -= trans | |

593 | bal /= 1 | |

594 | } | |

595 | quit | |

596 | \fR | |

597 | .RE | |

598 | .fi | |

599 | .PP | |

600 | The following is the definition of the recursive factorial function. | |

601 | .nf | |

602 | .RS | |

603 | \f(CW | |

604 | define f (x) { | |

605 | if (x <= 1) return (1); | |

606 | return (f(x-1) * x); | |

607 | } | |

608 | \fR | |

609 | .RE | |

610 | .fi | |

611 | .SS READLINE AND LIBEDIT OPTIONS | |

612 | GNU \fBbc\fR can be compiled (via a configure option) to use the GNU | |

613 | \fBreadline\fR input editor library or the BSD \fBlibedit\fR library. | |

614 | This allows the user to do editing of lines before sending them | |

615 | to \fBbc\fR. It also allows for a history of previous lines typed. | |

616 | When this option is selected, \fBbc\fR has one more special variable. | |

617 | This special variable, \fBhistory\fR is the number of lines of history | |

618 | retained. For \fBreadline\fR, a value of -1 means that an unlimited | |

619 | number of history lines are retained. Setting the value of | |

620 | \fBhistory\fR to a positive number restricts the number of history | |

621 | lines to the number given. The value of 0 disables the history | |

622 | feature. The default value is 100. For more information, read the | |

623 | user manuals for the GNU \fBreadline\fR, \fBhistory\fR and BSD \fBlibedit\fR | |

624 | libraries. One can not enable both \fBreadline\fR and \fBlibedit\fR | |

625 | at the same time. | |

626 | .SS DIFFERENCES | |

627 | This version of | |

628 | .B bc | |

629 | was implemented from the POSIX P1003.2/D11 draft and contains | |

630 | several differences and extensions relative to the draft and | |

631 | traditional implementations. | |

632 | It is not implemented in the traditional way using | |

633 | .I dc(1). | |

634 | This version is a single process which parses and runs a byte code | |

635 | translation of the program. There is an "undocumented" option (-c) | |

636 | that causes the program to output the byte code to | |

637 | the standard output instead of running it. It was mainly used for | |

638 | debugging the parser and preparing the math library. | |

639 | .PP | |

640 | A major source of differences is | |

641 | extensions, where a feature is extended to add more functionality and | |

642 | additions, where new features are added. | |

643 | The following is the list of differences and extensions. | |

644 | .IP "LANG environment" | |

645 | This version does not conform to the POSIX standard in the processing | |

646 | of the LANG environment variable and all environment variables starting | |

647 | with LC_. | |

648 | .IP names | |

649 | Traditional and POSIX | |

650 | .B bc | |

651 | have single letter names for functions, variables and arrays. They have | |

652 | been extended to be multi-character names that start with a letter and | |

653 | may contain letters, numbers and the underscore character. | |

654 | .IP Strings | |

655 | Strings are not allowed to contain NUL characters. POSIX says all characters | |

656 | must be included in strings. | |

657 | .IP last | |

658 | POSIX \fBbc\fR does not have a \fBlast\fR variable. Some implementations | |

659 | of \fBbc\fR use the period (.) in a similar way. | |

660 | .IP comparisons | |

661 | POSIX \fBbc\fR allows comparisons only in the if statement, the while | |

662 | statement, and the second expression of the for statement. Also, only | |

663 | one relational operation is allowed in each of those statements. | |

664 | .IP "if statement, else clause" | |

665 | POSIX \fBbc\fR does not have an else clause. | |

666 | .IP "for statement" | |

667 | POSIX \fBbc\fR requires all expressions to be present in the for statement. | |

668 | .IP "&&, ||, !" | |

669 | POSIX \fBbc\fR does not have the logical operators. | |

670 | .IP "read function" | |

671 | POSIX \fBbc\fR does not have a read function. | |

672 | .IP "print statement" | |

673 | POSIX \fBbc\fR does not have a print statement . | |

674 | .IP "continue statement" | |

675 | POSIX \fBbc\fR does not have a continue statement. | |

676 | .IP "return statement" | |

677 | POSIX \fBbc\fR requires parentheses around the return expression. | |

678 | .IP "array parameters" | |

679 | POSIX \fBbc\fR does not (currently) support array parameters in full. | |

680 | The POSIX grammar allows for arrays in function definitions, but does | |

681 | not provide a method to specify an array as an actual parameter. (This | |

682 | is most likely an oversight in the grammar.) Traditional implementations | |

683 | of \fBbc\fR have only call by value array parameters. | |

684 | .IP "function format" | |

685 | POSIX \fBbc\fR requires the opening brace on the same line as the | |

686 | \fBdefine\fR key word and the \fBauto\fR statement on the next line. | |

687 | .IP "=+, =-, =*, =/, =%, =^" | |

688 | POSIX \fBbc\fR does not require these "old style" assignment operators to | |

689 | be defined. This version may allow these "old style" assignments. Use | |

690 | the limits statement to see if the installed version supports them. If | |

691 | it does support the "old style" assignment operators, the statement | |

692 | "a =- 1" will decrement \fBa\fR by 1 instead of setting \fBa\fR to the | |

693 | value -1. | |

694 | .IP "spaces in numbers" | |

695 | Other implementations of \fBbc\fR allow spaces in numbers. For example, | |

696 | "x=1 3" would assign the value 13 to the variable x. The same statement | |

697 | would cause a syntax error in this version of \fBbc\fR. | |

698 | .IP "errors and execution" | |

699 | This implementation varies from other implementations in terms of what | |

700 | code will be executed when syntax and other errors are found in the | |

701 | program. If a syntax error is found in a function definition, error | |

702 | recovery tries to find the beginning of a statement and continue to | |

703 | parse the function. Once a syntax error is found in the function, the | |

704 | function will not be callable and becomes undefined. | |

705 | Syntax errors in the interactive execution code will invalidate the | |

706 | current execution block. The execution block is terminated by an | |

707 | end of line that appears after a complete sequence of statements. | |

708 | For example, | |

709 | .nf | |

710 | .RS | |

711 | a = 1 | |

712 | b = 2 | |

713 | .RE | |

714 | .fi | |

715 | has two execution blocks and | |

716 | .nf | |

717 | .RS | |

718 | { a = 1 | |

719 | b = 2 } | |

720 | .RE | |

721 | .fi | |

722 | has one execution block. Any runtime error will terminate the execution | |

723 | of the current execution block. A runtime warning will not terminate the | |

724 | current execution block. | |

725 | .IP "Interrupts" | |

726 | During an interactive session, the SIGINT signal (usually generated by | |

727 | the control-C character from the terminal) will cause execution of the | |

728 | current execution block to be interrupted. It will display a "runtime" | |

729 | error indicating which function was interrupted. After all runtime | |

730 | structures have been cleaned up, a message will be printed to notify the | |

731 | user that \fBbc\fR is ready for more input. All previously defined functions | |

732 | remain defined and the value of all non-auto variables are the value at | |

733 | the point of interruption. All auto variables and function parameters | |

734 | are removed during the | |

735 | clean up process. During a non-interactive | |

736 | session, the SIGINT signal will terminate the entire run of \fBbc\fR. | |

737 | .SS LIMITS | |

738 | The following are the limits currently in place for this | |

739 | .B bc | |

740 | processor. Some of them may have been changed by an installation. | |

741 | Use the limits statement to see the actual values. | |

742 | .IP BC_BASE_MAX | |

743 | The maximum output base is currently set at 999. The maximum input base | |

744 | is 16. | |

745 | .IP BC_DIM_MAX | |

746 | This is currently an arbitrary limit of 65535 as distributed. Your | |

747 | installation may be different. | |

748 | .IP BC_SCALE_MAX | |

749 | The number of digits after the decimal point is limited to INT_MAX digits. | |

750 | Also, the number of digits before the decimal point is limited to INT_MAX | |

751 | digits. | |

752 | .IP BC_STRING_MAX | |

753 | The limit on the number of characters in a string is INT_MAX characters. | |

754 | .IP exponent | |

755 | The value of the exponent in the raise operation (^) is limited to LONG_MAX. | |

756 | .IP "variable names" | |

757 | The current limit on the number of unique names is 32767 for each of | |

758 | simple variables, arrays and functions. | |

759 | .SH ENVIRONMENT | |

760 | The following environment variables are processed by \fBbc\fR: | |

761 | .IP "POSIXLY_CORRECT" | |

762 | This is the same as the \fB-s\fR option. | |

763 | .IP "BC_ENV_ARGS" | |

764 | This is another mechanism to get arguments to \fBbc\fR. The | |

765 | format is the same as the command line arguments. These arguments | |

766 | are processed first, so any files listed in the environment arguments | |

767 | are processed before any command line argument files. This allows | |

768 | the user to set up "standard" options and files to be processed | |

769 | at every invocation of \fBbc\fR. The files in the environment | |

770 | variables would typically contain function definitions for functions | |

771 | the user wants defined every time \fBbc\fR is run. | |

772 | .IP "BC_LINE_LENGTH" | |

773 | This should be an integer specifying the number of characters in an | |

774 | output line for numbers. This includes the backslash and newline characters | |

775 | for long numbers. | |

776 | .SH DIAGNOSTICS | |

777 | If any file on the command line can not be opened, \fBbc\fR will report | |

778 | that the file is unavailable and terminate. Also, there are compile | |

779 | and run time diagnostics that should be self-explanatory. | |

780 | .SH BUGS | |

781 | Error recovery is not very good yet. | |

782 | .PP | |

783 | Email bug reports to | |

784 | .BR bug-bc@gnu.org . | |

785 | Be sure to include the word ``bc'' somewhere in the ``Subject:'' field. | |

786 | .SH AUTHOR | |

787 | .nf | |

788 | Philip A. Nelson | |

789 | philnelson@acm.org | |

790 | .fi | |

791 | .SH ACKNOWLEDGEMENTS | |

792 | The author would like to thank Steve Sommars (Steve.Sommars@att.com) for | |

793 | his extensive help in testing the implementation. Many great suggestions | |

794 | were given. This is a much better product due to his involvement. |