AMOS Pro Variable Checker Version 1.01 ====================================== By Paul Hickman (ph@doc.ic.ac.uk) ================================= OVERVIEW ======== The variable checker is an accessory program which scans another programs source from the AMOS Pro editor, and reports possible errors in the use of variable names that AMOS Pro does not normally detect. This help debug programs, optimises them by allowing to remove assignments that are unneccessary, and leads to better programming practice. REQUIREMENTS ============ - Any version of AMOS Pro. - Enough memory to load the accessory, and the program to check simultaneously. - Easylife V1.4 (On aminet /pub/aminet/dev/amos/Easylife14b.lha DISTRIBUTION ============ This progam may be freely distributed, as long as no profit is made from doing so. It may not be put on a disk together with programs for which a profit is made from distributing them. GLOSSARY ======== Reference / Referal ------------------- A Reference to a variable is where the variable is used in the arguments of an AMOS function, or command where it's value is read, and not altered. The following are all references to VAR: Print "The Answer is:";VAR _CALL_THE_PROCUEDRE[1,"Fred",VAR,False] X=4+VAR*2 End Proc[VAR] Declaration ----------- The declaration of a variable notifies AMOS that it exists. All Definitions/Assignments are also declarations, as are variable names in Shared & Global statements. Definition / Assignments ------------------------ The definition / assignment of a variable is where the value of the variable is set by an AMOS command, or the '=' operation, without refering to VAR. The following are all definitions of VAR: VAR=4 Read VAR Input "Enter Value Of Var:";VAR Input #1,VAR; Line Input #1,VAR Procedure A_PROCEDURE[VAR] These are not definitions of VAR, as they always require VAR to be set (Or implicitly take it to be 0 if it isn't) VAR=VAR+4 (Also a reference to VAR) Add VAR,6 Dec VAR USAGE ===== Load the Variable Checker into AMOS Pro as an accessory program, then load the souce you wish to check into the editor,and test it. With the source window active, run the variable checker accessory. Firstly all procedures are unfolded, and the entire program is scanned for all shared variables, so that they to not show up as undefined if used in the main program before they are set. Then program is checked top to bottom, and the following errors are detected on the line they occur: Variables that are made Global after they have already been used. ----------------------------------------------------------------- Doing this can confuse the AMOS compiler, and it is generally bad programming practice. Move all Global statement to the top of your program. Global Variables that are shared in some procedures --------------------------------------------------- Making a global variable shared is a pointless exercise. Remove the shared statement from the offending procedure. NOTE: Even if a global variable is shared in several procedures, this error will only be reported once. Undefined Local Variables ------------------------- An undefined local variable is a variable which is not global, or shared, and is refered to in the program, before it has been defined (See Glossary) This error occurs if the variable is used above the point in the program at which it is defined. This should not be a problem with well structred programs, but those which use Goto/Gosub may find that frequently a variable is defined after the point it is used. NOTES: No error will occur at this stage, if the variable is a shared or global variable. They are only reported if they are never defined anywhere. This also applies to shared variables when they are used in the main program. This is the most frequently occuring error, and can be the most dangerous. If possible (practical -it's always possible), you should never asssume that a variable is uninitialised, and therefore 0, as: - You might modify the program to use it later, and it will then stop working. - The program will throw out loads of 'Local Varaible Undefined' errors, obscuring the times when you have actually mis-spelled a variable name, which is the case when this error being in your program makes it incorrect, and may make it crash. NOTE: This error will only occur the first time each undeclared variable is used in each procedure/the main program. When an 'End Proc' statement is encountered, in the program, the procedure is then checked for these errors: Unreferenced Local Variables ---------------------------- This is the opposite of the 'Undefined Local Variable' - A value has been assigned to a variable, but the variable is never refered to in the arguments of a function / command. This error only occurs within procedures during this stage of checking. NOTE: Sometimes an unreferenced variable is not an error e.g. A=Dialog Box(A$,0,B$). If you don't care what the dialog box returns, but just want to display it, A will be unreferenced. In such cases, A should be replaced with NULL. This program does not produce errors if NULL is unreferenced. By forcing you to use NULL, this shows other people reading the code that it is not used. (NULL# & NULL$ can be used when appropriate) NOTE: This error will not occur for variables that are defined as loop counters in For...Next loops. Unused Shared Variables ----------------------- This error occurs if a variable is made shared in a procedure, but is then not used in that procedure - I.E. it is not assigned to, or refered to. Finally, at the end of the source, the program checks for these errors. As each occurs, the cursor is moved to the line on which the varaible name was first used: Unused Shared / Global Variables -------------------------------- This error occurs for variables that are defined as Shared, or Global, and then not used anywhere in the program, either in definitions or references. Unreferenced Shared / Global Variables -------------------------------------- This error occurs for variables which are defined as Shared/Global, and have a value assigned to them at some point in the program, but are never refered to in the arguments of a command or function. Undefined Shared / Global Variables ----------------------------------- This error occurs for variables that are defined as Shared/Global, and are referenced, but never have a value assigned to them anywhere in the program. CAVATS ====== - Arrays are not checked, as AMOS requires that all arrays are dimensioned, before use, and produces an error if you try to refer to an undimensioned array. However, the index parameters are checked for references to other variables. - The arguments of Goto/Gosub statments are not checked for variable references, as there is no way to distinguish them from label references. The first expression of On Goto etc. statements is checked properly. - Commands names that have several words, the last of which is a single letter, and have no arguments may be mis-interpreted as shorter command names with 1 - letter variables as arguements e.g. An example is the AMOS Turbo Plus command 'Scene X'. This program would interpret that as the command 'Scene', followed by a reference to the variable 'X', and produce an error if 'X' is not defined. The program knows about a few commands such as 'Scene X' and ignores them. If you find any others, please E-Mail me. - Def Fn statements are not checked for references, as they are not interpreted at the point they are defined. - You might have to modify the MXVARS & Variable buffer size in the accessory if your program uses a lot of variables, and the accessory crashes. - Procedures which can not be unfolded (E.g. Contain Machine Code), will cause this program to think any code between them and then next procedure header is the code of the folded procedure, and not part of the main program. To prevent this, place these procedures at the end of your program, or follow them immediately by another procedure. - Wildcards in Global/Shared statements are ignored. If you didn't know that you could use them, don't bother finding out how - not only will it stop this program testing your program correctly, it is asking for trouble, with variables "accidently" becoming global. Don't be lazy, and list each one explicitly. It also makes your code easier for others to read. SUGGESTIONS =========== This program can be used in three ways: - To find out why a program isn't working. - To optimise them by removing unrefered to variables. - To remove all errors found by this program from your code, even if they are not "Real Errors" - E.g. this code woud produce an error but is not wrong. Procedure COUNT_NUMBERS[S$] X=1 While X48) and (C<=57) Then Inc RESULT Inc X Wend End Proc[RESULT] However, it is better coding to add to the end of the first line, ' : RESULT=0'. This will get rid of the 'Undifined Local Variable' error. I recommed you try to make your code produce no errors from this program, so it makes it less likely to go wrong if it is modified. This includes not using wildcares in Global/Shared statements (Which I only found out you could do today, and I think it was a rather stupid idea). CHANGES V1.00 ---> V1.01 ======================== - BUG FIX: Did not spot references to variables followed by spaces. This happened with variable names immediately before 'and','or','div','mod' etc. (Thanks to Ben Marty for spotting that one) TODO ==== - An options requester, so you can disable some of the checks. - Improve the speed of the variable lookup routine. - Write all errors to a file instead of bringing up a requester each time. (Thanks to Ryan Scott for that idea) BUG REPORTS =========== Given that the AMOS Pro editor itself sometimes cannot read your programs correctly, I will be amazed if I have managed to cover every possible case in this program. If you find it reports a name that is not a variable, or fails to report an error that it should, please E-Mail either the whole program (I never say no to free programs), or just the line that goes wrong. NOTE: If you use any extensions other than those listed below in code you send, either send me the extension as well (preferable if it's legal), or send it in AscII form, making clear what is command, and what is variable. I Have: AMOS Creator Compiler AMOS 3D ANOS Turbo / Turbo Plus EasyLife Intuition (Andrew Church's Extension - There are others,Or So I Hear) Paul Hickman ph@doc.ic.ac.uk