SpecBASBASIC interpreter User Guide Introduction There are many computer enthusiasts of a certain age who remember the great revolution in home computing of the 1980s. Computer manufacturers such as Commodore, Acorn and Sinclair made some of the most accessible and friendly devices ever found in the field of computing, and their style of Operating System has not been seen since, especially with the advent of multi gigahertz, multi-gigabyte memory PCs. Part of the magic of those bygone machines was the fact that space and resources available to the (single-core) CPUs was very restricted. It can be very hard to imagine any operating system running in just 16 kilobytes of memory, but that is exactly what they did. And they didn t just provide an OS, they a lso provided, in every case, a programming language with which the user could experiment and tinker to their heart s content. The Sinclair Spectrum was the most widely owned of these computers in the United Kingdom, and was graced with a fast 3.5mHz Z80 CPU and 64KB of memory 16KB of which was taken up by the ROM which provided the operating system routines and the BASIC interpreter. Based in the Dartmouth implementation of BASIC, it quickly gained a reputation as a very capable, if slightly slow, programming environment. SpecBAS is an implementation of the Sinclair BASIC programming language written for modern operating systems. It is intended to bring back some of the ease of use that the Spectrum was famous for to your modern PC. It is written to be as compatible as possible with the original BASIC, while providing more colours and a much faster interpreter with more features at the user s disposal which were not possible in the limited memory of the older 1982 computer. To this end, this manual is intended for those that are familiar, if not with the Sinclair Spectrum s BASIC, then BASIC programming in general. There are plenty of reference texts available which can teach this wonderful language, and a course in programming is beyond the scope of this ma nual. 1. The BASICs 1.1 Line numbers and statements SpecBAS is based around the concept of line numbers, which are generally not seen anymore in programming. This is quite often of benefit in helping to visualise the path the interpreter will take through y our code. Line numbers can be any from 1 to a very large number indeed, and you are unlikely to encounter an end to the highest number you can use. Take our word for it, it s very big. Line numbers are mandatory, and any line entered without them will be executed immediately. An individual command (or Keyword) is considered to be a statement. Statements must follow the line number, like so: 10 PRINT Hello Which is a line with one statement. Two or more statements may be concatenated with the : symbol, like so: 10 PRINT Hello : GO TO 10 Which illustrates the point quite nicely, but is a rather dull program to watch. Lines that are entered with a line number but no statement following it will be deleted from the program listing. You have been warned. 1.2 Flow Control Related to the way line numbers are used, it s worth mentioning how you can interrupt the program flow and direct excution to the line you want. In Sinclair BASIC, of course, this is achieved by using the GO TO and GO SUB commands, and SpecBAS is no different. However, there are a few nice methods available to you in SpecBAS which make things much more flexible. It s nice to take a jump to another region of your code only if a condition is met. To that end, there is the DO...LOOP constructor. The syntax of this command is: DO <WHILE condition> ... LOOP <UNTIL condition> So as you see, while a DO...LOOP structure will loop indefinitely, you can use WHILE and UNTIL to determine if it should loop. Conditions attached to a WHILE will be evaluated before the loop is run, whereas conditions attached to an UNTIL will be evaluated after a loop is run. If the condition is false, of course, then the loop will not run at all, and execution will resume at the statement following the LOOP command. 1.3 Logical Operators and Bitwise Operators Inequalities are the tests performed in the flow control structures mentioned above things like IF a<1 THEN ... Where the inequality is the a<1 part. A logical operator is similar, and consists of the AND and OR that is used. The problem with AND and OR is that they work logically (ie, their results depend on either side being true or false, or greater than zero and zero respectively). This is all very well when testing the truth of an equation, but other languages use AND and OR in a bitwise fashion that is, they re used to isolate and mask specific bits in a number. In order to perform the same tasks, SpecBAS uses & and | for bitwise AND and OR. They are written with special symbols to distinguish them from their logical counterparts. The other bitwise operators (SHL, SHR, XOR) are written as words. Like AND/& and OR/|, the operators ie, their syntax is shift and XOR commands work like maths <operand> <operator> <operand> The shift operators shift all the bits in a numbe r left or right one place, effectively doubling (SHL) or halving (SHR). Any bits shifted off the ends of the number (this is probably only observable in cases using SHR, as numbers in SpecBAS can get very large) will be lost. The XOR command will invert all the bits in the first number where bits of the second number are set. For instance, the number 128 consists of the binary sequence %10000000 Which, when XOR d with 255 (%11111111) will produce %01111111 Or 127 in binary. That % brings us nicely onto... 1.5 Numbers and Constants Numbers in SpecBAS don t have to be decimal they can be specified in either Binary, Hexadecimal or Decimal. To distinguish between them, you can use the % mark to indicate that a binary number follows, or a $ (or 0x ) mark er to indicate that a hexadecimal number is coming. Scientific numbering can also be used with the E marker, ie 1E+3 Will indicate that the number 1000 is to be used. Obviously, 1E-3 Will produce the number 0.001. Constants are words built into SpecBAS which can be used to identify numbers. The most obvious example of this is PI, which represents the number 3.1415926535897932385. There are others which represent TRUE (1), FALSE (0) and even common keys on the keyboard see the Appendices for the full list. These words can be used in place of the numbers they represent, and do not slow SpecBAS down at all when interpreting them. 1.4 Variables There are four types of variable available in SpecBAS string variables and their array equivalents. numeric variables, Numeric variables are always floating point with the use of built-in floating point units on modern CPUs, there is little benefit to using integer maths. Strings are always one byte per character, unless you are using UDGs (more on those later) there is no unicode in SpecBAS. Arrays are handled as the original BASIC would. Numerics are the same as you would expect from any other language. Strings variables are, when assigned to an array with DIM, always fixed-width. This means that doing: DIM a$(10,10) Will make an array of ten strings, each of ten characters each. Variable width string arrays are available with the DIM$ command in which case the above command would produce an array of one hundred strings, any one of which could be any length. Variables must be assigned with the LET command, which is not optional. You can quickly increment a numeric variable with the INC and DEC commands, which are quicker than LET a=a+1 Or LET a=a-1 But which will only work on numeric variables, not on strings, and only those variables that have previously been declared with LET. You can also optionally specify a range for the variable to be constrained to INC a,1,10 TO 50 Will ensure that when a overruns to 51, it will be wrapped back around to 10. This wrapping is in actual fact a modulus, so if a is incremented by 2, to make 52, then it will wrap around to 11. The SWAP command allows you to swap the contents of two variables of common type, such as two numeric variables or two string variables. Memory banks Storing your stuff Due to the fact that modern operating systems have nearly unlimited amounts of memory available due to the use of virtual memory managers and large hard drives for storing memory pages, SpecBAS has to provide a different method of accessing regions of memory to the old methods of PEEK and POKE which older computers used. This method is achieved using memory banks. Memory banks chunks of memory that hold a particular data type, such as screen or window data, or font information. SpecBAS provides two banks for this purpose, and one general-purpose raw binary data bank type. You can create a new bank using the BANK command BANK NEW newbnk,1000 Which will create a new bank which holds 1,000 bytes and assign the ID number of that bank to the variable newbnk. You should (and indeed, must) supply a numeric variable when creating the bank, so that you can refer to that bank later on. You can read the bytes held in a bank by using the PEEK function: PRINT PEEK(0,99) Which will return the value of the 100 th byte (0 is the first!) in Bank 0. You can set the values held in a bank with the POKE command: POKE 0,99,255 Which will set the 100 th byte of Bank 0 to 255. You can manipulate the bank with other BANK commands BANK SIZE id,newsize Will resize the bank s memory area to the size you specify. This is non destructive when growing the memory area, but shrinking it will unfortunately lose any data stored in the end of the bank that is lost after shrinking. BANK ERASE id Will remove the specified bank. Attempting to access this bank without recreating it with BANK NEW will result in an error. You can also copy one bank to another with BANK COPY src_id TO dst_id Which will duplicate the bank indicated by src_id in the bank specified by dst_id.