!BSquasher  Version 1.18  Mohsen Alshayef 1993 1994


Note:
=====

   This is a beta version with some facilities not yet completed (e.g. the protection
   option).

   There many options being worked on. This version gives you a taste of the program
   and does not show off all its capabilities.


Who is it for?
==============

It is made for all BASIC prgrammers who want to distribute their programs in BASIC, without
having others modify or understand what is happening in the program.

It is a very big advantage for lazy programmers who do not have a good programming style but
are able to make working programs.

!BSquasher is a utility program that allows you to compress basic programs while
still allowing the program to run correctly.

!BSquasher uses many techniques and alogrethims some which have never been used before.
The goal of all of this is to provide the following advantages on the result program:
  - Programs take less space on disc,
  - are slightly faster to load from disc.
  - take up less memory once loaded.
  - are difficult to hack and modify.
  - run slightly faster becasue there is less program to scan through for any calls.
  
  
What does it do?
================

Well, it basically compresses BASIC programs. Is that enough for an answer? I don't think so.
There are many similar utilities available, many are in the form of Public Domain and some
are in Shareware form.
I have come across many and have used many going back to similar utilites on the old BBC micros.
But, !BSquasher is all different.

What is special about BASIC Squasher?
=====================================

The goal of compressing BASIC program is to achieve two things (may be more); reduction in
size (and hence speed of execution), and making program very difficult to understand and
modify.

BASIC Squasher addresses each goal differently and in a unique way.
There are currently no BASIC squashing utilities that achieve the compression ratio achieved
with !BSquasher.

The only proof is to try it out and compare it with other compression utilities that you use.

!BSquasher is built around many modules (total of 34). This means 34 different methods of
data compression and space saving alogrethims.
I have opted to go this approach in order to make the program easily modifiable. In fact I
am looking forward to get my hands on the new BBC BASIC version which comes with RISC OS 4.
Upgrading the software will be very easy indeed.

How to use the application?
===========================

Once installed, drag a BASIC file onto the !BSquasher icon or its window. Only valid BASIC
programs are allowed.
Select the "Squash" icon and there you go. It can't be simpler.

When compression is finished, drag the result file to an open directory window to save it.

Why no options?
===============

The aim of a BASIC compression program is to generate the smallest possible program size. My
experience has shown that even when compression options are provided, the user will choose to
select ALL options.
Please let me know if you think an OPTION menu is necessary. You must have very strong points to
make me provide one.

Nested compressions:
====================

Once compression is finished you can drag the result file into itself to obtain further reduction
in size. This is only minor (few bytes saving).

Error messages:
===============

Assembly listing generated too long BASIC line
----------------------------------------------
This error will be encountered if you are compressing a program which is already compressed.

Fatal Error. Result file is expanding:
--------------------------------------
This is a failure of !BSquasher.
This error should not be seen under normal operation.


Functions provided by !BSquasher:
  
   1. Removes REMark lines
   2. Removes LET statements
   3. Converts numbers into shortest forms
   4. Removs unnecessary spaces
   5. Converts Poke and Peek keywords
   6. Converts into TRUE token
   7. Removes unneccary THEN statements
   8. Converts ASC tokens
   9. Converts SYS and SWI names into numbers
  10. Renames variables
  11. Renames procedures and functions
  12. Converts register names in assembly listings
  13. Removes unneccary WHEN
  14. Converts CHR$
  15. Concatenate lines
  16. Concatenate DIM
  17. Concatenate LOCAL
  18. Joins strings
  19. Converts into SPC
  20. Evaluates numbers
  21. Removes unnecassary brackets
  22. Converts real numbers
  23. Concatenate IF THEN ELSE multi-lines
  24. Removes garbage lines


There is only one thing !BSquasher can not cope with (yet); the EVAL function.


Line Numbers:
=============

!BSquasher can cope very easily with line numbers. However, if you use line numbers in a
program (there should be very few situations where you have to), they should be simple
line numbers in the range of 0 to 65279, not expressions. Otherwise, if the program is
renumbered (!BSquasher does not renumber your program), it will stop working since BASIC
does not know how to change the expression in the right way.

This line numbering also applies to RESTORE statements.

!BSquasher will cope with GOTO <line number>, GOSUB <line number>, RESTORE <line number>.

The RESTORE+<offset> statement should have no expressions assigned to Offset. Line numbers
and number offsets are allowed.

The RESTORE+<Offset number> will be replaced with RESTORE +0.


The Protection facility:
========================

This is not yet fully implemented.



                                     !!!!! Warning !!!!!
                                     ===================

  Do not use text editors to modify a compressed BASIC program. This will corrupt the program.
  Always keep a copy of the original un-compressed program.
  
-------------------------------------
                                       
Please write to me on:
  
  Mohsen Alshayef,
  PO Box 80647,
  AL-Wakrah,
  State of QATAR,
  The Arabian Gulf                                       
  
  for any bugs, corrections, modifications, suggestions, etc.
  
  If your final compressed program failed to run at a particular line then please inform me
  about the original and compressed line contents.
  
  
Best Regards

Mohsen Alshayef
  