docs: update docs

Author: adoyle-h

Makefile

@@ -24,3 +24,7 @@ bump-patch:
 .PHONY: build
 build:
 	./build -y ./dist/lobash.bash
+
+.PHONY: gen
+gen:
+	./tools/gen

config.example

@@ -40,6 +40,8 @@ PREFIX: l.
   - [ ] if
   - [ ] is_array
   - [ ] is_array.s
+  - [ ] is_associative_array
+  - [ ] is_associative_array.s
   - [ ] is_bash
   - [ ] is_bash.s
   - [ ] is_dir
@@ -165,6 +167,7 @@ PREFIX: l.
 - [ ]   Util
   - [ ] benchmark
   - [ ] compose
+  - [ ] parse_args
   - [ ] parse_params
   - [ ] repeat
   - [ ] sedi
@@ -174,4 +177,5 @@ PREFIX: l.
 - [ ]   Variable
   - [ ] cur_function_name
   - [ ] random
+  - [ ] var_attrs
   - [ ] xdg_config_home

docs/module-usages/README.md

@@ -1,6 +1,6 @@
 # Module Usages
 
-15 Categories, 139 Modules, 779 Test Cases.
+15 Categories, 143 Modules, 802 Test Cases.
 
 Each module provides only one function which naming prefixed with `l.` by default.
 
