Update documentation

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

Author: TIny-Hacker

docs/celticiiifunctions.rst

@@ -8,7 +8,7 @@ Some (not all) of the functions from Celtic III are included in Celtic CE.
 Documentation
 ~~~~~~~~~~~~~
 
-.. function:: GetListElem: det(30, list_element), Ans = list name
+.. function:: GetListElem: det(30, list_element); Ans = list name
 
     Gets a value at ``list_element`` in the list specified. For example, with ``Ans`` equal to ":sub:`L`\FOO" (Where :sub:`L`\  is the list token found in :menuselection:`List --> OPS`). This is useful if the list being accessed is archived, for example.
 
@@ -25,7 +25,7 @@ Documentation
 
 ------------
 
-.. function:: GetArgType: det(31), Ans = argument to check
+.. function:: GetArgType: det(31); Ans = argument to check
 
     Outputs a real number depicting the type of argument in ``Ans``.
 
@@ -68,7 +68,7 @@ Documentation
 
 ------------
 
-.. function:: FindProg: det(33, type), Ans = search string
+.. function:: FindProg: det(33, type); Ans = search string
 
     This does not search for file names, instead it searches for file contents. The search string checks for the beginning contents of a program. Type refers to the type of file to search, with 0 being programs and 1 being appvars. The function will return a string containing the names of the files containing the search phrase, with each name separated by a space.
     For example, to look for all the programs beginning with ":DCS", your code would look something like this::
@@ -85,3 +85,199 @@ Documentation
 
     Errors:
      * ``..P:NT:FN`` if no files are found containing the specified search string.
