iHeadAche v1.1
===============
  an iziBasic sample program
    Copyleft 2006-2007 by Laurent DUVEAU
    http://www.aldweb.com/




iHeadAche is an interpreter for the BrainF*ck esoteric language. 
iHeadAche can also convert a BrainF*ck source code to an iziBasic source code for being then compiled with iziBasic.




The BrainF*ck language
----------------------

BrainF*ck was created by Urban Mueller for the Amiga OS 2.0, and he wrote an assembler compiler which was only 240 bytes long!
This tiny language has only 8 instructions (yes, only 8!) but it still is Turing complete, meaning that any computable calculation can be computed using it.

The BrainF*ck operators are:
  <	decrements the pointer
  >	increments the pointer
  +	increments the pointed byte
  -	decrements the pointed byte
Note: bytes (8 bits integers) can be replaced by 16 bits integers as an option in iHeadAche
  .	outputs the pointed byte
  ,	reads a byte from the input and stores it at pointed byte
  [	jumps to matching ] if the pointed byte is null
  ]	jumps to matching [ if the pointed byte is not null

  #	this cheat operator is not an actual BrainF*ck instruction, it can be used for debugging. In iHeadAche, it can be followed by a number to tell which byte to start showing out of 6 shown bytes.

  !	this is another cheat operator allowing to add the input after the source code. This is useful if you want to work with the same input data over and over, not having to input it each time you execute your code. It is also useful to bypass the 63 characters limit of the interactive input and, so, to input more than 63 characters.




Writing BrainF*ck source code
-----------------------------

BrainF*ck source codes are read from the Memo Pad database, so you should input your source code in this application which is provided in all Palm devices.

iHeadAche identifies BrainF*ck source codes from the first line which should include the "BrainF*ck" key word followed by the name that you want to give to your source code.

The following lines can be some comments or instructions that will be displayed prior to execution.

Then follows the BrainF*ck source code itself. At this stage, all other characters but the BrainF*ck operators will be ignored.

Note: be careful not to put any one of the BrainF*ck operators in the title line or the comments line as they would be interpreted by iHeadAche as instructions to execute.

Trick: iHeadAche has a menu option to generate a few memos with sample BrainF*ck source codes. Generate them to visualize what is written above.




Installing iHeadAche
---------------------

iHeadAche is installed like any other Palm application, nothing special to say here.
Install one of the two following files:
- iHeadAche_35.prc if you have an older device with Palm OS < 5.0
- iHeadAche_50.prc if you have a newer device with Palm OS >= 5.0

The other provided files are:
- the iziBasic source files of iHeadAche (the iHeadAche_ibas.PDB DOC file that can be compiled with iziBasic, the iHeadAche_ibas.TXT text file if you are curious reading it from any other system) 
- and its resource file (iHeadAche_rsrc.PDB). 
These files are not required to run iHeadAche.




Using iHeadAche
----------------

A popup list right to the applications's name lets you choose one source code to execute among all the ones found by iHeadAche in the Memo Pad database (so, the ones following the structure explained above).

Tap on the [Run] button to run the program. If an input is required, an empty text field followed by an [Enter] button will be shown at the bottom of the screen. Type in some text in the field, then press the [Enter] button to start executing.

You may stop the execution of the program at any time by pressing the [Stop] button which replaces the [Run] button at runtime.




iHeadAche options
------------------

You may choose between 8 bits integers (or bytes) and 16 bits integers for the data stack. Check your BrainF*ck source codes requirements. 
Most BrainF*ck source codes were designed to run with the default 8 bits value.

You may also select between a so called Char #0 and a Char #255 end of input character marker.
In most cases, the default Char #0 option will make it. If the execution leads to an error message, try the alternate option.




iHeadAche limits
-----------------

The code stack is of 4096 operators, or 4096 operators + input data when using the ! pseudo-operator. 4096 bytes is the limit of a standard Memo Pad entry (new devices can hold more). I bet that your source codes will never reach this limit!

The usual recommended size for the data stack capacity in a BrainF*ck implementation is of 30000 bytes. Because of technical constraints on Palm devices, in iHeadAche it is of:
* 800 bytes (or 16 bits integers) if you installed the version running as from Palm OS 3.5
* 10000 bytes (or 16 bits integers) if you installed the version running as from Palm OS 5.0
This is not a real issue and not a big limit as even complex BrainF*ck programs usually use only a few bytes and hardly more than a few dizains.




BrainF*ck sample source code
----------------------------

iHeadAche has a menu option to generate a few memos with sample BrainF*ck source codes. Here below, as an illustration for the purpose of this help file, please find the BrainF*ck source code for the classical 'Hello World' sample program, which does nothing else but to display 'Hello World'.

++++++++[>+++++++++<-]>.<+++++[>++++++<-]>-.+++++++..+++.<++++++++[>>++++<<-]>>.<<++++[>------<-]>.<++++[>++++++<-]>.+++.------.--------.>+.

This seems quite weird... But, do not be afraid by this first feeling, please read below! 




Getting started with BrainF*ck
------------------------------

Plenty of resources and web sites made by people who like BrainF*ck a lot (yes, this is possible!) are easily found on the internet. Just type in "brainfuck" (Drat it! I wrote it replacing the * character by the u letter!) in the search field of any search engine and you will be amazed by the number of returned links...

Here below are just a few recommended links:

Link #1: http://home.planet.nl/~faase009/Ha_BF.html
Nieko Maatjes wrote back in 2002 what I believe to be the best tutorial for the BrainF*ck language, a must read.

Link #2: http://www.hevanet.com/cristofd/brainfuck/
Daniel Cristofani has a great collection of sample source codes, including a BrainF*ck interpreter written in BrainF*ck... amazing!), and plenty of other useful resources & links.

And, if you do not like my iHeadAche implementation, you will find not less than 2 other implementations of BrainF*ck running on the Palm devices (BrainF*ck is a so called esoteric development language but, as you can see, it is well widespread):
IDE Palm #1: http://arainyday.se/projects/palm/BFEdit/
IDE Palm #2: http://www.chocopoolp.com/go_freeware.php (this one by a good French friend of mine)




iHeadAche source code
----------------------

iHeadAche was itself written in iziBasic for Palm.
Its source code is to be found in the ZIP file you downloaded (please read the Installing iHeadAche paragraph).




Updates Description
-------------------

  1.1 (09/17/07)
    - recompiled this program with the latest iziBasic version 6.1 
      to avoid device freezes or soft resets on some devices
    - changed the applications's name from iBrainF*ck to iHeadAche 
      to bypass some American referencing site's prudish censorship!

  1.0 (05/24/06)
    - initial release
