Specify README Installation guide

README.md

@@ -1,6 +1,6 @@
 # Sh args parser
 
-This is POSIX-compliant code for parsing shell script arguments. It helps you focus on writing the script logic by separating argument parsing and basic validation.
+This is POSIX-compliant parser for script arguments. It helps you focus on writing the script logic by separating argument parsing and basic validation.
 
 ## Contents
 
@@ -14,14 +14,36 @@ This is POSIX-compliant code for parsing shell script arguments. It helps you fo
 
 ## Installation
 
-Include the `parser.sh` file in your script using [`dot`](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#dot) or [`source`](https://www.gnu.org/software/bash/manual/bash.html#index-source).
-
+Include `parser.sh` content before usage. The most convenient way is to include the `parser.sh` file in your script using [`dot`](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#dot) or [`source`](https://www.gnu.org/software/bash/manual/bash.html#index-source) shell built-ins.
+It is important to note that external files are included relative to the terminal's current directory, not the script's directory. If you decide to include files using a path relative to the script, use the following approach:
 ```bash
-#!/usr/bin/env sh
-. parser.sh
+script_dir="$(dirname "$(readlink -f "$0")")"
+. "$script_dir/parser.sh"
+```
+This will allow you to include the `parser.sh` from the script's directory, regardless of where you run the script from.
+### Git submodule
+
+It is convenient to include parser in your repository as a [Git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules):
+```bash
+git submodule add https://github.com/nikolaypronchev/sh-args-parser.git
+```
+The repository `nikolaypronchev/sh-args-parser` will be copied into your repository in the `sh-args-parser` directory:
+```
+your-repo/
+├ sh-args-parser/
+| ├ parser.sh
+| └ ...
+├ your-script.sh
+└ ...
+```
+Next, include `parser.sh` in your script using the approach from the previous section:
+```bash
+# your-script.sh
+script_dir="$(dirname "$(readlink -f "$0")")"
+. "$script_dir/sh-args-parser/parser.sh"
 ```
 
-Or copy the contents of the `parser.sh` file into your script.
+It’s important to remember that submodules are not fetched by Git by default when running `git clone`. To clone your repository including submodules, use the command `git clone --recurse-submodules`.
 
 ## Usage
 
@@ -103,6 +125,22 @@ Configuration is done by assigning values to special keys via [`_set_config`](#_
 
 ## Functions
 
+- [_set_config](#_set_config)
+- [_parse](#_parse)
+- [Functions for command and option mapping](#functions-for-command-and-option-mapping):
+  - [_map_command](#_map_command)
+  - [_map_option](#_map_option)
+- [Functions for working with parsing results](#functions-for-working-with-parsing-results):
+  - [_get_command](#_get_command)
+  - [_is_used_command](#_is_used_command)
+  - [_get_positional_args](#_get_positional_args)
+  - [_get_positional_args_count](#_get_positional_args_count)
+  - [_get_positional_arg](#_get_positional_arg)
+  - [_is_used_option](#_is_used_option)
+  - [_get_option_args](#_get_option_args)
+  - [_get_option_args_count](#_get_option_args_count)
+  - [_get_option_arg](#_get_option_arg)
+
 #### _set_config
 Sets the configuration variables. Full list of configuration variables and expected values can be found in the [Configuration](#configuration) section.
 ```bash
@@ -197,6 +235,20 @@ _is_used_command bar && echo 'Command "bar" was used'
 Command "foo" was used
 ```
 
+#### _get_positional_args
+
+Outputs the positional arguments separated by space. Delimiter can be changed by passing it's value as the first argument.
+
+```bash
+_parse foo bar baz
+_get_positional_args
+_get_positional_args "|"
+```
+```
+foo bar baz
+foo|bar|baz
+```
+
 #### _get_positional_args_count
 
 Outputs the number of positional arguments.
@@ -239,6 +291,20 @@ Option "--bar" was used
 Option "-c" was used
 ```
 
+#### _get_option_args
+
+Outputs the arguments of the option separated by space. Mandatory option alias is expected as the first argument. Delimiter can be changed by passing it's value as the second argument.
+
+```bash
+_parse -v foo bar baz
+_get_option_args -v
+_get_option_args -v "|"
+```
+```
+foo bar baz
+foo|bar|baz
+```
+
 #### _get_option_args_count
 
 Outputs the number of arguments for the option with the alias passed as the first argument.
@@ -266,8 +332,6 @@ baz
 ```
 
 ## TODO
-- Add function to set config variables and validates them;
-- Add "Debug" mode with verbose output;
 - Add examples;
 - Implement "Help" generation;
 - Add tests.

parser.sh

@@ -1007,6 +1007,24 @@ _is_used_command() {
   [ -n "$_command_index" ] && [ -n "$_used_command_index" ] && [ "$_command_index" -eq "$_used_command_index" ]
 }
 
+_get_positional_args() {
+  _delimiter=${1:-" "}
+
+
+  if [ "$_positional_args_count" -gt "1" ]; then
+    _positional_args=""
+
+    _i=1
+    while [ "$_i" -le "$_positional_args_count" ]; do
+        _positional_arg=$(_var_value "_positional_args_${_i}")
+        _positional_args="${_positional_args}${_delimiter}${_positional_arg}"
+        _i=$(_math "$_i + 1")
+    done
+
+    echo "${_positional_args#"$_delimiter"}"
+  fi
+}
+
 _get_positional_args_count() {
   echo  "$_positional_args_count"
 }
@@ -1030,6 +1048,25 @@ _is_used_option() {
   [ -n "$_option_index" ] && _is "$(_var_value "_options_${_option_index}_used")"
 }
 
+_get_option_args() {
+  _option_index=$(_get_mapped_option_index_by_alias "$1")
+  _delimiter=${2:-" "}
+
+  _option_args=""
+  if [ -n "$_option_index" ]; then
+    _option_args_count=$(_var_value "_options_${_option_index}_args_count")
+
+    _i=1
+    while [ "$_i" -le "$_option_args_count" ]; do
+        _arg=$(_var_value "_options_${_option_index}_args_${_i}")
+        _option_args="${_option_args}${_delimiter}${_arg}"
+        _i=$(_math "$_i + 1")
+    done
+
+    echo "${_option_args#"$_delimiter"}"
+  fi
+}
+
 _get_option_args_count() {
   _option_index=$(_get_mapped_option_index_by_alias "$1")