+
+------------
+
+.. function:: UngroupFile: det(34, overwrite); Str0 = group name
+    
+    This function ungroups the programs and AppVars from a group file specified in ``Str0``. It will only apply to files that are programs and AppVars, not other types like lists. If ``overwrite`` is true (not 0), files which already exist will be overwritten. If it is false (0), files will be preserved.
+    The group name (in ``Str0``) must be preceded by the ``*row(`` token, as specified in `General Syntax <gensyntax.html#argument-types>`__.
+
+    Parameters:
+     * ``overwrite``: Whether or not to overwrite files that already exist when extracting.
+     * ``Str0``: Contains the name of the specified group. The name must be preceded by the ``*row(`` token.
+
+    Returns:
+     * Ungroups all programs and AppVars from the specified group.
+
+    Errors:
+     * ``..G:NT:FN`` if the group specified does not exist.
+     * ``..P:NT:FN`` if no files in the group are able to be ungrouped (no programs or AppVars).
+
+------------
+
+.. function:: GetGroup: det(35); Str0 = group name
+
+    Puts the names of all program and AppVar files present in the specified group into ``Str9``, separated by spaces. The names will be in the same order in the string as they are found in the group.
+    The group name (in ``Str0``) must be preceded by the ``*row(`` token, as specified in `General Syntax <gensyntax.html#argument-types>`__.
+
+    Parameters:
+     * ``Str0``: Contains the name of the specified group. The name must be preceded by the ``*row(`` token.
+
+    Returns:
+     * ``Str9``: Contains a list of the names of all programs and AppVars in the group, separated by spaces.
+    
+    Errors:
+     * ``..G:NT:FN`` if the group specified does not exist.
+     * ``..P:NT:FN`` if no files in the group are valid (no programs or AppVars).
+
+------------
+
+.. function:: ExtGroup: det(36, item); Str0 = group name
+
+    Extracts the program or AppVar specified by ``item`` from the group specified in ``Str0``. If ``item`` is 1, it extracts the first program or AppVar, 2 extracts the second, and so on. This can be useful paired with ``GetGroup`` to figure out the order of the files in the group. If the file already exists with the same name, it will not be overwritten.
+    The group name (in ``Str0``) must be preceded by the ``*row(`` token, as specified in `General Syntax <gensyntax.html#argument-types>`__.
+
+    .. warning::
+        ``item`` only counts programs and AppVars, and ignores other types, like lists. If ``item`` is 2, it refers to the second **valid** file, not necessarily the second file including all types.
+
+    Parameters:
+     * ``item``: The item in the group to extract. Only applies to programs and AppVars, and begins at 1.
+
+    Returns:
+     * Extracts the specified program or AppVar from the group.
+
+    Errors:
+     * ``..G:NT:FN`` if the group specified does not exist.
+     * ``..E:NT:FN`` if the specified item did not exist.
+     * ``..P:IS:FN`` if the program already exists.
+
+------------
+
+.. function:: GroupMem: det(37, item); Str0 = group name
+
+    Returns the size of the program or AppVar specfied by ``item`` from the group specified in ``Str0``. ``item`` behaves the same way as in ``ExtGroup``.
+    The group name (in ``Str0``) must be preceded by the ``*row(`` token, as specified in `General Syntax <gensyntax.html#argument-types>`__.
+
+    Parameters:
+     * ``item``: The item in the group to extract. Only applies to programs and AppVars, and begins at 1.
+
+    Returns:
+     * ``theta``: The size of the specified program or AppVar from the group.
+
+    Errors:
+     * ``..G:NT:FN`` if the group specified does not exist.
+     * ``..E:NT:FN`` if the specified item did not exist.
+
+------------
+
+.. function:: BinRead: det(38, byte_start, number_of_bytes); Str0 = file name
+
+    Reads the contents of a file starting at ``byte_start`` for ``number_of_bytes`` bytes. ``byte_start`` is 0-indexed, meaning that the first byte of the program is 0, the second is 1, and so on. The output will be a hex string representing the bytes. For example, if the following bytes were in memory:
+
+    ==== == == == == ==
+    Byte 0  1  2  3  4
+    Data EF 7B 66 6F 6F
+    ==== == == == == ==
+
+    ``Str9`` would contain this::
+
+        EF7B666F6F
+
+    Parameters:
+     * ``byte_start``: The byte of the file to start reading from. It is 0-indexed, so the first byte of the file is 0, the second is 1, and so on.
+     * ``number_of_bytes``: The number of bytes to read, starting at ``byte_start``. You can also read past the end of the file.
+     * ``Str0``: The name of the file to read from. For AppVars, the name should be preceded by the ``rowSwap(`` token.
+
+    Returns:
+     * ``Str9``: Contains a text string of hex representing the bytes read.
+
+------------
+
+.. function:: BinWrite: det(39, byte_start); Str9 = hex string to write; Str0 = file name
+
+    Writes the hex bytes represented in ``Str9`` to 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 writing to. It is 0-indexed, so the first byte of the file is 0, the second is 1, and so on.
+     * ``Str9``: Contains a text string of hex representing the bytes to write.
+     * ``Str0``: The name of the file to write to. For AppVars, the name should be preceded by the ``rowSwap(`` token.
+
+    Returns:
+     * Writes the bytes specified in ``Str9`` to the specified file.
+
+    Errors:
+     * ``..E:NT:FN`` if ``byte_start`` is past the end of the file.
+     * ``..INVAL:S`` if there is not an even number of characters in the string or an invalid hex character is present.
+     * ``..NT:EN:M`` if there is not enough memory to complete the write.
+
+------------
+
+.. 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.
+
+    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.
+     * ``number_of_bytes``: The number of bytes to delete.
+     * ``Str0``: The name of the file to delete from. For AppVars, the name should be preceded by the ``rowSwap(`` token.
+
+    Returns:
+     * Deletes the specified number of bytes from the specified file.
+
+    Errors:
+     * ``..E:NT:FN`` if ``byte_start`` is past the end of the file, or the number of bytes deleted would exceed the end of the file.
+
+------------
+
+.. function:: HexToBin: det(41); Ans = hex string
+
+    Outputs the binary equivalent of the input string in ``Ans``. For example, if you did this::
+
+        :"464F4F424152
+        :det(41)
+
+    The result would be ``"FOOBAR"``.
+
+    Parameters:
+     * ``Ans``: Hex string to convert.
+
+    Returns:
+     * ``Str9``: The converted string.
+    
+    Errors:
+     * ``..INVAL:S`` if there is not an even number of characters in the string or an invalid hex character is present.
+
+------------
+
+.. function:: BinToHex: det(42); Ans = token string
+
+    Outputs the hex equivalent of the input string in ``Ans``. For example, if you did this::
+
+        :"FOOBAR
+        :det(42)
+
+    The result would be ``"464F4F424152"``.
+
+    Parameters:
+     * ``Ans``: Binary string to convert.
+    
+    Returns:
+     * ``Str9``: The converted string.
+
+------------
+
+.. function:: GraphCopy: det(43)
+
+    Copies the graph buffer to the screen.
+
+------------
+
+.. function:: Edit1Byte: det(44, string_number, target_byte, replace_byte)
+
+    Replaces the byte at ``target_byte`` of the specified string with the byte specified by ``replace_byte``. ``target_byte`` is 0-indexed, meaning that the first byte of the program is 0, the second is 1, and so on. For example::
+
+        :det(44, 0, 0, 255)
+
+    This code will replace byte 0 of ``Str0`` with the byte 255 in decimal, or 0xFF in hex.
+
+    Parameters:
+     * ``string_number``: The string to modify. 0 is ``Str0``, 1 is ``Str1``, and so on.
+     * ``target_byte``: The byte of the string to modify. It is 0-indexed, so the first byte of the file is 0, the second is 1, and so on.
+     * ``replace_byte``: The byte to replace the target byte with, in decimal format. Can be 0 - 255 (0x00 - 0xFF).
+    
+    Returns:
+     * Replaces the target byte of a string with the specified replacement byte.
+    
+    Errors:
+     * ``..E:NT:FN`` if the target byte does not exist in the string.

docs/conf.py

@@ -20,13 +20,13 @@
 # -- Project information -----------------------------------------------------
 
 project = 'Celtic CE'
-copyright = '2022, RoccoLox Programs, TIny_Hacker'
+copyright = '2022 - 2023, RoccoLox Programs, TIny_Hacker'
 author = 'RoccoLox Programs, TIny_Hacker'
 
 # The short X.Y version
-version = 'b1.1'
+version = 'b1.2'
 # The full version, including alpha/beta/rc tags
-release = 'Beta 1.1'
+release = 'Beta 1.2'
 
 
 # -- General configuration ---------------------------------------------------

docs/csefunctions.rst

@@ -8,7 +8,7 @@ These functions are the same as those included in Doors CSE 8 for the TI-84 Plus
 Documentation
 ~~~~~~~~~~~~~
 
-.. function:: ReadLine: det(0), Str0 = variable name, Ans = line number
+.. 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.
 
@@ -28,7 +28,7 @@ Documentation
 
 ------------
 
-.. function:: ReplaceLine: det(1), Str0 = variable name, Ans = line number, Str9 = replacement
+.. function:: ReplaceLine: det(1); Str0 = variable name; Ans = line number; Str9 = replacement
 
     Replaces (overwrites) a line in a program or AppVar. ``Ans`` refers to the line to replace.
 
@@ -45,7 +45,7 @@ Documentation
 
 ------------
 
-.. function:: InsertLine: det(2), Str0 = variable name, Ans = line number, Str9 = contents
+.. function:: InsertLine: det(2); Str0 = variable name; Ans = line number; Str9 = contents
 
     Insets a line into a program or AppVar. ``Ans`` refers to the line number to write to.
 
@@ -71,11 +71,11 @@ Documentation
     Stores the ``->`` and ``"`` characters into ``Str9``.
 
     Returns:
-     * ``Str9``: ``->`` and ``"``, respectively. You can use substrings to extract them. There are also 7 more characters in ``Str9``, which are junk.
+     * ``Str9``: ``->`` and ``"``, respectively. you can use substrings to extract them. There are also 7 more characters in ``Str9``, which are junk.
 
 ------------
 
-.. function:: CreateVar: det(4), Str0 = variable name
+.. function:: CreateVar: det(4); Str0 = variable name
 
     Create a program or AppVar given a name.
 
@@ -94,7 +94,7 @@ Documentation
 
 ------------
 
-.. function:: ArcUnarcVar: det(5), Str0 = variable name
+.. function:: ArcUnarcVar: det(5); Str0 = variable name
 
     Archive/unarchive a program or AppVar given a name.
 
@@ -106,7 +106,7 @@ Documentation
 
 ------------
 
-.. function:: DeleteVar: det(6), Str0 = variable name
+.. function:: DeleteVar: det(6); Str0 = variable name
 
     Delete a program variable or an AppVar given a name.
 
@@ -118,7 +118,7 @@ Documentation
 
 ------------
 
-.. function:: DeleteLine: det(7), Str0 = variable name, Ans = line number
+.. function:: DeleteLine: det(7); Str0 = variable name; Ans = line number
 
     Deletes a line from a program or AppVar. ``Ans`` is the line to delete.
 
@@ -131,7 +131,7 @@ Documentation
 
 ------------
 
-.. function:: VarStatus: det(8), Str0 = variable name
+.. function:: VarStatus: det(8); Str0 = variable name
 
     Output status string describing a program or AppVar's current state, including size, visibility, and more.
 
@@ -149,32 +149,32 @@ Documentation
 
 ------------
 
-.. function:: BufSprite: det(9, width, X, Y), Str9 = sprite data
+.. function:: BufSprite: det(9, width, x, y); Str9 = sprite data
 
     Draws indexed (palette-based) sprite onto the LCD and into the graph buffer. Copies the contents of the graph buffer under the sprite back into Str9, so that you can "erase" the sprite back to the original background. Good for moving player characters, cursors, and the like. Interacts politely with Pic variables and OS drawing commands like ``Line(``, ``Circle(``, ``Text(``, and so on. If you want to draw a lot of different sprites to the screen and won't need to erase them back to the background, then use BufSpriteSelect instead.
 
     Parameters:
      * ``Str9``: Sprite data as ASCII hex, one nibble per byte. The digits 1-F are valid colors (1 = blue, 2 = red, 3 = black, etc), while G will cause the routine to skip to the next line. 0 is normal transparency, and lets the background show through. H is a special kind of transparency that erases back to transparency instead of leaving the background color intact.
-     * ``X``: X coordinate to the top-left corner of the sprite.
-     * ``Y``: Y coordinate to the top-left corner of the sprite.
+     * ``x``: x coordinate to the top-left corner of the sprite.
+     * ``y``: y coordinate to the top-left corner of the sprite.
      *  ``width``: Sprite width (height is computed).
 
     Returns:
-     * ``Str9``: Same length as input, contains the previous contents of the graph buffer where the sprite was drawn. You can call ``det(9...)`` again without changing Str9 to effectively undo the first sprite draw.
+     * ``Str9``: Same length as input, contains the previous contents of the graph buffer where the sprite was drawn. you can call ``det(9...)`` again without changing Str9 to effectively undo the first sprite draw.
 
     Errors:
      * ``..INVAL:S`` if the string contains invalid characters.
 
 ------------
 
-.. function:: BufSpriteSelect: det(10, width, X, Y, start, length), Str9 = sprite data
+.. function:: BufSpriteSelect: det(10, width, x, y, start, length); Str9 = sprite data
 
     Draws indexed (palette-based) sprite onto the LCD and into the graph buffer. Good for drawing tilemaps, backgrounds, and other sprites that you won't want to individually erase. If you want to be able to erase the sprite drawn and restore the background, you should consider BufSprite instead. This routine takes an offset into Str9 and a sprite length as arguments, so that you can pack multiple sprites of different lengths into Str9.
 
     Parameters:
      * ``Str9``: Sprite data as ASCII hex, one nibble per byte. The digits 1-F are valid colors (1 = blue, 2 = red, 3 = black, etc), while G will cause the routine to skip to the next line. 0 is normal transparency, and lets the background show through. H is a special kind of transparency that erases back to transparency instead of leaving the background color intact.
-     * ``X``: X coordinate to the top-left corner of the sprite.
-     * ``Y``: Y coordinate to the top-left corner of the sprite.
+     * ``x``: x coordinate to the top-left corner of the sprite.
+     * ``y``: y coordinate to the top-left corner of the sprite.
      *  ``width``: Sprite width (height is computed).
      *  ``start``: Offset into ``Str9`` of the start of pixel data, begins at 0.
      *  ``length``: Length of sprite data in characters.
@@ -187,7 +187,7 @@ Documentation
 
 ------------
 
-.. function:: ExecArcPrgm: det(11, function, temp_prog_number), Ans = program name
+.. 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:
 
@@ -212,19 +212,19 @@ Documentation
 
 ------------
 
-.. function:: DispColor: det(12, FG_LO, FG_HI, BG_LO, BG_HI)
+.. function:: DispColor: det(12, fg_low, fg_high, bg_low, bg_high)
 
     Changes the foreground and background color for ``Output(``, ``Disp``, and ``Pause`` to arbitrary 16-bit colors, or disables this feature. Due to technical limitations, the foreground and background for ``Text()`` cannot be changed to arbitrary colors. To disable this mode, you should call ``det(12, 300)`` before exiting your program.
 
     Parameters:
-     * ``FG_LO``: low byte of foreground color.
-     * ``FG_HI``: high byte of foreground color.
-     * ``BG_LO``: low byte of background color.
-     * ``BG_HI``: high byte of background color.
-
-    Alternative method: ``det(12, FG_OS, BG_OS)``
-     * ``FG_OS``: Foreground color from TI-OS Colors menu, like RED or BLUE or NAVY.
-     * ``BG_OS``: Background color from TI-OS Colors menu, like RED or BLUE or NAVY.
+     * ``fg_low``: low byte of foreground color.
+     * ``fg_high``: high byte of foreground color.
+     * ``bg_low``: low byte of background color.
+     * ``bg_high``: high byte of background color.
+
+    Alternative method: ``det(12, fg_os, bg_os)``
+     * ``fg_os``: Foreground color from TI-OS Colors menu, like RED or BLUE or NAVy.
+     * ``bg_os``: Background color from TI-OS Colors menu, like RED or BLUE or NAVy.
 
     Colors:
      * A list of colors can be found `here <colors.html>`__.