Add everything for release 1.0

A
RoccoLoxPrograms · Jul 31, 2023 · 2cb2e3c · 2cb2e3c
1 parent bcda5bf
commit 2cb2e3c
Show file tree

Hide file tree

Showing 32 changed files with 432 additions and 357 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,4 +1,5 @@
 .vscode
+release
 build
 _build
 *.8xp
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,26 @@
 
 All notable changes to the Celtic CE library will be documented in this file.
 
+## [1.0.0] - 2023-07-31
+
+### Added
+- OS Utility Functions:
+    - SetParseByte
+- Custom app icon to be viewed in shells
+### Changed
+- Graphics Functions:
+    - DrawCircle will now draw a circle with a radius of zero
+    - FillCircle will now draw a circle with a radius of zero
+- OS Utility Functions:
+    - PrgmCleanUp command renamed to ResetScreen
+- <kbd>2nd</kbd> + <kbd>enter</kbd> hook now also displays the byte offset that you're currently at in the program while editing it
+
+### Fixed
+
+- OS Utility Functions:
+    - BackupString will no longer backup strings with no data in them
+- Celtic now handles invalid arguments correctly
+
 ## [1.0.0-rc.1] - 2023-07-24
 
 ### Added

diff --git a/COMMANDS.md b/COMMANDS.md
@@ -73,8 +73,9 @@ This file contains a simplified list of all commands in CelticCE, sorted by cate
 - BackupReal (77)
 - RestoreReal (78)
 - SetParseLine (79)
-- SwapFileType (80)
-- PrgmCleanUp (81)
+- SetParseByte (80)
+- SwapFileType (81)
+- ResetScreen (82)
 
 ### [Celtic III](https://roccoloxprograms.github.io/CelticCE/celticiiifunctions.html)
 

