chore: autopublish 2024-10-14T16:04:20Z

docs/library/ziputils.md

@@ -0,0 +1,134 @@
+# ziputils
+
+Functions for unzipping files. (Future may include zipping as well.)
+
+Dependencies:
+
+- Windows users must have `7z` installed. You can download it [here](https://www.7-zip.org/).
+- MacOS users must have `unzip` and `gunzip`, but these are usually installed with the OS.
+
+Pay careful attention to the comments about how strings are encoded. They are either encoded
+**platform** or **utf8**. On macOS, platform encoding is always utf8, but on Windows it can
+be any number of encodings depending on the locale settings and version of Windows. You can use
+`luaosutils.text` to convert them back and forth. Both `luaosutils.process.execute`
+requires platform encoding as do `lfs` and all built-in Lua `io` functions.
+
+Note that many functions require later versions of RGP Lua that include `luaosutils`
+and/or `lfs`. But the these dependencies are embedded in each function so that any version
+of Lua for Finale can at least load the library.
+
+## Functions
+
+- [calc_rmdir_command(path_to_remove)](#calc_rmdir_command)
+- [calc_delete_file_command(path_to_remove)](#calc_delete_file_command)
+- [calc_temp_output_path(archive_path)](#calc_temp_output_path)
+- [calc_gunzip_command(archive_path)](#calc_gunzip_command)
+- [calc_is_gzip(buffer)](#calc_is_gzip)
+
+### calc_rmdir_command
+
+```lua
+ziputils.calc_rmdir_command(path_to_remove)
+```
+
+[View source](https://github.com/finale-lua/lua-scripts/tree/refs/heads/master/src/library/ziputils.lua#L49)
+
+Returns the platform-dependent command to remove a directory. It can be passed
+to `luaosutils.process.execute`.
+
+**WARNING** The command, if executed, permanently deletes the contents of the directory.
+You would normally call this on the temporary directory name from `calc_temp_output_path`.
+But it works on any directory.
+
+| Input | Type | Description |
+| ----- | ---- | ----------- |
+| `path_to_remove` | `string` | platform-encoded path of directory to remove. |
+
+| Return type | Description |
+| ----------- | ----------- |
+| `string` | platform-encoded command string to execute. |
+
+### calc_delete_file_command
+
+```lua
+ziputils.calc_delete_file_command(path_to_remove)
+```
+
+[View source](https://github.com/finale-lua/lua-scripts/tree/refs/heads/master/src/library/ziputils.lua#L66)
+
+Returns the platform-dependent command to delete a file. It can be passed
+to `luaosutils.process.execute`.
+
+**WARNING** The command, if executed, permanently deletes the file.
+You would normally call this on the temporary directory name from `calc_temp_output_path`.
+But it works on any directory.
+
+| Input | Type | Description |
+| ----- | ---- | ----------- |
+| `path_to_remove` | `string` | platform-encoded path of directory to remove. |
+
+| Return type | Description |
+| ----------- | ----------- |
+| `string` | platform-encoded command string to execute. |
+
+### calc_temp_output_path
+
+```lua
+ziputils.calc_temp_output_path(archive_path)
+```
+
+[View source](https://github.com/finale-lua/lua-scripts/tree/refs/heads/master/src/library/ziputils.lua#L86)
+
+Returns a path that can be used as a temporary target for unzipping. The caller may create it
+either as a file or a directory, because it is guaranteed not to exist when it is returned and it does
+not have a terminating path delimiter. Also returns a platform-dependent unzip command that can be
+passed to `luaosutils.process.execute` to unzip the input archive into the temporary name as a directory.
+The command may not be compatible with `os.execute`.
+
+This function requires `luaosutils`.
+
+| Input | Type | Description |
+| ----- | ---- | ----------- |
+| `archive_path` (optional) | `string` | platform-encoded filepath to the zip archive that is included in the zip command. |
+
+| Return type | Description |
+| ----------- | ----------- |
+| `string` | platform-encoded temporary path generated by the system. |
+| `string` | platform-encoded unzip command that can be used to unzip a multifile archived directory structure into the temporary path. |
+
+### calc_gunzip_command
+
+```lua
+ziputils.calc_gunzip_command(archive_path)
+```
+
+[View source](https://github.com/finale-lua/lua-scripts/tree/refs/heads/master/src/library/ziputils.lua#L118)
+
+Returns the platform-dependent command to gunzip a file. It can be passed
+to `luaosutils.process.execute`, which will then return the text directly.
+
+| Input | Type | Description |
+| ----- | ---- | ----------- |
+| `archive_path` | `string` | platform-encoded path of source gzip archive. |
+
+| Return type | Description |
+| ----------- | ----------- |
+| `string` | platform-encoded command string to execute. |
+
+### calc_is_gzip
+
+```lua
+ziputils.calc_is_gzip(buffer)
+```
+
+[View source](https://github.com/finale-lua/lua-scripts/tree/refs/heads/master/src/library/ziputils.lua#L134)
+
+Detects if an input buffer is a gzip archive. Sometimes, Finale gzips the internal EnigmaXML document.
+
+| Input | Type | Description |
+| ----- | ---- | ----------- |
+| `buffer` | `string` | binary data to check if it is a gzip archive |
+
+| Return type | Description |
+| ----------- | ----------- |
+| `boolean` | true if the buffer is a gzip archive |