The Binops Programming Language
===============================

Binops is a turing complete language for writing obfuscated code. The following
code snippet is an implementation of a Brainf*ck interpreter written in Binops:

  DC505M22022M32032M606M42042M707M92092M4405022o032o06o042o07o092o044o1305022
  o06o042o092o52052q.q2305022o06o07o93093q.q5403206o07o14014q.q6403206o042o07
  o24024q.q74Yx34034z03MMMMMMMM034o3yY030401r3.4.101zyY040301r4.3.101zY01052g
  Z02Z040301052023s4.3.10zyY01023gZ02z030401023052s3.4.10zyY01093gZ02q20zyY01
  054gZ02u20zyY01014gZx20zyY01064gZ02X0zyY01024gZ03304302r33.43.20zyY01074gZ0
  4303302r43.33.20zyyQ6205.8Y06208g6206208iZ08M808013izy062U7205.9Y07209g7207
  209iz09M909013izy072R53.63.82063MMMMMMMM053o63082013i53082KKKKKKKK820530630
  82S84.94.12.73.83t012073083TY083073012r83.73.12012084gzY012094gZt0zyy......

Simply type 'make' to build the Binops interpreter. Binops programs can be
executed by running the 'binops' tool and passing the name of the program
file as parameter. Examples given:

	$ ./binops charlist.bo

	$ ./binops bfonbo.bo < bfdemo.bf

Binops does only know about binary operations - everything else (such as
arithmetric operations) must be implemented using binary operations. All
values in Binops are dynamically growing bit fields.

Comments in Binops code start with a '#' and reach until the end of the line.
Since Binops is a language for writing obfuscated code it is considered bad
coding style to leave any comments in the final version of a Binops program.

Binops variable names are built using the characters '1'..'9'. Writing '0'
followed by a variable name causes the variable to be pushed on the virtual
machine stack. Just writing the variable name pops a value from the virtual
machine stack and writes it to the variable. Writing '0' without a variable
name pushes a bit field with all bits cleared on the stack.

The uppercase letters 'A' to 'P' pop a value from the stack and create two
new values by left and right shifting the popped value. This two new values
are then combined as defined in the following table and the new value is
pushed on the virtual machine stack.

	Arg | A B C D E F G H I J K L M N O P
	----+--------------------------------
	0 0 | 0 1 0 1 0 1 0 1 0 1 0 1 0 1 0 1
	0 1 | 0 0 1 1 0 0 1 1 0 0 1 1 0 0 1 1
	1 0 | 0 0 0 0 1 1 1 1 0 0 0 0 1 1 1 1
	1 1 | 0 0 0 0 0 0 0 0 1 1 1 1 1 1 1 1

The lowercase letters 'a' to 'p' pop two values from the stack and combine
them as defined in the above table. The new value is pushed on the virtual
machine stack.

The uppercase letters 'Q' to 'W' can be used to declare functions. Functions
are declared after the main program and a function declaration is terminated
by the next function declaration or the end of file. The lowercase letters
'q' to 'w' can be defined to call a function. Arguments and return values
can be passed using variables or on the stack.

The comand 'x' reads one byte from the input and pushes the value as 8-bits
bitfield on the virtual machine stack. On EOF a bitfield with all bits cleared
is pushed. The command 'X' pops a value from the virtual machine stack and
writes the lower 8 bits to the output.

The command 'Y' marks the begin of a loop. The command 'y' marks the end of
a loop. The loop runs forever unless it is aborted using eighter the command
'Z' or the command 'z'. Both abort commands pop a value from the virtual
machine stack. The 'z' command terminates the loop when the popped value has
all bits cleared and the 'Z' command terminates the loop when at least on
bit of the popped value is set.

The special command '!' dumps the virtual machine stack and the values of all
variables. This command is for debugging purposes only and should not be used
in the final version of any Binops program.

The special command '.' is a no-op. Binop ignores all unknown characters in
the program text (including whitespaces). So the '.' command is needed in some
cases to seperate variable or funcion names.

Popping from an empty virtual machine stack simply pops a value with all bits
cleared.

It is illegal to use 'z' or 'Z' outside a 'Y..y' block or have more or less
'Y' than 'y' in the program. The behavior of a program breaking this rules is
undefined.