Docs

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.

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.

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)

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)**

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)

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 <csrlin.bas>
 ```

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 <hex.bas>
+```
+
+## 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
+

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 <input42.bas>
+```
+
+## 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)

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. <u>Don't expect _True_ value number to be always **1**</u>.
-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:

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)

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

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
 <br /> 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**
 <br /> Unlike Sinclair BASIC, Your program, being converted to machine code, won't be affected by BREAK.