View Source: bc(1) - Waikato Linux Users Group

Edit PageHistory Diff Info LikePages
bc
!!!bc
NAME
SYNTAX
VERSION
DESCRIPTION
ENVIRONMENT VARIABLES
DIAGNOSTICS
BUGS
AUTHOR
ACKNOWLEDGEMENTS
----
!!NAME


bc - An arbitrary precision calculator language
!!SYNTAX


__bc__ [[ __-hlwsqv__ ] [[long-options] [[ ''file
...'' ]
!!VERSION


This man page documents GNU bc version 1.06.
!!DESCRIPTION


__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. __bc__ starts by processing
code from all the files listed on the command line in the
order listed. After all files have been processed, __bc__
reads from the standard input. All code is executed as it is
read. (If a file contains a command to halt the processor,
__bc__ will never read from the standard
input.)


This version of __bc__ contains several extensions beyond
traditional __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.


__OPTIONS__


-h, --help


Print the usage and exit.


-i, --interactive


Force interactive mode.


-l, --mathlib


Define the standard math library.


-w, --warn


Give warnings for extensions to POSIX
__bc__.


-s, --standard


Process exactly the POSIX __bc__ language.


-q, --quiet


Do not print the normal GNU bc welcome.


-v, --version


Print the version number and copyright and
quit.


__NUMBERS__


The most basic element in __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.
1935.000 has a length of 7 and a scale of 3.


__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 alpha-numeric names are an
extension. In POSIX __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, __scale, ibase,
obase,__ and __last__. __scale__ defines how some
operations use digits after the decimal point. The default
value of __scale__ is 0. __ibase__ and __obase__
define the conversion base for input and output numbers. The
default for both input and output is base 10. __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.


__COMMENTS__


Comments in __bc__ start with the characters __/*__
and end with the characters __*/__. 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 __bc__, a single line
comment has been added as an extension. A single line
comment starts at a __#__ 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.


__EXPRESSIONS__


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


A simple expression is just a constant. __bc__ converts
constants into internal decimal numbers using the current
input base, specified by the variable __ibase__. (There
is an exception in functions.) The legal values of
__ibase__ are 2 through 16. Assigning a value outside
this range to __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 __ibase__. (i.e.
A = 10.) For multi-digit numbers, __bc__ changes all
input digits greater or equal to ibase to the value of
__ibase__-1. This makes the number __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
__scale__. Legal values of the variable __scale__ are
0 to the maximum number representable by a C
integer.


In the following descriptions of legal expressions,


''name''


and an array variable is specified as


''name''[[''expr'']


Unless specifically mentioned the scale of the result is the
maximum scale of the expressions involved.


- expr


The result is the negation of the expression.


++ var


The variable is incremented by one and the new value is the
result of the expression.


-- var


The variable is decremented by one and the new value is the
result of the expression.


var ++


The result of the expression is the value of the variable
and then the variable is incremented by one.


var --


The result of the expression is the value of the variable
and then the variable is decremented by one.


expr + expr


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


expr - expr


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


expr * expr


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


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 __scale__.


expr % expr


The result of the expression is the
scale__ digits. That result is
used to compute a-(a/b)*b to the scale of the maximum of
__scale__+scale(b) and scale(a). If __scale__ is set
to zero and both expressions are integers this expression is
the integer remainder function.


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 __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 __scale__ and the scale of the first expression. (e.g.
scale(a^b) = min(scale(a)*b, max( __scale,__ scale(a))).)
It should be noted that expr^0 will always return the value
of 1.


( expr )


This alters the standard precedence to force the evaluation
of the expression.


var = expr


The variable is assigned the value of the
expression.


var


This is equivalent to


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 bc requires that relational expressions
are used only in if, while, and for statements and that only
one relational test may be done in them.) The relational
operators are


expr1


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


expr1


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


expr1


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


expr1


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


expr1 == expr2


The result is 1 if expr1 is equal to expr2.


expr1 != expr2


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


Boolean operations are also legal. (POSIX __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:


!expr


The result is 1 if expr is 0.


expr


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


expr || expr


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


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


|| operator, left associative
This precedence was chosen so that POSIX compliant __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:


a = 3


Most C programmers would assume this would assign the result
of
bc__ is assign the
value 3 to the variable
__


There are a few more special expressions that are provided
in __bc__. These have to do with user defined functions
and standard functions. They all appear as
__name''__(__''parameters''__)__
__


length ( expression )


The value of the length function is the number of
significant digits in the expression.


read ( )


The 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 read function is the number
read from the standard input using the current value of the
variable __ibase__ for the conversion base.


scale ( expression )


The value of the scale function is the number of digits
after the decimal point in the expression.


sqrt ( expression )


The value of the sqrt function is the square root of the
expression. If the expression is negative, a run time error
is generated.


__STATEMENTS__


Statements (as in most algebraic languages) provide the
sequencing of expression evaluation. In __bc__ statements
are executed
__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
__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
__bc__ statements and what they do: (Things enclosed in
brackets ([[]) are optional parts of the
statement.)


expression


This statement does one of two things. If the expression
starts with
obase__. The legal
values for __obase__ are 2 through BC_BASE_MAX. (See the
section LIMITS.) For bases 2 through 16, the usual method of
writing numbers is used. For bases greater than 16,
__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
__bc__, printing a number
causes the side effect of assigning the printed value to the
special variable __last__. This allows the user to
recover the last value printed without having to retype the
expression that printed the number. Assigning to __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
__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 __last__.)


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 take
literally, including any newline. No newline character is
printed after the string.


__print__ list


The print statement (an extension) provides another method
of output. The
last__. Strings in
the print statement are printed to the output and may
contain special characters. Special characters start with
the backslash character (). The special characters
recognized by __bc__ are
__


{ statement_list }


This is the compound statement. It allows multiple
statements to be grouped together for
execution.


__if__ ( expression ) statement1 [[__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 else
clause is an extension.)


__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
break statement.


__for__ ( [[expression1] ; [[expression2] ; [[expression3] )
statement


The for statement controls repeated execution of the
statement. Expression1 is evaluated before the loop.
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, expression3 is evaluated before the
reevaluation of expression2. If expression1 or expression3
are missing, nothing is evaluated at the point they would be
evaluated. If expression2 is missing, it is the same as
substituting the value 1 for expression2. (The optional
expressions are an extension. POSIX __bc__ requires all
three expressions.) The following is equivalent code for the
for statement:


expression1;
while (expression2) {
statement;
expression3;
}


__break__


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


__continue__


The continue statement (an extension) causes the most recent
enclosing for statement to start the next
iteration.


__halt__


The halt statement (an extension) is an executed statement
that causes the __bc__ processor to quit only when it is
executed. For example,
__bc__ to terminate because the halt is not
executed.


__return__


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


__return__ ( expression )


Return the value of the expression from a function. (See the
section on functions.) As an extension, the parenthesis are
not required.


__PSEUDO STATEMENTS__


These statements are not statements in the traditional
sense. They are not executed statements. Their function is
performed at


__limits__


Print the local limits enforced by the local version of
__bc__. This is an extension.


__quit__


When the quit statement is read, the __bc__ processor is
terminated, regardless of where the quit statement is found.
For example,
__bc__ to terminate.


__warranty__


Print a longer warranty notice. This is an
extension.


__FUNCTIONS__


Functions provide a method of defining a computation that
can be executed later. Functions in __bc__ always compute
a value and return it to the caller. Function definitions
are
__


__       define__ ''name'' __(__ ''parameters'' __) {__ ''newline
auto_list   statement_list'' __}
__A function call is just an expression of the form name''__(__''parameters''__)____


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 name''__[[]__
__


The ''auto_list'' is an optional list of variables that
are for
''auto__ ''name'', ... ;
''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, __bc__
supports recursive functions.


The function body is a list of __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, __return__
__return (__ ''expression''
__)__
__return (0)__
__


Functions also change the usage of the variable
__ibase__. All constants in the function body will be
converted using the value of __ibase__ at the time of the
function call. Changes of __ibase__ will be ignored
during the execution of the function except for the standard
function __read__, which will always use the current
value of __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 __define__ keyword and all other
parts must be on following lines. This version of __bc__
will allow any number of newlines before and after the
opening brace of the function. For example, the following
definitions are legal.


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


__MATH LIBRARY__


If __bc__ is invoked with the __-l__ option, a math
library is preloaded and the default 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:


s (''x'')


The sine of x, x is in radians.


c (''x'')


The cosine of x, x is in radians.


a (''x'')


The arctangent of x, arctangent returns
radians.


l (''x'')


The natural logarithm of x.


e (''x'')


The exponential function of raising e to the value
x.


j (''n,x'')


The bessel function of integer order n of x.


__EXAMPLES__


In /bin/sh, the following will assign the value of
pi__.


pi=$(echo


The following is the definition of the exponential function
used in the math library. This function is written in POSIX
__bc__.


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
The following is code that uses the extended features of __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.


scale=2
print
The following is the definition of the recursive factorial function.


define f (x) {
if (x


__READLINE AND LIBEDIT OPTIONS__


GNU __bc__ can be compiled (via a configure option) to
use the GNU __readline__ input editor library or the BSD
__libedit__ library. This allows the user to do editing
of lines before sending them to __bc__. It also allows
for a history of previous lines typed. When this option is
selected, __bc__ has one more special variable. This
special variable, __history__ is the number of lines of
history retained. For __readline__, a value of -1 means
that an unlimited number of history lines are retained.
Setting the value of __history__ to a positive number
restricts the number of history lines to the number given.
The value of 0 disables the history feature. The default
value is 100. For more information, read the user manuals
for the GNU __readline__, __history__ and BSD
__libedit__ libraries. One can not enable both
__readline__ and __libedit__ at the same
time.


__DIFFERENCES__


This version of __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 ''dc(1).'' This version is a single process
which parses and runs a byte code translation of the
program. There is an
''


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.


LANG


This version does not conform to the POSIX standard in the
processing of the LANG environment variable and all
environment variables starting with LC_.


names


Traditional and POSIX __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.


Strings


Strings are not allowed to contain NUL characters. POSIX
says all characters must be included in
strings.


last


POSIX __bc__ does not have a __last__ variable. Some
implementations of __bc__ use the period (.) in a similar
way.


comparisons


POSIX __bc__ allows comparisons only in the if statement,
the while statement, and the second expression of the for
statement. Also, only one relational operation is allowed in
each of those statements.


if statement, else clause


POSIX __bc__ does not have an else clause.


for statement


POSIX __bc__ requires all expressions to be present in
the for statement.




POSIX __bc__ does not have the logical
operators.


read function


POSIX __bc__ does not have a read function.


print statement


POSIX __bc__ does not have a print statement
.


continue statement


POSIX __bc__ does not have a continue
statement.


return statement


POSIX __bc__ requires parentheses around the return
expression.


array parameters


POSIX __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 __bc__ have only call by value array
parameters.


function format


POSIX __bc__ requires the opening brace on the same line
as the __define__ key word and the __auto__ statement
on the next line.


=+, =-, =*, =/, =%, =^


POSIX __bc__ does not require these
__a__ by 1 instead of setting __a__ to the value
-1.


spaces in numbers


Other implementations of __bc__ allow spaces in numbers.
For example,
__bc__.


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,


a = 1
b = 2
has two execution blocks and


{ a = 1
b = 2 }
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.


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
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 __bc__.


__LIMITS__


The following are the limits currently in place for this
__bc__ processor. Some of them may have been changed by
an installation. Use the limits statement to see the actual
values.


BC_BASE_MAX


The maximum output base is currently set at 999. The maximum
input base is 16.


BC_DIM_MAX


This is currently an arbitrary limit of 65535 as
distributed. Your installation may be
different.


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.


BC_STRING_MAX


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


exponent


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


variable names


The current limit on the number of unique names is 32767 for
each of simple variables, arrays and functions.
!!ENVIRONMENT VARIABLES


The following environment variables are processed by
__bc__:


POSIXLY_CORRECT


This is the same as the __-s__ option.


BC_ENV_ARGS


This is another mechanism to get arguments to __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
__bc__. The files in the environment
variables would typically contain function definitions for
functions the user wants defined every time __bc__ is
run.


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.
!!DIAGNOSTICS


If any file on the command line can not be opened, __bc__
will report that the file is unavailable and terminate.
Also, there are compile and run time diagnostics that should
be self-explanatory.
!!BUGS


Error recovery is not very good yet.


Email bug reports to __bug-bc@gnu.org__. Be sure to
include the word ``bc'' somewhere in the ``Subject:''
field.
!!AUTHOR


Philip A. Nelson
philnelson@acm.org
!!ACKNOWLEDGEMENTS


The author would like to thank Steve Sommars
(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.
----
5 pages link to bc(1):
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.
Last edited on Monday, June 3, 2002 6:49:59 pm by "perry"
Edit PageHistory Diff Info LikePages