
          BRAINF*CK COMPILER FOR SHARP PC-1500/A and TANDY PC-2

The brainf*ck compiler is Copyright 2015 Christophe Gottheimer <cgh750215@gmail.com>
It is distributed in under the terms of the GNU Public Licence GPL v2.

This version is still in pre-alpha release. It is not fully mature and bugs
are present.

           +------------------- DISCLAIMER --------------------+
           | YOU USE THIS CODE AT YOUR OWN RISK ! I AM NOT     |
           | RESPONSIBLE FOR ANY DAMMAGE OR ANY DATA LOST OR   |
           | CORRUPTED BY USING THIS SOFTWARE OR BY USING THE  |
           | BINARY IMAGES CREATED WITH THIS SOFTWARE WHILE    |
           | RUNNING THEM ON A SHARP PC-1500/A or TANDY PC-2.  |
           | BE SURE TO SAVE YOUR IMPORTANT DATA OR PROGRAMS   |
           | BEFORE LOADING AND RUNNING THE BINARY IMAGES.     |
           +---------------------------------------------------+


1/ Presentation
   ============

BrainF*uck is a turing-complete programmation language created by Urban Mller.
It consists of a very minimalist manguage using only 8 instructions.

   <   decrement the pointer position
   >   increment the pointer position
   -   decrement the value at the current pointer position
   +   increment the value at the current pointer position
   [   if the value at the current pointer position continue at the next
       instruction, else "jump" after the ]
   ]   jump to the [
   ,   input a key from the keyboard and store it at the current pointer
       position
   .   output as ASCII character the current pointer position to the display
 
See more informations in http://en.wikipedia.org/wiki/Brainfuck


2/ Install
   =======

The brainf_ck compiler is fully relocatable and may be installed at any position.
The compiled code is not relocatable and it stored just fater the compiler. A
new compilation will overwrite the previous, so it not possible to keep several
compiled program at the same time.

The source brainf_ck.asm is the assembly code source. It needs the lhtools-0.7.0
to be assembled.

The PocketTools (bin2wav) are required to generate the .wav files to do transfer
with the audio interface (CE-150 or CE-162).

The lhTools-0.7.2 are required to generate the CSAVE header for a transfert on
serial line (CE-158).

The lhTools-0.7.3 are to generate the BASIC source from the binary image.

The binary and WAV images files are located into the directory Images/. The .bin
files are the resulting binary from the assembler. All .bin are same. The .lst
are the assembly listing file. The .frg are the fragment files. Even the base
addresses are different, the resulting binares are the same. The .wav are the
audio files to play (with audacity or mplayer) for an audio download. The wav
are ready to be transfered at the good base address. The .bin158 are the binaries
images for a download with the serial interface CE-158. These images are ready
to be sent at the good base address. Some others files (.bin, .wav, .bin158) also
exist:
   Images/bf-ceXXX.bin            Binary for the CE-XXX module
   Images/bf-ceXXX.wav            Audio image for the CE-XXX module (CE-150/-162)
   Images/bf-ceXXX.bin158         Binary for a serial download (CE-158)
where XXX  correspond to the CE-151, CE-155, CE-159 or CE-161 modules. For a
CE-163, use the CE-161. For a standalone PC-1500, use the CE-151.

   Images/brainf_ckbas.bin        Binary as BASIC program to relocate everywhere
   Images/brainf_ckbas.wav        Audio image as BASIC program
   Images/brainf_ckbas.bin158     BASIC program for a serial transfer
Just download the BASIC program and do RUN to install the BrainF*ck compiler.
If you desire ton install it at a specific position, answer it at the question
   BRAINF*CK BASE ?
Else, just do RETURN to install the BrainF*ck at the begining of the RAM.
For example, giving &4100 to the question will install the compiler at the base
address &4100.

Three BrainF*ck programs are given as examples:
   hello.bas    - Display the "Hello World!"
   mulasc.bas   - Perform the multiplication of N by M with N and M in 0..9
   rot13.bas    - Perform a 13 rotation on letter (A->N, B->O...)
The compiler needs 350 bytes of memory. The differents WAV images provided are
for the different modules and the compiler is installed at the following
position:
   CE-151 : Images/bf-ce151.wav  : &40C5 (also for main unit only)
   CE-155 : Images/bf-ce155.wav  : &38C5
   CE-159 : Images/bf-ce159.wav  : &20C5
   CE-161 : Images/bf-ce161.wav  : &00C5 (also for CE-163)
The addresses above are also called <base address>.

First, you need to reserve some space for the compiler and the compiled code.
This is done by the command NEW &yyyy where &yyyy is the address to set BASIC
area. Space before will be reserved for the compiler and compiled code. The
compiled code may be huge, so if you plan to write big programs, you will
reserve a bog amount of space.

In our case, we assume the PC-1500 main unit with a base address to &40C5. We
will reserve 1000 bytes of memory for the compiler by doing:
   NEW &4500

If you want to reserve some space without handling the address do:
   NEW
   NEW <amount of memory to reserve>+STATUS 2

For example to reserve 1180 bytes, do
   NEW
   NEW 1180+STATUS 2


 2.a/ Audio (CE-150) installation
      ---------------------------

Install the PC-1500 on the CE-150 and plug the audio wires. On the PC-1500
do a CLOAD M and start playing the Images/bf-ceXXX.wav image according to the
module inserted.

If you desire install the compiler at another position, just do CLOAD M&xxxx
where &xxxx is the base address to locate the compiler and play the
Images/bf-ce151.wav image.


 2.b/ Serial (CE-158) installation
      ----------------------------

Plug the PC-1500 to the CE-158 and plug the wire between the CE-158 interface
and the serial port of the remote PC. On the PC-1500 do
   SETCOM 2400,8,N,1
   SETDEV CI
   CLOAD M

On the remote PC, initiate a serial transfer at 2400 bauds, 8bits, NO parity
and 1 stop bit, using the image according to your module inserted. For serial,
use the Images/bf-ceXXX.bin158 binary images.

If you desire install the compiler at another position, just do CLOAD M&xxxx
where &xxxx is the base address to locate the compiler and start to send the
Images/bf-ce151.bin158 image.


3/ PC-1500/A/PC-2 BrainF*ck compiler
   =================================

Once installed (see 2/), the compiler is called by a CALL <base address>. It
may be called in command mode (RUN or PRO) or while a BASIC program is running.

The BrainF*ck source is located as a BASIC program. If the compiler is called
from command mode, it assume that the whole BASIC program is a BrainF_ck source
code. If the compiler is called in running program, it will start at the
following BASIC line and until the end of the BASIC program.

Note that all character which not match one of < > + - , . ( ) is treated as
comment.  So you will never reach an error while compiling except for memory
or stack overflow.

Because the [ and ] characters are not present on the PC-1500/A/PC-2 (they are
the "Square Root" and the "PI" signs), the ( and ) characters are used instead.
The compiler still understands and evaluates the Square Root and the PI signs
as [ and ].

 3.a/ Examples
      --------

In the following, we assume that the bf-ce151 image is loaded. So the base
address is &40C5

Enter the following program
   10 CALL &40C5:END
   20 +(,.)
and do
   RUN
The code is compiled starting at the line 20. The END exits from the BASIC
program, else an ERROR 1 will be raised.

Another example (see mulasc.bas):
   10 ,>,,>>++++++++++++++++(-<+++<---<--->>>)<<(<(>>+>+<<<-)>>>(<<<+>>>-)<<-)>.
and do
   CALL &40C5
The code is compiled. The whole BASIC memory is assumed as BrainF*ck code.


4/ Executing BrainF*ck compiled code
   =================================

The compiled code IS NOT RELOCATABLE. Some addresses for the "while" loops, i.e
( and ), are hardcoded to reduce the compiled code.

The compiled code is launched by a CALL <base address>+3. The executable code
may be called in command mode (RUN or PRO) or while a BASIC program is running.

When starting, the code prolog will clear (&00) the space from &78C0 and &79BF
(i.e A$-D$ and A-X). The current pointer position is set to &7900 (A). No check
is performed, so the whole memory is accessible.

When the BrainF*ck code ends, it returns directly from the BASIC call, so if
called from running program, the program will continue.
If the BrainF*ck code performs some output (instruction .), the LCD remains
until it is cleared by another message or by returning to command mode. So may
be useful to do:
   10 WAIT :CALL <base address>+3:PRINT :END
to look the output message from the BrainF*ck code. Also the code may finish by
   ,
to wait until a key is pressed.

While reading an input key, the compiled code acts as follow:
   ENTER  returns the value &00 (null)
   OFF    returns the value -1 (&FF) also assumed as EOF
The others key keep their internal code.


 4.a/ Examples
      --------

Returning to the first example, after compiling it, do
   CALL &40C8
Any key typed is displayed to the LCD, until ENTER (value &00) is pressed.

Taking the second example, after compiling it, do
   10 WAIT:CALL &40C8:PRINT :END
and do RUN (in RUN mode)
Enter a first digit 2 a multiply * and a second digit 3 and you see 6.

Others examples are provided with the files:
   hello.bas
   mulasc.bas
   rot13.bas


5/ Compiler internals
   ==================

The compiled code use DE as pointer. It is initialized to &7900 and the area
&78C0..&79BF is filled to 0. No check is performed on DE, so it is possible
to access the whole memory.

The BrainF*ck compiler will compile the instructions as follow:

   <  ::=  DEC   DE

   >  ::=  INC   DE

   -  ::=  ADD   (DE),&FF

   +  ::=  ADD   (DE),&01

   (  ::=  $$$_startloop:
           LDA   (DE)
           JR    NZ,+&03
           JP    $$$_endloop

   )  ::=  JP    $$$_startloop

   ,  ::=  PUSH  DE
           CALL  &E24A
           POP   DE
           CPA   0F      ; If OFF, put -1 (EOF)
           JR    NZ,+&02
           LDA   FF
           CPA   0D      ; If ENTER, put 0
           JR    NZ,+&01
           CLA           ; &34 ::= LDA N
           STA   (DE)

   .  ::=  LDA   (DE)
           PUSH  DE
           CALL  &ED4D
           POP   DE


6/ Bug and license
   ===============

Please report bugs or suggestion to cgh75015@gmail.com

Copyright 1992-2015 Christophe Gottheimer <cgh75015@gmail.com>

BrainF_uck compiler is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License version 2 as published by
the Free Software Foundation.  Note that I am not granting permission to
redistribute or modify BrainF_uck compiler under the terms of any later version
of the General Public License.

This program is distributed in the hope that it will be useful (or at
least amusing), but WITHOUT ANY WARRANTY; without even the implied warranty
of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
Public License for more details.

You should have received a copy of the GNU General Public License along with
this program (in the file "COPYING"); if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

