ARIBAS(1)                                               ARIBAS(1)


NAME
       aribas - Multiprecision Arithmetic Interpreter


SYNOPSIS
       aribas [options] [<ari-file> [<arg1> <arg2> ...]]

       This  man  page  was  written for Debian since the orginal
       software did not contain a man page.


DESCRIPTION
       Aribas is an  interactive  interpreter  suitable  for  big
       integer   arithmetic  and  multiprecision  floating  point
       arithmetic.  It has a syntax similar  to  Pascal  or  Mod­
       ula-2,  but  contains also features from other programming
       languages like C, Lisp, Oberon.


USAGE
       The simplest way to use aribas is as a calculator for (big
       integer)  arithmetic. After aribas is started, it displays
       a prompt ==> and is ready to accept  input.  Simply  enter
       the  expression  you want to calculate, followed by a full
       stop, and then press RETURN, for example

           ==> 123 + 456*789.

       Aribas answers

           -: 359907

       The symbol -: introduces the result.
       IMPORTANT.  To mark the end of your input, you must always
       type a full stop `.'  and then press RETURN.

       You  can assign the result of a calculation to a variable,
       as in

           ==> F6 := 2**64 + 1.
           -: 18446_74407_37095_51617

       This calculates the 6th Fermat number (** denotes exponen­
       tiation)  and  assigns  it  to  the variable F6 (note that
       aribas is case sensitive, so this is not the same as  f6).
       Later you can use this variable for example in the expres­
       sion

           ==> 123**(F6 - 1) mod F6.
           -: 688_66214_58712_63971

       which shows (by Fermat's theorem) that F6 is not  a  prime
       number.
       The  three  most  recent  results are stored in the pseudo
       variables _, __, and ___. For example you  can  store  the
       last result in the variable x by the command

           ==> x := _.
           -: 688_66214_58712_63971

       As  you  can  see  in  the above examples, aribas uses the
       underscore _ to structure the output of big  integers  (>=
       2**32).  Also for input of integers you may use the under­
       score, the only condition is that immediately  before  and
       after the underscore there are digits, example:

           ==> z := 123_4567_890.
           -: 1234567890

       Here the output contains no underscore, which shows that z
       is less than 2**32.

       Aribas has several built-in functions  for  factorization,
       for  example rho_factorize, which uses Pollard's rho algo­
       rithm.

           ==> rho_factorize(F6).

           working ..
           factor found after 512 iterations

           -: 274177

       To find the remaining cofactor, give the command

           ==> x := F6 div _.
           -: 6728_04213_10721

       To test whether this factor is prime, Rabin's  probabilis­
       tic test rab_primetest can be applied:

           ==> rab_primetest(x).
           -: true

       The  function rho_factorize is good for finding small fac­
       tors (say up to 10 decimal digits); for  more  complicated
       factorization  tasks  a  more  powerful algorithm like the
       quadratic sieve qs_factorize should be used

           ==> qs_factorize(2**128+1).

       (Depending on the power of your computer, it will  take  a
       few  seconds  up to a few minutes to get a prime factor of
       the 7th Fermat number.)


   Control structures
       The for loop and the while loop in aribas have a syntax as
       in  Modula-2.  For example, the following command sequence
       calculates the factorial of 100.

           ==> x := 1;
               for i := 2 to 100 do
                   x := x*i;
               end;
               x.

       As you can see in this example, the input may extend  over
       several lines.

       The  above  for  loop is equivalent to the following while
       loop

           ==> x := 1; i := 2;
               while i <= 100 do
                   x := x*i;
                   inc(i);
               end;
               x.


       The branching construct
       if ...  then ...  elsif ...  else ...  end
       has also the same syntax as in Modula-2.

   Multiprecision floating point arithmetic
       Aribas supports different types of floating point  numbers
       which are internally represented with mantissas of differ­
       ent bit-length:

               single_float    32 bits
               double_float    64 bits
               long_float     128 bits

       and several higher  precisions  up  to  an  implementation
       dependent limit, typically 1024 or 4096 bits, which can be
       determined by the function  max_floatprec().  By  default,
       when  calculating  with  numbers  of  data type real, sin­
       gle_floats are used. This corresponds to a precision of  9
       to  10  decimal  places.   A precision of 4096 bits corre­
       sponds to over 1200 decimal places.

       The precision can be changed using the function set_float­
       prec.  The  function  takes one integer argument, which is
       the desired precision in bits. It is automatically rounded
       to the next higher available value. For example, after

           ==> set_floatprec(100).
           -: 128

       the  floating point precision is 128 bits and you can cal­
       culate

           ==> arctan(sqrt(3)).
           -: 1.04719_75511_96597_74615_42144_61093_16762_8

           ==> _/pi.
           -: 0.33333_33333_33333_33333_33333_33333_33333_33


   User defined functions
       The user can define his or her own  functions.  A  typical
       example looks like

           ==> function fac(n: integer): integer;
               var
                   x,i: integer;
               begin
                   x := 1;
                   for i := 2 to n do
                       x := x*i;
                   end;
                   return x;
               end.

       If  you  have  entered  this  correctly, aribas echoes the
       function name

           -: fac

       and from now on you can use fac  in  the  same  way  as  a
       built-in function, e.g.

           ==> fac(32).
           -: 2_63130_83693_36935_30167_21801_21600_00000

       Note  that  inside function definitions all used variables
       must be explicitly declared, whereas on top level  of  the
       aribas  interpreter  variables  can  be  simply created by
       assignments. Here is another  example,  which  shows  some
       other data types supported by aribas:

           ==> function sqrt_list(n: integer): array of real;
               var
                   vec: array[n] of real;
                   i: integer;
               begin
                   for i := 1 to n do
                       vec[i-1] := sqrt(i);
                   end;
                   return vec;
               end.

       This  function returns an array of the square roots of the
       integers from 1 to n, for example

           ==> sqrt_list(10).
           -: (1.00000000, 1.41421356, 1.73205081, 2.00000000,
           2.23606798, 2.44948974, 2.64575131, 2.82842712, 3.00000000,
           3.16227766)

       In a bigger programming project  where  you  need  several
       functions  you would not enter them directly at the aribas
       prompt but prepare the function definitions with an exter­
       nal  text  editor and save them in a file  with the exten­
       sion .ari , for example abcd.ari . This file can  then  be
       loaded by aribas using the command

           ==> load("abcd").

       If  there  is a syntax error in the file, you get an error
       message of the form

           error in line <= 23 of loaded file
           if: end expected

       which tells you (in this example) that there is  an  error
       in  the  if  construct  in line 23 or earlier in the file.
       (Note that the error messages are sometimes not very  pre­
       cise.)  You  can  then correct the error and load the file
       again.

   Online help
       The command

           ==> symbols(aribas).

       returns a list of all keywords and names of builtin  func­
       tions  of  aribas.   This  list has about 180 entries, and
       begins and ends as follows:

       (ARGV, _, __, ___, abs, alloc, and, arccos,  arcsin,  arc­
       tan,  arctan2,  aribas,  array, atof, atoi, begin, binary,
       bit_and, bit_clear, bit_length, ...... , tolower, toupper,
       transcript,  true, trunc, type, user, var, version, while,
       write, write_block, write_byte, writeln)

       For most of the symbols in this list, you can get a  short
       online  help  using  the function help(). For example, the
       command

           ==> help(ARGV).

       gives an information on the builtin variable ARGV, whereas

           ==> help(while).

       describes  the  syntax of the while loop. If you need more
       information than that contained in the online  help,  con­
       sult   the   documentation   which   can   be   found   in
       /usr/share/doc/aribas.

   How to exit
       To end an aribas session, type exit at the aribas prompt

           ==> exit

       and then press the RETURN (ENTER) key.

       If you don't want to leave aribas, but want to  break  out
       of  an infinite loop or a calculation that lasts too long,
       type CONTROL-C (if you  are  running  aribas  from  within
       Emacs, you must press CONTROL-C twice). This will (in most
       cases) stop the current  calculation  and  return  to  the
       aribas prompt.

       When you are not using the Emacs interface but the command
       line version of aribas, you sometimes get into the follow­
       ing situation: Some previous line contains a typing error,
       but you cannot return to that line to correct it.  In this
       case  you should simply type a full stop `.' , followed by
       RETURN. You will get an error message which you can safely
       ignore,  and a new prompt ==> appears, allowing you to try
       again.

