From 3a7a7091c065df764942d07ef7b7330eab47e9b2 Mon Sep 17 00:00:00 2001 From: Irmen de Jong Date: Sat, 23 Nov 2024 16:26:17 +0100 Subject: [PATCH] update some docs --- README.md | 5 +++-- docs/source/index.rst | 5 +++-- docs/source/libraries.rst | 3 ++- docs/source/programming.rst | 4 ++++ docs/source/syntaxreference.rst | 2 ++ docs/source/todo.rst | 13 +++++++++++ examples/test.p8 | 4 +--- syntax-files/Vim/prog8_builtins.vim | 34 +++++++++++++++++++---------- 8 files changed, 51 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index a124b0b44..2632f5eb1 100644 --- a/README.md +++ b/README.md @@ -84,11 +84,12 @@ What does Prog8 provide? *Multiple supported compiler targets* (contributions to improve these or to add support for other machines are welcome!): +- "cx16": [CommanderX16](https://www.commanderx16.com) (65c02 CPU) - "c64": Commodore-64 (6502 like CPU) - "c128": Commodore-128 (6502 like CPU - the Z80 cpu mode is not supported) -- "cx16": [CommanderX16](https://www.commanderx16.com) (65c02 CPU) -- "pet32": Commodore PET (experimental) +- "pet32": Commodore PET (limited support) - "atari": Atari 8 bit such as 800XL (experimental) +- "neo": Neo6502 (experimental) - If you only use standard kernal and prog8 library routines, it is possible to compile the *exact same program* for different machines (just change the compiler target flag) diff --git a/docs/source/index.rst b/docs/source/index.rst index e44ab490c..eff8dc433 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -22,11 +22,12 @@ such as the `Commodore 64 `_. You can compile programs for various machines: -* Commander X16 (with 65c02 cpu, 65816 cpu specifics are currently not supported) +* Commander X16 (with 65c02 cpu, 65816 cpu specifics are currently not supported by prog8 itself) * Commodore 64 * Commodore 128 (limited support) * Commodore PET (limited support) -* Atari 800 XL (limited support) +* Atari 800 XL (very limited support) +* Neo6502 (very imited support) Some language features are mentioned below, and you can also read :ref:`comparingprog8` if you want to quickly read about how Prog8 compares to well-known other languages. diff --git a/docs/source/libraries.rst b/docs/source/libraries.rst index 02bfa74dc..9f199dc9d 100644 --- a/docs/source/libraries.rst +++ b/docs/source/libraries.rst @@ -103,8 +103,9 @@ msb (x) bnk (x) Get the 'bank' byte from the value x. This means bits 16-24 of that value: bnk($1234567) = $12. + (To get the 16 bit address out of a value simply use ``x & $ffff``) If x is a word or smaller, bnk(x) will always be zero. - You can consider this equivalent to the expression ``lsb(x >> 16)``. + You can consider this function equivalent to the expression ``lsb(x >> 16)``. mkword (msb, lsb) Efficiently create a word value from two bytes (the msb and the lsb). Avoids multiplication and shifting. diff --git a/docs/source/programming.rst b/docs/source/programming.rst index 9cd95c7c5..37b144b89 100644 --- a/docs/source/programming.rst +++ b/docs/source/programming.rst @@ -276,6 +276,10 @@ Unsigned integers are in the range 0-255 for unsigned byte types, and 0-65535 fo The signed integers integers are in the range -128..127 for bytes, and -32768..32767 for words. +Only for ``const`` numbers, you can use larger values (32 bits signed integers). The compiler can handle those +internally in expressions. As soon as you have to actually store it into a variable, +you have to make sure the resulting value fits into the byte or word size of the variable. + .. attention:: Doing math on signed integers can result in code that is a lot larger and slower than when using unsigned integers. Make sure you really need the signed numbers, otherwise diff --git a/docs/source/syntaxreference.rst b/docs/source/syntaxreference.rst index dc5616f2b..f531407a6 100644 --- a/docs/source/syntaxreference.rst +++ b/docs/source/syntaxreference.rst @@ -427,6 +427,8 @@ type identifier type storage size example var declara ``bool`` boolean 1 byte = 8 bits ``bool myvar = true`` or ``bool myvar == false`` ``word`` signed word 2 bytes = 16 bits ``word myvar = -12345`` ``uword`` unsigned word 2 bytes = 16 bits ``uword myvar = $8fee`` +``long`` signed 32 bits integer n/a ``const long LARGE = $12345678`` + (only for consts) ``float`` floating-point 5 bytes = 40 bits ``float myvar = 1.2345`` stored in 5-byte cbm MFLPT format ``byte[x]`` signed byte array x bytes ``byte[4] myvar`` diff --git a/docs/source/todo.rst b/docs/source/todo.rst index 4c05cbbfd..e76e4951a 100644 --- a/docs/source/todo.rst +++ b/docs/source/todo.rst @@ -1,12 +1,25 @@ TODO ==== + +fix weird error messages for long vars long @shared foo2 = 123456 + +what to do with bnk(): it's an awkward name but bank() is too general a name and will forbid you to use 'bank' as a variable... +add a function like addr() or lsw() to complement bnk() in getting easy access to the lower 16 bits of a long integer? + +convert examples/cx16/vtui/testvtui.p8 and zsmkit to new extsub addr capability + + + + ... Future Things and Ideas ^^^^^^^^^^^^^^^^^^^^^^^ +- a way to specify subroutine params for normal (non-asmsub) subs to be in r0-r15 registers instead of allocating a new localvariable for them +- the previous should give another footgun warning (the @dirty info should be a footgun warning/info as well). Need a switch to turn off footgun warnings. - something to reduce the need to use fully qualified names all the time. 'with' ? Or 'using '? - on the C64: make the floating point routines @banked so that basic can be permanently banked out even if you use floats? But this will crash when the call is done from program code at $a000+ - Libraries: improve ability to create library files in prog8; for instance there's still stuff injected into the start of the start() routine AND there is separate setup logic going on before calling it. diff --git a/examples/test.p8 b/examples/test.p8 index 26f02a64e..0a67138b7 100644 --- a/examples/test.p8 +++ b/examples/test.p8 @@ -1,8 +1,6 @@ -%import floats - -%import strings main { sub start() { + long @shared foo2 = 123456 } } diff --git a/syntax-files/Vim/prog8_builtins.vim b/syntax-files/Vim/prog8_builtins.vim index 6e5d8a5ff..4dc9cd146 100644 --- a/syntax-files/Vim/prog8_builtins.vim +++ b/syntax-files/Vim/prog8_builtins.vim @@ -766,17 +766,29 @@ syn match prog8BuiltInFunc "\" " prog8_lib.p8 -" string.p8 -syn match prog8BuiltInFunc "\" -syn match prog8BuiltInFunc "\" -syn match prog8BuiltInFunc "\" -syn match prog8BuiltInFunc "\" -syn match prog8BuiltInFunc "\" -syn match prog8BuiltInFunc "\" -syn match prog8BuiltInFunc "\" -syn match prog8BuiltInFunc "\" -syn match prog8BuiltInFunc "\" -syn match prog8BuiltInFunc "\" +" strings.p8 +syn match prog8BuiltInFunc "\" +syn match prog8BuiltInFunc "\" +syn match prog8BuiltInFunc "\" +syn match prog8BuiltInFunc "\" +syn match prog8BuiltInFunc "\" +syn match prog8BuiltInFunc "\" +syn match prog8BuiltInFunc "\" +syn match prog8BuiltInFunc "\" +syn match prog8BuiltInFunc "\" +syn match prog8BuiltInFunc "\" +syn match prog8BuiltInFunc "\" +syn match prog8BuiltInFunc "\" +syn match prog8BuiltInFunc "\" +syn match prog8BuiltInFunc "\" +syn match prog8BuiltInFunc "\" +syn match prog8BuiltInFunc "\" +syn match prog8BuiltInFunc "\" +syn match prog8BuiltInFunc "\" +syn match prog8BuiltInFunc "\" +syn match prog8BuiltInFunc "\" +syn match prog8BuiltInFunc "\" +syn match prog8BuiltInFunc "\" " test_stack.p8