bf manual
_-_-_-_-_
-_-_-_-_-

This is bogusforth, an obfuscated language based mainly upon forth 
(widely known) and false, another obfuscated language 
by Wouter van Oortmerssen. Many ideas were also taken from TRUE, from Dewi.
Thanks to Moore, Wouter and Dewi.

It's GPL! Enjoy!

Antonio Maschio <tbin@libero.it>

language specs
-_-_-_-_-_-_-_-

notation
--------

The following stack values are used:
n	a number
[f]	a function
"s"	a string
d	a number, string or a function
f	a flag (true/false)
v	a variable
x*d	a non definite number of data


input strings
-------------

Input string are evaluated from left to right, just like in forth. 
Any line is 80 characters long (this is not a limitation, since commands use 
a stack or variables, so any command may reside on a single line each,
and the result would be same). Please, refer to the last section for
finding how to deal with special characters not present into your keyboard.


entities
--------

The following are the bricks of the whole language. 

numbers
0-9; H; O; B
numbers are long int type (-2^31 to 2^31-1);
negative numbers must be input with '\' (negate) after them, as in 345\;
hex numbers may be input with H *JUST* after them, as in 345H;
octal numbers may be input with O *JUST* after them, as in 345O;
binary numbers may be input with B *JUST* after them, as in 1010B.
	
variables
a-z; A-Z 
for numbers, strings and functions;
variables names are formed by a single letter, and a and A are distinct 
variables. Use ! to store information into a variable, as in 23a!, and
use : to retrieve information from a variable, as in a:
Remember to insert a blank if you want to check stack status (with :).
In sum:
23a! 	stores
a:		fetches
a :		executes command a (bitwise and) and then shows stack content.
a !		executes command a (bitwise and) and then tries to execute nth root.
		if stack is empty you will get an underflow error message in the
		last two cases.
Ranging from a to z and from A to Z you may use only 26x2=52 variables.
Not much, but a wise use of the stack may help.
	
strings
"..."	
they are simply input enclosing a text into double quotes - ( - "s" )
if you don't close the string, everything from the first " up to the
end of line will be a string.

