From 4544af441bf232d66ce14f112c0b1b5f010f7f76 Mon Sep 17 00:00:00 2001 From: Irmen de Jong Date: Sun, 17 Dec 2023 01:49:29 +0100 Subject: [PATCH] doc tweaks, explain str a bit more --- docs/source/programming.rst | 9 +++++++-- docs/source/technical.rst | 9 ++++----- docs/source/todo.rst | 13 +++---------- 3 files changed, 14 insertions(+), 17 deletions(-) diff --git a/docs/source/programming.rst b/docs/source/programming.rst index 8c4519877..08377c08f 100644 --- a/docs/source/programming.rst +++ b/docs/source/programming.rst @@ -289,7 +289,7 @@ Here are some examples of arrays:: byte[] array = [1, 2, 3, 4] ; initialize the array, size taken from value ubyte[99] array = 255 ; initialize array with 99 times 255 [255, 255, 255, 255, ...] byte[] array = 100 to 199 ; initialize array with [100, 101, ..., 198, 199] - str[] names = ["ally", "pete"] ; array of string pointers/addresses (equivalent to uword) + str[] names = ["ally", "pete"] ; array of string pointers/addresses (equivalent to array of uwords) uword[] others = [names, array] ; array of pointers/addresses to other arrays value = array[3] ; the fourth value in the array (index is 0-based) @@ -349,7 +349,7 @@ Note that the maximum length of a split word array is 256! (regular word arrays Strings ^^^^^^^ -Strings are a sequence of characters enclosed in ``"`` quotes. The length is limited to 255 characters. +Strings are a sequence of characters enclosed in double quotes. The length is limited to 255 characters. They're stored and treated much the same as a byte array, but they have some special properties because they are considered to be *text*. Strings (without encoding prefix) will be encoded (translated from ASCII/UTF-8) into bytes via the @@ -407,6 +407,11 @@ for a character in such strings (one that stops at the first 0 byte) For regular assignments you still need to use an explicit ``&`` (address-of) to take the address of the string or array. +.. hint:: + You can declare parameters and return values of subroutines as ``str``, + but in this case that is equivalent to declaring them as ``uword`` (because + in this case, the address of the string is passed as argument or returned as value). + .. note:: Strings and their (im)mutability *String literals outside of a string variable's initialization value*, diff --git a/docs/source/technical.rst b/docs/source/technical.rst index 60fc7ea8e..6ddaad112 100644 --- a/docs/source/technical.rst +++ b/docs/source/technical.rst @@ -52,14 +52,13 @@ Subroutine Calling Convention Calling a subroutine requires three steps: -#. preparing the arguments (if any) and passing them to the routine -#. calling the routine +#. preparing the arguments (if any) and passing them to the routine. + Numeric types are passed by value (bytes, words, booleans, floats), + but array types and strings are passed by reference which means as ``uword`` being a pointer to their address in memory. +#. calling the subroutine #. preparing the return value (if any) and returning that from the call. -Calling the routine is just a simple JSR instruction, but the other two work like this: - - ``asmsub`` routines ^^^^^^^^^^^^^^^^^^^ diff --git a/docs/source/todo.rst b/docs/source/todo.rst index 77f6eeffb..9c6dce83a 100644 --- a/docs/source/todo.rst +++ b/docs/source/todo.rst @@ -2,10 +2,6 @@ TODO ==== -- merge branch optimize-st for some optimizations regarding SymbolTable use - -- fix that pesky unit test that puts temp files in the compiler directory - - [on branch: call-pointers] allow calling a subroutine via a pointer variable (indirect JSR, optimized form of callfar()) modify programs (shell, paint) that now use callfar @@ -18,7 +14,7 @@ Future Things and Ideas ^^^^^^^^^^^^^^^^^^^^^^^ Compiler: -- What happens when subs return a boolean not in A, but in Carry flag? +- (after shortcircuit is in:) What happens when we make all subs return a boolean not as ubyte in A, but in the cpu's Carry flag? - What happens when we keep the BOOL type around until in codegen? (so, get rid of Boolean->ubyte and boolean remover) - Multidimensional arrays and chained indexing, purely as syntactic sugar over regular arrays. - make a form of "manual generics" possible like: varsub routine(T arg)->T where T is expanded to a specific type @@ -34,11 +30,6 @@ Compiler: - OR.... make all this more generic and use some %segment option to create real segments for 64tass? - (need separate step in codegen and IR to write the "golden" variables) -- [on branch: no-vardecls] - remove astNode from StNode in the symboltable - remove IPtVariable and the 3 derived types (var, constant, memmapped) in the codegen ast - remove VarDecls in compiler ast - - do we need (array)variable alignment tag instead of block alignment tag? You want to align the data, not the code in the block? - ir: getting it in shape for code generation - ir: related to the one above: block alignment doesn't translate well to variables in the block (the actual stuff that needs to be aligned in memory) but: need variable alignment tag instead of block alignment tag, really @@ -92,5 +83,7 @@ What if we were to re-introduce Structs in prog8? Some thoughts: Other language/syntax features to think about --------------------------------------------- +- add (rom/ram)bank support to romsub. A call will then automatically switch banks, use callfar and something else when in banked ram. + challenges: how to not make this too X16 specific? How does the compiler know what bank to switch (ram/rom)? - chained comparisons `10 x==true) - negative array index to refer to an element from the end of the array. Python `[-1]` or Raku syntax `[\*-1]` , `[\*/2]` .... \*=size of the array