1015 lines
38 KiB
Plaintext
1015 lines
38 KiB
Plaintext
\input texinfo @c -*-texinfo-*-
|
|
@c %**start of header
|
|
@setfilename bc.info
|
|
@settitle bc Command Manual
|
|
@c %**end of header
|
|
|
|
@c This file has the new style title page commands.
|
|
@c Run `makeinfo' rather than `texinfo-format-buffer'.
|
|
|
|
@smallbook
|
|
|
|
@c tex
|
|
@c \overfullrule=0pt
|
|
@c end tex
|
|
|
|
@titlepage
|
|
@title @command{bc}
|
|
@subtitle an arbitrary precision calculator language
|
|
@subtitle version 1.06
|
|
|
|
@author Philip A. Nelson
|
|
@page
|
|
|
|
This manual documents @command{bc}, an arbitrary precision calculator language.
|
|
|
|
This manual is part of GNU @command{bc}.@*
|
|
@sp4
|
|
Copyright (C) 1991, 1992, 1993, 1994, 1997 Free Software Foundation, Inc.
|
|
59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
|
|
|
|
Permission is granted to make and distribute verbatim copies of
|
|
this manual provided the copyright notice and this permission notice
|
|
are preserved on all copies.
|
|
|
|
@iftex
|
|
Permission is granted to process this file through TeX and print the
|
|
results, provided the printed document carries copying permission
|
|
notice identical to this one except for the removal of this paragraph
|
|
(this paragraph not being relevant to the printed manual).
|
|
@end iftex
|
|
|
|
Permission is granted to copy and distribute modified versions of this
|
|
manual under the conditions for verbatim copying, provided that the entire
|
|
resulting derived work is distributed under the terms of a permission
|
|
notice identical to this one.
|
|
|
|
Permission is granted to copy and distribute translations of this manual
|
|
into another language, under the above conditions for modified versions,
|
|
except that this permission notice may be stated in a translation approved
|
|
by the Foundation.
|
|
|
|
You may contact the author by:
|
|
e-mail: @email{phil@@cs.wwu.edu}@*
|
|
us-mail: Philip A. Nelson@*
|
|
Computer Science Department, 9062@*
|
|
Western Washington University@*
|
|
Bellingham, WA 98226-9062
|
|
|
|
@end titlepage
|
|
|
|
@node Top, Introduction, (dir), (dir)
|
|
|
|
@menu
|
|
* Introduction::
|
|
* Basic Elements::
|
|
* Expressions::
|
|
* Statements::
|
|
* Functions::
|
|
* Examples::
|
|
* Readline and Libedit Options::
|
|
* GNU @command{bc} and Other Implementations::
|
|
* Limits::
|
|
* Environment Variables::
|
|
@end menu
|
|
|
|
@node Introduction, Basic Elements, Top, Top
|
|
@chapter Introduction
|
|
@menu
|
|
* Description::
|
|
* Command Line Options::
|
|
@end menu
|
|
|
|
@node Description, Command Line Options, Introduction, Introduction
|
|
@section Description
|
|
|
|
@command{bc} [ -hlwsqv ] [long-options] [ @var{ file ...} ]
|
|
|
|
@command{bc} is a language that supports arbitrary precision numbers
|
|
with interactive execution of statements. There are some similarities
|
|
in the syntax to the C programming language.
|
|
A standard math library is available by command line option.
|
|
If requested, the math library is defined before processing any files.
|
|
@command{bc} starts by processing code from all the files listed
|
|
on the command line in the order listed. After all files have been
|
|
processed, @command{bc} reads from the standard input. All code is
|
|
executed as it is read. (If a file contains a command to halt the
|
|
processor, @command{bc} will never read from the standard input.)
|
|
|
|
This version of @command{bc} contains several extensions beyond
|
|
traditional @command{bc} implementations and the POSIX draft standard.
|
|
Command line options can cause these extensions to print a warning or to
|
|
be rejected. This document describes the language accepted by this
|
|
processor. Extensions will be identified as such.
|
|
|
|
The author would like to thank Steve Sommars
|
|
(@email{Steve.Sommars@@att.com}) for his extensive help in testing the
|
|
implementation. Many great suggestions were given. This is a much
|
|
better product due to his involvement.
|
|
|
|
Email bug reports to @email{bug-bc@@gnu.org}. Be sure to include
|
|
the word ``bc'' somewhere in the ``Subject:'' field.
|
|
|
|
@node Command Line Options, Numbers, Description, Introduction
|
|
@section Command Line Options
|
|
|
|
@command{bc} takes the following options from the command line:
|
|
@table @code
|
|
|
|
@item -h, --help
|
|
Print the usage and exit.
|
|
|
|
@item -l, --mathlib
|
|
Define the standard math library.
|
|
|
|
@item -w, --warn
|
|
Give warnings for extensions to POSIX @command{bc}.
|
|
|
|
@item -s, --standard
|
|
Process exactly the POSIX @command{bc} language.
|
|
|
|
@item -q, --quiet
|
|
Do not print the normal GNU @command{bc} welcome.
|
|
|
|
@item -v, --version
|
|
Print the version number and copyright and quit.
|
|
|
|
@end table
|
|
|
|
|
|
@node Basic Elements, Expressions, Introduction, Top
|
|
@chapter Basic Elements
|
|
@menu
|
|
* Numbers::
|
|
* Variables::
|
|
* Comments::
|
|
@end menu
|
|
|
|
@node Numbers, Variables, Command Line Options, Basic Elements
|
|
@section Numbers
|
|
|
|
The most basic element in @command{bc} is the number. Numbers are
|
|
arbitrary precision numbers. This precision is both in the integer part
|
|
and the fractional part. All numbers are represented internally in
|
|
decimal and all computation is done in decimal. (This version truncates
|
|
results from divide and multiply operations.) There are two attributes
|
|
of numbers, the length and the scale. The length is the total number of
|
|
significant decimal digits in a number and the scale is the total number
|
|
of decimal digits after the decimal point. For example, .000001 has a
|
|
length of 6 and scale of 6, while 1935.000 has a length of 7 and a scale
|
|
of 3.
|
|
|
|
@node Variables, Comments, Numbers, Basic Elements
|
|
@section Variables
|
|
|
|
Numbers are stored in two types of variables, simple variables and
|
|
arrays. Both simple variables and array variables are named. Names
|
|
begin with a letter followed by any number of letters, digits and
|
|
underscores. All letters must be lower case. (Full alphanumeric
|
|
names are an extension. In POSIX @command{bc} all names are a single
|
|
lower case letter.) The type of variable is clear by the context
|
|
because all array variable names will be followed by brackets ( [ ] ).
|
|
|
|
There are four special variables, @var{scale}, @var{ibase}, @var{obase}, and
|
|
@var{last}. @var{scale} defines how some operations use digits after the
|
|
decimal point. The default value of @var{scale} is 0. @var{ibase}
|
|
and @var{obase} define the conversion base for input and output
|
|
numbers. The default for both input and output is base 10.
|
|
@var{last} (an extension) is a variable that has the value of the last
|
|
printed number. These will be discussed in further detail where
|
|
appropriate. All of these variables may have values assigned to them
|
|
as well as used in expressions.
|
|
|
|
@node Comments, , Variables, Basic Elements
|
|
@section Comments
|
|
|
|
Comments in @command{bc} start with the characters @code{/*} and end with
|
|
the characters @code{*/}. Comments may start anywhere and appear as a
|
|
single space in the input. (This causes comments to delimit other
|
|
input items. For example, a comment can not be found in the middle of
|
|
a variable name.) Comments include any newlines (end of line) between
|
|
the start and the end of the comment.
|
|
|
|
To support the use of scripts for @command{bc}, a single line comment has been
|
|
added as an extension. A single line comment starts at a @code{#}
|
|
character and continues to the next end of the line. The end of line
|
|
character is not part of the comment and is processed normally.
|
|
|
|
@node Expressions, Statements, Basic Elements, Top
|
|
@chapter Expressions
|
|
|
|
@menu
|
|
* About Expressions and Special Variables::
|
|
* Basic Expressions::
|
|
* Relational Expressions::
|
|
* Boolean Expressions::
|
|
* Precedence::
|
|
* Special Expressions::
|
|
@end menu
|
|
|
|
@node About Expressions and Special Variables, Basic Expressions, Expressions, Expressions
|
|
@section About Expressions and Special Variables
|
|
|
|
The numbers are manipulated by expressions and statements. Since
|
|
the language was designed to be interactive, statements and expressions
|
|
are executed as soon as possible. There is no main program. Instead,
|
|
code is executed as it is encountered. (Functions, discussed in
|
|
detail later, are defined when encountered.)
|
|
|
|
A simple expression is just a constant. @command{bc} converts constants
|
|
into internal decimal numbers using the current input base, specified by
|
|
the variable @var{ibase}. (There is an exception in functions.) The
|
|
legal values of @var{ibase} are 2 through 16. Assigning a value outside
|
|
this range to @var{ibase} will result in a value of 2 or 16. Input
|
|
numbers may contain the characters 0-9 and A-F. (Note: They must be
|
|
capitals. Lower case letters are variable names.) Single digit numbers
|
|
always have the value of the digit regardless of the value of
|
|
@var{ibase}. (i.e. A = 10.) For multi-digit numbers, @command{bc}
|
|
changes all input digits greater or equal to @var{ibase} to the value of
|
|
@var{ibase}-1. This makes the number @code{FFF} always be the largest
|
|
3 digit number of the input base.
|
|
|
|
Full expressions are similar to many other high level languages.
|
|
Since there is only one kind of number, there are no rules for mixing
|
|
types. Instead, there are rules on the scale of expressions. Every
|
|
expression has a scale. This is derived from the scale of original
|
|
numbers, the operation performed and in many cases, the value of the
|
|
variable @var{scale}. Legal values of the variable @var{scale} are
|
|
0 to the maximum number representable by a C integer.
|
|
|
|
@node Basic Expressions, Relational Expressions, About Expressions and Special Variables, Expressions
|
|
@section Basic Expressions
|
|
|
|
In the following descriptions of legal expressions, "expr" refers to a
|
|
complete expression and "@var{var}" refers to a simple or an array variable.
|
|
A simple variable is just a
|
|
|
|
@var{name}
|
|
|
|
and an array variable is specified as
|
|
|
|
@var{name}[@var{expr}]
|
|
|
|
Unless specifically mentioned the scale of the result is the maximum
|
|
scale of the expressions involved.
|
|
|
|
@table @code
|
|
@item - expr
|
|
The result is the negation of the expression.
|
|
|
|
@item ++ @var{var}
|
|
The variable is incremented by one and the new value is the result of
|
|
the expression.
|
|
|
|
@item -- @var{var}
|
|
The variable
|
|
is decremented by one and the new value is the result of the
|
|
expression.
|
|
|
|
@item @var{var} ++
|
|
The result of the expression is the value of
|
|
the variable and then the variable is incremented by one.
|
|
|
|
@item @var{var} --
|
|
The result of the expression is the value of the variable and then
|
|
the variable is decremented by one.
|
|
|
|
@item expr + expr
|
|
The result of the expression is the sum of the two expressions.
|
|
|
|
@item expr - expr
|
|
The result of the expression is the difference of the two expressions.
|
|
|
|
@item expr * expr
|
|
The result of the expression is the product of the two expressions.
|
|
|
|
@item expr / expr
|
|
The result of the expression is the quotient of the two expressions.
|
|
The scale of the result is the value of the variable @code{scale}
|
|
|
|
@item expr % expr
|
|
The result of the expression is the "remainder" and it is computed in the
|
|
following way. To compute a%b, first a/b is computed to @var{scale}
|
|
digits. That result is used to compute a-(a/b)*b to the scale of the
|
|
maximum of @var{scale}+scale(b) and scale(a). If @var{scale} is set
|
|
to zero and both expressions are integers this expression is the
|
|
integer remainder function.
|
|
|
|
@item expr ^ expr
|
|
The result of the expression is the value of the first raised to the
|
|
second. The second expression must be an integer. (If the second
|
|
expression is not an integer, a warning is generated and the
|
|
expression is truncated to get an integer value.) The scale of the
|
|
result is @var{scale} if the exponent is negative. If the exponent
|
|
is positive the scale of the result is the minimum of the scale of the
|
|
first expression times the value of the exponent and the maximum of
|
|
@var{scale} and the scale of the first expression. (e.g. scale(a^b)
|
|
= min(scale(a)*b, max(@var{scale}, scale(a))).) It should be noted
|
|
that expr^0 will always return the value of 1.
|
|
|
|
@item ( expr )
|
|
This alters the standard precedence to force the evaluation of the
|
|
expression.
|
|
|
|
@item @var{var} = expr
|
|
The variable is assigned the value of the expression.
|
|
|
|
@item @var{var} <op>= expr
|
|
This is equivalent to "@var{var} = @var{var} <op> expr" with the
|
|
exception that the "@var{var}" part is evaluated only once. This can
|
|
make a difference if "@var{var}" is an array.
|
|
@end table
|
|
|
|
@node Relational Expressions, Boolean Expressions, Basic Expressions, Expressions
|
|
@section Relational Expressions
|
|
|
|
Relational expressions are a special kind of expression that always
|
|
evaluate to 0 or 1, 0 if the relation is false and 1 if the relation is
|
|
true. These may appear in any legal expression. (POSIX @command{bc}
|
|
requires that relational expressions are used only in @code{if},
|
|
@code{while}, and @code{for} statements and that only one relational
|
|
test may be done in them.) The relational operators are
|
|
|
|
@table @code
|
|
@item expr1 < expr2
|
|
The result is 1 if expr1 is strictly less than expr2.
|
|
|
|
@item expr1 <= expr2
|
|
The result is 1 if expr1 is less than or equal to expr2.
|
|
|
|
@item expr1 > expr2
|
|
The result is 1 if expr1 is strictly greater than expr2.
|
|
|
|
@item expr1 >= expr2
|
|
The result is 1 if expr1 is greater than or equal to expr2.
|
|
|
|
@item expr1 == expr2
|
|
The result is 1 if expr1 is equal to expr2.
|
|
|
|
@item expr1 != expr2
|
|
The result is 1 if expr1 is not equal to expr2.
|
|
@end table
|
|
|
|
@node Boolean Expressions, Precedence, Relational Expressions, Expressions
|
|
@section Boolean Expressions
|
|
|
|
Boolean operations are also legal. (POSIX @command{bc} does NOT have
|
|
boolean operations). The result of all boolean operations are 0 and 1
|
|
(for false and true) as in relational expressions. The boolean
|
|
operators are:
|
|
|
|
@table @code
|
|
@item !expr
|
|
The result is 1 if expr is 0.
|
|
|
|
@item expr && expr
|
|
The result is 1 if both expressions are non-zero.
|
|
|
|
@item expr || expr
|
|
The result is 1 if either expression is non-zero.
|
|
@end table
|
|
|
|
@node Precedence, Special Expressions, Boolean Expressions, Expressions
|
|
@section Precedence
|
|
|
|
The expression precedence is as follows: (lowest to highest)
|
|
|
|
@example
|
|
|| operator, left associative
|
|
&& operator, left associative
|
|
! operator, nonassociative
|
|
Relational operators, left associative
|
|
Assignment operator, right associative
|
|
+ and - operators, left associative
|
|
*, / and % operators, left associative
|
|
^ operator, right associative
|
|
unary - operator, nonassociative
|
|
++ and -- operators, nonassociative
|
|
@end example
|
|
|
|
This precedence was chosen so that POSIX compliant @command{bc} programs
|
|
will run correctly. This will cause the use of the relational and
|
|
logical operators to have some unusual behavior when used with
|
|
assignment expressions. Consider the expression:
|
|
|
|
@example
|
|
a = 3 < 5
|
|
@end example
|
|
|
|
Most C programmers would assume this would assign the result of "3 <
|
|
5" (the value 1) to the variable "a". What this does in @command{bc} is
|
|
assign the value 3 to the variable "a" and then compare 3 to 5. It is
|
|
best to use parentheses when using relational and logical operators
|
|
with the assignment operators.
|
|
|
|
@node Special Expressions, , Precedence, Expressions
|
|
@section Special Expressions
|
|
|
|
There are a few more special expressions that are provided in
|
|
@command{bc}. These have to do with user-defined functions and standard
|
|
functions. They all appear as
|
|
"@var{name}@code{(}@var{parameters}@code{)}". @xref{Functions}, for
|
|
user-defined functions. The standard functions are:
|
|
|
|
@table @code
|
|
@item length ( expression )
|
|
The value of the length function is the number of significant digits in the
|
|
expression.
|
|
|
|
@item read ( )
|
|
The @code{read} function (an extension) will read a number from the
|
|
standard input, regardless of where the function occurs. Beware, this
|
|
can cause problems with the mixing of data and program in the standard
|
|
input. The best use for this function is in a previously written
|
|
program that needs input from the user, but never allows program code to
|
|
be input from the user. The value of the @code{read} function is the
|
|
number read from the standard input using the current value of the
|
|
variable @var{ibase} for the conversion base.
|
|
|
|
@item scale ( expression )
|
|
The value of the @code{scale} function is the number of digits after the
|
|
decimal point in the expression.
|
|
|
|
@item sqrt ( expression )
|
|
The value of the @code{sqrt} function is the square root of the
|
|
expression. If the expression is negative, a run time error is
|
|
generated.
|
|
@end table
|
|
|
|
@node Statements, Functions, Expressions, Top
|
|
@chapter Statements
|
|
|
|
@menu
|
|
* Pseudo Statements::
|
|
@end menu
|
|
|
|
Statements (as in most algebraic languages) provide the sequencing of
|
|
expression evaluation. In @command{bc} statements are executed "as soon
|
|
as possible." Execution happens when a newline in encountered and there
|
|
is one or more complete statements. Due to this immediate execution,
|
|
newlines are very important in @command{bc}. In fact, both a semicolon
|
|
and a newline are used as statement separators. An improperly placed
|
|
newline will cause a syntax error. Because newlines are statement
|
|
separators, it is possible to hide a newline by using the backslash
|
|
character. The sequence "\<nl>", where <nl> is the newline appears to
|
|
@command{bc} as whitespace instead of a newline. A statement list is a
|
|
series of statements separated by semicolons and newlines. The
|
|
following is a list of @command{bc} statements and what they do: (Things
|
|
enclosed in brackets ( [ ] ) are optional parts of the statement.)
|
|
|
|
@table @var
|
|
@item expression
|
|
This statement does one of two things. If the expression starts with
|
|
"<variable> <assignment> ...", it is considered to be an assignment
|
|
statement. If the expression is not an assignment statement, the
|
|
expression is evaluated and printed to the output. After the number is
|
|
printed, a newline is printed. For example, "a=1" is an assignment
|
|
statement and "(a=1)" is an expression that has an embedded assignment.
|
|
All numbers that are printed are printed in the base specified by the
|
|
variable @var{obase}. The legal values for @var{obase} are 2 through
|
|
BC_BASE_MAX (@pxref{Environment Variables}). For bases 2 through 16,
|
|
the usual method of writing numbers is used. For bases greater than 16,
|
|
@command{bc} uses a multi-character digit method of printing the numbers
|
|
where each higher base digit is printed as a base 10 number. The
|
|
multi-character digits are separated by spaces. Each digit contains the
|
|
number of characters required to represent the base ten value of
|
|
"@var{obase} -1". Since numbers are of arbitrary precision, some
|
|
numbers may not be printable on a single output line. These long
|
|
numbers will be split across lines using the "\" as the last character
|
|
on a line. The maximum number of characters printed per line is 70.
|
|
Due to the interactive nature of @command{bc}, printing a number causes
|
|
the side effect of assigning the printed value to the special variable
|
|
@var{last}. This allows the user to recover the last value printed
|
|
without having to retype the expression that printed the number.
|
|
Assigning to @var{last} is legal and will overwrite the last printed
|
|
value with the assigned value. The newly assigned value will remain
|
|
until the next number is printed or another value is assigned to
|
|
@var{last}. (Some installations may allow the use of a single period
|
|
(.) which is not part of a number as a short hand notation for for
|
|
@var{last}.)
|
|
|
|
@item string
|
|
The string is printed to the output. Strings start with a double quote
|
|
character and contain all characters until the next double quote character.
|
|
All characters are taken literally, including any newline. No newline
|
|
character is printed after the string.
|
|
|
|
@item @code{print} @var{list}
|
|
The @code{print} statement (an extension) provides another method of
|
|
output. The @var{list} is a list of strings and expressions separated by
|
|
commas. Each string or expression is printed in the order of the list.
|
|
No terminating newline is printed. Expressions are evaluated and their
|
|
value is printed and assigned to the variable @code{last}. Strings in
|
|
the print statement are printed to the output and may contain special
|
|
characters. Special characters start with the backslash character (\e).
|
|
The special characters recognized by @command{bc} are "a" (alert or
|
|
bell), "b" (backspace), "f" (form feed), "n" (newline), "r" (carriage
|
|
return), "q" (double quote), "t" (tab), and "\e" (backslash). Any other
|
|
character following the backslash will be ignored.
|
|
|
|
@item @{ statement_list @}
|
|
This is the compound statement. It allows multiple statements to be
|
|
grouped together for execution.
|
|
|
|
@item @code{if} ( expression ) statement1 [@code{else} statement2]
|
|
The if statement evaluates the expression and executes statement1 or
|
|
statement2 depending on the value of the expression. If the expression
|
|
is non-zero, statement1 is executed. If statement2 is present and
|
|
the value of the expression is 0, then statement2 is executed. (The
|
|
@code{else} clause is an extension.)
|
|
|
|
@item @code{while} ( expression ) statement
|
|
The while statement will execute the statement while the expression
|
|
is non-zero. It evaluates the expression before each execution of
|
|
the statement. Termination of the loop is caused by a zero
|
|
expression value or the execution of a @code{break} statement.
|
|
|
|
@item @code{for} ( [expression1] ; [expression2] ; [expression3] ) statement
|
|
The @code{for} statement controls repeated execution of the statement.
|
|
@var{Expression1} is evaluated before the loop. @var{Expression2} is
|
|
evaluated before each execution of the statement. If it is non-zero,
|
|
the statement is evaluated. If it is zero, the loop is terminated.
|
|
After each execution of the statement, @var{expression3} is evaluated
|
|
before the reevaluation of expression2. If @var{expression1} or
|
|
@var{expression3} are missing, nothing is evaluated at the point they
|
|
would be evaluated. If @var{expression2} is missing, it is the same as
|
|
substituting the value 1 for @var{expression2}. (The optional
|
|
expressions are an extension. POSIX @command{bc} requires all three
|
|
expressions.) The following is equivalent code for the @code{for}
|
|
statement:
|
|
|
|
@example
|
|
expression1;
|
|
while (expression2) @{
|
|
statement;
|
|
expression3;
|
|
@}
|
|
@end example
|
|
|
|
@item @code{break}
|
|
This statement causes a forced exit of the most recent enclosing @code{while}
|
|
statement or @code{for} statement.
|
|
|
|
@item @code{continue}
|
|
The @code{continue} statement (an extension) causes the most recent enclosing
|
|
@code{for} statement to start the next iteration.
|
|
|
|
@item @code{halt}
|
|
The @code{halt} statement (an extension) is an executed statement that
|
|
causes the @command{bc} processor to quit only when it is executed. For
|
|
example, "if (0 == 1) halt" will not cause @command{bc} to terminate
|
|
because the @code{halt} is not executed.
|
|
|
|
@item @code{return}
|
|
Return the value 0 from a function. (@xref{Functions}.)
|
|
|
|
@item @code{return} ( expression )
|
|
Return the value of the expression from a function. (@xref{Functions}.)
|
|
As an extension, the parenthesis are not required.
|
|
@end table
|
|
|
|
@node Pseudo Statements, , Statements, Statements
|
|
@section Pseudo Statements
|
|
|
|
These statements are not statements in the traditional sense. They are
|
|
not executed statements. Their function is performed at "compile" time.
|
|
|
|
@table @code
|
|
@item limits
|
|
Print the local limits enforced by the local version of @command{bc}. This
|
|
is an extension.
|
|
|
|
@item quit
|
|
When the @code{quit} statement is read, the @command{bc} processor
|
|
is terminated, regardless of where the @code{quit} statement is found. For
|
|
example, "if (0 == 1) quit" will cause @command{bc} to terminate.
|
|
|
|
@item warranty
|
|
Print a longer warranty notice. This is an extension.
|
|
@end table
|
|
|
|
@node Functions, Examples, Statements, Top
|
|
@chapter Functions
|
|
|
|
@menu
|
|
* Math Library Functions::
|
|
@end menu
|
|
|
|
Functions provide a method of defining a computation that can be
|
|
executed later. Functions in @command{bc} always compute a value and
|
|
return it to the caller. Function definitions are "dynamic" in the
|
|
sense that a function is undefined until a definition is encountered in
|
|
the input. That definition is then used until another definition
|
|
function for the same name is encountered. The new definition then
|
|
replaces the older definition. A function is defined as follows:
|
|
|
|
@example
|
|
@code{define} @var{name} @code{(} @var{parameters} @code{)} @code{@{} @var{newline}
|
|
@var{auto_list statement_list} @code{@}}
|
|
@end example
|
|
|
|
A function call is just an expression of the form
|
|
"@code{name} @code{(}@var{parameters}@code{)}".
|
|
|
|
Parameters are numbers or arrays (an extension). In the function definition,
|
|
zero or more parameters are defined by listing their names separated by
|
|
commas. Numbers are only call by value parameters. Arrays are only
|
|
call by variable. Arrays are specified in the parameter definition by
|
|
the notation "@var{name}@code{[ ]}". In the function call, actual parameters
|
|
are full expressions for number parameters. The same notation is used
|
|
for passing arrays as for defining array parameters. The named array is
|
|
passed by variable to the function. Since function definitions are dynamic,
|
|
parameter numbers and types are checked when a function is called. Any
|
|
mismatch in number or types of parameters will cause a runtime error.
|
|
A runtime error will also occur for the call to an undefined function.
|
|
|
|
The @var{auto_list} is an optional list of variables that are for
|
|
"local" use. The syntax of the auto list (if present) is "@code{auto}
|
|
@var{name}, ... ;". (The semicolon is optional.) Each @var{name} is
|
|
the name of an auto variable. Arrays may be specified by using the
|
|
same notation as used in parameters. These variables have their
|
|
values pushed onto a stack at the start of the function. The
|
|
variables are then initialized to zero and used throughout the
|
|
execution of the function. At function exit, these variables are
|
|
popped so that the original value (at the time of the function call)
|
|
of these variables are restored. The parameters are really auto
|
|
variables that are initialized to a value provided in the function
|
|
call.
|
|
Auto variables are different than traditional local variables
|
|
because if function A calls function B, B may access function
|
|
A's auto variables by just using the same name, unless function B has
|
|
called them auto variables. Due to the fact that auto variables and
|
|
parameters are pushed onto a stack, @command{bc} supports recursive functions.
|
|
|
|
The function body is a list of @command{bc} statements. Again, statements
|
|
are separated by semicolons or newlines. Return statements cause the
|
|
termination of a function and the return of a value. There are two
|
|
versions of the return statement. The first form, "@code{return}", returns
|
|
the value 0 to the calling expression. The second form,
|
|
"@code{return} ( @var{expression} )", computes the value of the expression
|
|
and returns that value to the calling expression. There is an implied
|
|
"@code{return} (0)" at the end of every function. This allows a function
|
|
to terminate and return 0 without an explicit @code{return} statement.
|
|
|
|
Functions also change the usage of the variable @var{ibase}. All
|
|
constants in the function body will be converted using the value of
|
|
@var{ibase} at the time of the function call. Changes of @var{ibase}
|
|
will be ignored during the execution of the function except for the
|
|
standard function @code{read}, which will always use the current value
|
|
of @var{ibase} for conversion of numbers.
|
|
|
|
As an extension, the format of the definition has been slightly relaxed.
|
|
The standard requires the opening brace be on the same line as the
|
|
@code{define} keyword and all other parts must be on following lines.
|
|
This version of @command{bc} will allow any number of newlines before and
|
|
after the opening brace of the function. For example, the following
|
|
definitions are legal.
|
|
|
|
@example
|
|
define d (n) @{ return (2*n); @}
|
|
define d (n)
|
|
@{ return (2*n); @}
|
|
@end example
|
|
|
|
|
|
@node Math Library Functions, , Functions, Functions
|
|
@section Math Library Functions
|
|
|
|
If @command{bc} is invoked with the @code{-l} option, a math library is
|
|
preloaded and the default @var{scale} is set to 20. The math functions will
|
|
calculate their results to the scale set at the time of their call. The
|
|
math library defines the following functions:
|
|
|
|
@table @code
|
|
@item s (@var{x})
|
|
The sine of @var{x}, @var{x} is in radians.
|
|
|
|
@item c (@var{x})
|
|
The cosine of @var{x}, @var{x} is in radians.
|
|
|
|
@item a (@var{x})
|
|
The arctangent of @var{x}, arctangent returns radians.
|
|
|
|
@item l (@var{x})
|
|
The natural logarithm of @var{x}.
|
|
|
|
@item @var{e} (@var{x})
|
|
The exponential function of raising @var{e} to the value @var{x}.
|
|
|
|
@item @var{j} (@var{n,x})
|
|
The bessel function of integer order @var{n} of @var{x}.
|
|
@end table
|
|
|
|
@node Examples, Readline and Libedit Options, Functions, Top
|
|
@chapter Examples
|
|
|
|
In /bin/sh, the following will assign the value of "pi" to the shell
|
|
variable @var{pi}.
|
|
@example
|
|
|
|
pi=$(echo "scale=10; 4*a(1)" | bc -l)
|
|
|
|
@end example
|
|
|
|
The following is the definition of the exponential function used in the
|
|
math library. This function is written in POSIX @command{bc}.
|
|
|
|
@example
|
|
|
|
scale = 20
|
|
|
|
/* Uses the fact that e^x = (e^(x/2))^2
|
|
When x is small enough, we use the series:
|
|
e^x = 1 + x + x^2/2! + x^3/3! + ...
|
|
*/
|
|
|
|
define e(x) @{
|
|
auto a, d, e, f, i, m, v, z
|
|
|
|
/* Check the sign of x. */
|
|
if (x<0) @{
|
|
m = 1
|
|
x = -x
|
|
@}
|
|
|
|
/* Precondition x. */
|
|
z = scale;
|
|
scale = 4 + z + .44*x;
|
|
while (x > 1) @{
|
|
f += 1;
|
|
x /= 2;
|
|
@}
|
|
|
|
/* Initialize the variables. */
|
|
v = 1+x
|
|
a = x
|
|
d = 1
|
|
|
|
for (i=2; 1; i++) @{
|
|
e = (a *= x) / (d *= i)
|
|
if (e == 0) @{
|
|
if (f>0) while (f--) v = v*v;
|
|
scale = z
|
|
if (m) return (1/v);
|
|
return (v/1);
|
|
@}
|
|
v += e
|
|
@}
|
|
@}
|
|
|
|
@end example
|
|
|
|
The following is code that uses the extended features of @command{bc} to
|
|
implement a simple program for calculating checkbook balances. This
|
|
program is best kept in a file so that it can be used many times
|
|
without having to retype it at every use.
|
|
|
|
@example
|
|
|
|
scale=2
|
|
print "\nCheck book program\n!"
|
|
print " Remember, deposits are negative transactions.\n"
|
|
print " Exit by a 0 transaction.\n\n"
|
|
|
|
print "Initial balance? "; bal = read()
|
|
bal /= 1
|
|
print "\n"
|
|
while (1) @{
|
|
"current balance = "; bal
|
|
"transaction? "; trans = read()
|
|
if (trans == 0) break;
|
|
bal -= trans
|
|
bal /= 1
|
|
@}
|
|
quit
|
|
|
|
@end example
|
|
|
|
|
|
The following is the definition of the recursive factorial function.
|
|
|
|
@example
|
|
|
|
define f (x) @{
|
|
if (x <= 1) return (1);
|
|
return (f(x-1) * x);
|
|
@}
|
|
|
|
@end example
|
|
|
|
@node Readline and Libedit Options, GNU @command{bc} and Other Implementations, Examples, Top
|
|
@chapter Readline and Libedit Options
|
|
|
|
GNU @command{bc} can be compiled (via a configure option) to use the GNU
|
|
@command{readline} input editor library or the BSD @command{libedit}
|
|
library. This allows the user to do
|
|
more editing of lines before sending them to @command{bc}. It also
|
|
allows for a history of previous lines typed. When this option is
|
|
selected, @command{bc} has one more special variable. This special
|
|
variable, @var{history} is the number of lines of history retained. A
|
|
value of -1 means that an unlimited number of history lines are
|
|
retained. This is the default value. Setting the value of
|
|
@var{history} to a positive number restricts the number of history lines
|
|
to the number given. The value of 0 disables the history feature. For
|
|
more information, read the user manuals for the GNU @command{readline},
|
|
@command{history} and BSD @command{libedit} libraries. One can not
|
|
enable both @command{readline} and @command{libedit} at the same time.
|
|
|
|
@node GNU @command{bc} and Other Implementations, Limits, Readline and Libedit Options, Top
|
|
@chapter GNU @command{bc} and Other Implementations
|
|
|
|
This version of @command{bc} was implemented from the POSIX P1003.2/D11
|
|
draft and contains several differences and extensions relative to the
|
|
draft and traditional implementations. It is not implemented in the
|
|
traditional way using @command{dc}. This version is a single process
|
|
which parses and runs a byte code translation of the program. There is
|
|
an "undocumented" option (-c) that causes the program to output the byte
|
|
code to the standard output instead of running it. It was mainly used
|
|
for debugging the parser and preparing the math library.
|
|
|
|
A major source of differences is extensions, where a feature is extended
|
|
to add more functionality and additions, where new features are added.
|
|
The following is the list of differences and extensions.
|
|
|
|
@table @var
|
|
|
|
@item LANG environment
|
|
This version does not conform to the POSIX standard in the processing
|
|
of the LANG environment variable and all environment variables starting
|
|
with LC_.
|
|
|
|
@item names
|
|
Traditional and POSIX @command{bc}
|
|
have single letter names for functions, variables and arrays. They have
|
|
been extended to be multi-character names that start with a letter and
|
|
may contain letters, numbers and the underscore character.
|
|
|
|
@item Strings
|
|
Strings are not allowed to contain NUL characters. POSIX says all characters
|
|
must be included in strings.
|
|
|
|
@item last
|
|
POSIX @command{bc} does not have a \fBlast variable. Some implementations
|
|
of @command{bc} use the period (.) in a similar way.
|
|
|
|
@item comparisons
|
|
POSIX @command{bc} allows comparisons only in the @code{if} statement,
|
|
the @code{while} statement, and the second expression of the @code{for}
|
|
statement. Also, only one relational operation is allowed in each of
|
|
those statements.
|
|
|
|
@item if statement, else clause
|
|
POSIX @command{bc} does not have an @code{else} clause.
|
|
|
|
@item for statement
|
|
POSIX @command{bc} requires all expressions to be present in the
|
|
@code{for} statement.
|
|
|
|
@item &&, ||, !
|
|
POSIX @command{bc} does not have the logical operators.
|
|
|
|
@item read function
|
|
POSIX @command{bc} does not have a @code{read} function.
|
|
|
|
@item print statement
|
|
POSIX @command{bc} does not have a @code{print} statement.
|
|
|
|
@item continue statement
|
|
POSIX @command{bc} does not have a continue statement.
|
|
|
|
@item array parameters
|
|
POSIX @command{bc} does not (currently) support array parameters in full.
|
|
The POSIX grammar allows for arrays in function definitions, but does
|
|
not provide a method to specify an array as an actual parameter. (This
|
|
is most likely an oversight in the grammar.) Traditional implementations
|
|
of @command{bc} have only call by value array parameters.
|
|
|
|
@item function format
|
|
POSIX @command{bc} requires the opening brace on the same line as the
|
|
@code{define} key word and the @code{auto} statement on the next line.
|
|
|
|
@item =+, =-, =*, =/, =%, =^
|
|
POSIX @command{bc} does not require these "old style" assignment
|
|
operators to be defined. This version may allow these "old style"
|
|
assignments. Use the @code{limits} statement to see if the installed
|
|
version supports them. If it does support the "old style" assignment
|
|
operators, the statement "a =- 1" will decrement @code{a} by 1 instead
|
|
of setting @code{a} to the value -1.
|
|
|
|
@item spaces in numbers
|
|
Other implementations of @command{bc} allow spaces in numbers. For example,
|
|
"x=1 3" would assign the value 13 to the variable x. The same statement
|
|
would cause a syntax error in this version of @command{bc}.
|
|
|
|
@item errors and execution
|
|
This implementation varies from other implementations in terms of what
|
|
code will be executed when syntax and other errors are found in the
|
|
program. If a syntax error is found in a function definition, error
|
|
recovery tries to find the beginning of a statement and continue to
|
|
parse the function. Once a syntax error is found in the function, the
|
|
function will not be callable and becomes undefined.
|
|
Syntax errors in the interactive execution code will invalidate the
|
|
current execution block. The execution block is terminated by an
|
|
end of line that appears after a complete sequence of statements.
|
|
For example,
|
|
|
|
@example
|
|
a = 1
|
|
b = 2
|
|
@end example
|
|
|
|
has two execution blocks and
|
|
|
|
@example
|
|
@{ a = 1
|
|
b = 2 @}
|
|
@end example
|
|
|
|
has one execution block. Any runtime error will terminate the execution
|
|
of the current execution block. A runtime warning will not terminate the
|
|
current execution block.
|
|
|
|
@item Interrupts
|
|
During an interactive session, the SIGINT signal (usually generated by
|
|
the control-C character from the terminal) will cause execution of the
|
|
current execution block to be interrupted. It will display a "runtime"
|
|
error indicating which function was interrupted. After all runtime
|
|
structures have been cleaned up, a message will be printed to notify the
|
|
user that @command{bc} is ready for more input. All previously defined
|
|
functions remain defined and the value of all non-auto variables are the
|
|
value at the point of interruption. All auto variables and function
|
|
parameters are removed during the clean up process. During a
|
|
non-interactive session, the SIGINT signal will terminate the entire run
|
|
of @command{bc}.
|
|
@end table
|
|
|
|
@node Limits, Environment Variables, GNU @command{bc} and Other Implementations, Top
|
|
@chapter Limits
|
|
|
|
The following are the limits currently in place for this @command{bc}
|
|
processor. Some of them may have been changed by an installation. Use
|
|
the @code{limits} statement to see the actual values.
|
|
|
|
@table @code
|
|
|
|
@item BC_BASE_MAX
|
|
The maximum output base is currently set at 999. The maximum input base
|
|
is 16.
|
|
|
|
@item BC_DIM_MAX
|
|
This is currently an arbitrary limit of 65535 as distributed. Your
|
|
installation may be different.
|
|
|
|
@item BC_SCALE_MAX
|
|
The number of digits after the decimal point is limited to INT_MAX digits.
|
|
Also, the number of digits before the decimal point is limited to INT_MAX
|
|
digits.
|
|
|
|
@item BC_STRING_MAX
|
|
The limit on the number of characters in a string is INT_MAX characters.
|
|
|
|
@item exponent
|
|
The value of the exponent in the raise operation (^) is limited to LONG_MAX.
|
|
|
|
@item multiply
|
|
The multiply routine may yield incorrect results if a number
|
|
has more than LONG_MAX / 90 total digits. For 32 bit longs, this number is
|
|
23,860,929 digits.
|
|
|
|
@item variable names
|
|
The current limit on the number of unique names is 32767 for each of
|
|
simple variables, arrays and functions.
|
|
@end table
|
|
|
|
@node Environment Variables, , Limits, Top
|
|
@chapter Environment Variables
|
|
|
|
The following environment variables are processed by @command{bc}:
|
|
|
|
@table @code
|
|
|
|
|
|
@item POSIXLY_CORRECT
|
|
This is the same as the -s option (@pxref{Command Line Options}).
|
|
|
|
@item BC_ENV_ARGS
|
|
This is another mechanism to get arguments to @command{bc}. The format
|
|
is the same as the command line arguments. These arguments are
|
|
processed first, so any files listed in the environent arguments are
|
|
processed before any command line argument files. This allows the user
|
|
to set up "standard" options and files to be processed at every
|
|
invocation of @command{bc}. The files in the environment variables
|
|
would typically contain function definitions for functions the user
|
|
wants defined every time @command{bc} is run.
|
|
|
|
@item BC_LINE_LENGTH
|
|
This should be an integer specifing the number of characters in an
|
|
output line for numbers. This includes the backslash and newline
|
|
characters for long numbers.
|
|
@end table
|
|
|
|
@contents
|
|
@bye
|
|
|
|
|