From 0c2f80ea925f1fff06fc09a3788edb6c1ed306be Mon Sep 17 00:00:00 2001
From: zawz <zawz@hotmail.fr>
Date: Sun, 28 Feb 2021 15:30:44 +0100
Subject: [PATCH] set version to 1.0.0 + update doc

---
 README.md         | 75 ++++++++++++++++++++++++++++++++++++++++++-----
 include/version.h |  2 +-
 2 files changed, 68 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 4af5d9a..fbe24e2 100644
--- a/README.md
+++ b/README.md
@@ -6,9 +6,25 @@ Extended shell linker for linking, processing and minimizing shell code
 
 ## linux-amd64
 
+### zpkg
+
+Available from the `zpkg` repository:
+```shell
+wget -qO- https://zpkg.zawz.net/install.sh | sh
+zpkg install lxsh
+```
+
+### Binary
+
 Download the `lxsh-linux-amd64.tar.gz` archive, extract it,
 and move the `lxsh` binary in a PATH folder (`/usr/local/bin` is the recommended).
 
+```shell
+wget https://github.com/zawwz/lxsh/releases/download/v1.0.0/lxsh-linux-amd64.tar.xz
+tar -xvf lxsh.tar.gz
+sudo mv lxsh /usr/local/bin
+```
+
 ## Other
 
 See [Build](#build).
@@ -44,12 +60,55 @@ Unused functions and variables can be removed with `--remove-unused`.
 
 ## Debashify
 
-Bash specific features can be translated into POSIX code.
+Some bash specific features can be translated into POSIX shell code.
 
-This is a work in progress and for now only some are translated:
+The following bash features can be debashified:
 - `<()` and `>()` process substitutions
 - `<<<` herestring
 - `>&`, `&>` and `&>>` output redirects
+- `[[ ]]` conditions
+- indexed arrays and associative arrays (+ their `declare` and `typeset` definitions)
+
+### Advantages
+
+- Removes dependency on bash and makes a script more portable.
+- In some cases it can also provide improved performance given that some more minimalist shells like `dash` have better performance.
+  * this doesn't always apply for all situations, make sure to verify through testing
+
+### Limitations
+
+#### Process substitution
+
+The debashifying of process substitution assumes that /dev/urandom will exist and will provide proper randomness. <br>
+Temporary files with random names are used to create named pipes for the commands in the substitution.
+
+There may be some slight performance loss on the creation of said process subtitution.
+
+#### Indexed/Associative Arrays
+
+Indexed arrays and associative arrays are detected on parse instead of runtime.
+By default if an array operator is found, it is assumed to be an indexed array,
+and associative arrays are detected through the use of `declare` (or `typeset`). <br>
+In cases where there is ambiguity, the result upon execution might be undesired.
+
+> To avoid such ambiguities, put the `declare` statement of a variable first of all,
+> and don't mix and match different types on the same variable name
+
+Getting the value of an array without index will give the full value instead of the first value.
+
+> To avoid such situation, always get values from an index in your array
+
+Arrays are store as strings. Indexed arrays are delimited by tabs and associative arrays by newlines,
+This means inserting values containing these characters will have undesired behavior.
+
+Debashified arrays have substantially reduced performance.
+
+Where bash would present proper errors upon incorrectly accessing arrays,
+these features will continue working with undesired behavior.
+
+> To avoid this, make sure to never access incorrect values
+
+Array argument with `[@]` does not work with spaces, tabs and newlines in values.
 
 ## Other features
 
@@ -67,9 +126,10 @@ Directly execute an extended lxsh script with either
 - shebang is lxsh
 
 > Direct execution introduces direct dependency on lxsh and code generation overhead,
-> therefore it should be avoided outside of development use
+> therefore it should be avoided outside of development use.
+> This may be optimized in a later version
 
-> There may be some issues with direct execution as of now
+> There are some issues with direct execution as of now
 
 ### Variable/Function/command listing
 
@@ -92,11 +152,10 @@ You can use environment variables to alter some aspects:
 # Work in progress
 
 The full POSIX syntax is supported and should produce a functioning result. <br>
-However not all bash syntax is supported yet.
+Most bash syntax is also supported, but not all.
 
 ## Known bash issues
 
-- `${!VAR}` does not register as a variable
 - Extended globs (`*()`) are not supported
-- `(())` creates two subshells instead of one object
-- Unsetting functions will not work properly when minimizing variables or functions
+- `(())` is parsed as subshells
+- Unsetting functions can have undesired effects
diff --git a/include/version.h b/include/version.h
index d491a60..4038084 100644
--- a/include/version.h
+++ b/include/version.h
@@ -1,6 +1,6 @@
 #ifndef VERSION_H
 #define VERSION_H
 
-#define VERSION_STRING "v0.3a"
+#define VERSION_STRING "v1.0.0"
 
 #endif //VERSION_H