Guide to writing libraries
... Note: This article specifically applies to re-usable code libraries. Another use of the INSTA…
Note: This article specifically applies to re-usable code libraries. Another use of the INSTALL statement is as a means of splitting a large program into modules. Several of the guidelines listed below do not apply to that use, apart from the prohibition on the use of line numbers and labels, and the necessity to enable the Crunch embedded program files compile option.
A BBC BASIC for Windows LIBRARY is a special kind of program file which contains functions and/or procedures which can be called from the main program in which it is INSTALLed (or from another library installed by that same program). Fundamentally it is no different from any other program file except that it contains no 'main program' (unless you wish to include some code which will report an error if it is executed directly, see Preventing a library from being run). In addition, a library must be saved as an internal format (tokenised) .BBC file rather than a plain-text (ASCII) .BAS file. If you attempt to INSTALL a library saved in the wrong format a Bad library error will result.
Having said that a
An overriding consideration, which lies behind many of the recommendations, is that a library must be as self-contained as possible. Ideally it should not be dependent on any specific characteristics of the program in which it is INSTALLed, nor should it impose any avoidable restrictions on that program.
Libraries may contain neither line numbers nor labels. It follows that a library should not use GOTO, GOSUB or ON GOSUB statements. A library may use RESTORE but only the special RESTORE +n relative form.
The shared information may be passed between the various library routines by the calling program, for example as passed-by-reference parameters or opaque structures. Using this method the functions and procedures don't communicate directly, but use the main program as an 'intermediary'.
The functions and procedures may share information by means of PRIVATE variables, arrays and/or structures. See the article Sharing PRIVATE variables for more information.
as incorporating the name of the library or a Globally Unique Identifier as part of the name. Also consider using a specific naming convention for library globals, such as containing (but not starting with) the @ character.
Temporary variables (other than formal parameters) used within an individual procedure or function should always be declared as LOCAL or PRIVATE. Note that PRIVATE variables are incompatible with certain types of error trapping, in which the main program attempts to recover from an error. This is because if an error occurs at a time when a variable has been made PRIVATE you cannot call that routine again (it will be treated as a re-entrant call). This problem can be circumvented by careful use of local error trapping as follows: