diff --git a/docs/external_resources.md b/docs/external_resources.md index 4abecbcc0..3fa445a18 100644 --- a/docs/external_resources.md +++ b/docs/external_resources.md @@ -9,7 +9,7 @@ Other people contribute to it creating alternative IDEs, libraries, tools and ut ### Tommy Gun A free IDE created by [Tony Thompson](http://www.users.on.net/~tonyt73). This powerful tool is designed to create generic 8-bit and 16-bit projects, and can be set up to be used with ZX Basic. -Have a look at the [TommyGun files](https://sourceforge.net/projects/tommygun/files/) page. +Have a look at the [TommyGun files](https://sourceforge.net/projects/tommygun/files/) or [source code](https://github.com/tonyt73/TommyGun) pages. To integrate ZX Basic with Tommy Gun, please follow this [tutorial](https://forum.boriel.com/showthread.php?tid=110). @@ -25,7 +25,7 @@ further information. The documentation of it is very well maintained. * [Multipaint](http://multipaint.kameli.net/), a Java-based graphics editor that allows you to draw pictures with the color limitations of some typical screen formats from 8-bit computer platforms, like ZX Spectrum, C64 and Plus/4 high-resolution and multicolor, MSX 1 and Amstrad CPC0. -* [ZX-Paintbrush] (https://zx-modules.de/), a Windows graphics editor specifically for ZX-Spectrum screen formats, including multicolor. +* [ZX-Paintbrush](https://zx-modules.jimdofree.com/), a Windows graphics editor specifically for ZX-Spectrum screen formats, including multicolor. ## Utilities Other generic utilities not above are: @@ -45,13 +45,13 @@ There are several external engines that can be used within compiler to achieve e * [FASE](https://forum.boriel.com/showthread.php?tid=568) (or [here](https://forum.boriel.com/showthread.php?tid=575)), a sprite, tile and map engine. * [Nirvana](https://spectrumcomputing.co.uk/entry/30001/ZX-Spectrum/NIRVANA_ENGINE) - (or [https://www.ime.usp.br/~einar/bifrost/ here]), a multicolour 8x2 (30x22 chars) graphics engine. + (or [here](https://www.ime.usp.br/~einar/bifrost/)), a multicolour 8x2 (30x22 chars) graphics engine. * [Nirvana+](https://spectrumcomputing.co.uk/entry/30002/ZX-Spectrum/NIRVANA_ENGINE) - (or [https://www.ime.usp.br/~einar/bifrost/ here]), a multicolour 8x2 (32x23 chars) graphics engine. + (or [here](https://www.ime.usp.br/~einar/bifrost/)), a multicolour 8x2 (32x23 chars) graphics engine. * [Bifrost*](https://spectrumcomputing.co.uk/entry/27405/ZX-Spectrum/BIFROST*_ENGINE) - (or [https://www.ime.usp.br/~einar/bifrost/ here]), a multicolour 8x1 (18x18 chars) graphics engine. + (or [here](https://www.ime.usp.br/~einar/bifrost/)), a multicolour 8x1 (18x18 chars) graphics engine. * [Bifrost*2](https://spectrumcomputing.co.uk/entry/30003/ZX-Spectrum/BIFROST*2_ENGINE) - (or [https://www.ime.usp.br/~einar/bifrost/ here]), a multicolour 8x1 (20x22 chars) graphics engine. + (or [here](https://www.ime.usp.br/~einar/bifrost/)), a multicolour 8x1 (20x22 chars) graphics engine. * [Zxodus\]\[Engine](https://spectrumcomputing.co.uk/entry/26639/ZX-Spectrum/ZXodus_Engine) (or [here](https://forum.boriel.com/showthread.php?tid=568)), a 3d maze and RPG engine with multicolour 8x1 (18x18 chars) support. diff --git a/docs/for.md b/docs/for.md index 3ad506557..5fbc1dc7a 100644 --- a/docs/for.md +++ b/docs/for.md @@ -10,7 +10,6 @@ ## Parameters * _iterator_: a variable identifier that is used to iterate from an initial value to an end value. -* _datatype_: If specified, the variable iterator will automatically be declared with the type datatype. * _startvalue_: an expression that denotes the starting value of the iterator. * _endvalue_: an expression used to compare with the value of the iterator. * _stepvalue_: an expression that is added to the iterator after every iteration. diff --git a/docs/function.md b/docs/function.md index f622874ae..5a009d309 100644 --- a/docs/function.md +++ b/docs/function.md @@ -80,5 +80,6 @@ that can be ignored. * [ASM](asm.md) * [END](end.md) * [RETURN](return.md) +* [DECLARE](declare.md) * [ByREF](byref.md) * [ByVAL](byval.md) diff --git a/docs/identifier.md b/docs/identifier.md index 05cc3d0c7..9f9a3294d 100644 --- a/docs/identifier.md +++ b/docs/identifier.md @@ -9,7 +9,7 @@ Note that there are a number of common statements that you may find in ZX BASIC ## Reserved Identifiers -The following identifiers are _reserved words_, and can't be used as variables, functions or labels. Reserved identifiers are _case insensitive_ (it doesn't matter whether you write them in upper or lower case letters, or a mix of them). So **PRINT**, **print** and **PrInT** means all the same in ZX BASIC. On the other hand, non-reserved words can be either case sensitive or not (depending on the [options](options.md)) in effect. +The following identifiers are _reserved words_, and can't be used as variables, functions or labels. Reserved identifiers are _case insensitive_ (it doesn't matter whether you write them in upper or lower case letters, or a mix of them). So **PRINT**, **print** and **PrInT** means all the same in ZX BASIC. On the other hand, non-reserved words can be either case sensitive or not (depending on the [options](zxb.md#command-line-options) in effect). Identifiers shown in bold are taken from the Sinclair BASIC (beware their meaning here might be different, however). Some of them has been marked as _statements_, _functions_ or _operators_: @@ -120,7 +120,7 @@ You should also avoid defining (with a SUB or FUNCTION command) routines with th * **[CSRLIN (Library Function)](library/csrlin.md)** **(function)** * [HEX (Library Function)](library/hex.md) **(function)** * [HEX16 (Library Function)](library/hex.md) **(function)** -* **[INPUT (Library Function)](library/input.md)** **(function)** +* **[INPUT42 (Library Function)](library/input42.md)** **(function)** * **[GetKey (Library Function)](library/keys/getkey.md)** **(function)** * **[MultiKeys (Library Function)](library/keys/multikeys.md)** **(function)** * **[GetKeyScanCode (Library Function)](library/keys/getkeyscancode.md)** **(function)** diff --git a/docs/library/attr.md b/docs/library/attr.md index 481eedf3f..51bcbf5b5 100644 --- a/docs/library/attr.md +++ b/docs/library/attr.md @@ -31,5 +31,5 @@ PRINT AT 0, 0; "The attribute of screen position 9, 10 is "; s ## See also * [ CSRLIN ](csrlin.md) -* [ POS](pos.md) +* [ POS ](pos.md) * [ AT ](../at.md) diff --git a/docs/library/csrlin.md b/docs/library/csrlin.md index d0725bbad..c31d13479 100644 --- a/docs/library/csrlin.md +++ b/docs/library/csrlin.md @@ -2,6 +2,7 @@ ## Syntax + ``` CSRLIN() ``` @@ -14,6 +15,7 @@ Returns the row (line) position of the text cursor (0 means the top line). CSRLIN is a library function to be included with the following command: + ``` # include ``` diff --git a/docs/library/hex.md b/docs/library/hex.md new file mode 100644 index 000000000..e04868855 --- /dev/null +++ b/docs/library/hex.md @@ -0,0 +1,37 @@ +# HEX/HEX16/HEX8 + +## Syntax + + +```basic +A$ = hex(n32) +B$ = hex16(n16) +C$ = hex8(n8) +``` +Where `n32` is a 32-bit ULONG, `n16` is a 16-bit UINTEGER and `n8` is an 8-bit UBYTE. + +## Description + +* HEX: +Takes one _32_ bit unsigned integer number and returns an 8 chars str containing the HEX string representation. +* HEX16: +Takes one _16_ bit unsigned integer number and returns a 4 chars str containing the HEX string representation. +* HEX8: +Takes one _8_ bit unsigned integer number and returns a 2 chars str containing the HEX string representation. + +## Requirements + +HEX, HEX16 and HEX8 can be included with the following command: + +``` +#include +``` + +## Remarks + +* This function is not available in Sinclair BASIC. +* Avoid recursive / multiple inclusion when calling this function. +* HEX16 ad HEX8 both call HEX to perform conversion, but differ in the size of the string they return. + +## See also + diff --git a/docs/library/input42.md b/docs/library/input42.md new file mode 100644 index 000000000..59a6debe6 --- /dev/null +++ b/docs/library/input42.md @@ -0,0 +1,35 @@ +# Input42.bas + +## INPUT42 + +Simple INPUT routine (not as powerful as Sinclair BASIC's), but this one uses the PRINT42 routine. +Issues a cursor to the screen, waits for the user to type and returns the user's input through PRINT42 when the user presses ENTER. + +## Syntax + +```basic +A$ = INPUT42(MaxChars) +``` +MaxChars is the number of characters the INPUT42 function will accept as a maximum. It is a UINTEGER and thus has a maximum value of 65535. + +## Requirements + +INPUT42 is a library function that must be included before it can be used. Use the following directive: + +``` +# include +``` + +## Remarks + +* Note that this function ALWAYS RETURNS A STRING, which is very different from Sinclair BASIC's INPUT statement. +* This function places the Input cursor at the last print position, not at the bottom of the screen. Remember that ZX Basic allows access to all 24 screen lines, so PRINT AT 24,0; sets the PRINT cursor to the bottom of the screen. +* Avoid recursive / multiple inclusion +* The input subroutine DOES NOT act like ZX Spectrum INPUT command +* Uses ZX SPECTRUM ROM + +## See also + +* [ INKEY ](../inkey.md) +* [ INPUT ](../input.md) +* [ PRINT42 ](print42.bas.md) diff --git a/docs/operators.md b/docs/operators.md index c66889333..0e5106ed7 100644 --- a/docs/operators.md +++ b/docs/operators.md @@ -39,10 +39,8 @@ which is _wrong_. If in doubt, use always parenthesis to enforce the desired eva ## Logical Operators -Logicals operators are like in ZX Spectrum Basic. Their result can be either _False_ (which is represented with 0) -or _True_, which might be any other value. Don't expect _True_ value number to be always **1**. -If you need 0/1 values for boolean evaluations, use `--strict-boolean` [compiler option](zxb.md#Command Line Options). -This might add a little overhead to boolean evaluations, tough. +Logicals operators are like in ZX Spectrum Basic. Their result can be either False +(which is represented with 0) or True (represented by 1). Operator arguments must be numbers and the result is an unsigned byte value. For binary operators, if arguments are of different types they are [converted](cast.md) to a common type before being evaluated: diff --git a/docs/sub.md b/docs/sub.md index 4734b8f6b..1905a5df7 100644 --- a/docs/sub.md +++ b/docs/sub.md @@ -1,6 +1,5 @@ # SUB - ZX Basic allows function and subroutines declarations. Sinclair Basic does not allow named subroutines, only calls with the GOSUB command. A subroutine defined with the SUB statement is invoked directly. Unlike a [FUNCTION](function.md), a SUB does not return a value. This is the fundamental difference between code defined with SUB and code defined with FUNCTION. Other than that, the setup for SUB and FUNCTION are almost identical. @@ -71,3 +70,4 @@ It will also issue a warning (perhaps you forgot to call it?), that can be ignor * [ASM](asm.md) * [END](end.md) * [RETURN](return.md) +* [DECLARE](declare.md) diff --git a/docs/to.md b/docs/to.md new file mode 100644 index 000000000..eef3c9218 --- /dev/null +++ b/docs/to.md @@ -0,0 +1,10 @@ +# TO + +**TO** is a keyword used to specify a sequence of numbers to be used in a statement. + +a TO b (STEP c) will give the statement a sequence of numbers starting at a and ending at [the closest number less than or equal to] b, +with each number after a being the previous number plus 1, or c if the STEP keyword is used (only supported by FOR). +In the case of a TO b with a and b integers, the sequence will include both a and b. +A, B and C can be expressions, can be floating point numbers [FOR i = 0 TO PI / 2 STEP q - circle.bas.md] +Statements that can be used with TO are FOR, DIM [DIM b(0 TO 10) - dim.md, DIM a(3 TO 5, 1 TO 8) - lbound.md, only dimensions, indexes will only be valid within the declared range], [variable value assignments? NO, not even arrays], NOT array, string indexing [s$(TO N - 1) - left.md, s$(len(s$) - N - 1 TO) - right.md] +GO TO, despite having TO, is a different statement and these rules do not apply to it diff --git a/docs/zxb.md b/docs/zxb.md index 298e936d9..2a2bd2087 100644 --- a/docs/zxb.md +++ b/docs/zxb.md @@ -53,64 +53,82 @@ You can change the default origin using the -S command line parameter. ZXB provides several (and useful) command line options. To see them, just type **_zxb.py -h_**, which outputs: ``` - usage: zxb [-h] [-d] [-O OPTIMIZE] [-o OUTPUT_FILE] [-T] [-t] [-B] [-a] [-A] + usage: zxbc.py [-h] [-d] [-O OPTIMIZE] [-o OUTPUT_FILE] + [-T | -t | -A | -E | --parse-only | -f {asm,bin,ir,sna,tap,tzx,z80}] [-B] [-a] [-S ORG] [-e STDERR] [--array-base ARRAY_BASE] - [--string-base STRING_BASE] [-Z] [-H HEAP_SIZE] [--debug-memory] - [--debug-array] [--strict-bool] [--enable-break] [-E] [--explicit] - [-D DEFINES] [-M MEMORY_MAP] [-i] [-I INCLUDE_PATH] [--strict] + [--string-base STRING_BASE] [-Z] [-H HEAP_SIZE] [--heap-address HEAP_ADDRESS] [--debug-memory] + [--debug-array] [--strict-bool] [--enable-break] [--explicit] + [-D DEFINES] [-M MEMORY_MAP] [-i] [-I INCLUDE_PATH] [--strict] [--headerless] [--version] + [--append-binary APPEND_BINARY] [--append-headless-binary APPEND_HEADLESS_BINARY] + [-N] [--arch ARCH] + [--expect-warnings EXPECT_WARNINGS] [-W DISABLE_WARNING] [+W ENABLE_WARNING] [--hide-warning-codes] + [-F CONFIG_FILE] [--save-config SAVE_CONFIG] [--opt-strategy {size,speed,auto}] PROGRAM positional arguments: PROGRAM BASIC program file - optional arguments: + options: -h, --help show this help message and exit - -d, --debug Enable verbosity/debugging output. Additional -d - increase verbosity/debug level - -O OPTIMIZE, --optimize OPTIMIZE - Sets optimization level. 0 = None (default level is 2) - -o OUTPUT_FILE, --output OUTPUT_FILE - Sets output file. Default is input filename with .bin - extension - -T, --tzx Sets output format to tzx (default is .bin) - -t, --tap Sets output format to tap (default is .bin) - -B, --BASIC Creates a BASIC loader which loads the rest of the - CODE. Requires -T or -t + -d, --debug Enable verbosity/debugging output. Additional -d increase verbosity/debug level + -O, --optimize OPTIMIZE + Sets optimization level. 0 = None (default level is 2 + -o, --output OUTPUT_FILE + Sets output file. Default is input filename with .bin extension + -T, --tzx Sets output format to .tzx (default is .bin). + -t, --tap Sets output format to .tap (default is .bin). + -A, --asm Sets output format to .asm. DEPRECATED. Use -f + -E, --emit-backend Emits backend code (IR) instead of ASM or binary. + --parse-only Only parses to check for syntax and semantic errors + -f, --output-format {asm,bin,ir,sna,tap,tzx,z80} + Output format + -B, --BASIC Creates a BASIC loader which loads the rest of the CODE. Requires -T ot -t -a, --autorun Sets the program to be run once loaded - -A, --asm Sets output format to asm - -S ORG, --org ORG Start of machine code. By default 32768 - -e STDERR, --errmsg STDERR - Error messages file (standard error console by - default) + -S, --org ORG Start of machine code. By default 32768 + -e, --errmsg STDERR Error messages file (standard error console by default) --array-base ARRAY_BASE Default lower index for arrays (0 by default) --string-base STRING_BASE Default lower index for strings (0 by default) - -Z, --sinclair Enable by default some more original ZX Spectrum - Sinclair BASIC features: ATTR, SCREEN$, POINT - -H HEAP_SIZE, --heap-size HEAP_SIZE + -Z, --sinclair Enable by default some more original ZX Spectrum Sinclair BASIC features: ATTR, SCREEN$, POINT + -H, --heap-size HEAP_SIZE Sets heap size in bytes (default 4768 bytes) - --heap-size HEAP_ADDRESS - Sets the start address of the heap + --heap-address HEAP_ADDRESS + Sets the heap address. --debug-memory Enables out-of-memory debug --debug-array Enables array boundary checking - --strict-bool Enforce boolean values to be 0 or 1 + --strict-bool Enforce boolean values to be 0 or 1 (Deprecated) --enable-break Enables program execution BREAK detection - -E, --emit-backend Emits backend code instead of ASM or binary - --explicit Requires all variables and functions to be declared - before used - -D DEFINES, --define DEFINES - Defines de given macro. Eg. -D MYDEBUG or -D - NAME=Value - -M MEMORY_MAP, --mmap MEMORY_MAP + --explicit Requires all variables and functions to be declared before used + -D, --define DEFINES Defines de given macro. Eg. -D MYDEBUG or -D NAME=Value + -M, --mmap MEMORY_MAP Generate label memory map - -i, --ignore-case Ignore case. Makes variable names are case insensitive - -I INCLUDE_PATH, --include-path INCLUDE_PATH - Add colon separated list of directories to add to - include path. e.g. -I dir1:dir2 + -i, --ignore-case Ignore case. Makes variable and function names insensitive + -I, --include-path INCLUDE_PATH + Add colon separated list of directories to add to include path. e.g. -I dir1:dir2 --strict Enables strict mode. Force explicit type declaration + --headerless Header-less mode: omit asm prologue and epilogue --version show program's version number and exit + --append-binary APPEND_BINARY + Appends binary to tape file (only works with -t or -T) + --append-headless-binary APPEND_HEADLESS_BINARY + Appends binary to tape file (only works with -t or -T) + -N, --zxnext Enables ZX Next asm extended opcodes + --arch ARCH Target architecture (defaults is'zx48k'). Available architectures: zx48k,zxnext + --expect-warnings EXPECT_WARNINGS + Expects N warnings: first N warnings will be silenced + -W, --disable-warning DISABLE_WARNING + Disables warning WXXX (i.e. -W100 disables warning with code W100) + +W, --enable-warning ENABLE_WARNING + Enables warning WXXX (i.e. -W100 disables warning with code W100) + --hide-warning-codes Hides WXXX codes + -F, --config-file CONFIG_FILE + Loads config from config file + --save-config SAVE_CONFIG + Save options into a config file + --opt-strategy {size,speed,auto} + Optimization strategy (optimize for speed or size). Default: auto ``` Some options (-h, --version) are quite obvious. Let's focus on the rest: @@ -193,10 +211,11 @@ _Out of Memory_ errors. Setting this flag will raise ROM error Subscript out of Range. This flag will add a little overhead to your program execution, but it's useful to detect Out of Range errors. -* **--strict-bool** +* **--strict-bool** DEPRECATED
By default, ZX BASIC will treat boolean values as 0 = False, Any other value = True. Some programmers expect TRUE = 1 always. Using this option will enforce boolean results to be always 0 or 1. Using this option might add a little overhead to your program. Using `--sinclair` option will also enable this feature. +This option is currently deprecated, and will be removed in a future release. * **--enable-break**
Unlike Sinclair BASIC, Your program, being converted to machine code, won't be affected by BREAK.