~ubuntu-branches/ubuntu/oneiric/bc/oneiric

« back to all changes in this revision

Viewing changes to doc/bc.info

  • Committer: Bazaar Package Importer
  • Author(s): Matthias Klose
  • Date: 2007-12-05 12:24:03 UTC
  • mfrom: (3.1.2 lenny)
  • Revision ID: james.westby@ubuntu.com-20071205122403-rv1a7x90ktu1wl95
Tags: 1.06.94-3ubuntu1
* Merge with Debian; remaining changes:
  - Make bc/dc notice read and write errors on its input and output.

Show diffs side-by-side

added added

removed removed

Lines of Context:
1
 
This is bc.info, produced by makeinfo version 4.0 from bc.texi.
 
1
This is bc.info, produced by makeinfo version 4.8 from bc.texi.
 
2
 
 
3
START-INFO-DIR-ENTRY
 
4
* bc: (bc).                    An arbitrary precision calculator language.
 
5
END-INFO-DIR-ENTRY
2
6
 
3
7
 
4
8
File: bc.info,  Node: Top,  Next: Introduction,  Prev: (dir),  Up: (dir)
12
16
* Functions::
13
17
* Examples::
14
18
* Readline and Libedit Options::
15
 
* GNU `bc' and Other Implementations::
 
19
* Comparison with Other Implementations::
16
20
* Limits::
17
21
* Environment Variables::
18
22
 
19
23
 
20
24
File: bc.info,  Node: Introduction,  Next: Basic Elements,  Prev: Top,  Up: Top
21
25
 
22
 
Introduction
23
 
************
 
26
1 Introduction
 
27
**************
24
28
 
25
29
* Menu:
26
30
 
30
34
 
31
35
File: bc.info,  Node: Description,  Next: Command Line Options,  Prev: Introduction,  Up: Introduction
32
36
 
33
 
Description
34
 
===========
 
37
1.1 Description
 
38
===============
35
39
 
36
 
   `bc' [ -hlwsqv ] [long-options] [  FILE ... ]
 
40
`bc' [ -hlwsqv ] [long-options] [  FILE ... ]
37
41
 
38
42
   `bc' is a language that supports arbitrary precision numbers with
39
43
interactive execution of statements.  There are some similarities in
63
67
 
64
68
File: bc.info,  Node: Command Line Options,  Next: Numbers,  Prev: Description,  Up: Introduction
65
69
 
66
 
Command Line Options
67
 
====================
 
70
1.2 Command Line Options
 
71
========================
68
72
 
69
 
   `bc' takes the following options from the command line:
 
73
`bc' takes the following options from the command line:
70
74
`-h, --help'
71
75
     Print the usage and exit.
72
76
 
85
89
`-v, --version'
86
90
     Print the version number and copyright and quit.
87
91
 
 
92
 
88
93
 
89
94
File: bc.info,  Node: Basic Elements,  Next: Expressions,  Prev: Introduction,  Up: Top
90
95
 
91
 
Basic Elements
92
 
**************
 
96
2 Basic Elements
 
97
****************
93
98
 
94
99
* Menu:
95
100
 
100
105
 
101
106
File: bc.info,  Node: Numbers,  Next: Variables,  Prev: Command Line Options,  Up: Basic Elements
102
107
 
103
 
Numbers
104
 
=======
 
108
2.1 Numbers
 
109
===========
105
110
 
