__ ___ (__ | | | | ' __ _|__ \ | | | | | | (__ | ___/ \__|__/ _|_ |____ ( ___) (__ © 1 9 9 5 S t r a y l i g h t _____________________________________________________________________________ ABOUT SWILIST If you use C or the objasm assembler, and you need to use SWIs, then you'll probably want to have a file defining names for all the SWIs you'll be using, which you can include in any files which need it. SWIList is a small program designed to generate such files. There are lots of programs which do this job, although SWIList provides several important features which the others don't: * It's language independent. So you can use the same program to generate SWI files for C, assembler, or any other language you need. All you have to do is describe the language to SWIList. * It doesn't just scan the modules in memory. You can drop module files onto SWIList's icon in order to add their SWIs to the list. SWIList also keeps a file of all the names so far, which you can save, so you can add new modules easily when you obtain (or write) them. _____________________________________________________________________________ RUNNING SWILIST Introduction SWIList runs when you double-click its icon in a Filer window. It will add its icon to the icon bar in the traditional way. If you haven't yet saved a SWI dump (see below), SWIList will take a little while to read in all the modules currently loaded. The main menu If you click /menu/ on the SWIList icon, the main menu will be opened, from which you can choose the following options: Info Displays a dialogue box showing information about the SWIList application, including the version number, which you should note with any bug reports. Save list Displays a submenu of languages. Choosing one of the items from this submenu opens a dialogue box which will let you save a SWI list file in the appropriate language. Save dump Displays a dialogue box which lets you save the `SWI dump' -- a file containing all the SWI names currently in memory. More information about SWI dumps is given below. Rescan modules Discards all the SWI names currently in memory and rescans the loaded modules. This can take a short while. Quit Removes the SWIList application from memory. SWI dumps A *SWI dump* contains information about SWI names and numbers. It's a binary file, not intended for `user consumption'. SWIList will attempt to load the file `SWIdump' from its application directory when it starts up; if it can't find this then it will scan the modules in memory. This feature allows you to add to the SWIs currently recognised when new modules come along, rather than having to redo the whole lot from scratch. Format files In order to make SWIList language independent, all the information about specific languages is contained in a file called `Format' in SWIList's application directory. You can alter the existing formats, or ad your own for languages which aren't already supported (e.g. Pascal). The file's layout is fairly straightforward. The description of how to format each language is held in a `chunk', headed by the name of the language in square brackets (`[', `]'). (Actually, this isn't quite true -- the thing in the brackets is the menu item text, so we've followed it with `...' because the item leads to a dialogue box.) SWIList's output files are structured, and the format description echoes this. At the top of an output file is a header. Then, for each SWI-providing module, there is a header line, and this is followed by a piece of text for each individual SWI. Finally, the file is finished off with a footer. The format for a language is divided into four sections, separated by `%%'s: 1. The header text for the output. This is where you'd set up any macros needed, and ensure that the file is only included once, if this is required. 2. The header line (or lines) for each module. This is usually just a comment. 3. The text to define each individual SWI. Don't forget to define the `X' versions of the SWIs here. 4. The footer text for the output file. The text within each section can contain *format specifiers*, which are replaced with appropriate text while the file is being written. A format specifier begins with a `%' character. The replacement text is determined by the next character: `%m' Replaced by the name of the module whose SWIs are being written. This is usually used in the module separator lines. `%s' Replaced by the name of the SWI currently being defined. This is intended to be used when defining the individual SWIs. `%n' Replaced by the number of the SWI currently being defined. The number is written in hex, so be sure to include the appropriate specifier for the language (e.g. `&' in assembler or `0x' in C). `%x' Replaced by the number of the `X' version of the SWI being defined, also in hex. `%p' Replaced by a `%' character, just in case you need one. `%d' Replaced by the current date and time. The default format of the date is determined by an entry in SWIList's `Messages' file, although you can supply your own by placing it in square brackets immediately after the `%d'. The syntax of date formats is as described for the Alarm application, and the SWI OS_ConvertDateAndTime. For an example, which should help make everything clear, see the `Format' file supplied. Choices The Risc PC boot system sets up a system variable `Choices$Path' which allows applications to find configuration files kept separately from the application directory. If you have a Risc PC, or have set up the `Choices$Path' variable, SWIList will search for the `Format' and `SWIDump' files there before it looks in its application directory. _____________________________________________________________________________ TECHNICAL THINGS SWIList was written entirely in ARM Assembler. It gobbles large amounts of memory because it's using the Sapphire library which is completely excessive for SWIList's fairly modest needs. Some of the more advanced features of SWIList would have been difficult to implement without Sapphire however, and I doubt that I could have been bothered. For example: * RAM transfer support, for both loading and saving (including formatted SWI list files). * The format file support. * The dynamic menu of formats. * All the little luxuries like pointer changing and DragASprite support (including the icon being hidden when it's dragged). So there! The SWIList source code uses the BASIC assembler and Straylight's BASIC Assembler Supplement (BAS), which allows AOF object files to be generated from BASIC; the object was then linked to the Sapphire library. Sapphire was however written using Acorn's objasm assembler, which was a considerably more pleasant experience. _____________________________________________________________________________