home *** CD-ROM | disk | FTP | other *** search
/ APDL Public Domain 1 / APDL_PD1A.iso / program / basic / squish / !Squish / !Help next >
Encoding:
Text File  |  1993-07-29  |  18.5 KB  |  494 lines
  1.                                    !Squish
  2.                                    -------
  3.                                 Release  2.38
  4.  
  5.  
  6. ARM-Code BASIC Squishing software : Kevin J Swinton
  7. C RISC OS WIMP Interface software : Stuart Swinton
  8.  
  9. © Kevin J Swinton and Stuart Swinton 1990/1991/1992
  10. Published by : Unique Software       1993
  11.  
  12.  
  13. -----------------------------------------------------------------------------
  14.                                   Disclaimer
  15. -----------------------------------------------------------------------------
  16.  
  17.  The software is provided "as is". Neither the authors or Unique Software
  18.  make any warranty, express or implied, of the merchantability of this
  19.  software or its fitness for any particular purpose. In no circumstances
  20.  shall either be liable for any damage, loss of profits, or any indirect or
  21.  consequential loss arising out of the use of this software or inability to
  22.  use this software, even if advised of the possibility of such loss.
  23.  
  24.  
  25. -----------------------------------------------------------------------------
  26.                       Rules and regulations for !Squish
  27. -----------------------------------------------------------------------------
  28.  
  29. * Squish is not perfect. After an extremely long development time, Squish
  30.   has reached the stage whereby it can squash any program by someone with a
  31.   respect for 'sensible' programming. One can lecture about the principles of
  32.   good design in today's competing environment, but no. Though suffice to
  33.   mention a statement made by Dijkstra in 1979, on the subject of software:
  34.  
  35.   "The advent of cheap and powerful devices will put Software Engineering
  36.    back 25 years."
  37.  
  38.   This, of course, is absolutely true.
  39.  
  40.   The BBC BASIC interpreter is quite simple. It's syntax rules are good,
  41.   but very flexible. This allows people to tackle the subject of programming
  42.   in very different ways. Squish uses general algorithms to reduce the size
  43.   of programs, but there are restrictions should you want the resulting file
  44.   to work! These are listed below, along with hints on how to avoid these.
  45.  
  46.  
  47. ------------------------- Restrictions with Squish --------------------------
  48.  
  49.  
  50. * GOTO, GOSUB and RESTORE.
  51.  
  52.   Squish will simply ignore these commands by skipping past them. Nowadays it
  53.   is absolutely unforgiveable to use GOTO/GOSUB so Squish will NEVER support
  54.   these. RESTORE commands are generally OK, but
  55.  
  56.   a) don't use formula based RESTORE commands if you can avoid doing so, and
  57.   b) don't RESTORE pointers to blank lines/REMs that will be deleted.
  58.  
  59.   Please note that, if a program has been written sensibly, it is perfectly
  60.   possible for it's GOTO, GOSUB, and/or RESTORE commands to be squished and
  61.   still work correctly. (Eg. RISC User's !Dustbin.)
  62.  
  63.  
  64.           ----------------------------------------------------------
  65.  
  66.  
  67. * DATA statements
  68.  
  69.   If a variable is an element of a DATA statement, it will need to be
  70.   renamed along with the other references to it throughout the program.
  71.  
  72.   In DATA statements, BASIC determines a string from a variable by the fact
  73.   that the former is enclosed within quotation marks, although the syntax
  74.   does allow certain strings to exclude quotation marks.
  75.  
  76.   Squish works on the principle that ALL strings are enclosed within
  77.   quotation marks. If not, the DATA element is liable to be renamed.
  78.   For example :
  79.  
  80.   100 DATA window                <- This will be renamed
  81.   100 DATA "window"              <- This will NOT be renamed
  82.  
  83.  
  84.           ----------------------------------------------------------
  85.  
  86.  
  87. * Pointless lines.
  88.  
  89.   Don't use pointless lines to separate PROCedures etc.. Use blank/commented
  90.   lines instead, else Squish will attempt to rename the text inbetween
  91.   (should you ask Squish to "Rename Variables", but not "Remove REMs etc."
  92.   first.)
  93.  
  94.   Eg. :
  95.  
  96.   ENDPROC
  97.   :
  98.   : --- Routine to read TIME --- <- Squish will assume these are VARIABLEs
  99.   :
  100.   DEF PROCget_time
  101.  
  102.   The annotation of programs using REM statements is the correct method. So,
  103.   to implement the above example :
  104.  
  105.   ENDPROC
  106.   :
  107.   : REM Routine to read TIME     <- Correct style, acceptable by Squish
  108.   :
  109.   DEF PROCget_time
  110.  
  111.  
  112.           ----------------------------------------------------------
  113.  
  114.  
  115. * The EVAL problem.
  116.  
  117.   This refers to FuNctions like :
  118.   
  119.   A% = EVAL( "FNdoodah(" + STR$ input + ")" )
  120.  
  121.   Squish sees "FNdoodah" as a constant (quite correctly) and does not rename
  122.   it. There are other language constructs available that can be used in place
  123.   of this method, and should be whenever possible (particularly if the
  124.   program is to be Squished at a later date.) Note that EVAL statements which
  125.   use FN/PROC identifiers can be used by renaming variables WITHOUT the
  126.   "PROCs" and "FNs" options.
  127.  
  128.  
  129.           ----------------------------------------------------------
  130.  
  131.  
  132. -----------------------------------------------------------------------------
  133.    Special Notes on !Squish for programmers (and other interested parties)
  134. -----------------------------------------------------------------------------
  135.  
  136.  
  137. * When determining if a line is blank, the one thing that seperates a 'dummy'
  138.   line from a real one is if it contains a KEYWORD. The routine that checks
  139.   for this simply scans the tokenised line for a hex value of &7F or greater.
  140.   If this is the case, a KEYWORD is present, and the line is taken to be
  141.   'real', regardless of whether or not it is ever executed.
  142.   The exceptions are lines that consist of a '*' command, a line containing a
  143.   return assignment (eg. =result$), or a line consisting solely of '[', or
  144.   ']', as these are all valid lines containing no KEYWORDs.
  145.  
  146. * When removing SPACEs from a line, there are many conditions whereupon a
  147.   single SPACE must be left so that the BASIC interpreter can make sense of
  148.   what is going on. For an example, Squishing 'X = Y NOT Z' can only be
  149.   Squished to 'X=Y NOTZ', because taking the remaining SPACE out results in
  150.   the BASIC interpreter recognising this as an assignment, as opposed to a
  151.   logical operation. Although Squish doesn't take all of these conditions
  152.   into account, it still provides a more than adequate reduction rate.
  153.  
  154. * Note that recognising if you are in Assembler or not depends entirely
  155.   upon how many '[' and ']' signs have been encountered, and when Squishing
  156.   assembler commands, all statements are left with a single SPACE between
  157.   each field of the statement. ';' comments are also deleted.
  158.   (Although the idea of Squish is to Squish BASIC programs, the assembler
  159.   Squisher has been included to improve those programs that use small amounts
  160.   of ARM code, just to please those who like to do so.)
  161.  
  162. * To remove REM statements, Squish scans the tokenised line for the Hex
  163.   value for 'REM'. If this is found, the line is shortened appropriately.
  164.   This works fine, but there is one occasion when this doesn't work, and that
  165.   is when you put a REM statement after a DATA statement, as the interpreter
  166.   stores this as a string, failing to tokenise it.
  167.  
  168. * As mentioned above, everything following a DATA statement is stored as pure
  169.   ASCII, and the same also applies to REM statements, so if you concatenate a
  170.   program without removing REM statements, if 2 (or more) REMs are Squished
  171.   together, the supplementary REMs are de-tokenised into ASCII form, which is
  172.   why Squished REM statements look a little weird.
  173.  
  174. KJS (08-08-90) - Release version 1.00
  175.  
  176.  
  177. -----------------------------------------------------------------------------
  178.                                   History file
  179. -----------------------------------------------------------------------------
  180.  
  181.  
  182. * Amended the blank-line removal code to account for OTHERWISE statements
  183.   being present [OTHERWISE->&7F]
  184. * Restructured logic format for IF... statements. Previously 'dead' logic has
  185.   now been redesigned to cope with IF... statements without THENs.
  186. * Additional logic to ensure 'OTHERWISE' keywords start on a new line.
  187.  
  188.   KJS (10-08-90) - Release version 1.01
  189.  
  190.  
  191. * Inserted additional code to rename variables.
  192.  
  193.   KJS (21-09-90) - Release version 1.02
  194.  
  195.  
  196. * Variable renamer now copes with ARM code, and instructions are not
  197.   treated as variables. (eg. LDMEQIA.)
  198. * RESTORE statements are left alone (BASIC encodes ensuing pointers), making
  199.   renumbering possible after compaction.
  200. * Labels such as '.Address' are not treated as an ADD instruction (variable
  201.   code used to check the ADD part and be fooled by this.)
  202. * Option of fast/slow compaction inserted. Slow allows Squish to compact as
  203.   a background task, whilst fast allows Squish to control the system during
  204.   compaction.
  205. * Renaming code altered to produce liberally-spread variable names, a feature
  206.   from the old BBC days, as the interpreter takes less time to identify the
  207.   variable it wants.
  208.  
  209.   KJS (25-09-90) - Release version 1.03
  210.  
  211.  
  212. * Additional code added so that semicolon-text in Assembly language is not
  213.   treated as variables (if you Squish a program using the rename variable
  214.   option WITHOUT removing REMs etc., REMarks in Assembly language were
  215.   renamed)
  216. * Additional code also added to the renaming procedures, since, when using
  217.   Assembly language, AND and EOR instructions are tokenised as if they were
  218.   BASIC instructions.
  219.  
  220.   KJS (03-10-90) - Release version 1.04
  221.  
  222.  
  223. * Logic in the SPACE-Squishing procedures restructured for DIM statements.
  224. * Save-over-original option altered to a 'final-info' one, so that the old
  225.   and new program-length, and the compression rate, may be seen.
  226. * Procedure that removes SPACEs rewritten to be a lot speedier.
  227.  
  228.   KJS (22-10-90) - Release version 1.05
  229.  
  230.  
  231. * Additional code added to cope with the BY keyword used in conjunction with
  232.   certain graphic commands. BY itself is stored as ASCII text straight after
  233.   the tokenised graphic keyword.
  234.  
  235.   KJS (25-10-90) - Release version 1.06
  236.  
  237.  
  238. * Algorithms completely rewritten in ARM Code.
  239. * Algorithms VASTLY improved.
  240.   (Has competently Squished everything tried so far.)
  241. * Windows redrawn from scratch.
  242. * User interface completely rewritten in C.
  243.  
  244.   KJS (22-08-91) - Release version 2.00
  245.  
  246.  
  247. * User interface
  248.     - bugs sorted out.
  249.     - made completely !Help compatible.
  250.     - pause facility / swap between fast & slow options implemented
  251.     - etc. etc.
  252.  
  253.   Izzy (26-10-91) - Release version 2.10
  254.  
  255.  
  256. * ARM and C interface recoded to allow >8k programs to be loaded and have
  257.   their variables compacted. Filename extraction for in-memory-data-transfers
  258.   implemented (so why doesn't everyone else use it?)
  259.  
  260.   Izzy (23-11-91) - Release version 2.11
  261.  
  262.  
  263. * Problem with 'flex_midextend' cured by using 'flex_extend' instead.
  264.  
  265.   Izzy (24-12-91) - Release version 2.12
  266.  
  267.  
  268. * 'Rename under flex' bugs solved. Only ALI-vars still remain a problem.
  269.  
  270.   KJS (31-12-91) - Release version 2.14 (2.13 is unlucky, man!)
  271.  
  272.  
  273. * DIV and MOD spacing problems removed (why had I not noticed this before?)
  274.   All variables now forced to lower-case to remove FN/PC/IF/ON problems
  275.   (why had I not noticed this either?!)
  276.  
  277.   KJS (12-01-92) - Release version 2.15
  278.  
  279.  
  280. * Renaming of program variables vastly restructured. Now renames ARM Code
  281.   variables properly, without renaming shift mnemonics. Help file redone
  282.   to a more 'serious programmer attitude' style ... NOT!
  283.  
  284.   KJS (26-01-92) - Release version 2.16
  285.  
  286.  
  287. * Minor modifications to run under RISC OS 3.10
  288.  
  289.   Izzy (18-12-92) - Release version 2.17
  290.  
  291.  
  292. * Major modifications to run under RISC OS 3.10. Squish can now save without
  293.   constantly falling over.
  294.  
  295.   Izzy (07-01-93) - Release version 2.18
  296.  
  297.  
  298. * Help system rewritten. Templates generally 'tidied' up. Modification to
  299.   SPACE remover to correctly handle removal of multiple SPACEs within
  300.   particular DIM statements.
  301.  
  302.   KJS (08-01-93) - Release version 2.19
  303.  
  304.  
  305. * ERROR EXT problem solved. OPT problem solved, specifically renaming of 1
  306.   character pass variables. Register renaming solved. Can now rename ARM
  307.   registers that have been assigned to 1 character variable names. Anomalies
  308.   with C interface (WIMP drags, IMDTs etc.) solved. Validation of BASIC file
  309.   included, as per !Edit. BackDrop icon created. Adjust click on main window
  310.   forces filer window to appear.
  311.  
  312.   KJS (11-01-93) - Release version 2.20
  313.  
  314.  
  315. * REM removal code rewritten. Squish can now remove comments from ARM
  316.   assembler correctly. (Assembler can have further statements after a
  317.   comment, BASIC can't.)
  318. * Variable renamer changed to cope with the rewritten REM code. Can now
  319.   rename variables AFTER concatenation, without renaming all the embedded
  320.   ARM comments.
  321. * Save routines now made more robust.
  322.  
  323.   KJS / Izzy (13-01-93) - Release version 2.21
  324.  
  325.  
  326. * C interface updated. RAM transfers work correctly. Interface examined for
  327.   consistency.
  328. * ARM routines compared to BASIC CRUNCH command - ARM routines found to be
  329.   somewhat better.
  330. * Save routine now suffixes filename with S or Q as appropriate. Code fixed
  331.   to prevent renaming ARM variables that begin with a register definition
  332.   (eg. "r13pointer"). Problem with *commands solved.
  333.  
  334.   KJS / Izzy (19-01-93) - Release version 2.22
  335.  
  336.  
  337. * A 'bug' in the "Pause" feature removed. If squishing is paused, pressing
  338.   either the Cancel or the Fast icon failed to reset the Pause status, and
  339.   subsequent icons reflected erroneous states.
  340.  
  341.   KJS (24-02-93) - Release version 2.23
  342.  
  343.  
  344. * SERIOUS problem in the messaging system removed, which had only became
  345.   apparent after release RISC OS 3.10 was fitted. Option added to the Rename
  346.   algorithm to allow suppression of renaming PROCEDURE and/or FUNCTION
  347.   identifiers.
  348.  
  349.   KJS/Izzy (25-02-93) - Release version 2.24
  350.  
  351.  
  352. * Dialogue box handler code completely re-written. Squish can now be quit
  353.   from the menu without a problem. Modified RAM save routine slightly -
  354.   now if you save using an in-memory data transfer the data is considered
  355.   safe. It will be up to the other package to warn the user that the data
  356.   is unsafe, since Squish will by now have effectively finished processing.
  357. * Bug in rename variables fixed. If a *command was part of an IF...THEN
  358.   construct, it was renamed.
  359.  
  360.   Izzy (01-03-93) - Release version 2.25
  361.  
  362.  
  363. * Put in code to differentiate between a PREQUIT message being application
  364.   specific / a general desktop shutdown routine.
  365.  
  366.   Izzy (02-03-93) - Release version 2.26
  367.  
  368.  
  369. * Completely re-wrote dialogue box code. All dboxes now self-centre across
  370.   MODE changes.
  371. * Changed the code back so that in-memory data transfers are NOT considered
  372.   safe.
  373. * Options for squishing are now automatically displayed if none are selected
  374.   when attempting to squish a program.
  375. * Messages file and templates tidied up. Help messages for menus taken out
  376.   as not supported by the current C compiler.
  377.  
  378.   Izzy (03-03-93) - Release version 2.27
  379.  
  380.  
  381. * Squish will now intelligently deal with an attempt to quit the program.
  382. * The RISC OS desktop boot file facility is also now supported.
  383. * Extra code inserted to allow identifiers to be 'locked' from renaming.
  384.   Principally, this allows libraries to have global PROC/FN/vars exported
  385.   to individual RunImages without the need to concatenate, also retaining
  386.   their uncompressed format. The syntax for listing identifiers is held
  387.   within REM statements in the source program, as per example :
  388.  
  389.   100 REM LOCK <identifier 1> , <identifier 2> , ... , <identifier n>
  390.  
  391.   so a WIMP program which uses a global WIMP procedure library may
  392.   have a LOCK statement something like this :
  393.  
  394.   100 REM LOCK PROCopen_window , PROCclose_window , WINDOW% , ICON_TEXT$
  395.  
  396.   Of course, both the main RunImage AND the library itself will need to have
  397.   a copy of the LOCK statements, else one will have it's identifiers renamed
  398.   and the other won't. Also note that subscripts must be omitted, so a LOCK
  399.   cannot have something like this :
  400.  
  401.   100 REM LOCK PROCedure_OpenWindow( x% )     <- the "( x% )" should be
  402.                                                  omitted from this line
  403.  
  404.   KJS/Izzy (17-03-93) - Release version 2.28
  405.  
  406.  
  407. * C interface now allows multiple re-squish attempts without losing the list
  408.   of LOCKed variables. Also advises when re-squishing may be advisable due to
  409.   lack of memory when renaming variables.
  410. * All calculations on savings are now based on the original program size.
  411. * Help now given on SAVE dialogue box.
  412.  
  413.   Izzy (18-03-93) - Release version 2.29
  414.  
  415.  
  416. * Bug in variable renamer fixed. One character identifiers caused problems
  417.   in some places, especially in the third opcode field, in use as an
  418.   immediate (eg. #X).
  419.  
  420.   KJS (19-03-93) - Release version 2.30
  421.  
  422.  
  423. * Put in new save routines to use the drag-a-sprite facility.
  424.  
  425.   Izzy (21-03-93) - Release version 2.31
  426.  
  427.  
  428. * Iconise facility implemented fully. Now when iconised, Squish will
  429.   continue to process the BASIC program. When finished the iconbar
  430.   sprite will change to indicate that the process has been completed,
  431.   but that the window is still iconised. Double click on the iconised
  432.   window to continue. Also fixed minor bug when using ADJUST on the
  433.   close window icon to open the programs directory.
  434.  
  435.   Izzy (01-04-93) - Release version 2.32
  436.  
  437.  
  438. * Patch over initialisation routines to cope with new Wimp_Initialise
  439.   specification, as C library doesn't allow for this.
  440.  
  441.   Izzy (03-04-93) - Release version 2.33
  442.  
  443.  
  444. * Patch over 'wimpt' routines. Had to insert our task handle into the
  445.   'wimpt' routines workspace directly, as Acorn have forgotten to tell
  446.   us that 'xfer_send' uses, for in memory data transfers, the 'wimpt_task'
  447.   function - which meant that Squish version 2.33 fell over when doing
  448.   in-memory data transfers.
  449.  
  450.   Izzy (06-04-93) - Release version 2.34
  451.  
  452.  
  453. * Put in hourglass routines to include the LED indicator and changed
  454.   message warning order when you attempt to Squish a program.
  455.  
  456.               No LED : Initialising general internal routines,
  457.              Top LED : Extracting LOCK information,
  458.           Bottom LED : Initialising variables.
  459.    
  460.  
  461. * SYS reduction code altered, so that renaming of OS_WriteC (SYS &0)
  462.   does not have it's only zero stripped off by the leading_zero code.
  463.  
  464.   KJS/Izzy (07-04-93) - Release version 2.35
  465.  
  466.  
  467. * Fixed * command bug.
  468.  
  469.   KJS (15-04-93) - Release version 2.36
  470.  
  471.  
  472. * Adjusted !Run file so as not to re-instate a CLib that is already active.
  473.  
  474.   Izzy (10-05-93) - Release version 2.37
  475.  
  476.  
  477. * Removed bug in EOL removal code. Now removes EOL rubbish, without also
  478.   removing out of bound characters at the end of a * command.
  479.  
  480.   KJS (29-07-93) - Release version 2.38
  481.  
  482.  
  483. -----------------------------------------------------------------------------
  484.                                   Special note
  485. -----------------------------------------------------------------------------
  486.  
  487. * After concatenation, although the tokenised line may be less than or equal
  488.   to 255 bytes long, the UNtokenised may be a lot longer. BASIC editors do
  489.   not like this (sad isn't it?) and kick up errors of the sort : 'Line xxxx
  490.   is too long to be edited.'. Please note that this is not a 'bug' with
  491.   Squish, but a limitation of the editors.
  492.  
  493. ------------------------------ End Of Help File -----------------------------
  494.