COMMAND LINE ARGUMENTS
       aribas [options] [<ari-file> [<arg1> <arg2> ...]]


   options
       The following options are available:

       -q     (quiet mode) Suppresses all messages to the  screen
              (version no, copyright notice, etc.) when aribas is
              started

       -v     (verbose mode, default) Does not suppress  messages
              to the screen when aribas is started.

       -c <cols>
              aribas  does  its own line breaking when writing to
              the screen.  Normally it supposes that  the  screen
              (or  the  window  in  which  aribas  runs)  has  80
              columns. With the -c option  you  can  set  another
              number,  which must be between 40 and 160 (in deci­
              mal  representation).   For  example,  if  you  run
              aribas  in an Xterm window with 72 columns, use the
              option -c72 (or -c 72, the space between -c and the
              number is optional).

       -m <mem>
              Here  <mem> is a number (in decimal representation)
              between 64 and 16000.  This  number  indicates  how
              many  Kilobytes  of  RAM  aribas should use for the
              aribas heap.  The  default  value  depends  on  the
              options  used  when aribas was compiled. Typically,
              under UNIX or LINUX it is 6 Megabytes,  correspond­
              ing to -m6000

       -h <path of help file>
              The  online  help  of  aribas  depends  on  a  file
              aribas.hlp which should be situated  in  the  range
              of  the  environment  variable PATH. If this is not
              the case you can specify the exact path of the help
              file  with  the  -h option. If for example the file
              aribas.hlp is in the directory /usr/local/lib,  use
              the option -h /usr/local/lib (the space after -h is
              not necessary).  The -h option can also be used  if
              the  help  file  has  a different name. If the help
              file is named help-aribas and lies in the directory
              /home/joe/ari, use -h/home/joe/ari/help-aribas.

              With  a properly installed Debian package of aribas
              it should not be necessary to use this option.

       -p <ari-search-path>
              With this option you can specify a search path  for
              loading files with aribas source code. <ari-search-
              path> may be either the (absolute) pathname of  one
              directory or several pathnames separated by colons.
              Suppose that you have called aribas with the option

                   -p/usr/local/lib/aribas:~/ari/examples

              and  that your home directory is /home/alice/. Then
              the command

                   ==> load("factor").

              will search the file factor.ari first in  the  cur­
              rent    directory,    then    in    the   directory
              /usr/local/lib/aribas      and      finally      in
              /home/alice/ari/examples.


       -b     Batch  mode when loading an aribas source code file
              from the command line, see below.


       One letter options  which  require  no  arguments  may  be
       merged, for example

           aribas -q -b

       is equivalent to

           aribas -qb

   Further command line arguments
       <ari-file>
              The next command line argument after the options is
              interpreted as the  name  of  a  file  with  aribas
              source  code.  If  the  file name has the extension
              .ari, this extension may be omitted.  The  file  is
              loaded  as  if  the  command load("<ari-file>") had
              been given after the start of aribas at the  aribas
              prompt.  If  the  file  is not found in the current
              directory it is searched in the directories  speci­
              fied by the -p option.  If the option -b was given,
              the file is loaded and executed.  Afterwards aribas
              exits without showing it's prompt. If the file can­
              not be  loaded  completely  because  of  an  error,
              aribas exits immediately after the error message.

       <arg1> <arg2> ...
              When  further  command  line arguments follow <ari-
              file>, they are  collected  (as  strings)  together
              with  <ari-file>  in  the  vector ARGV which can be
              accessed from within aribas.  Example: If you  call
              aribas with the command line

                   aribas startup 4536 eisenstein

              and   the   current  directory  contains  the  file
              startup.ari, then aribas loads it  and  the  vector
              ARGV has the form

                  ==> ARGV.
                  -: ("startup", "4536", "eisenstein")

              If  you  need  some arguments as numbers and not as
              strings, you can transform them by atoi (or  atof);
              in our example

                  ==> x := atoi(ARGV[1]).
                  -: 4536

              will  do  it.  The length of the vector ARGV can be
              determined by length(ARGV).

