ARIBAS(1)

📦 version 1.65, in debian bookworm, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 ARIBAS(1) 💖 — General Commands Manual, section 1, bestie edition

okay so you opened the manual for aribas and honestly? good taste. this is the Debian-flavored aribas man page and it is so much. let's get into it ✨

🌸 NAME 🌸

aribas — Multiprecision Arithmetic Interpreter 💅

🦋 SYNOPSIS 🦋

aribas [options] [<ari-file> [<arg1> <arg2> ...]]
💌 real talk: this man page was written for Debian since the original software did not contain a man page. so like. we made one. you're welcome 🫶

🌈 DESCRIPTION 🌈

aribas is an interactive interpreter built for big integer arithmetic and multiprecision floating point arithmetic. its syntax is giving Pascal or Modula-2 energy, but it also has features borrowed from other programming languages like C, Lisp, and Oberon. she contains multitudes, okay? 💅

✨ USAGE ✨

The simplest way to use aribas is as a calculator for (big integer) arithmetic. Once aribas is started, it shows you a prompt ==> and is ready to accept input. Just type the expression you wanna calculate, follow it with a full stop, and then press RETURN, for example

==> 123 + 456*789.

and 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. no cap. that dot is not optional, bestie.

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. heads up: 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. slay? no. not slay. but mathematically iconic 🔥

The three most recent results are stored in the pseudo variables _, __, and ___. For example you can store the last result in the variable x with 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. 💀 she said "small number detected."

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.) so like. go make a snack 🍓

🎀 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. multi-line input? we love to see it 🦋

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. 1500 decimal places. bestie. that is so many 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. the error messages being a little vague is lowkey relatable 🙈

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

and that's the vibe so far, bestie — but there's more coming in the next part, so don't go anywhere 💖

🌸 COMMAND LINE ARGUMENTS 🌸

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

✨ options ✨

okay so here's the whole menu of options bestie, take notes 📝

  • -q — quiet mode, babes 🤫 it shushes all the messages that would normally pop up on your screen when aribas starts (the version number, the copyright notice, all of it).
  • -v — verbose mode, and this is the default 💖 it's the opposite of -q, so it does not suppress the startup messages.
  • -c <cols> — aribas does its own line breaking when it writes to the screen, iconic behaviour honestly. Normally it assumes your screen (or the window it's living in) is 80 columns wide. With -c you can set a different number, and it must be between 40 and 160 (in decimal). So like, if you're running aribas in an Xterm window with 72 columns, hit it with -c72 (or -c 72 — the space between -c and the number is optional, she's flexible 💅).
  • -m <mem> — here <mem> is a number (decimal, pls) between 500 and 32000. This number tells aribas how many Kilobytes of RAM it should use for the aribas heap 🧠 The default depends on the options used when aribas was compiled. Typically, under UNIX or LINUX, it's 6 Megabytes, which corresponds to -m6000.
  • -h <path of help file> — the online help of aribas relies on a file called aribas.hlp, and that file should be somewhere in the range of the environment variable PATH. If it's not, you can hand over the exact path of the help file with -h 🫶 Say for example the file aribas.hlp lives in the directory /usr/local/lib — then use the option -h /usr/local/lib (the space after -h is not necessary). The -h option also works if your help file has a totally different name. If the help file is named help-aribas and sits 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, so don't stress 🌸

  • -p <ari-search-path> — with this one 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. So imagine you called aribas with the option
-p/usr/local/lib/aribas:~/ari/examples

and your home directory is /home/alice/. Then this 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, used when loading an aribas source code file from the command line (see below, bestie 👇).

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 gets 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, and afterwards aribas exits without showing its 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 get collected (as strings) together with <ari-file> in the vector ARGV, which you can access 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 the 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, yes twice, that's not a typo 💅).

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 also be specified using a configuration file with the name .arirc. aribas searches for a configuration file in this order:

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

There's a third possibility bestie: 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 ⭐

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 🫶

and that's a wrap bestie!! 💖 this whole page is from the ARIBAS manual, section ARIBAS(1), dated February 2010 — go forth and compute, you absolute icon 🎀✨

📦 where this page comes from