106
 
   The most basic element in `bc' is the number.  Numbers are arbitrary
 
111
The most basic element in `bc' is the number.  Numbers are arbitrary
107
112
precision numbers.  This precision is both in the integer part and the
108
113
fractional part.  All numbers are represented internally in decimal and
109
114
all computation is done in decimal.  (This version truncates results
117
122
 
118
123
File: bc.info,  Node: Variables,  Next: Comments,  Prev: Numbers,  Up: Basic Elements
119
124
 
120
 
Variables
121
 
=========
 
125
2.2 Variables
 
126
=============
122
127
 
123
 
   Numbers are stored in two types of variables, simple variables and
 
128
Numbers are stored in two types of variables, simple variables and
124
129
arrays.  Both simple variables and array variables are named.  Names
125
130
begin with a letter followed by any number of letters, digits and
126
131
underscores.  All letters must be lower case.  (Full alphanumeric names
140
145
 
141
146
File: bc.info,  Node: Comments,  Prev: Variables,  Up: Basic Elements
142
147
 
143
 
Comments
144
 
========
 
148
2.3 Comments
 
149
============
145
150
 
146
 
   Comments in `bc' start with the characters `/*' and end with the
 
151
Comments in `bc' start with the characters `/*' and end with the
147
152
characters `*/'.  Comments may start anywhere and appear as a single
148
153
space in the input.  (This causes comments to delimit other input
149
154
items.  For example, a comment can not be found in the middle of a
158
163
 
159
164
File: bc.info,  Node: Expressions,  Next: Statements,  Prev: Basic Elements,  Up: Top
160
165
 
161
 
Expressions
162
 
***********
 
166
3 Expressions
 
167
*************
163
168
 
164
169
* Menu:
165
170
 
173
178
 
174
179
File: bc.info,  Node: About Expressions and Special Variables,  Next: Basic Expressions,  Prev: Expressions,  Up: Expressions
175
180
 
176
 
About Expressions and Special Variables
177
 
=======================================
 
181
3.1 About Expressions and Special Variables
 
182
===========================================
178
183
 
179
 
   The numbers are manipulated by expressions and statements.  Since
180
 
the language was designed to be interactive, statements and expressions
181
 
are executed as soon as possible.  There is no main program.  Instead,
182
 
code is executed as it is encountered.  (Functions, discussed in detail
 
184
The numbers are manipulated by expressions and statements.  Since the
 
185
language was designed to be interactive, statements and expressions are
 
186
executed as soon as possible.  There is no main program.  Instead, code
 
187
is executed as it is encountered.  (Functions, discussed in detail
183
188
later, are defined when encountered.)
184
189
 
185
190
   A simple expression is just a constant. `bc' converts constants into
205
210
 
206
211
File: bc.info,  Node: Basic Expressions,  Next: Relational Expressions,  Prev: About Expressions and Special Variables,  Up: Expressions
207
212
 
208
 
Basic Expressions
209
 
=================
 
213
3.2 Basic Expressions
 
214
=====================
210
215
 
211
 
   In the following descriptions of legal expressions, "expr" refers to
212
 
a complete expression and "VAR" refers to a simple or an array variable.
 
216
In the following descriptions of legal expressions, "expr" refers to a
 
217
complete expression and "VAR" refers to a simple or an array variable.
213
218
A simple variable is just a
214
219
 
215
220
   NAME
290
295
 
291
296
File: bc.info,  Node: Relational Expressions,  Next: Boolean Expressions,  Prev: Basic Expressions,  Up: Expressions
292
297
 
293
 
Relational Expressions
294
 
======================
 
298
3.3 Relational Expressions
 
299
==========================
295
300
 
296
 
   Relational expressions are a special kind of expression that always
 
301
Relational expressions are a special kind of expression that always
297
302
evaluate to 0 or 1, 0 if the relation is false and 1 if the relation is
298
303
true.  These may appear in any legal expression.  (POSIX `bc' requires
299
304
that relational expressions are used only in `if', `while', and `for'
321
326
 
322
327
File: bc.info,  Node: Boolean Expressions,  Next: Precedence,  Prev: Relational Expressions,  Up: Expressions
323
328
 
324
 
Boolean Expressions
325
 
===================
 
329
3.4 Boolean Expressions
 
330
=======================
326
331
 
327
 
   Boolean operations are also legal.  (POSIX `bc' does NOT have
328
 
boolean operations). The result of all boolean operations are 0 and 1
329
 
(for false and true) as in relational expressions.  The boolean
330
 
operators are:
 
332
Boolean operations are also legal.  (POSIX `bc' does NOT have boolean
 
333
operations). The result of all boolean operations are 0 and 1 (for
 
334
false and true) as in relational expressions.  The boolean operators
 
335
are:
331
336
 
332
337
`!expr'
333
338
     The result is 1 if expr is 0.
341
346
 
342
347
File: bc.info,  Node: Precedence,  Next: Special Expressions,  Prev: Boolean Expressions,  Up: Expressions
343
348
 
344
 
Precedence
345
 
==========
 
349
3.5 Precedence
 
350
==============
346
351
 
347
 
   The expression precedence is as follows: (lowest to highest)
 
352
The expression precedence is as follows: (lowest to highest)
348
353
 
349
354
     || operator, left associative
350
355
     && operator, left associative
373
378
 
374
379
File: bc.info,  Node: Special Expressions,  Prev: Precedence,  Up: Expressions
375
380
 
376
 
Special Expressions
377
 
===================
 
381
3.6 Special Expressions
 
382
=======================
378
383
 
379
 
   There are a few more special expressions that are provided in `bc'.
 
384
There are a few more special expressions that are provided in `bc'.
380
385
These have to do with user-defined functions and standard functions.
381
386
They all appear as "NAME`('PARAMETERS`)'".  *Note Functions::, for
382
387
user-defined functions.  The standard functions are:
407
412
 
408
413
File: bc.info,  Node: Statements,  Next: Functions,  Prev: Expressions,  Up: Top
409
414
 
410
 
Statements
411
 
**********
 
415
4 Statements
 
416
************
412
417
 
413
418
* Menu:
414
419
 
540
545
 
541
546
File: bc.info,  Node: Pseudo Statements,  Prev: Statements,  Up: Statements
542
547
 
543
 
Pseudo Statements
544
 
=================
 
548
4.1 Pseudo Statements
 
549
=====================
545
550
 
546
 
   These statements are not statements in the traditional sense.  They
547
 
are not executed statements.  Their function is performed at "compile"
548
 
time.
 
551
These statements are not statements in the traditional sense.  They are
 
552
not executed statements.  Their function is performed at "compile" time.
549
553
 
550
554
`limits'
551
555
     Print the local limits enforced by the local version of `bc'.  This
562
566
 
563
567
File: bc.info,  Node: Functions,  Next: Examples,  Prev: Statements,  Up: Top
564
568
 
565
 
Functions
566
 
*********
 
569
5 Functions
 
570
***********
567
571
 
568
572
* Menu:
569
573
 
585
589
 
586
590
   Parameters are numbers or arrays (an extension).  In the function
587
591
definition, zero or more parameters are defined by listing their names
588
 
separated by commas.  Numbers are only call by value parameters.
589
 
Arrays are only call by variable.  Arrays are specified in the
590
 
parameter definition by the notation "NAME`[ ]'".   In the function
591
 
call, actual parameters are full expressions for number parameters.
592
 
The same notation is used for passing arrays as for defining array
593
 
parameters.  The named array is passed by variable to the function.
594
 
Since function definitions are dynamic, parameter numbers and types are
595
 
checked when a function is called.  Any mismatch in number or types of
596
 
parameters will cause a runtime error.  A runtime error will also occur
597
 
for the call to an undefined function.
 
592
separated by commas.  All parameters  are call by value parameters.
 
593
Arrays are specified in the parameter definition by the notation
 
594
"NAME`[ ]'".   In the function call, actual parameters are full
 
595
expressions for number parameters.  The same notation is used for
 
596
passing arrays as for defining array parameters.  The named array is
 
597
passed by value to the function.  Since function definitions are
 
598
dynamic, parameter numbers and types are checked when a function is
 
599
called.  Any mismatch in number or types of parameters will cause a
 
600
runtime error.  A runtime error will also occur for the call to an
 
601
undefined function.
598
602
 
599
603
   The AUTO_LIST is an optional list of variables that are for "local"
600
604
use.  The syntax of the auto list (if present) is "`auto' NAME, ... ;".
630
634
function `read', which will always use the current value of IBASE for
631
635
conversion of numbers.
632
636
 
633
 
   As an extension, the format of the definition has been slightly
634
 
relaxed.  The standard requires the opening brace be on the same line
635
 
as the `define' keyword and all other parts must be on following lines.
636
 
This version of `bc' will allow any number of newlines before and after
637
 
the opening brace of the function.  For example, the following
638
 
definitions are legal.
 
637
   Several extensions have been added to functions.  First, the format
 
638
of the definition has been slightly relaxed.  The standard requires the
 
639
opening brace be on the same line as the `define' keyword and all other
 
640
parts must be on following lines.  This version of `bc' will allow any
 
641
number of newlines before and after the opening brace of the function.
 
642
For example, the following definitions are legal.
639
643
 
640
644
        define d (n) { return (2*n); }
641
645
        define d (n)
642
646
            { return (2*n); }
643
647
 
 
648
   Functions may be defined as `void'.  A void funtion returns no value
 
649
and thus may not be used in any place that needs a value.  A void
 
650
function does not produce any output when called by itself on an input
 
651
line.  The key word `void' is placed between the key word `define' and
 
652
the function name.  For example, consider the following session.
 
653
 
 
654
     define py (y) { print "--->", y, "<---", "\n"; }
 
655
     define void px (x) { print "--->", x, "<---", "\n"; }
 
656
     py(1)
 
657
     --->1<---
 
658
     0
 
659
     px(1)
 
660
     --->1<---
 
661
 
 
662
   Since `py' is not a void function, the call of `py(1)' prints the
 
663
desired output and then prints a second line that is the value of the
 
664
function.  Since the value of a function that is not given an explicit
 
665
return statement is zero, the zero is printed.  For `px(1)', no zero is
 
666
printed because the function is a void function.
 
667
 
 
668
   Also, call by variable for arrays was added.  To declare a call by
 
669
variable array, the declaration of the array parameter in the function
 
670
definition looks like "`*'NAME`[]'".  The call to the function remains
 
671
the same as call by value arrays.
 
672
 
644
673
 
645
674
File: bc.info,  Node: Math Library Functions,  Prev: Functions,  Up: Functions
646
675
 
647
 
Math Library Functions
648
 
======================
 
676
5.1 Math Library Functions
 
677
==========================
649
678
 
650
 
   If `bc' is invoked with the `-l' option, a math library is preloaded
 
679
If `bc' is invoked with the `-l' option, a math library is preloaded
651
680
and the default SCALE is set to 20.  The math functions will calculate
652
681
their results to the scale set at the time of their call.  The math
653
682
library defines the following functions:
664
693
`l (X)'
665
694
     The natural logarithm of X.
666
695
 
667
 
`E (X)'
 
696
`e (X)'
668
697
     The exponential function of raising E to the value X.
669
698
 
670
 
`J (N,X)'
671
 
     The bessel function of integer order N of X.
 
699
`j (N,X)'
 
700
     The Bessel function of integer order N of X.
672
701
 
673
702
 
674
703
File: bc.info,  Node: Examples,  Next: Readline and Libedit Options,  Prev: Functions,  Up: Top
675
704
 
676
 
Examples
677
 
********
 
705
6 Examples
 
706
**********
678
707
 
679
 
   In /bin/sh,  the following will assign the value of "pi" to the shell
 
708
In /bin/sh,  the following will assign the value of "pi" to the shell
680
709
variable PI.
681
710
 
682
711
     pi=$(echo "scale=10; 4*a(1)" | bc -l)
686
715
 
687
716
 
688
717
     scale = 20
689
 
     
 
718
 
690
719
     /* Uses the fact that e^x = (e^(x/2))^2
691
720
        When x is small enough, we use the series:
692
721
          e^x = 1 + x + x^2/2! + x^3/3! + ...
693
722
     */
694
 
     
 
723
 
695
724
     define e(x) {
696
725
       auto  a, d, e, f, i, m, v, z
697
 
     
 
726
 
698
727
       /* Check the sign of x. */
699
728
       if (x<0) {
700
729
         m = 1
701
730
         x = -x
702
731
       }
703
 
     
 
732
 
704
733
       /* Precondition x. */
705
734
       z = scale;
706
735
       scale = 4 + z + .44*x;
708
737
         f += 1;
709
738
         x /= 2;
710
739
       }
711
 
     
 
740
 
712
741
       /* Initialize the variables. */
713
742
       v = 1+x
714
743
       a = x
715
744
       d = 1
716
 
     
 
745
 
717
746
       for (i=2; 1; i++) {
718
747
         e = (a *= x) / (d *= i)
719
748
         if (e == 0) {
736
765
     print "\nCheck book program\n!"
737
766
     print "  Remember, deposits are negative transactions.\n"
738
767
     print "  Exit by a 0 transaction.\n\n"
739
 
     
 
768
 
740
769
     print "Initial balance? "; bal = read()
741
770
     bal /= 1
742
771
     print "\n"
758
787
     }
759
788
 
760
789
 
761
 
File: bc.info,  Node: Readline and Libedit Options,  Next: GNU `bc' and Other Implementations,  Prev: Examples,  Up: Top
762
 
 
763
 
Readline and Libedit Options
764
 
****************************
765
 
 
766
 
   GNU `bc' can be compiled (via a configure option) to use the GNU
 
790
File: bc.info,  Node: Readline and Libedit Options,  Next: Comparison with Other Implementations,  Prev: Examples,  Up: Top
 
791
 
 
792
7 Readline and Libedit Options
 
793
******************************
 
794
 
 
795
GNU `bc' can be compiled (via a configure option) to use the GNU
767
796
`readline' input editor library or the BSD `libedit' library.  This
768
797
allows the user to do more editing of lines before sending them to
769
798
`bc'.  It also allows for a history of previous lines typed.  When this
778
807
same time.
779
808
 
780
809
 
781
 
File: bc.info,  Node: GNU `bc' and Other Implementations,  Next: Limits,  Prev: Readline and Libedit Options,  Up: Top
782
 
 
783
 
GNU `bc' and Other Implementations
784
 
**********************************
785
 
 
786
 
   This version of `bc' was implemented from the POSIX P1003.2/D11
787
 
draft and contains several differences and extensions relative to the
788
 
draft and traditional implementations.  It is not implemented in the
 
810
File: bc.info,  Node: Comparison with Other Implementations,  Next: Limits,  Prev: Readline and Libedit Options,  Up: Top
 
811
 
 
812
8 Comparison with Other Implementations
 
813
***************************************
 
814
 
 
815
This version of `bc' was implemented from the POSIX P1003.2/D11 draft
 
816
and contains several differences and extensions relative to the draft
 
817
and traditional implementations.  It is not implemented in the
789
818
traditional way using `dc'.  This version is a single process which
790
819
parses and runs a byte code translation of the program.  There is an
791
820
"undocumented" option (-c) that causes the program to output the byte
903
932
     session, the SIGINT signal will terminate the entire run of `bc'.
904
933
 
905
934
 
906
 
File: bc.info,  Node: Limits,  Next: Environment Variables,  Prev: GNU `bc' and Other Implementations,  Up: Top
907
 
 
908
 
Limits
909
 
******
910
 
 
911
 
   The following are the limits currently in place for this `bc'
 
935
File: bc.info,  Node: Limits,  Next: Environment Variables,  Prev: Comparison with Other Implementations,  Up: Top
 
936
 
 
937
9 Limits
 
938
********
 
939
 
 
940
The following are the limits currently in place for this `bc'
912
941
processor.  Some of them may have been changed by an installation.  Use
913
942
the `limits' statement to see the actual values.
914
943
 
945
974
 
946
975
File: bc.info,  Node: Environment Variables,  Prev: Limits,  Up: Top
947
976
 
948
 
Environment Variables
949
 
*********************
 
977
10 Environment Variables
 
978
************************
950
979
 
951
 
   The following environment variables are processed by `bc':
 
980
The following environment variables are processed by `bc':
952
981
 
953
982
`POSIXLY_CORRECT'
954
983
     This is the same as the -s option (*note Command Line Options::).
956
985
`BC_ENV_ARGS'
957
986
     This is another mechanism to get arguments to `bc'.  The format is
958
987
     the same as the command line arguments.  These arguments are
959
 
     processed first, so any files listed in the environent arguments
 
988
     processed first, so any files listed in the environment arguments
960
989
     are processed before any command line argument files.  This allows
961
990
     the user to set up "standard" options and files to be processed at
962
991
     every invocation of `bc'.  The files in the environment variables
964
993
     wants defined every time `bc' is run.
965
994
 
966
995
`BC_LINE_LENGTH'
967
 
     This should be an integer specifing the number of characters in an
 
996
     This should be an integer specifying the number of characters in an
968
997
     output line for numbers. This includes the backslash and newline
969
 
     characters for long numbers.
 
998
     characters for long numbers. As an extension, the value of zero
 
999
     disables the multi-line feature.  Any other value of this variable
 
1000
     that is less than 3 sets the line length to 70.
970
1001
 
971
1002
 
972
1003
 
973
1004
Tag Table:
974
 
Node: Top65
975
 
Node: Introduction354
976
 
Node: Description515
977
 
Node: Command Line Options1969
978
 
Node: Basic Elements2533
979
 
Node: Numbers2704
980
 
Node: Variables3467
981
 
Node: Comments4576
982
 
Node: Expressions5317
983
 
Node: About Expressions and Special Variables5597
984
 
Node: Basic Expressions7333
985
 
Node: Relational Expressions10274
986
 
Node: Boolean Expressions11279
987
 
Node: Precedence11834
988
 
Node: Special Expressions12994
989
 
Node: Statements14376
990
 
Node: Pseudo Statements21001
991
 
Node: Functions21649
992
 
Node: Math Library Functions25703
993
 
Node: Examples26413
994
 
Node: Readline and Libedit Options28431
995
 
Node: GNU `bc' and Other Implementations29458
996
 
Node: Limits34700
997
 
Node: Environment Variables35953
 
1005
Node: Top181
 
1006
Node: Introduction473
 
1007
Node: Description638
 
1008
Node: Command Line Options2097
 
1009
Node: Basic Elements2667
 
1010
Node: Numbers2842
 
1011
Node: Variables3610
 
1012
Node: Comments4724
 
1013
Node: Expressions5470
 
1014
Node: About Expressions and Special Variables5754
 
1015
Node: Basic Expressions7495
 
1016
Node: Relational Expressions10441
 
1017
Node: Boolean Expressions11451
 
1018
Node: Precedence12011
 
1019
Node: Special Expressions13176
 
1020
Node: Statements14563
 
1021
Node: Pseudo Statements21192
 
1022
Node: Functions21845
 
1023
Node: Math Library Functions27008
 
1024
Node: Examples27723
 
1025
Node: Readline and Libedit Options29707
 
1026
Node: Comparison with Other Implementations30738
 
1027
Node: Limits35990
 
1028
Node: Environment Variables37247
998
1029
 
999
1030
End Tag Table