@@ -49,6 +49,8 @@ Most Lobash modules support Bash 4.0+ except below modules.
   - [if](./condition.md#if)
   - [is_array](./condition.md#is_array)
   - [is_array.s](./condition.md#is_arrays)
+  - [is_associative_array](./condition.md#is_associative_array)
+  - [is_associative_array.s](./condition.md#is_associative_arrays)
   - [is_bash](./condition.md#is_bash)
   - [is_bash.s](./condition.md#is_bashs)
   - [is_dir](./condition.md#is_dir)
@@ -164,6 +166,7 @@ Most Lobash modules support Bash 4.0+ except below modules.
 - [Util](./util.md)
   - [benchmark](./util.md#benchmark)
   - [compose](./util.md#compose)
+  - [parse_args](./util.md#parse_args)
   - [parse_params](./util.md#parse_params)
   - [repeat](./util.md#repeat)
   - [sedi](./util.md#sedi)
@@ -172,4 +175,5 @@ Most Lobash modules support Bash 4.0+ except below modules.
 - [Variable](./variable.md)
   - [cur_function_name](./variable.md#cur_function_name)
   - [random](./variable.md#random)
+  - [var_attrs](./variable.md#var_attrs)
   - [xdg_config_home](./variable.md#xdg_config_home)

docs/module-usages/condition.md

@@ -13,6 +13,8 @@
 - [if](#if)
 - [is_array](#is_array)
 - [is_array.s](#is_arrays)
+- [is_associative_array](#is_associative_array)
+- [is_associative_array.s](#is_associative_arrays)
 - [is_bash](#is_bash)
 - [is_bash.s](#is_bashs)
 - [is_dir](#is_dir)
@@ -135,6 +137,7 @@
 
 - Usage: `l.is_array <var_name>`
 - Description: When the variable is array or associative array, it returns 0 (true). Otherwise it returns 1 (false). This function should never throw exception error.
+- Dependent: [`var_attrs`](./variable.md#var_attrs)
 - Since: 0.3.0
 - Bash: 4.0+
 - **Notice**:
@@ -156,6 +159,30 @@
 - Test Cases: [tests/modules/is_array.s.bats](../../tests/modules/is_array.s.bats)
 - Source Code: [src/modules/is_array.s.bash](../../src/modules/is_array.s.bash)
 
+### is_associative_array
+
+- Usage: `l.is_associative_array <var_name>`
+- Description: When the variable is associative array, it returns 0 (true). Otherwise it returns 1 (false). This function should never throw exception error.
+- Dependent: [`var_attrs`](./variable.md#var_attrs)
+- Since: 0.7.0
+- Bash: 4.0+
+- **Notice**:
+  - **Only with bash 4.3, this function return 1 when the variable declared without initialization.**
+  - **Because `declare -p a` shows `declare: a: not found` when `declare -a a`. It's a bug in bash 4.3.**
+- Source Code: [src/modules/is_associative_array.bash](../../src/modules/is_associative_array.bash)
+
+### is_associative_array.s
+
+- Usage: `l.is_associative_array.s <var_name>`
+- Description: When the variable is array or associative array, it prints `true`. Otherwise it prints `false`. And it always exit with code 0.
+- Dependent: [`is_associative_array`](./condition.md#is_associative_array)
+- Since: 0.7.0
+- Bash: 4.0+
+- **Notice**:
+  - **Only with bash 4.3, this function will echo `false` when the variable declared without initialization.**
+  - **Because `declare -p a` shows `declare: a: not found` when `declare -a a`. It's a bug in bash 4.3.**
+- Source Code: [src/modules/is_associative_array.s.bash](../../src/modules/is_associative_array.s.bash)
+
 ### is_bash
 
 - Usage: `l.is_bash`
@@ -259,6 +286,7 @@
 - Description:
   - Check whether a shell variable is exported.
   - Return 0 (true) or 1 (false). This function should never throw exception error.
+- Dependent: [`var_attrs`](./variable.md#var_attrs)
 - Since: 0.5.0
 - Bash: 4.0+
 - **Notice**:

docs/module-usages/util.md

@@ -6,6 +6,7 @@
 
 - [benchmark](#benchmark)
 - [compose](#compose)
+- [parse_args](#parse_args)
 - [parse_params](#parse_params)
 - [repeat](#repeat)
 - [sedi](#sedi)
@@ -32,6 +33,28 @@
 - Test Cases: [tests/modules/compose.bats](../../tests/modules/compose.bats)
 - Source Code: [src/modules/compose.bash](../../src/modules/compose.bash)
 
+### parse_args
+
+- Usage: `l.parse_args <definition> "$@"`
+- Description:
+  - the `definition` is an associative array, which likes {[opts]=opts_name [args]=args_name ['-f,--flag']='bool'}.
+  - The `[opts]` and `[args]` are required for `<definition>`.
+  - It parses all parameters "$@". Put arguments to the `args_name` and options to `opts_name`.
+  - The `opts_name` must be an associative array or `_`. If set `_`, the options will be ignored.
+  - The `args_name` must be an array or `_`. If set `_`, the arguments will be ignored.
+  - The option has tree type:
+  -   "bool": For example, `-f`, `--flag` means `${f}` and `${flag}` equal to `"true"` and `--no-f` and `--no-flag` equal to `"false"`.
+  -   "count": the value of option defaults to 0. And increasing count by times. For example: `-v` `-vv` `-vvv`.
+  -   "kv": key/value. It means the option must has an argument. If user not pass argument to "kv" option. It will print error and stop.
+  - See test cases for details.
+- Dependent: [`each`](./array.md#each) [`match_list`](./string.md#match_list) [`var_attrs`](./variable.md#var_attrs)
+- Since: 0.7.0
+- Bash: 4.0+
+- **Notice**: **Only with bash 4.3, there may be something wrong if opts and args are not array.**
+- Test Cases: [tests/modules/parse_args.bats](../../tests/modules/parse_args.bats)
+- Source Code: [src/modules/parse_args.bash](../../src/modules/parse_args.bash)
+- Example: [example/modules/parse_args](../../example/modules/parse_args)
+
 ### parse_params
 
 - Usage:
@@ -44,6 +67,7 @@
   - `args_name` must be an array or `_`. If `_`, no arguments will be parsed.
   - See test cases for details.
 - Dependent: [`start_with`](./condition.md#start_with) [`match`](./string.md#match) [`match_list`](./string.md#match_list)
+- Deprecated: true
 - Since: 0.4.0
 - Bash: 4.0+
 - Test Cases: [tests/modules/parse_params.bats](../../tests/modules/parse_params.bats)

docs/module-usages/variable.md

@@ -6,6 +6,7 @@
 
 - [cur_function_name](#cur_function_name)
 - [random](#random)
+- [var_attrs](#var_attrs)
 - [xdg_config_home](#xdg_config_home)
 
 ## Modules
@@ -32,6 +33,20 @@
 - Test Cases: [tests/modules/random.bats](../../tests/modules/random.bats)
 - Source Code: [src/modules/random.bash](../../src/modules/random.bash)
 
+### var_attrs
+
+- Usage: `l.var_attrs <var_name>`
+- Description:
+  - Return the attributions of variable.
+  - If variable undefined, return ''.
+- Since: 0.7.0
+- Bash: 4.0+
+- **Notice**:
+  - **Only with bash 4.3, this function return 1 when the variable declared without initialization.**
+  - **Because `declare -p a` shows `declare: a: not found` when `declare -a a`. It's a bug in bash 4.3.**
+- Test Cases: [tests/modules/var_attrs.bats](../../tests/modules/var_attrs.bats)
+- Source Code: [src/modules/var_attrs.bash](../../src/modules/var_attrs.bash)
+
 ### xdg_config_home
 
 - Usage: `l.xdg_config_home`

src/internals/categories/condition

@@ -7,6 +7,8 @@ has_not.s
 if
 is_array
 is_array.s
+is_associative_array
+is_associative_array.s
 is_bash
 is_bash.s
 is_dir

src/internals/categories/util

@@ -1,5 +1,6 @@
 benchmark
 compose
+parse_args
 parse_params
 repeat
 sedi

src/internals/categories/variable

@@ -1,3 +1,4 @@
 cur_function_name
 random
+var_attrs
 xdg_config_home