~ubuntu-branches/ubuntu/utopic/bc/utopic-proposed : revision 14

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.

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

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

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

87

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

88

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

89

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

90

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

90

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

91

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

92

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

93

.PP

94

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

95

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

96

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

96

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

97

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

98

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

99

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

124

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

125

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

126

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

127

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

127

or 16. Input numbers may contain the characters 0\(en9 and A\(enF. (Note:

128

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

129

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

130

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

130

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

131

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

132

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

133

the largest 3 digit number of the input base.

148

.RE

149

and an array variable is specified as

150

.RS

151

\fIname\fR[\fIexpr\fR]

151

.\"\fIname\fR[\fIexpr\fR]

152

.IR name [ expr ]

152

153

.RE

153

154

Unless specifically

154

155

mentioned the scale of the result is the maximum scale of the

186

187

integer remainder function.

187

188

.IP "expr ^ expr"

188

189

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

189

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

190

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

190

191

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

191

192

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

192

193

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

193

194

is positive the scale of the result is the minimum of the scale of the

194

195

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

195

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

196

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

196

197

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

197

198

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

198

199

.IP "( expr )"

225

226

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

226

227

.PP

227

228

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

228

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

229

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

229

230

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

230

231

operators are:

231

232

.IP "!expr"

252

253

.fi

253

254

.PP

254

255

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

255

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

256

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

256

257

logical operators to have some unusual behavior when used with

257

258

assignment expressions. Consider the expression:

258

259

.RS

267

268

.PP

268

269

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

269

270

These have to do with user defined functions and standard

270

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

271

functions. They all appear as "\,\fIname\/\fB(\,\fIparameters\/\fB)\fR".

271

272

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

272

273

functions are:

273

274

.IP "length ( expression )"

280

281

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

281

282

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

282

283

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

283

the standard input using the current value of the variable

284

the standard input using the current value of the variable

284

285

\fBibase\fR for the conversion base.

285

286

.IP "scale ( expression )"

286

287

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

293

294

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

294

295

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

295

296

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

296

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

297

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

297

298

semicolon and a newline are used as statement separators. An

298

299

improperly placed newline will cause a syntax error. Because newlines

299

300

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

311

312

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

312

313

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

313

314

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

314

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

315

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

315

316

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

316

317

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

317

318

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

324

325

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

325

326

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

326

327

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

327

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

328

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

328

329

last value printed without having to retype the expression that

329

330

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

330

331

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

331

332

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

332

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

333

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

333

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

334

use of a single period (.\&) which is not part of a number as a short

334

335

hand notation for for \fBlast\fR.)

335

336

.IP "string"

336

337

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

342

343

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

343

344

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

344

345

terminating newline is printed. Expressions are evaluated and their

345

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

346

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

346

347

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

347

348

special characters. Special characters start with the backslash

348

349

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

349

350

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

350

351

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

351

Any other character following the backslash will be ignored.

352

Any other character following the backslash will be ignored.

352

353

.IP "{ statement_list }"

353

354

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

354

355

grouped together for execution.

364

365

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

365

366

expression value or the execution of a break statement.

366

367

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

367

The for statement controls repeated execution of the statement.

368

The for statement controls repeated execution of the statement.

368

369

Expression1 is evaluated before the loop. Expression2 is evaluated

369

370

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

370

371

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

373

374

evaluated at the point they would be evaluated.

374

375

If expression2 is missing, it is the same as substituting

375

376

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

376

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

377

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

377

378

The following is equivalent code for the for statement:

378

379

.nf

379

380

.RS

388

389

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

389

390

statement or for statement.

390

391

.IP "\fBcontinue\fR"

391

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

392

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

392

393

for statement to start the next iteration.

393

394

.IP "\fBhalt\fR"

394

395

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

398

399

.IP "\fBreturn\fR"

399

400

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

400

401

.IP "\fBreturn\fR ( expression )"

401

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

402

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

402

403

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

403

404

.SS PSEUDO STATEMENTS

404

405

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

414

415

Print a longer warranty notice. This is an extension.

415

416

.SS FUNCTIONS

416

417

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

417

later. Functions in

418

later. Functions in

418

419

.B bc

419

420

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

420

421

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

428

429

.RE

429

430

.fi

430

431

A function call is just an expression of the form

431

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

432

"\,\fIname\/\fB(\,\fIparameters\/\fB)\fR".

432

433

.PP

433

434

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

434

435

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

435

commas. All parameters are call by value parameters.

436

commas. All parameters are call by value parameters.

436

437

Arrays are specified in the parameter definition by

437

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

438

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

438

439

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

439

440

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

440

441

passed by value to the function. Since function definitions are dynamic,

463

464

are separated by semicolons or newlines. Return statements cause the

464

465

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

465

466

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

466

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

467

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

467

468

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

468

469

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

469

470

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

493

494

.fi

494

495

.PP

495

496

Functions may be defined as \fBvoid\fR. A void

496

funtion returns no value and thus may not be used in any place that needs

497

function returns no value and thus may not be used in any place that needs

497

498

a value. A void function does not produce any output when called by itself

498

499

on an input line. The key word \fBvoid\fR is placed between the key word

499

500

\fBdefine\fR and the function name. For example, consider the following

501

502

.nf

502

503

.RS

503

504

\f(CW

504

define py (y) { print "--->", y, "<---", "\n"; }

505

define void px (x) { print "--->", x, "<---", "\n"; }

505

define py (y) { print "--->", y, "<---", "\en"; }

506

define void px (x) { print "--->", x, "<---", "\en"; }

506

507

py(1)

507

508

--->1<---

508

509

0

519

520

.PP

520

521

Also, call by variable for arrays was added. To declare

521

522

a call by variable array, the declaration of the array parameter in the

522

function definition looks like "\fI*name\fB[]\fR". The call to the

523

function remains the same as call by value arrays.

523

function definition looks like "\,\fI*name\/\fB[]\fR". The call to the

524

function remains the same as call by value arrays.

524

525

.SS MATH LIBRARY

525

526

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

526

527

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

527

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

528

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

528

529

The math library defines the following functions:

529

.IP "s (\fIx\fR)"

530

.IP "s (\,\fIx\/\fR)"

530

531

The sine of x, x is in radians.

531

.IP "c (\fIx\fR)"

532

.IP "c (\,\fIx\/\fR)"

532

533

The cosine of x, x is in radians.

533

.IP "a (\fIx\fR)"

534

.IP "a (\,\fIx\/\fR)"

534

535

The arctangent of x, arctangent returns radians.

535

.IP "l (\fIx\fR)"

536

.IP "l (\,\fIx\/\fR)"

536

537

The natural logarithm of x.

537

.IP "e (\fIx\fR)"

538

.IP "e (\,\fIx\/\fR)"

538

539

The exponential function of raising e to the value x.

539

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

540

.IP "j (\,\fIn,x\/\fR)"

540

541

The Bessel function of integer order n of x.

541

542

.SS EXAMPLES

542

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

543

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

543

544

variable \fBpi\fR.

544

545

.RS

545

546

\f(CW

566

567

if (x<0) {

567

568

m = 1

568

569

x = \-x

569

}

570

}

570

571

572

/* Precondition x. */

572

573

z = scale;

598

599

.PP

599

600

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

600

601

implement a simple program for calculating checkbook balances. This

601

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

602

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

602

603

without having to retype it at every use.

603

604

.nf

604

605

.RS

645

646

number of history lines are retained. Setting the value of

646

647

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

647

648

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

648

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

649

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

649

650

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

650

651

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

651

652

at the same time.

652

653

.SS DIFFERENCES

653

This version of

654

This version of

654

655

.B bc

655

656

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

656

657

several differences and extensions relative to the draft and

665

666

.PP

666

667

A major source of differences is

667

668

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

668

additions, where new features are added.

669

additions, where new features are added.

669

670

The following is the list of differences and extensions.

670

671

.IP "LANG environment"

671

672

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

682

683

must be included in strings.

683

684

.IP "last"

684

685

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

685

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

686

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

686

687

.IP "comparisons"

687

688

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

688

689

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

696

697

.IP "read function"

697

698

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

698

699

.IP "print statement"

699

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

700

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

700

701

.IP "continue statement"

701

702

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

702

703

.IP "return statement"

708

709

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

709

710

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

710

711

.IP "function format"

711

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

712

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

712

713

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

713

714

.IP "=+, =\-, =*, =/, =%, =^"

714

715

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

731

732

Syntax errors in the interactive execution code will invalidate the

732

733

current execution block. The execution block is terminated by an

733

734

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

734

For example,

735

For example,

735

736

.nf

736

737

.RS

737

738

a = 1

761

762

clean up process. During a non-interactive

762

763

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

763

764

.SS LIMITS

764

The following are the limits currently in place for this

765

The following are the limits currently in place for this

765

766

.B bc

766

767

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

767

768

Use the limits statement to see the actual values.

797

798

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

798

799

.IP "BC_LINE_LENGTH"

799

800

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

800

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

801

for long numbers. As an extension, the value of zero disables the

801

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

802

for long numbers. As an extension, the value of zero disables the

802

803

multi-line feature. Any other value of this variable that is less than

803

804

3 sets the line length to 70.

804

805

.SH DIAGNOSTICS

813

814

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

814

815

.SH AUTHOR

815

816

.nf

816

Philip A. Nelson

817

Philip A.\& Nelson

817

818

philnelson@acm.org

818

819

.fi

819

820

.SH ACKNOWLEDGEMENTS