The Amos Browser Copyright 1995-7 by Steven Goodwin -- Abstract -- This program is a useful tool for the Amos, or Amos Pro, programmer. The browser creates a database of your program that knows every variable, procedure and label you've used. It also knows where it was used, how often, where the procedures were called from and when the variables are changed. This helps code management as it shows redundant code and variables, where globals are being changed (possibly corrupted) and what code can be optimised. This program is intended to work regardless of what extensions are used, and how complex the code is. It extends beyond the usual facilities provided by search, as the browser will differentiate between 'Print', 'Int' and variables called 'RIN', ignore text in quotes or segments of code hiding in comments and distinguish between local, global and shared variables using the same name! It also know the difference between strings, arrays, real and integer variables! -- Menu Options -- Project: Open ASCII This loads your AMOS program into the browser and creates a database for it. A sample is included. The source input file to the browser must be: 1. Saved in plain ASCII format, from within the Amos editor. You should 'select all' and 'save ascii' from within AMOS. 2. Completely open. i.e. all closed procedures must be opened from within AMOS using 'Open All'. If the procedures in question have been 'locked', then simply delete the 'Procedure _CLOSED_PROC_NAME' from the file with a text editor, and replace it with a dummy 'Procedure- End Proc' pair. This is not essential, but it maintains accuracy within the parser (see Important Information below). 3. A fully legal program. i.e. the 'Test' (F2) option returns 'No Errors'. The browser relies on the spacing and case-sensitive nature of the source in the Amos editor. Changing it may result in inaccuracies! If you program using an external editor you should load the source into the AMOS editor, and re-save. Once loaded, the browser will scan your program, and create its' own internal tables. This process can take a long time. Often two or three times longer than it does to 'Test' it through AMOS. One reason is that the source must be scanned in ASCII mode. AMOS tests it using a tokenised form, which is much quicked, due its compacted nature. (another reason is that Amos scans in assembler...I don't!). Open Browser This loads a '.browse' file into memory, and refreshs each window. Save Browser This saves a '.browse' file of the current browse database. Using this file saves a lot of time over importing an ASCII file, and re- calculating the database. Quit Leaves the program! -- Window -- Variable Window: The left hand side lists each variable used in the program. The right hand side shows its definition and where it has been used (the references). The definition list is given thus, Definition: Variable name (also known as the identifier) Variable type (global string, int array, etc) References: Line XX Procedure it appears in. Proc_Line ..etc.. The 'XX' above consists of two special characters. The first character is either: D Declared - The variables first appearance in the source. S Shared - The variable is declared as shared for this procedure. (note, this only appears on one line as all other variables of this name within that procedure must, by definition, be shared). - Nothing special. The second character is either: * The variable is changed on this line. It may be through an expression (A=B+4), or an instruction like Inc or Dec. If the variable is an array, then changing any element in the array will produce a '*'. : Nothing special The text requester in the centre of the window allows you to restrict the variables listed in the list on the left hand side. This is done by typing the variable name into the requester and pressing 'Find'. This will then list the variable (if it exists), and (on the right hand side), its definition and references. To use wildcards on the variable name, append a '*' to the end of the name. This means that 'ID_*' (for example) will list all the variables that start with 'ID_', and no others. Using '*' or '**' will list all the variables. A trailing wildcard character is, currently, the only acceptable variation (ie. VAR_*_SIZE will not work). The other option in this window is a set of check boxes labelled 'Include?'. These options specify what types of variable will be included in the search initiated with the 'Find' button. One point to bear in mind; if the variable is a string array, it will be included as both a string, AND an array, so you will have un-tick each box to exclude it from the search. To list all the variables in the left hand side scroll box just press 'Find Variable' with an empty text requester. This does the same as a search for '*' or '**' (i.e. a search for everything). Procedure Window: This functions in the same manner as the 'variable window', it shows each procedure and where it is called from. The right hand window, however, has three possible display methodologies, selected from the radio buttons. They are: References Shows the procedure name, the line it is declared on, and each reference that calls the procedure. Call Graph Shows, in a graphical manner, each procedure and what subsequent procedures it calls. By starting with the main Amos program, it might show: Main Amos Program +--INIT | +--SETUP_BANKS | +--LOAD_ICONS +--OPEN_MAIN_WINDOW +--EVENT_LOOP | +--EMULATE | +--HANDLE_EVENT | | +--HANDLE_MAIN | | +--HANDLE_PREFS | +--NAGWARE_WINDOW +--CLOSE_ALL_WINDOWS +--QUIT Caller Graph Much the same as the call graph, this shows the "is called by" procedures. So, if your CLEAR_SCREEN procedure is being called too often, this graph will show you which routines can call it. Because it is not possible for a procedure to re-run the program (only the Amos editor can do this) the list will be empty in this case. Note: In the current version, the order of procedure calls is not supported, so they may appear in the reverse order of a call graph, or caller graph list. Labels Window: This window works in the same way as both the variables and procedure windows. However, this only has 'Find Label' function. Again, the '*' wildcard may only be placed at the end of the label identifier. Preferences Window: This allows you to set the maximum number of variables, procedures and labels held internally. The browser must be restarted for these options to take effect. This information is stored in the configuration file which is saved in s: and loaded into memory upon program boot-up. -- IMPORTANT NOTES -- The main processing routine inside the browser is the 'parser'. This reads through the program file looking for variables, procedures and labels (refered to as identifiers). However, when coding this, I had no access to the actual syntax rules, or the tokenised file form of AMOS. This meant I had to 'reverse-engineer' my own rules for the language. Although I have tested a great deal of code through the parser, I may not have catered for certain 'tricks' or cases which seem 'obvious' to some programmers. In which case you may get strange variables appearing in the browse tables...but it should not be fatal. Furthermore, the browser should work through most (if not all) extensions. Here are some of the more 'exotic' uses of the Amos parser that the browser WILL cope with: _CLEAR[SCR=Screen] _$="" Data NAME$,ADDRESS$,AGE LAB: PRC_NOT_LAB : PRC_NOT_LAB In order to improve the parser speed, some liberties were taken. The most obvious of these is the lack of error checking! If the program is not correct, or it runs out of space to hold all the identifiers then it will stop, and the program will exit without warning. The registered version includes a 'safe' version that will not exit, should any of the tables become full. All identifiers are significant to 32 characters. When loaded, the browser immediately creates space for the variable, procedure and label tables. If it suceeds, the only other memory required will be for the ASCII program. Therefore, if the program can start, there should be no memory allocation problems during execution (saving a browser file also uses allocated memory, but it should be less than that of the ASCII program - which is currently removed after parsing - so if the Amiga managed to allocate memory for that, it should be able to do so again). -- Known Bugs and Omissions -- Functions (in the form, Def Fn(x) etc) are not handled. The code is parsed, although if it deals with any variables they will not appear correct in the list. When running the browser as an Amos Pro accessory (only available to registered users), using key shortcuts inside the browser can cause the keys to echo within the Amos Pro editor. They will be visible upon exit. If present, they will appear at the end of your source code. -- The Final Word -- This program is shareware, you can use it for 30 days without paying for it. If, however, you want the source (enabling you to run the browser as an accessory from within Amos Pro!), or you wish to use the software after this period, then send me £5, and I'll return you a disc with all the source, the latest version, and any other utilities I've written that haven't been released yet. Now, Q. Where do I send my money? A. Steven Goodwin 105 St. Johns Road Clacton-on-Sea Essex CO16 8DB Q. What do I say? A. Try printing this off.... (or copying the relevant bits if you're without a printer) o/_________________________ CUT HERE ________________________________ O\ Your Name:_______________ Address :_______________ _______________ _______________ _______________ Hi Mr. Steven Goodwin, I would like to register my copy of The AMOS Browser because a) It's brilliant! (a very good reason, I might add) b) I think I'd prefer the 'safe' version, despite the performance hit. c) I'd like to run it as an accessory! d) I need access to the preferences because my programs are too big and powerful! e) I have a tremendous guilt complex! f) All of the above (circle as appropriate) I enclose a cheque/postal order for £5 (which includes P&P) because I'm a kind hearted soul whos cares about the people you make my software. Thanks very much, Name ________________ (not completely necessary, but ties up the letter nicely) o/_________________________ CUT HERE ________________________________ O\ That's all folks!!!! See you on the next release...