RUNNING ARIBAS WITHIN EMACS
       You can run aribas from within Emacs by giving the command
       (in Emacs' minibuffer)

            M-x run-aribas

       (If  you  don't have a META key, use ESC x instead of M-x)
       Then aribas will be loaded into an Emacs window with  name
       *aribas*  and  you  can edit your input to aribas with the
       usual Emacs commands.

       If your input ends with a full  stop  '.'  and  you  press
       RETURN,  it  is  sent to aribas.  If however your complete
       input does not end with  a  full  stop,  (for  example  in
       response  to a readln), the input is sent to aribas by C-j
       (Control-j) or C-c RETURN.

       If you want to repeat a previous input,  M-p  (or  ESC  p)
       cycles  backward through input history, and M-n (or ESC n)
       cycles forward.

       A Control-C is sent  to  aribas  by  C-c  C-c  (press  C-c
       twice).

       It  is  also possible to start aribas from Emacs with com­
       mand line arguments. For this purpose the command

            C-u M-x run-aribas

       has to be given. Then a prompt

            run-aribas: aribas

       appears in the Minibuffer of Emacs and  you  can  complete
       the command line, for example

            run-aribas: aribas startup 4536 eisenstein

       (see above).

CONFIGURATION FILE
       Options  for  running aribas can be specified also using a
       configuration file with name .arirc.  Aribas searches  for
       a configuration file in the following order:

           1) the current directory
           2) the home directory of the user

       There  is  a third possibility: You can define an environ­
       ment variable ARIRC containing the name of the  configura­
       tion  file (which may be different from .arirc), including
       the full path.

       In the configuration file you can specify all command line
       options described above which begin with a - sign, however
       a separate line must be  used  for  every  single  option.
       Lines  beginning  with  the character # or empty lines are
       ignored.  In addition to the options described above,  the
       configuration  file  may  contain  aribas source code. For
       this purpose there must be a line reading

       -init

       Then everything after  this  line  is  treated  as  aribas
       source code and executed when aribas is started.
       The  existence of a configuration file for aribas does not
       exclude the possibility to give command line arguments. If
       an  option  (e.g.  the -m option) is specified both in the
       configuration file and the command line but with different
       values,  then  the  specification  at  the command line is
       valid. Analogously, a -v option on the command line  over­
       rides  a -q option in the configuration file.  If there is
       -init code in the configuration  file  and  an  <ari-file>
       argument  at the command line, then the -init code is exe­
       cuted first and afterwards the <ari-file>  is  loaded  and
       its code executed.


FILES
       $ARIRC, .arirc, $HOME/.arirc

              Optional configuration file.


ENVIRONMENT VARIABLES
       $ARIRC Location of the optional configuration file.


SEE ALSO
       emacs(1)

       More  information  on  how  to  use aribas can be found in
       /usr/share/doc/aribas.

       The  aribas  home   page   is   http://www.mathematik.uni-
       muenchen.de/~forster/sw/aribas.html.

BUGS
       Bug reports should be sent by email to

           forster@mathematik.uni-muenchen.de


AUTHOR
       Otto  Forster  <forster@mathematik.uni-muenchen.de> is the
       author of the aribas program. This man page  was  compiled
       by Ralf Treinen <treinen@debian.org> from the aribas docu
       mentation for the Debian package of  aribas,  and  supple­
       mented by the author.


ARIBAS                    February 2001                        