diff --git a/README.md b/README.md
@@ -13,7 +13,7 @@ If you'd like a more detailed and complete documentation, you can view the onlin
 1. Download the latest release of CelticCE [here](https://github.com/roccoloxprograms/celticce/releases/latest). To avoid confusion, this is the file with the `.8xp` file extension.
 2. Transfer the CelticCE installer that you just downloaded to your calculator using a linking program of your choice, such as [TI-Connect CE](https://education.ti.com/en/software/details/en/CA9C74CAD02440A69FDC7189D7E1B6C2/swticonnectcesoftware) or [TiLP](http://lpg.ticalc.org/prj_tilp/).
 3. Run the **CELTICCE** program on your calculator, which can be found under the <kbd>prgm</kbd> menu. If you are on an OS version 5.5 or greater, you will need to use the [arTIfiCE jailbreak](https://yvantt.github.io/arTIfiCE/).
-4. Finish running the installer by selecting whether or not to delete the installer program. It will not be needed unless you for some reason wish to reinstall CelticCE, so it is safe to delete.
+4. Finish running the installer by selecting whether or not to delete the installer program. It will not be needed unless you for some reason wish to reinstall the CelticCE app, so it is safe to delete.
 5. Find **CelticCE** in the <kbd>apps</kbd> menu and open it.
 6. Press <kbd>1</kbd> to install CelticCE, then press <kbd>3</kbd> to exit the app.
 
@@ -23,11 +23,11 @@ CelticCE commands are called in TI-BASIC programs using the `det(` token followe
 
 Along with the CelticCE app installer, you'll notice that there is another program, **AINSTALL**, which comes with Celtic. If you choose to send this to your calculator, running it will install Celtic's hooks outside of the app, as long as the app is present on your calculator. This can be useful if you want to install CelticCE when during the execution of another program. You can learn more about this in the [General Syntax](https://roccoloxprograms.github.io/CelticCE/gensyntax.html) section of CelticCE's documentation.
 
-CelticCE also has a few useful features which are added to the TI-OS editor when it is installed. The first of these is a command preview, which will diplay the basic syntax of a command on the status bar if the cursor is hovering over a valid Celtic command as seen below:
+CelticCE also has a few useful features which are added to the TI-OS editor when it is installed. The first of these is a command preview, which will display the basic syntax of a command on the status bar if the cursor is hovering over a valid Celtic command as seen below:
 
 ![Command Preview](docs/images/functionPreview.png)
 
-If you press <kbd>2nd</kbd> + <kbd>enter</kbd> in the OS editor when Celtic is installed, it will also display the current line number and program size like so:
+If you press <kbd>2nd</kbd> + <kbd>enter</kbd> in the OS editor when Celtic is installed, it will also display the current line number, byte offset, and program size like so:
 
 ![Status Bar Info](docs/images/statusBarInfo.png)
 

diff --git a/docs/celticiiifunctions.rst b/docs/celticiiifunctions.rst
@@ -3,7 +3,7 @@ Celtic III Functions
 
 Overview
 ~~~~~~~~
-Some (not all) of the functions from Celtic III are included in Celtic CE.
+Essentially all of the functions from Celtic III are included in Celtic CE.
 
 Documentation
 ~~~~~~~~~~~~~
@@ -14,7 +14,7 @@ Documentation
 
     Parameters:
      * ``list_element``: Element of the list to access, beginning at 1. Accessing 0 will return the dimension of the list.
-     * ``Ans``: Name of the list to access. Begins with the :sub:`L`\  token found in the :menuselection:`List --> OPS`. (:kbd:`2nd` + :kbd:`stat` + :kbd:`left arrow` + :kbd:`alpha` + :kbd:`apps`).
+     * ``Ans``: Name of the list to access. The data in ``Ans`` must be a string beginning with the :sub:`L`\  token found in the :menuselection:`List --> OPS` (:kbd:`2nd` + :kbd:`stat` + :kbd:`left arrow` + :kbd:`alpha` + :kbd:`apps`), unless you are using a default OS list such as L :sub:`1`\. When using default OS lists, simply use the corresponding list name token, such as L :sub:`1`\ or L :sub:`2`\.
 
     Returns:
      * ``Theta``: The number at the element of the list accessed, or the dimension of the list if ``list_element`` was 0.
@@ -30,26 +30,26 @@ Documentation
     Outputs a real number depicting the type of argument in ``Ans``.
 
     Parameters:
-     * ``Ans``: Argument to check the type of
+     * ``Ans``: Argument to check the type of.
 
     Returns:
      * ``Theta``: The number corresponding to the argument's type. A table with the possible types is below.
 
-    ====== ========
+    ====== =========
     Number Type
     0      Real
     1      List
     2      Matrix
     4      String
     12     Complex
-    13     Cpx List
-    ====== ========
+    13     Cplx List
+    ====== =========
 
 ------------
 
 .. function:: ChkStats: det(32, function)
 
-    This is a multi-purpose command used to read various system statuses. The output will very based on the specified function. A table with the possible functions and their resulting outputs is below.
+    This is a multi-purpose command used to read various system statuses. The output will vary based on the specified function. A table with the possible functions and their resulting outputs is below.
 
     ======== ==============================================================================
     Function Output
@@ -61,10 +61,10 @@ Documentation
     ======== ==============================================================================
 
     Parameters:
-     * ``function``: Function to complete
+     * ``function``: Function to complete.
 
     Returns:
-     * Varies based on input
+     * Varies based on input.
 
 ------------
 
@@ -205,7 +205,7 @@ Documentation
 
 .. function:: BinDelete: det(40, byte_start, number_of_bytes); Str0 = file name
 
-    Deletes the ``number_of_bytes`` bytes from the file specified by ``Str0``, starting at ``byte_start``. ``byte_start`` is 0-indexed, meaning that the first byte of the program is 0, the second is 1, and so on.
+    Deletes ``number_of_bytes`` bytes from the file specified by ``Str0``, starting at ``byte_start``. ``byte_start`` is 0-indexed, meaning that the first byte of the program is 0, the second is 1, and so on.
 
     Parameters:
      * ``byte_start``: The byte of the file to start deleting from. It is 0-indexed, so the first byte of the file is 0, the second is 1, and so on.
@@ -290,10 +290,12 @@ Documentation
 
     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.
 
+    .. warning:: ErrorHandle cannot be used recursively. This means that if you attempt to run ErrorHandle on a program and then run ErrorHandle again inside that second program, the ErrorHandle command in that second program will be ignored.
+
     .. 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
+     * ``Ans``: The name of the program to run, or TI-BASIC code to be executed.
      * ``get_offset``: If ``get_offset`` is 1, ErrorHandle will return the byte offset the error occured at in ``Ans``. If it is 0, it will not. This only works with running programs, not strings.
 
     Returns:
@@ -311,9 +313,9 @@ Documentation
     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
+     * ``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.
@@ -326,7 +328,7 @@ Documentation
     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
+     * ``Ans``: Hex string to convert.
 
     Returns:
      * ``Theta``: Decimal integer converted from hex string.
@@ -341,8 +343,8 @@ Documentation
     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
+     * ``number``: Decimal integer to convert.
+     * ``override``: 1 to output all leading zeroes, or 0 to not.
 
     Returns:
      * ``Str9``: Hex string converted from decimal integer.
@@ -358,15 +360,15 @@ Documentation
     .. 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
+     * ``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
+     * Modifies the string with the specified word.
 
     Errors:
-     * ``..E:NT:FN`` If the offset is past the end of the string
+     * ``..E:NT:FN`` If the offset is past the end of the string.
 
 ------------
 
@@ -387,12 +389,12 @@ Documentation
     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.
+    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
+     * ``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.
@@ -401,7 +403,7 @@ Documentation
 
 .. 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::
+    This function will return a space-delimited string consisting of the names of programs, appvars, or groups whose names partially match the search string. Which is to say::
 
         "TEMP
         det(51, 0) 
@@ -420,12 +422,12 @@ Documentation
         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
+     * ``type``: The type of file to search for, as seen above.
+     * ``Ans``: String to find in file names.
 
     Returns:
-     * ``Str9``: Filtered list of files
+     * ``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
+     * ``..S:NT:FN`` if ``Ans`` is not a string.
+     * ``..P:NT:FN`` if no files were found containing the search string.
diff --git a/docs/conf.py b/docs/conf.py
@@ -24,9 +24,9 @@
 author = 'RoccoLox Programs, TIny_Hacker'
 
 # The short X.Y version
-version = '1.0-rc.1'
+version = '1.0'
 # The full version, including alpha/beta/rc tags
-release = 'Release Candidate 1.0'
+release = '1.0'
 
 
 # -- General configuration ---------------------------------------------------

diff --git a/docs/convertsprites.rst b/docs/convertsprites.rst
@@ -13,7 +13,7 @@ First you'll need to download the latest version of convimg from the `GitHub rel
 
 .. note::
 
-    If you already have the CE C toolchain installed, chances are that convimg has already been installed and is in your Path. You can check this by opening a terminal and running `convimg --version`.
+    If you already have the CE C toolchain installed, chances are that convimg has already been installed and is in your Path. You can check this by opening a terminal and running :code:`convimg --version`.
 
 On Windows:
     * Extract the zip to a file path without spaces.
@@ -96,6 +96,6 @@ Once you have completed your yaml, navigate to the directory with the sprites an
             image | 256 bytes
             "FFFFFFFF0000000000000000FFFFFFFFFFFFFFFF0000... (Data continues)
 
-You can then use the data in your programs by copying it into the source code or pasting it into a TI-BASIC IDE like SourceCoder.
+You can then use the data in your programs by copying it into the source code or pasting it into a TI-BASIC IDE like `SourceCoder <https://www.cemetech.net/sc/>`__.
 
 For more documentation on convimg, check out the README `here <https://github.com/mateoconlechuga/convimg/blob/master/README.md>`__. For more info on glob patterns, look `here <https://en.wikipedia.org/wiki/Glob_(programming)>`__.
diff --git a/docs/csefunctions.rst b/docs/csefunctions.rst
@@ -86,8 +86,7 @@ Documentation
      * ``HEADER``: whether or not to include a header which allows `CEaShell <https://github.com/roccoloxprograms/shell>`__ to edit the appvar. This extra argument is optional. 1 to include the header, and 0 to not.
 
     Returns:
-     * ``Str9``: Intact if no error occured; otherwise, contains an error code.
-     * ``Str0``: Intact with program's name to be created.
+     * Creates the program or AppVar.
 
     Errors:
      * ``..P:IS:FN`` if the program already exists.
@@ -127,13 +126,13 @@ Documentation
      * ``Ans``: Line number to delete from, begins at 1.
 
     Returns:
-     * ``Str9``: Intact if no error occured; otherwise, contains an error code.
+     * Deletes the specified line from the program or AppVar.
 
 ------------
 
 .. function:: VarStatus: det(8); Str0 = variable name
 
-    Output status string describing a program or AppVar's current state, including size, visibility, and more.
+    Output a status string describing a program or AppVar's current state, including size, visibility, and more.
 
     Parameters:
      * ``Str0``: Name of program or AppVar to examine.
@@ -189,7 +188,7 @@ Documentation
 
 .. function:: ExecArcPrgm: det(11, function, temp_prog_number); Ans = program name
 
-    Copies a program to the ``XTEMP`` program of the specified ``temp_prog_number``. ``Ans`` is the name of the program to copy. ``function`` refers to the behavior of the ``ExecArcPrgm`` command, as seen in the table below:
+    Copies a program to the ``XTEMP`` program of the specified ``temp_prog_number``. ``temp_prog_number`` can only be 0 - 15. ``Ans`` is the name of the program to copy. ``function`` refers to the behavior of the ``ExecArcPrgm`` command, as seen in the table below:
 
     ==== ================================================================
     Code Function
@@ -201,7 +200,7 @@ Documentation
 
     Parameters:
      * ``function``: The requested behavior of the function. Can be 0, 1, or 2.
-     * ``temp_prog_number``: The number of the ``XTEMP`` program to create/delete.
+     * ``temp_prog_number``: The number of the ``XTEMP`` program to create/delete. This must be within 0 - 15.
      * ``Ans``: Name of program to copy from.
 
     Returns:

diff --git a/docs/dcefunctions.rst b/docs/dcefunctions.rst
@@ -55,7 +55,7 @@ Documentation
 
 .. 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.
+    Draws a filled, colored rectangle on the screen.
 
     Parameters:
      * ``low``: low byte of color.