#MAIN Basic1 Ver 0.04 Copyright 2018 Greg Sydney-Smith You can get help on the following topics: STARTUP COMMANDS LANGUAGE FUNCTIONS LICENSE CHANGES Use HELP for more info. #ADV Advanced commands are: C DBG LISTC LISTV Use HELP for more info. #C Command: C [n] Compile the program but don't run it. If "n" is included, Basic1 will show you internal information about the compile. n can be: 1 Splits program lines into tokens. 2 Produces an intermediate language listing with all labels intact. 3 As above but after jump addresses are assigned and labels have been removed. #CHANGES Ver 0.05 (2018-07-01) - Uses faster (binary) search for opcodes. - Added "IF expr THEN statements". Type HELP CHANGES 0.04 for earlier changes. #CHANGES-0.01 Ver 0.01 (2018-06-03) - Allows in line comments with single quotes ('). - Improved associativity (10-2-1 was 9; now 7). - Added NOT AND and OR operators. - Added power operator (eg 4^2). - Variable names are no longer case sensitive. - Better formatting of PRINTed numbers. - Comparisons also work with strings. - Improved precision during calculations. - LEN(str) - MID(str,start,len) - INSTR(hay,needle) - UCASE(str) - LCASE(str) - Updated grammar for better performance. #CHANGES-0.02 Ver 0.02 (2018-06-10) - The improved precision during calculations in ver 0.01 broke the INT() function. As numbers now consist of a mantissa and exponent, INT() was only working on the mantissa. This meant, in most cases, you'd only ever get a 1-9 result eg: INT(12+0) -> INT(1.2e+001) -> 1; or INT(0.9+0) -> INT(9.0e-001) -> 9 This has been fixed in ver 0.02. - Added CLS, PRINT AT(row,column), COLOR() and INKEY(). - Now supports lines like "statement : statement ..." Note IF is still "IF ... THEN NUM" not "IF ... THEN statements". You can achieve the same result though by: "IF ... THEN : statements : ENDIF" - Added CHR(num) and ASC(str). - Removed &. Strings can now be joined with + as that's what old programs were using. I'm using str+any->str, nonstr+any->num. - Added "ON expr GOTO line [, line]*" - Added LEFT(), RIGHT(), VAL() and STR() - For historic reasons MID$(), LEFT$(), RIGHT$() CHR$() and STR$() are also accepted. - Added LISTV command. Type HELP CHANGES 0.01 for earlier changes. #CHANGES-0.03 Ver 0.03 (2018-06-17) - "GOTO expr" is now "GOTO num" as "ON expr GOTO ..." was included in ver 0.02. - Added RENUM command. - Increased mem size to allow more complex programs. - INPUT allows multiple variables on the same line. - Added LINE INPUT [#num,] var. - Added OPEN, CLOSE, FREEFILE() and EOF(fd). - Added PRINT #num, expr [;]. - Added WHILE and WEND. Type HELP CHANGES 0.02 for earlier changes. #CHANGES-0.04 Ver 0.04 (2018-06-24) - Corrected CHANGES 0.03 to note FREEFILE() and EOF() are present. - Added STR(val,width,dec) - STR(val) no longer includes a leading and trailing space. eg: STR(2) was " 2 "; now "2". - Added DELETE filename and RENAME filename TO newname. - Added DIR(afn), SDIR(afn) and RUN(prog,args,mode). Type HELP CHANGES 0.03 for earlier changes. #CLEAR Command: CLEAR This command clears all variables from memory. It can be useful if you want to rerun a program from a clean starting point (as if Basic1 had just been loaded). See also LISTV #CLOSE Statement: CLOSE #num This CLOSEs an OPENed file. #CLS Statement: CLS This clears the screen. Basic1 sends an ANSI clear screen sequence to the console. On early versions of Windows with the ANSI.SYS driver loaded, this will clear the console screen. With Win10, ANSI is built in and Basic1 enables its use when it starts. See also: PRINT, COLOR. #COMMANDS Recognized commands include: CLEAR NEW LOAD SAVE LIST RUN QUIT HELP TRON TROFF Use HELP for more info. #DBG Command: DBG Use =20 to turn on VM tracing. This also shows stack activity. Use =0 to turn it off again. 22 Turns on timing for immediate mode. #DELETE Statement: DELETE filename This deletes a file. filename is a string expression. It can contain a direcory name or a path. See also: DIR. #DIR Function: DIR(afn) This does a directory listing and returns the name of a file in that directory. afn is an ambiguous file name. It can contain "?" or "*" to match one or more characters of a filename and is commonly seen as "*.*" (to match any filename) or like "*.txt" (to match all filenames ending in ".txt"). You can include a directory or a path as well, eg DIR("C:\UPLOADED FILES\*.jpg"). If you use an empty string ("") for afn, it will return the name of another file from the same directory. If there are no more files in the directory, it returns "". This function understands modern directories and only returns the names of files. It skips over subdirectory names. You can use IF DIR("filename")<>"" to check that "filename" exists. See also: SDIR. #END Statement: END A program should have an statement as the last line. Whilst the ECMA-55 standard requires an error to be displayed if you forget it, Basic1 will add one for you. #EOF Function: EOF(num) This returns true if file num is positioned at the end of the file. It also returns true if the file isn't open, so IF NOT EOF(num) it is safe to do a LINE INPUT #num, var. #EXAMPLES EXAMPLES A good source of programs for Basic1 is http://www.vintage-basic.net/games.html #FREEFILE Function: FREEFILE() This returns a small positive integer that can be used as a new file num. If it returns a negative value, then all file num values are already in use. See also: OPEN, CLOSE, PRINT2, LINE INPUT. #FUNCTIONS ABS(v) - absolute value of v (-3 -> 3) ASC(str) - Returns the ASCII code for the first char in str. "A"->65 ATN(v) - arctan of v (result is in radians) CHR[$](n) - Converts an ASCII code to a one char string. 13->"\r" COLOR(n) - an ANSI string that sets the foreground and background color for the following text. n=0-255. Use -1 for normal. COS(v) - cosine of v (v is in radians) EXP(v) - e^v INKEY() - Input a key. "" if none pressed yet. INSTR(hay,needle) - Position of needle string in hay string. 0 if not found. INT(v) - Integer value of v (2.3 -> 2) LCASE(str) - Convert string to lowercase LEFT[$](str,n) - Returns the leftmost n chars of str. LEFT("ab",1)="a" LEN(str) - Length of string LOG(v) - Log to base e of v MID[$](str,start,len) - Substring of str. RIGHT[$](str,n) - Returns the rightmost n chars of str. RIGHT("ab",1)="b" RND([v]) - provides a random number between 0 and 1 SGN(v) - sign of v (-> -1, 0 or 1) SIN(v) - sine of v (v is in radians) SQR(v) - squareroot of v STR[$](n) - Convert a number to a string. 2 -> "2" STR[$](n,width,dec)- Convert a number to a string. 2,5,1 -> " 2.0" TAN(v) - tangent of v (v is in radians) UCASE(str) - Convert string to uppercase. VAL(str) - Convert a string to a number. " -6" -> -6 #HELP Command: HELP [topic|command] Get general help, or help on a topic or command. #INKEY Function: INKEY() When a key has been pressed, INKEY() returns the key. If a key hasn't been pressed, INKEY() returns an empty string. The inputted key is not echoed to the screen by default. This can make it useful for passwords. If you want to echo the character, use PRINT. Example: 10 A$=INKEY() 20 IF A$="" THEN 10 30 PRINT A$; 40 IF A$="1" THEN ... 50 IF A$="2" THEN ... 60 ... #INPUT Statement: INPUT [string;] var [, var2]* This gets one or more values from the keyboard and stores them in variables. If [string;] is included, it is output to the screen (typically as a prompt) beforehand. #LANGUAGE CLS [LET] var = expr GOTO expr ON expr GOTO number [, number]* FOR var1 = expr TO expr [STEP expr] NEXT [var1] WHILE expr WEND IF expr THEN number IF expr THEN (statement(s)) [ELSE (statement(s))] ENDIF IF expr THEN statements PRINT [expr|TAB(expr)|AT(row,col)|,|;]* PRINT #num,expr[;] OPEN filename FOR mode AS #num CLOSE #num DIM var (expr [,expr]), ... INPUT var LINE INPUT [#num,] var GOSUB number RETURN STOP RESTORE READ var [, var]* RANDOMIZE END DELETE filename RENAME filename TO newname The language is based on the ECMA-55 standard but it has significant additions, some omissions, and a few changes. Not supported: DEF FNx [(parameter)] = expr - IMHO rarely used. Replace with subroutines. Changed: RND - Use RND([v]). END - This is optional. Added: Variables may be any number of characters long (not just 1 or 2). #LICENSE Basic1 Copyright 2018 Greg Sydney-Smith This software is available from www.sydneysmith.com The language may be freely used anywhere. This includes for commercial purposes. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. #LINE-INPUT Statement: LINE INPUT [#num,] var This gets a line of text from the specified file num, or from the keyboard, and stores it in a variable. See OPEN for how to associate a file name and num. #LIST Command: LIST [start [end]] LIST - List all program lines. LIST start - List 20 lines starting from line number "start". LIST start end - List lines between "start" and "end" (inclusive). #LISTC Command: LISTC - List compiled (VM code). Note: You need to have ompiled or something first. #LISTV Command: LISTV [0|1] LISTV - List all variables. LISTV 0 - Same. LISTV 1 - List the content of all arrays. This command is more useful after RUNning a program. See also CLEAR. #LOAD Command: LOAD "filename" Read text lines from "filename" in as the current program. #NEW Command: NEW This clears the current program so you can enter a new one. If you don't do a before a the new lines will be merged with existing ones. This could be useful for overlays; but Basic1 doesn't yet support a CHAIN statement. #ON-GOTO Statement: ON expr GOTO line1[,line2,...,lineN] If expr = 1, go to line1; or if = 2 to line2; etc. If expr is not in the range 1..N, the program continues to the next step. If expr is not a whole number, it is rounded to the nearest integer first. #OPEN Statement: OPEN filename FOR mode AS # num This opens a text file for reading, writing or appending. filename should be a quoted string (or a variable containe one or an expression giving one). mode should be "r", "w" or "a" for read, write or append. num is a file number, typically 2-9. See also FREEFILE. An OPENed file may be CLOSEd. Files are automatically closed when a program finishes (STOP, END, or after an error). See also LINE INPUT and PRINT. #PRINT Statement: PRINT * is: numeric expression string expression , ; TAB(n) AT(row,col) PRINT displays something on the screen. In its simplest form, with no print items, it moves the cursor to the start of the next line. See also: CLS, COLOR, PRINT2 #PRINT2 Statement: PRINT #num, expr [;] This prints expr to the specified file num. If the semicolon at the end is omitted, a newline sequence will also be written to the file. expr can be any string expression. If num is 0, output will be to the screen. See also OPEN, CLOSE, CHR. #QUIT Command: QUIT Exit Basic1 back to the operating system prompt. #RENAME Statement: RENAME filename TO newname This renames a file. filename is a string expression giving the existing file name. newname is a string expression giving the new file name. #RENUM Command: RENUM [start [step]] This command renumbers the loaded program so that the program starts with line "start" and each line number is "step" more than the previous one. The defaults are: start at 100 and step by 10. RENUM can be useful if you need to insert lines between existing ones. #RUN Type HELP RUN1 for the RUN command, or HELP RUN2 for the RUN() function. #RUN1 Command: RUN Run the ed or entered program. You can manually enter program lines by starting them with a line number. An entered line with the same line number will replace an existing one. Entering a line number, without anything else on the line, will remove an existing line. #RUN2 Function: RUN(prog,args[,mode]) This function runs another program and returns the exit code of that program. Programs typically have an exit code of 0 if they succeed, or 1-255 if they report errors. If the program couldn't be found, or if it couldn't be run, RUN() returns a value of -1. The Basic1 program waits until the RUN program finishes before it goes to the next step. prog is a string expression for the program name, eg "notepad.exe". args is a string expression for the command line arguments for the program. Use "" for none. mode is a number for the window mode. 1 is the default and that gives a normal window. Other values give windows that are maximized or minimized, and/or ones that don't receive "focus" (keyboard and mouse input stay in the existing program). #SAVE Command: SAVE "filename" Save the current program as "filename". This will overwrite an existing file. #SDIR Function: SDIR(afn) This does a directory listing and returns the name of a subdirectory in that directory. This function wasn't available in old versions of BASIC so it won't be needed to get old programs to run. However, modern directories are organised as trees and include sub directories. If you need to search through an entire tree, or simply check that a subdirectory exists; this will be useful. afn is an ambiguous file name. It can contain "?" or "*" to match one or more characters of a subdirectory name. You can use "*.*" to match any subdirectory. You can include a directory or a path as well, eg SDIR("C:\UPLOADS\*"). If you use an empty string ("") for afn, it will return the name of another subdirectory from the same directory. If there are no more subdirectories in the directory, it returns "". This function skips over files and oly returns subdirectory names. You can use IF SDIR("subdir_name")<>"" to check that "subdir_name" exists. See also: DIR. #STARTUP Basic1 [[-r] filename] Basic1 Starts in interactive mode. You can or manually enter a program. Basic1 filename This will start in interactive mode with filename ed. Basic1 -r filename This loads and runs "filename". It doesn't display the Basic1 details at the beginning and it exits after the program finishes. #STR Function: STR[$](n) - Convert a number to a string. 2 -> "2" STR[$](n,width,dec)- Convert a number to a string. 2,5,1 -> " 2.0" Convert a number to a string. In the first version, with a single parameter, the minimum width string is produced. It may contain upto 6 digits to the right of the decimal point; but will only use as many as needed. STR(2) -> "2", STR(1/5) -> "0.2" The second version allows formatting numbers as strings with a given width and a set number of decimal places. This can be useful, for example, when formatting monetary values. eg STR(100,8,2) -> " 100.00". If you specify a width that is too small, the width will be expanded as needed. eg: STR(123.4,0,2) -> "123.40". For historic reasons, you can use STR$(...) as well as STR(...). #TODO - TRIM(str) #TODO-LATER - DATE() number of days since epoch - TIME() frac of day (seconds/86400) - but then also need date/time to formatted and formatted to date/time - [MORE] for help: "Press RETURN to continue (Q to quit / B for beginning) " - LOADC filename / SAVEC filename (incl GOTO table and DATA sections) (note: also need var info - names and array dimensions) - ASIN(num) - ACOS(num) - a MOD b - vba has REPLACE(str,from,to) - does all occurances #TROFF Command: TROFF Turn tracing off. See for details. #TRON Command: TRON Turn tracing ON. This displays the line number of each program step as it is run. See also: TROFF. #TOPICS TOPICS The following topics exist in this HELP file: ADV C CHANGES CHANGES-0.01 CHANGES-0.02 CHANGES-0.03 CLEAR CLOSE CLS COMMANDS DBG END EOF EXAMPLES FREEFILE FUNCTIONS HELP INKEY INPUT LANGUAGE LICENSE LINE-INPUT LIST LISTC LISTV LOAD MAIN NEW ON-GOTO OPEN PRINT PRINT2 QUIT RENUM RUN SAVE STARTUP STR TODO TODO-LATER TOPICS TROFF TRON ##