CST1229/zip: multi-archive (#1351)

A major update to the Zip extension, mainly adding support for multiple archives at a time

https://github.com/TurboWarp/extensions/assets/68464103/56c6dada-cb51-4c09-b22e-cf30409e6898

docs/CST1229/zip.md

@@ -1,6 +1,8 @@
 # Zip
 
-The Zip extension allows you to read, create and edit .zip format files, including Scratch project and sprite files (.sb3, .sprite3). 
+The Zip extension allows you to read, create and edit .zip format files, including Scratch project and sprite files (.sb3, .sprite3).
+
+The extension handles archives **entirely in-memory**; to interact with the file system you'll have to use it alongside other extensions, like Files. In-memory zip files will be referred to as *archives* in this documentation (and in the blocks).
 
 ## Paths
 
@@ -13,24 +15,25 @@ Most blocks in this extension work with a path format:
  - A `/` at the very start goes to the root directory, like `/file.txt`
  - A `/` at the end denotes a directory, like `folder/`
  - Multiple slashes in a row or trying to go above the root directory will result in an error (usually the block doing nothing or returning the empty value)
+ - When working with multiple archives, each archive has its own current directory which is retained while switching between them
 
 ## Archive management blocks
 
-Blocks for creating and saving the current archive. Only one archive can be open at a time. 
+Blocks for creating and saving archives. 
 
 ---
 
 ```scratch
-create empty archive :: #a49a3a
+create empty archive named [archive] :: #a49a3a
 ```
-Creates and opens an empty archive with nothing in it. 
+Creates and opens an empty archive with nothing in it. The name is used for dealing with multiple archives at time; it can be any non-empty string and does *not* have to be the archive's filename.
 
 ---
 
 ```scratch
-open zip from (URL v) [https://extensions.turbowarp.org] :: #a49a3a
+open zip from (URL v) [https://extensions.turbowarp.org] named [archive] :: #a49a3a
 ```
- Opens a .zip (or .sb3 or .sprite3...) file.
+Opens a .zip (or .sb3 or .sprite3...) file.
 
 The type can be one of the following:
 
@@ -40,14 +43,16 @@ The type can be one of the following:
  - **binary**: A sequence of binary bytes (like `000000010010101001101011`), without a separator.
  - **string**: Plain text. **Not recommended!** Text encoding behavior will likely break it, as it's a binary file.
 
-If the file is not of zip format (e.g RAR or 7z) or is password-protected, it won't be opened. Make sure to check if it loaded successfully with the archive `is open?` block. 
+The name is used for dealing with multiple archives at time; it can be any non-empty string and does *not* have to be the archive's filename.
+
+If the file is not of zip format (e.g RAR or 7z) or is password-protected, it won't be opened. Make sure to check if it loaded successfully with the `error opening archive?` block. 
 
 ---
 
 ```scratch
 (output zip type (data: URI v) compression level (6 v) :: #a49a3a)
 ```
-Save the zip data into a string, which can be saved with e.g the Files extension.
+Saves the current archive into a zip data string, which can be saved with e.g the Files extension.
 
 The type can be one of the following:
 
@@ -65,9 +70,9 @@ A compression level of 0 (no compression) is the fastest, but will often result
 ---
 
 ```scratch
-close archive :: #a49a3a
+remove current archive :: #a49a3a
 ```
-Closes the archive. Use after you're done working with it.
+Removes the current archive from the list of opened archives. Use this after you're done working with it.
 
 ---
 
@@ -76,6 +81,45 @@ Closes the archive. Use after you're done working with it.
 ```
 Returns true if an archive is open.
 
+---
+
+```scratch
+<error opening archive? :: #a49a3a>
+```
+Returns true if the last "open archive" block used had an error (e.g if you provided an empty archive name or passed an invalid zip file).
+
+## Multi-archive blocks
+
+Multiple archives can be open at a time, but there is one "current archive" that most blocks operate on. These blocks handle switching between and using multiple archives.
+
+---
+
+```scratch
+(current archive name :: #a49a3a)
+```
+Returns the name of the currently open archive (or an empty string if there isn't one).
+
+---
+
+```scratch
+(currently open archives :: #a49a3a)
+```
+Returns the list of currently open archives, as a JSON array (which you can parse with the JSON extension). 
+
+---
+
+```scratch
+switch to archive named [other archive] :: #a49a3a
+```
+Switches the current archive to another one. If the given archive name does not exist. does nothing. If the given archive name is an empty string, switches to no currently open archive without removing any.
+
+---
+
+```scratch
+remove all archives :: #a49a3a
+```
+Removes all archives that are currently open.
+
 ## File blocks
 
 Blocks for working with files (and blocks that are general to both files and folders/directories.) 
@@ -111,6 +155,20 @@ Renames a file or directory to another name. If the target file already exists,
 
 ---
 
+```scratch
+copy [hello.txt] to [Copy of hello.txt] :: #a49a3a
+```
+Copies a file or directory elsewhere. If the target file already exists, it will be overwritten.
+
+---
+
+```scratch
+copy [hello.txt] in [archive] to [Copy of hello.txt] in [other archive] :: #a49a3a
+```
+Copies a file or directory between archives. If the target file already exists, it will be overwritten.
+
+---
+
 ```scratch
 delete [hello.txt] :: #a49a3a
 ```
@@ -192,7 +250,7 @@ Moves the current directory (the default origin of most file operations) to the
 ```scratch
 (contents of directory [.] :: #a49a3a)
 ```
-Returns a list of files in a directory, as JSON (which you can parse with the JSON extension). 
+Returns a list of files in a directory, as a JSON array (which you can parse with the JSON extension). 
 
 ---