Copyright © 2002 Leaf Mindcraft and Melotech
To the right:- The Set Up Panel - Presented in the expanded form. To obtain the expanded form, click on the 'toggle size' icon in the upper right hand corner.
The name of the BBC BASIC file to be translated can be typed in here. The name will be inserted if the file concerned is dragged onto the panel or dragged to the !BBC_C icon on the icon bar. The file is 'grabbed' if it is double clicked upon. The !BBC_C program will detect non BBC BASIC files when run.
3.2. Run Button.Runs the !BBC_C program when clicked upon. Various messages are displayed on the screen to indicate the progress of the translation followed by a message giving the number of identifiers used in the BBC BASIC program. The number of constructs not recognised by the grammar (syntax errors) is also given. Syntax errors result in comments in the generated C and error message panels on the screen. These panels are usually suppressed. (See below).
The generated C is offered for saving within the same directory as the source BBC BASIC with the same name prefixed by a capital 'C'. Click on 'OK' or press the Return key if you are satisfied with this, otherwise alter the file name. If you hold down 'Control' and press 'U', the slot is cleared and a new name can be typed in and the icon dragged to the directory of your choice.
To the right:- The 'Save As' Panel.
Clicking here removes the application panel from the screen and returns you to the previous set of options.
3.4. Description Button.Clicking here and selecting 'Run' makes the !BBC_C application present the user with two panels giving a description of itself.
3.5. Help Button.Clicking here and selecting 'Run' makes the !BBC_C application present the user with two panels giving general help information. 'Description' and 'Help' cannot both be ticked at the same time, because selecting one deselects the other.
3.6. Verbose Button.Clicking here makes !BBC_C output debugging information concerning the process it is going through as it scans the BBC BASIC program i.e. the identifiers, literals and tokens it is encountering. This process considerably slows up the processing, so it is advisable not to turn this feature on unless you really want to see what !BBC_C is doing. At the end of the process, by clicking 'menu' over the window concerned, it is possible to save the diagnostics to a separate text file. Note that by the use of 'menu' it is possible to pause, resume or abort the process.
Also note that by clicking 'menu' over the main panel one is able to instigate the options 'Help', 'Debug' or 'Description' from a special menu. The opportunity to alter the command line that controls !BBC_C is also available from this menu.
3.7. Indexes Button.A facility to make FOR loop indexes and the indexes used in array arguments to be taken as integer variables. This facility was introduced in order to overcome the necessity for array arguments to have an integer type within the C language. However the C compiler does not need 'for' loops to use integers and if this option is not chosen, array indexes are still given a cast of 'int' if required.
Choosing this option could cause calculations with the relevant variables in other places to be truncated, so it should be used with caution.
3.8. Single Precision Button.When enabled, this option causes all floating point variables (those holding fractional values) to be made C type 'float'. Otherwise such variables are given the C type 'double', which offers more precision in floating point calculations. For various reasons, this option is best not enabled.
3.9. Remove REMs Button.When enabled, this option prevents BBC BASIC REMs (comments) from being translated into C comments within the translated code. Since one may prevent C compilers from keeping comments in the final compiled code, this option is only included for completeness.
3.10. All Lower Case Button.Problems can be encountered when the Translator turns all identifiers to lower case in line with C programming conventions. BBC BASIC identifiers such as 'a%' and 'A%' are quite frequently used and could be confused with each other if they were both converted to lower case. When this option is not enabled it prevents the first character of the identifier from being altered. With most programs you are advised not to convert entirely to lower case.
3.11. Integer, String and Float Terminators.In BBC BASIC, integer variables are terminated by '%' and character string variables by '$', otherwise they are taken as floating point. In the C language all variables must be declared before you use them, so they can have any name you like. These writable slots offer the user an alternative value to % and $, since $ and % cannot appear in C variable names. There should not be any need to alter the default values automatically supplied. If you should alter these values, only alphabetic upper or lower case characters or the underscore character may be entered into these slots.
Note this principal difference between BBC BASIC and the C language, as mentioned above. In BBC BASIC, variable names become available immediately they are mentioned anywhere in the code whereas the C language requires that all variables must be declared before they are used.
3.12. FN/PROC Terminators.BBC BASIC FNs (Functions) and PROCs (Procedures) can have the same name without any conflict arising, but in the C language every identifier must be unique. The two letter terminators are postfixed before any terminator due to data type, so a FN called 'mess%' with the defaults would become 'messfn_i'.
The BBC BASIC interpreter is also able to cope with such names beginning with numerics and containing keywords in the language. The C compiler requires that identifiers begin with an alphabetical character, so numerics are converted to 'a' - 'i' and 'z' for zero e.g. '1st' becomes 'ast', '0th' becomes 'zth' and a procedure called PROCTO becomes 'procto'.
There should not be any need to alter the default values. As with variable name terminators only up to two upper or lower case characters or the underscore character may be entered in these slots.
3.13. Array Terminators.As with BBC BASIC FNs and PROCs, there is no confusion if an array name is the same as a variable, FN or PROC, but the C compiler requires all identifiers to be unique. A three letter terminator for array variables names in the translated C is made available by this option. This terminator is in addition to any data type terminator, so an array name 'data%' in BBC BASIC would become 'dataarr_i' in the translated C with the defaults supplied.
There should not be any need to alter the default value supplied. As above only upper and lower case characters or the underscore character may be entered in this slot.
3.14. DEF Argument Terminators.It was found that the names of the formal parameters of FNs and PROCs in DEF statements were being confused with the same variable names used elsewhere. These names are purely dummy names, so this facility enables one to give these parameters a terminator that distinguishes them from other variable names. As before this terminator is in addition to the data type terminator and the default value of 'arg' need not be altered.
Should you wish to disenable this facility, clear out the slot.
3.15. Primary and Secondary Indentation.The single numerics entered in these slots determine the indentation to be applied to the translated C. The primary indentation applies to the whole code and indents each code line within the main program and C functions by the supplied number of spaces, making the code more readable by supplying an initial margin to the code.
The secondary indentation is added to the primary for each programming structure encountered (IF, REPEAT, WHILE, FOR and CASE). It is reduced by the same amount when the structure ends (with ENDIF, UNTIL, ENDWHILE, NEXT or ENDCASE respectively).
This also makes the translated C code more readable. The indentation in no way affects the speed or size of the compiled code, as the compiler ignores any embedded spaces. However the supplied BBC BASIC may have been 'squeezed' to remove spaces, as these do affect the speed of the interpreted BASIC.
3.16. Errors:- Quiet Button.When enabled, this option suppresses the error panels generated when a syntax (or parse) error is detected in the BBC BASIC program. As mentioned above, this may not be a fault in the BBC BASIC program, but a deficiency in the grammar that is being used by !BBC_C to parse the program.
Some programs produce many error messages, so this option is enabled by default to avoid constantly having to respond to the error panels.
If !BBC_C terminates with a 'Untrapped Parser Error' message, then it has fallen over at some point and the output file will be empty. In any case, the total number of errors is given. Use the tips above to reduce the errors to a minimum.
In some cases, badly bracketed programming structures result in !BBC_C searching for a terminating statement (containing ENDIF, ENDWHILE, UNTIL, NEXT or ENDCASE), which is never found and the program falls over.
!BBC_C does attempt keep track of structures and close higher structures when lower ones close e.g. a WHILE loop within a CASE structure will be closed with an injected ENDWHILE upon encountering a new WHEN or OTHERWISE.
3.17. Errors:- Maximum.!BBC_C will abort if the number of errors exceeds the indicated number. By default this is 300. If you do not wish the program to abort, you should increase this number, but by experience, if a large number of errors are generated then !BBC_C usually falls over and produces a blank output file. Sometimes this is due to not selecting the correct options for your program from the options described above.
3.18. Order of Identifier Declarations.!BBC_C keeps an internal table of all the identifiers (symbol table), which can be kept in different sorted orders. The writable icon can only contain 0, 1 or 2.
With 0 in it, the identifiers are just added to the end of the list every time a new identifier is encountered, so they are declared at the head of the generated C code in 'As Found' order. With 1 in the icon, the identifiers are kept in alphabetical order and with 2 in the icon, the identifiers are further sorted on their 'type', that is whether they are variables, functions or procedures. The option '2' is selected by default.
It is recommended that you should at least select option '1', or better still '2', because it makes it easier to search for a particular identifier in the declarations at the head of the generated C code. Also with 'As Found' order, the search for new identifiers in the symbol table is less efficient and can slow down !BBC_C.
3.19. Keep Separate List of Local Variables.When this option is enabled, the variables local to a BBC BASIC function or procedure are kept in a separate symbol table, which is renewed for each new function or procedure. This means that variable data types are only determined from their behaviour within the function or procedure and not the behaviour of any global variable with the same name.
Variables local to the function or procedure are their arguments and any variables declared as LOCAL in BBC BASIC within the routine.
This option can often reduce the number of syntax errors and furthermore BBC BASIC functions are often given much more accurate data types for the value that they return. For these reasons, this option is enabled by default.
3.20 Named Wimp Control Block/s.By default this option is ticked 'Off' and the writable icon is disenabled. This option, when enabled, allows you to specify the BBC BASIC names for up to ten variables used as Wimp control blocks. These blocks are used in SWI (SYS) calls, particularly in Wimp applications.
Such names may consist of alphanumeric characters, in both upper and lower case, and also the symbols '%', '$' and underscore. No other characters will be accepted in the writable icon. Each variable name must be separated from the next by a comma, and the whole string of names cannot exceed 100 characters. Such variables are given the data type of a string variable in the generated C code (char *).
3.21. Further Technical Information.For further information concerning the processing that !BBC_C does with BBC BASIC, consult 'TechNote' present within the application. In particular, note that variably dimensioned arrays need suitable fixed values for their dimensions to be filled in manually within the generated C code (in #define directives at the head of the code). If this is not done, then C compiler errors occur.
Certain BBC BASIC constructs were found to be untranslatable into an equivalent construct in the C language. !BBC_C will warn you in the generated C code where this occurs and the supplied 'TechNote' gives a list of those things that !BBC_C is unable to handle. Most of these constructs are only rarely used.
3.22. Writable Icons.Pointing the mouse at a writable slot and clicking 'Select' (left hand key) will insert a red cursor in the slot concerned. The backspace or delete key will delete characters to the left. Type into slots from the keyboard. Those slots with a white background will only accept alphabetic characters from the keyboard, whilst those in light yellow will only accept numeric characters.
If you clear the variable terminator slots to spaces, !BBC_C returns to its default e.g. for the integer variable terminator, it will take the value '_i' if the slot is cleared out. However the other terminator slots can be cleared to a null string.
Having entered a writable slot, pressing the 'Return' (Enter) key moves the cursor in turn to the next writable slot. Pressing the 'Return' (Enter) key when the final slot has been reached has the effect of running the application.
3.23 StartUp Banner Panel.Upon double clicking with the left hand mouse button over the !BBC_C Application icon, a banner panel appears giving proprietary information about !BBC_C. At the same time the !BBC_C icon appears on the icon bar. The panel appears for about five seconds, but the panel can be immediately removed from the screen by clicking once over it once with the mouse. The panel only appears once during any one session on the computer. That is, if you quit the !BBC_C application, carry on working without switching off the computer, then start !BBC_C again, then the panel does not reappear.
This document was generated on 20th May 2002 for !BBC_C distributed by Melotech for Martin Carradus.