Update docs and changelog for 1.3 beta

Co-Authored-By: RoccoLox Programs <roccoloxprograms2018@gmail.com>

Author: TIny-Hacker

CHANGELOG.md

@@ -2,6 +2,62 @@
 
 All notable changes to the Celtic CE library will be documented in this file.
 
+## [1.3.0-beta] - 2023-06-01
+
+### Added
+
+- Graphics Functions:
+    - GetStringWidth
+    - TransSprite
+    - ScaleSprite
+    - ScaleTSprite
+    - ScrollScreen
+    - RGBto565
+    - DrawRect
+    - DrawCircle
+    - FillCircle
+    - DrawArc
+    - DispTransText
+    - ChkRect
+- OS Utility Functions:
+    - SearchFile
+    - CheckGC 
+- Celtic III Functions:
+    - ErrorHandle
+    - StringRead
+    - HexToDec 
+    - DecToHex
+    - EditWord
+    - BitOperate
+    - GetProgList
+
+### Changed
+
+- Doors CE 9 Functions:
+    - DispText command uses a 16-bit number to count the number of characters being displayed on the screen instead of an 8-bit one
+    - TextRect command renamed to FillRect and no longer uses the TI-OS routine
+- Graphics Functions:
+    - DrawLine command no longer uses the TI-OS routine
+    - Greatly optimized SetPixel command
+    - PixelTestColor now returns in Ans
+    - PutSprite can now read sprite data from a user-specified string variable
+- Celtic III Functions:
+    - FindProg command now returns a memory error if there isn't enough RAM to store the return string
+- Split up files
+- Better formatting consistency in CHANGELOG.md
+- Allocated an extra 3 bytes for a 9th argument to be passed in Celtic instructions
+- Celtic now uses its own ConvOP1 routine (borrowed from Doors CS 7 and modified for eZ80) rather than the TI-OS one
+- Some arbitrary numbers in the source code were changed to equates for better readability
+- X and Y coordinates on the screen are now calculated in VRAM using a routine provided by [calc84maniac](https://github.com/calc84maniac)
+- Status bar command preview in the TI-OS BASIC editor now says "NA" instead of "None" when there are no input arguments for a command
+- Several minor optimizations
+
+### Fixed
+- Installer will automatically delete itself even if the program has been renamed
+- Celtic will pop all remaining arguments off the FPS if it encounters an invalid argument
+- Celtic correctly detects if not enough arguments have been passed for certain commands
+- Longer variable names and groups are now properly detected
+
 ## [1.2.0-beta] - 2023-02-22
 
 ### Added
@@ -21,15 +77,15 @@ All notable changes to the Celtic CE library will be documented in this file.
 
 ### Changed
 
-- OS Utility Functions
+- OS Utility Functions:
     - PrgmToStr now returns an error if the specified file contains no data
 - Jump table is now an LUT. Jumping code has also been reworked
 - Optimized app UI code
 - Zero out help hook pointer to be safe
 
 ### Fixed
 
-- Fixed HidePrgm function to work with archived programs
+- Fixed HidePrgm command to work with archived programs
 
 ## [1.1.0-beta] - 2022-11-29
 
@@ -61,12 +117,12 @@ All notable changes to the Celtic CE library will be documented in this file.
 ### Changed
 
 - Temp storage now uses pixelShadow2 with an offset of 100 bytes instead of using pixelShadow
-- ExecHex function no longer has a restriction of 255 characters, instead it is limited to 8192
+- ExecHex command no longer has a restriction of 255 characters, instead it is limited to 8192
 - Preserve stack pointer when running a command and restore it when exiting to the OS
 
 ### Fixed
 
-- Potential error with VarStatus function when a hidden program name starts with a 'T'
+- Potential error with VarStatus command when a hidden program name starts with a 'T'
 
 ## [1.0.0-beta] - 2022-09-17
 

CelticCE.pdf

@@ -281,3 +281,149 @@ Documentation
 
     Errors:
      * ``..E:NT:FN`` if the target byte does not exist in the string.
+
+------------
+
+.. function:: ErrorHandle: det(45); Ans = program to run
+
+    Executes BASIC code with an error handler installed. That means the code you execute can do anything it wants including divide by zero, and it will simply end the execution but an obvious system error will not trigger. Instead, this command will return with a value that indicates the error condition. This command has two different modes. If ``Ans`` contains a program name (beginning with the ``prgm`` token), it will run that program. If ``Ans`` contains program code, it will execute that code instead. This will also work with programs beginning with the ``Asm84CEPrgm`` token.
+
+    A list of return values and their corresponding errors can be found in the `error codes <errorcodes.html#ti-os-errors>`__ section, under TI-OS Errors.
+
+    .. note:: When using ErrorHandle from the homescreen, it will not run BASIC programs, though it can still run programs beginning with the Asm84CEPrgm token.
+
+    Parameters:
+     * ``Ans``: The name of the program to run, or TI-BASIC code to be executed
+
+    Returns:
+     * ``Theta``: Contains the error code returned by the program, or 0 if no error occured.
+
+    Errors:
+     * ``..NULLVAR`` if the program is empty.
+     * ``..SUPPORT`` if the file is not a TI-BASIC program.
+
+------------
+
+.. function:: StringRead: det(46, string, start, bytes);
+
+    Works almost identically to BASIC's sub() command, except that the output will be in hexadecimal and two-byte tokens will read as two instead of one byte. It is particularly useful for extracting data from a string that may contain nonsensical data that simply needs to be manipulated. If you allow the start point to be zero, the size of the string in bytes is returned instead. For data manipulation, you should use the Edit1Byte command.
+
+    Parameters:
+     * ``string``: Which string variable to read from, where 0 = Str0, 9 = Str9, and so on
+     * ``start``: The byte of the string to begin reading at
+     * ``bytes``: How many bytes to read
+
+    Returns:
+     * ``Str9``: The extracted substring.
+     * ``Theta``: The size of the string in bytes, if ``start`` was 0.
+
+------------
+
+.. function:: HexToDec: det(47); Ans = hex
+
+    Converts up to 4 hex digits back to decimal. If you pass a string longer than 4 digits, only the first four are read.
+
+    Parameters:
+     * ``Ans``: Hex string to convert
+
+    Returns:
+     * ``Theta``: Decimal integer converted from hex string.
+
+    Errors:
+     * ``..INVAL:S`` if an invalid hex digit is passed.
+
+------------
+
+.. function:: DecToHex: det(48, number, override)
+
+    Converts a number between 0 and 65535 to its hexadecimal equivalent. The number of hexadecimal output to the string will have its leading zeroes stripped so inputting 15 will result in “F” and 16 will result in “10”. If override is 1, it will output all leading zeroes, which may be useful for routines that require four hex digits at all times but cannot spend the memory/time whipping up a BASIC solution to fill the missing zeroes.
+
+    Parameters:
+     * ``number``: Decimal integer to convert
+     * ``override``: 1 to output all leading zeroes, or 0 to not
+
+    Returns:
+     * ``Str9``: Hex string converted from decimal integer.
+
+------------
+
+.. function:: EditWord: det(49, string, start, word)
+
+    This command, otherwise, works just like Edit1Byte. Its documentation is rewritten here for convenience. Replaces a word in some string variable, Str0 to Str9, with a replacement value 0 through 65535 starting at some specified byte (start is at 0). The string supplied is edited directly so there's no output. See Edit1Byte for more details.
+
+    The replacement is written in little-endian form and if the number is between 0 and 255, the second byte is written in as a zero.
+
+    .. note:: Note: A “word” in this sense is two bytes. Useful for editing a binary string which entries are all two bytes in length, such as a special string tilemap. You’re required, however, to specify offset in bytes. Also know that all words are stored little-endian. That means that the least significant byte is stored before the most significant byte is.
+
+    Parameters:
+     * ``string``: Which string variable to read from, where 0 = Str0, 9 = Str9, and so on
+     * ``start``: The byte to start editing in the string
+     * ``word``: The two bytes to rewrite
+
+    Returns:
+     * Modifies the string with the specified word
+
+    Errors:
+     * ``..E:NT:FN`` If the offset is past the end of the string
+
+------------
+
+.. function:: BitOperate: det(50, value1, value2, function)
+
+    Performs a bitwise operation between value1 and value2 using a supplied function value. It will only work with up to 16-bit numbers.
+
+    The different functions are below:
+
+    ===== ===========
+    Value Operation
+    ===== ===========
+    0     NONE
+    1     AND
+    2     OR
+    3     XOR
+    4     Left Shift
+    5     Right Shift
+    ===== ===========
+
+    If the numbers are out of bounds, then the function will exit out with an error. This command really helps mask out hex digits but if you use strings to store those digits, you'll need to use the HexToDec command for each value you need.
+
+    Parameters:
+     * ``value1``: First value to perform bit operation with
+     * ``value2``: Second value to perform bit operation with
+     * ``function``: Which operation to perform, as seen in the table above
+
+    Returns:
+     * ``Theta``: Result of the bit operation.
+
+------------
+
+.. function:: GetProgList: det(51, type); Ans = search string
+
+    This function will return a space-delimited string consisting of the names of programs, appvars, or groups that match partial name of the search string. Which is to say::
+
+        "TEMP
+        det(51, 0) 
+
+    would return all program names that start with the characters “TEMP”, which may be something like “TEMP001 " or “TEMP001 TEMP002 TEMP003 “, etc.
+
+    ===== =========
+    Value File Type
+    ===== =========
+    0     Programs
+    1     AppVars
+    2     Groups
+    ===== =========
+
+    .. note:: 
+        This command is NOT to be confused with FindProg, which outputs a string consisting of files whose CONTENTS starts with the specified string. Also use the fact that the final name in the list is terminated with a space to make extracting names from the list easier. It also will not find hidden variables.
+
+    Parameters:
+     * ``type``: The type of file to search for, as seen above
+     * ``Ans``: String to find in file names
+
+    Returns:
+     * ``Str9``: Filtered list of files
+
+    Errors:
+     * ``..S:NT:FN`` if ``Ans`` is not a string
+     * ``..P:NT:FN`` if no files were found containing the search string

docs/celticiiifunctions.rst

@@ -24,9 +24,9 @@
 author = 'RoccoLox Programs, TIny_Hacker'
 
 # The short X.Y version
-version = 'b1.2'
+version = 'b1.3'
 # The full version, including alpha/beta/rc tags
-release = 'Beta 1.2'
+release = 'Beta 1.3'
 
 
 # -- General configuration ---------------------------------------------------

docs/conf.py

@@ -10,7 +10,7 @@ Documentation
 
 .. function:: ReadLine: det(0); Str0 = variable name; Ans = line number
 
-    Reads a line from a program or AppVar. If ``Ans`` (line number) equals 0, then Theta will be overwritten with the number of lines in the program being read. Otherwise, ``Ans`` refers to the line being read.
+    Reads a line from a program or AppVar. If ``Ans`` (line number) equals 0, then Theta will be overwritten with the number of lines in the program being read, though it will still return the ``..NUMSTNG`` error, like the original Celtic 2 CSE. Otherwise, ``Ans`` refers to the line being read.
 
     .. warning::
         If you attempt to read the line of an assembly program, there is a risk of a reset. If Celtic passes an invalid token to ``Str9``, it could cause a RAM clear.

docs/csefunctions.rst

@@ -13,9 +13,6 @@ Documentation
 
     Displays colored text from ``Str9`` at ``x`` and ``y`` on the screen, using the OS large or small font.
 
-    .. warning::
-        you can only use a maximum of 128 characters in ``Str9`` at a time with this command. However, this should be plenty, since the text does not wrap.
-
     Parameters:
      * ``large_font`` = whether to use OS large or small font. 0 means to use the OS small font, and 1 means to use the large font.
      * ``fg_low``: low byte of foreground color.
@@ -56,7 +53,7 @@ Documentation
 
 ------------
 
-.. function:: TextRect: det(15, low, high, x, y, width, height)
+.. function:: FillRect: det(15, low, high, x, y, width, height)
 
     Draw a filled, colored rectangle on the screen. This command can also be used to draw an individual pixel by setting the width and height to 1, or a line by setting either the width or height to 1.
 

docs/dcefunctions.rst

@@ -6,8 +6,9 @@ Overview
 
 Celtic does its best to prevent errors. However, if something goes wrong with running a function, Celtic will return an error code. This can be from lack of memory, an incorrect argument, or something else.
 Keep in mind that Celtic might not always detect the exact error, or realize that there is one in the first place. You can use the error codes to help with the debugging process.
+This page also contains TI-OS errors and the corresponding values returned in the ErrorHandle command.
 
-Documentation
+Celtic Errors
 ~~~~~~~~~~~~~
 
 ========== ================================================================================================
@@ -34,3 +35,63 @@ Error Code Description
 ..NT:A:GP  The file specified was not a group.
 ..SUPPORT  Whatever happened was not supported by Celtic.
 ========== ================================================================================================
+
+TI-OS Errors
+~~~~~~~~~~~~
+
+===== ===========
+Value Error
+===== ===========
+0     No Error
+1     Overflow
+2     DivBy0
+3     SingularMat
+4     Domain
+5     Increment
+6     Break
+7     NonReal
+8     Syntax
+9     DataType
+10    Argument
+11    DimMismatch
+12    Dimension
+13    Undefined
+14    Memory
+15    Invalid
+16    IllegalNest
+17    Bound
+18    GraphRange
+19    Zoom
+20    Label
+21    Stat
+22    Solver
+23    Singularity
+24    SignChange
+25    Iterations
+26    BadGuess
+27    StatPlot
+28    TolTooSmall
+29    Reserved
+30    Mode
+31    LnkErr
+32    LnkMemErr
+33    LnkTransErr
+34    LnkDupErr
+35    LnkMemFull
+36    Unknown
+37    Scale
+38    IdNotFound
+39    NoMode
+40    Validation
+41    Length
+42    Application
+43    AppErr1
+44    AppErr2
+45    ExpiredApp
+46    BadAddr
+47    Archived
+48    Version
+49    ArchFull
+50    Variable
+51    Duplicate
+===== ===========

docs/errorcodes.rst

@@ -15,7 +15,7 @@ If you have entered a valid argument, Celtic will tell you what function the arg
 
     Celtic's function preview feature.
 
-The function preview follows a general syntax: "``CommandName(Arguments)``: ``Input Vars`` (if any): ``Output Vars`` (if any)". As you can see in the example above, ReadLine is listed with no arguments, ``Str0`` and ``Ans`` as the input variables, and ``Str9`` or ``theta`` as the output variables. 
+The function preview follows a general syntax: "``CommandName(Arguments)``: ``Input Vars`` (if any): ``Output Vars`` (if any)". As you can see in the example above, ReadLine is listed with no arguments, ``Str0`` and ``Ans`` as the input variables, and ``Str9`` or ``theta`` as the output variables. If no input variables are necessary (though there are still output variables), it will say "NA" instead. Nothing will be listed of there are no input and output variables.
 
 .. note::
     In the event that you pass invalid arguments to Celtic, it will return an error. All errors are returned in ``Str9``. See the `Error Codes <errorcodes.html>`__ page for more information.
@@ -53,6 +53,8 @@ When using ``Str0`` as a program name, simply store the name of the program into
 
 If a string is used, it must be in the RAM when the function is called.
 
+.. warning:: In almost all cases, Celtic will detect if you passed invalid arguments and return an error instead. However, in the (extremely) rare case that you tried to pass a string with the length of 0, it will not handle this. Don't worry, there shouldn't be any reason this would happen without you trying to make it happen.
+
 Returns
 ~~~~~~~
 Depending on the function, Celtic will return a value after it runs. For example, the ``SpecialChars`` function fills ``Str9`` with certain special characters.