Copyright (c) 2006 Edwin Steiner <>


bb is a hex calculator for the console. It has nice basic features:

…and many advanced features:

See the file FEATURES for more.

bb is free software distributed under the GPL. See the file COPYING for details.


If you want to use Hugs to run bb you do not need any special installation. Just run the bb.hs program.

To compile bb with ghc type make after unpacking. (If you do not have the happy parser generator, be sure that BBParser.hs does not have a timestamp older than grammar.y.) You can then run ./bb or put the bb binary anywhere you like.


After starting bb you can enter expressions to evaluate. You can also pass bb an expression on the command line (be sure to do the appropriate quoting for your shell).

The FEATURES file lists supported number formats and operators. Look at the test cases in the t directory to get an idea what you can enter. (Everything after a "> " is a valid expression.)

Type Ctrl-D to quit bb.


By default bb interprets all bare numbers as hexadecimal. This includes numbers starting with a letter [a-fA-F]. To enter a decimal number or a name staring with [a-fA-F], use the quote:

10    # 'sixteen'
'10   # 'ten'
af    # hex 0xaf
'af   # name 'af'
_All_ unquoted numbers are interpreted as hex! To shift left by ten bits for example do one of:
cafe << '10
cafe << a

Some numbers are fixed parts of operators. bb regards them as being quoted, so they are always interpreted as decimal. Examples:

:hi16     # always select the high 'sixteen' bits
[...]32   # constructs a box of 'thirty-two' bits

If you wonder if a number is quoted or not, ask yourself: Could I insert a space directly before the first digit? If the answer is no, then the number is quoted.

For example in [10]32 (a "thirty-two" bit box containing "sixteen"), you can put a space before "10":

[ 10]32

but not before 32:

[12] 32  ### ILLEGAL!


Names can be similar to variables. You can bind a result to a name with the <- operator:

ten <- 5+5

You can now use




everywhere you can use an _unquoted_ number.

The result of the last evaluation is always bound to _ (a single underscore).


Often you will want to tell bb how "wide" your numbers are, so it does the right clipping for modulo 2^n arithmetic, for example. You do this by putting a value in a "box". For example:

[ -1 ]12

This puts the value -1 in a box of twelve bits:

[ 0xfff ]12 dec: 4095 sdec: -1

The box is itself a value and you can do calculations with it as if you had a 12-bit register:

[ -1 ]12 >> '4

evaluates to:

[ 0xff ]12 dec: 255

There are many operators that can do special thing with boxes. For example signed/unsigned multiplication:

[ 0xff ]8 u*s [ 0xff ]8

evaluates to:

[ 0xff01 ]16 dec: 65281 sdec: -255

The unary ^ operator is used for unboxing boxed values. If you want to unbox a value interpreting it as signed, use ^s.

Have fun -Edwin