Provided by: aribas_1.65-1_amd64 bug

NAME

       aribas - Multiprecision Arithmetic Interpreter

SYNOPSIS

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

       This  man  page  was  written for Debian since the original 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 Modula-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 exponentiation) 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 expression

           ==> 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  underscore,  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 algorithm.

           ==> 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 probabilistic test rab_primetest can be
       applied:

           ==> rab_primetest(x).
           -: true

       The function rho_factorize is good for  finding  small  factors  (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 different 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
       5120 bits, which can be determined by  the  function  max_floatprec().  By  default,  when
       calculating  with numbers of data type real, single_floats are used. This corresponds to a
       precision of 9 to 10 decimal places.  A precision of 5120 bits corresponds  to  over  1500
       decimal places.

       The  precision  can  be  changed  using the function set_floatprec. 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 calculate

           ==> 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  external  text
       editor and save them in a file  with the extension .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 precise.) 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 functions of aribas.   This  list  has
       about 200 entries, and begins and ends as follows:

       (ARGV,  _, __, ___, abs, alloc, and, arccos, arcsin, arctan, 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, consult 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 following 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 decimal
              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  500  and  32000.  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, corresponding 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  current 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 specified 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 cannot 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 command 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 environment variable ARIRC containing the
       name of the configuration 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 overrides 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 executed 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
       documentation for the Debian package of aribas, and supplemented by the author.