sbase/bc.1

.Dd December 17, 2026
.Dt BC 1
.Os sbase
.Sh NAME
.Nm bc
.Nd arbitrary-precision arithmetic language
.Sh SYNOPSIS
.Nm
.Op Fl p Ar dc
.Op Fl cdls
.Op Ar file ...
.Sh DESCRIPTION
.Nm
is an arbitrary-precision arithmetic language with syntax similar to C.
.Nm
reads each
.Ar file
in sequence and compiles the bc code into dc code,
which is then executed
by spawning
.Xr dc 1
as a subprocess.
After all the files are loaded and executed then
it reads from stdin.
.Sh OPTIONS
.Bl -tag -width Ds
.It Fl p Ar dc
Dc program spawned to run the translated code generated by
.Ar bc .
By default,
it is
.Ar dc .
.It Fl c
Compile only mode.
Generate dc code without spawning a dc subprocess.
The compiled dc code is written to stdout.
.It Fl d
Debug mode.
Enable yacc parser debugging output.
.It Fl l
Load the mathematical library
that is loaded before any file from the command line.
.It Fl s
Enable the extended mode.
In this mode,
the automatic printing of expression results is suppressed,
and only explicit
.Ic print
statements produce output.
Names of variables and functions can be longer than 1 character,
but still constrained to lower case latin characters.
The output of
.Ar bc
in this mode is suitable only for the suckless
.Ar dc
version.
.El
.Sh LANGUAGE
.Ss Comments
Comments are enclosed in
.Ql /*
and
.Ql */ .
.Ss Numbers
Numbers may contain digits 0-9 and, when the input base is greater than 10,
letters A-F as hexadecimal digits.
Numbers may include a decimal point.
.Ss Variables
Variables are single lowercase letters
.Ql a
through
.Ql z .
Variables hold arbitrary-precision numbers and are automatically initialized to 0.
The special variable .
holds the value of the last expression calculated,
useful to avoid retyping long numbers.
.Ss Arrays
Array elements are referenced as
.Ar name Ns Oo Ar expr Oc .
Arrays are single lowercase letters
.Ql a
through
.Ql z .
Array indices may be any expression.
Arrays are automatically initialized with all elements set to 0.
.Ss Special Variables
.Bl -tag -width "scale"
.It Ic scale
The number of digits after the decimal point in results.
Default is 0.
Affects division, modulus, power, and square root operations.
.It Ic ibase
The input number base.
Must be between 2 and 16 inclusive.
Default is 10.
.It Ic obase
The output number base.
Must be at least 2.
Default is 10.
.El
.Ss Operators
Arithmetic operators in order of precedence (highest to lowest):
.Bl -tag -width "^"
.It Ic \&^ ^=
Exponentiation (right associative).
The exponent is truncated to an integer.
.It Ic * / % *= /= %=
Multiplication, division, modulus.
.It Ic + \- += \-=
Addition, subtraction.
.It Ic ++ \-\-
Increment and decrement (prefix or postfix).
.It Ic =
Assignment.
.El
.Ss Built-in Functions
.Bl -tag -width "length(expr)"
.It Fn sqrt expr
Square root of
.Ar expr .
.It Fn length expr
Number of significant decimal digits in
.Ar expr .
.It Fn scale expr
Number of digits after the decimal point in
.Ar expr .
.El
.Ss Expressions
.Pp
Expressions are combinations of operators,
function calls,
numbers and variables following the
normal arithmetic rules.
Parenthesis can be used to modify the precedence of operators.
.Ss Relational
.Pp
Relational expressions are composed by
expressions combined using relational operators.
They only can be used in the context of
a
.Ic if ,
.Ic while
or
.Ic for
statements.
.Pp
Relational operators:
.Bl -tag -width "!="
.It Ic ==
Equal to.
.It Ic !=
Not equal to.
.It Ic <
Less than.
.It Ic <=
Less than or equal to.
.It Ic >
Greater than.
.It Ic >=
Greater than or equal to.
.El
.Ss Statements
.Bl -tag -width Ds
.It Ar expr
A expression in a single line,
or separated by the character
.Ar ;
is a statement.
If the expression is not an assignment expression then
the result value is printed to stdout
unless the option
.Ic -s
is used.
.It Ic print Ar expr
Print the value of
.Ar expr
followed by a newline.
.It Ic print Qo Ar string Qc
Print
.Ar string
without a newline.
.It Ic print Qo Ar string Qc , Ar expr
Print
.Ar string
without a newline, then print
.Ar expr
with a newline.
.It Qo Ar string Qc
A string by itself is printed without a newline.
.It Ic if ( Ar rel ) Ar stat
Execute
.Ar stat
if
.Ar rel
is non-zero.
.It Ic while ( Ar rel ) Ar stat
Execute
.Ar stat
repeatedly while
.Ar rel
is non-zero.
.It Ic for ( Ar expr1 ; Ar rel ; Ar expr2 ) Ar stat
Equivalent to
.Ar expr1 ;
.Ic while ( Ar rel )
{
.Ar stat ;
.Ar expr2
}.
The 3 components of the for loop are required.
.It Ic break
Exit from the innermost
.Ic while
or
.Ic for
loop.
.It Ic quit
Exit
.Nm
when the statement is read,
independently of being under an if statement or in a function.
.It Ic return
Return 0 from a function.
.It Ic return ( )
Return 0 from a function.
.It Ic return ( Ar expr )
Return
.Ar expr
from a function.
.It Ic { Ar stat-list Ic }
Group statements.
.El
.Ss Function Definitions
Functions are defined as:
.Bd -literal -offset indent
define name(parameters) {
	auto local-variables
	statements
}
.Ed
.Pp
Notice that the opening brace must be in the same line
than the define statement.
Function names are single lowercase letters.
Parameters and local variables are comma-separated lists of simple
variables or arrays (denoted by
.Ar array Ns Ic [] ) .
The
.Ic auto
statement is optional and must appear first in the function body if present.
.Pp
Functions are called as
.Fn name arguments .
Array arguments must be passed as
.Ar array Ns Ic [] .
Functions return a value using the
.Ic return
statement.
If no
.Ic return
is executed, the function returns 0.
.Ss Namespaces
The variables, arrays and function names
are composed of only one letter,
but they are independent namespaces.
The same letter can be used for a variable,
array or function without problems.
.Sh LIBRARY
When invoked with the
.Fl l
option,
.Nm
preloads a mathematical library that defines the following functions:
.Bl -tag -width "j(n,x)"
.It Fn e x
Exponential function.
Returns e raised to the power
.Ar x .
.It Fn l x
Natural logarithm of
.Ar x .
.It Fn s x
Sine of
.Ar x
where
.Ar x
is in radians.
.It Fn c x
Cosine of
.Ar x
where
.Ar x
is in radians.
.It Fn a x
Arctangent of
.Ar x .
Returns the value in radians.
.It Fn j n,x
Bessel function of order
.Ar n
of
.Ar x .
.El
.Pp
The library also sets
.Ic scale
to 20 by default.
.Sh IMPLEMENTATION NOTES
This implementation of
.Nm
is a compiler that translates bc language into dc commands.
.Pp
Variables are mapped to dc registers.
Functions are compiled to dc macros stored in registers identified by
function name.
Control flow statements are implemented using dc's conditional macro
execution commands.
.Pp
The maximum nesting level for control structures and function calls is 32.
.Sh SEE ALSO
.Xr dc 1
.Rs
.%A L. L. Cherry
.%A R. H. Morris
.%T "BC \(em An Arbitrary Precision Desk-Calculator Language"
.Re
.Sh STANDARDS
POSIX.1-2013.
The
.Ic print
statement and the
.Fl d
and
.Fl s
flags are extensions to the POSIX specification.