comments
{...}	
they are simply input enclosing a comment into curly brackets 
If you don't close the comment, everything from the first { up to the
end of line will be a comment; besides, you can reopen a comment inside
a comment, as in {...{...{, but the first closing bracket will close the
whole comment.

functions
[...]	
they are simply input enclosing commands into square brackets ( - [f] ); 
functions may be nested.

tests
0	zero - false value (left by tests).
1	one - true value (left by tests). Anyway, any non-zero value is true,
	like in C.

Any other char than those compounding the language is discarded, so
you may overobfuscate your code by inserting here and there any char,
which will confound the reader (but not the compiler, I hope!).


commands
--------

variable treatment
The following commands must be put *JUST* after the variable name.
treated as different commands or discarded.

!	exclamation mark ( d v - ) stores a value into a variable.
:	colon ( v - d ) fetches variable content.

function command
@ 	at ( [f] - x*d ) executes function executes [f].

control flow commands
? 	question mark - ( f [f] | f [f1] [f2] - x*d ) if-then-else
	executes [f] if f in the first case, executes [f1] if f otherwise [f2]
	in the second case
# 	number - ( [f1] [f2] - x*d ) while [f1] executes [f2].
t	letter t - ( n - ) tear away remaining input line if tos is true

stack commands
% 	percent - ( n - n n ) dup.
; 	semi-colon - ( n - ) drop.
$	dollar - ( n1 n2 - n2 n1 ) swap.
_	underscore - ( n3 n2 n1 - n2 n1 n3 ) rot.
r 	letter r - ( n1 - n2 ) roll, with control over limits. 0r does nothing; 
	1r does nothing; 2r = $; 3r = _. If n1 is beyond stack depth, does nothing.
p	letter p - ( n1 - n2 ) pick, with control over limits. 0p does nothing; 
	1p = %; 2p = over (like in forth, but this specific command is not
	part of bf).
:	colon - ( - ) Shows stack content, leaving it untouched.
)	right parenthesis - ( x*d - ) empties stack (but maintains variables).
	Good programming should always end with the stack empty, after all 
	calculations are done and results shown, and this command helps in doing
	this.
}	right curly bracket - ( - ) If used outside a comment, leaves on tos
	current  stack depth, a value between 0 and 255. If you need more 
	stack space, change the value of STACKMAX in bf.h and recompile.
	
math commands	
* 	asterisk - ( n1 n2 - n1*n2 ) multiplication.
+ 	plus - plus ( n1 n2 - n1+n2 ) addition.
- 	hyphen - minus ( n1 n2 - n1-n2 ) subtraction.
/ 	slash - ( n1 n2 - n1/n2 ) integer division.
m	letter m - ( n1 n2 - n3 ) modulus n3 of n1/n2.
^	circumflex accent - ( n1 n2 - n3 ) nth power; gives n2th power of n1.
	Controls are taken over zero base and negative exponent, which would
	lead to a 1/0 fraction.
!	exclamation mark - ( n1 n2 - n3 ); if used not just after a letter, 
	gives the integer n2th root of n1, with control over zero root 
	(which would lead to a 1/0 exponent) and over negative base and
	odd exponent (which would lead to a complex mathematics).
\	backslash - ( n - -n ) negates number on tos.
g	letter g - ( n - ) generates random number if n is True, otherwise
	sets random seed

logical commands
= 	equal - ( d1 d2 - f ) true if d1 = d2.
	(for strings and function, usual conventions apply).
>	greater than - ( d1 d2 - f ) true if d1 > d2 
	(for strings and functions, usual conventions apply).
& 	ampersand - ( n1 n2 - f ) logical and.
| 	vertical bar - ( n1 n2 - f ) logical or.
~ 	tilde - ( n - f ) logical not.
l	letter l - ( n1 n2 - f ) logical xor

bitwise commands
a	letter a - ( n1 n2 - n3 ) bitwise and.
o	letter o - ( n1 n2 - n3 ) bitwise or.
n	letter n - ( n1 - n2 ) bitwise not (1 complement).
x	letter x - ( n1 n2 - n3 ) bitwise xor.

input/output commands
i	letter i - ( n - ) prints tos on screen, number, string or function.
j	letter j - ( n1 n2 - ) prints number n1 in a field of n2 chars 
	(filled with spaces if number is smaller). If number is longer than n2, 
	n1 is printed with no field.
k	letter k - ( n1 n2 - ) prints number n1 with n2 decimal digits after
	the dot (useful for printing fixed sized decimal numbers calculated as
	integers)
< 	lesser than - ( - "s" ) reads input string from keyboard.
( 	left parenthesis - ( "s" - x*d ) reads input stream from file whose 
	name is on tos. File lines are read sequentially until EOF
	or an error is met. Stack may result changed, after this operation,
	so you may ) before launching a file, if you need stack checking.
	Use the form f( to read and execute buffer file (see f).

string and char commands
`	grave - ( - n ) puts on tos ascii code of the following char 
	on stream; it's the only command which must be put before its input.
	If followed by a blank space, puts 32; if followed by a tab, puts 9;
	if last on stream, assumes next command is a return, so leaves 13.
	This command always succeeds (and never return '\0').
'	single quote - ( n - ) emits char whose ascii code is on tos.
	13' is a CR, 9' is a HT (horizontal tab), 7' is the bell (on some
	systems, 7' may not work).
,	comma - ( "s" - n ) converts string on tos to number, leaving it on tos. 		input numbers with <, (see <)
.	period - ( - ) emits a Carriage Return (more elegant than 13').
e	letter e - ( "s1" n - "s2" | n ) extracts nth char of string "s" and
	leaves it on tos. Values of n range from 0 to strlen("s") - 1. 
	If n is >= strlen("s"), returns a null string. If negative, returns
	string length.
u	letter u - ( "s" - n ) unveils ascii code of first char of string "s"
	and leaves it on tos.

system commands
Some of the following commands are #def driven.
In unix systems commands such pwd and cat are very common and useful.
In windows they are available only through external software
such as djgpp and mynsys. If you happen to have a working gcc and some
unix software (ls.exe, pwd.exe, cat.exe and less.exe are needed)
uncomment the #undef WIN32 line in bf.h and recompile. You will
gain the full bf capabilities.
	
h	letter h - ( - ) help on system command list.
v	letter v - ( - ) print vocabulary by screens.
d	letter d - ( - ) lists directory. Executes "dir" on windows/dos
	systems, and "ls" on unix systems. You can change commands (adding
	options, for example) modifying COMDIR in bf.h for unix
	environments and recompiling.
w	letter w - ( - ) print working directory (only for unix systems).
	If you have similar system commands for windows/dos, you may 
	redefine COMDIR for WIN32 environments in bf.h and recompile.
c	letter c - ( "s" - ) changes working directory. to "s". Absolute, 
	relative and mnemonics strings (like ..) may be used.
b	letter b - ( "s" - ) resets buffer file name to "s".
f	letter f - ( - "s" ) leaves on tos current buffer file name.
y	letter y - ( "s" - ) yields stack content to file.
]	right square bracket - ( - ) if used outside a function, toggles on/off 
	appending current input line into file ./bf.bf. Use b to change buffer 
	file name (see). If ] is contained in the input line, the char itself 
	won't be written to file.
s	letter s - ( "s" - ) shows contents of file identified by "s"
	(only for unix systems)
q	letter q -	( n - ) quits interpreter immediately with status n. 
	Of course, following commands will never be executed,
	and stack content will be lost. Normal program termination is 0q,
	abnormal is nq, where n is a programmer's defined error code (the
	same code is returned to the operating system, for the appropriate
	measures, if it can manage it).
