updated readme to clarify #57

Author: DannyBen

README.md

@@ -1,8 +1,7 @@
 <div align='center'>
 <img src='logo.svg' width=280>
 
-Bashly - Bash CLI Framework and Generator
-==================================================
+# Bashly - Bash CLI Framework and Generator
 
 Create beautiful bash scripts from simple YAML configuration
 
@@ -16,10 +15,28 @@ Create beautiful bash scripts from simple YAML configuration
 
 </div>
 
+## Table of Contents
+
+- [Table of Contents](#table-of-contents)
+- [Installation](#installation)
+- [Prerequisites](#prerequisites)
+- [What is Bashly](#what-is-bashly)
+- [Usage](#usage)
+  - [Using the input arguemnts in your code](#using-the-input-arguemnts-in-your-code)
+- [Examples](#examples)
+  - [Sample configuraiton for a script without commands](#sample-configuraiton-for-a-script-without-commands)
+  - [Sample configuraiton for a script with commands](#sample-configuraiton-for-a-script-with-commands)
+- [Configuration Reference](#configuration-reference)
+  - [Command options](#command-options)
+  - [Argument options](#argument-options)
+  - [Flag options](#flag-options)
+  - [Environment Variable options](#environment-variable-options)
+- [Real World Examples](#real-world-examples)
+- [Contributing / Support](#contributing--support)
+
 ---
 
-Installation
---------------------------------------------------
+## Installation
 
 ```shell
 $ gem install bashly
@@ -31,15 +48,13 @@ or with Docker:
 $ alias bashly='docker run --rm -it --volume "$PWD:/app" dannyben/bashly'
 ```
 
-Prerequisites
---------------------------------------------------
+## Prerequisites
 
 The bash scripts generated by bashly require bash 4 or higher due to heavy
 use of associative arrays.
 
 
-What is Bashly
---------------------------------------------------
+## What is Bashly
 
 Bashly is a command line application (written in Ruby) that lets you generate
 feature-rich bash command line tools.
@@ -68,8 +83,7 @@ Bahsly is responsible for:
   - **YAML parsing**.
   - and more.
 
-Usage
---------------------------------------------------
+## Usage
 
 In an empty directory, create a sample configuration file by running
 
@@ -99,9 +113,46 @@ Finally, edit the files in the `src` folder. Each of your script's commands
 get their own file. Once you edit, run `bashly generate` again to merge the
 content from your functions back into the script.
 
+### Using the input arguemnts in your code
+
+In order to access the parsed arguments in any of your partial scripts, you
+may simply access the `$args` associative array.
+
+For example:
+
+1. Generate a minimal configuration with `bashly init --minimal`
+2. Generate the bash script with `bashly generate`
+3. Run the script with `./download hello --force`
+
+You will notice that all the arguments of the associative array are printed 
+on screen. This is done by the `inspect_args` function that was inserted into
+the generated partial script `src/root_command.sh`.
+
+You can now access these variables by modifying `sec/root_command.sh` like
+this:
+
+
+```bash
+# src/root_command.sh
+source_url=${args[source]}
+force=${args[--force]}
+
+if [[ $force ]]; then
+  echo "downloading $source_url with --force"
+else
+  echo "downloading $source_url"
+fi
+```
+
+After editing the file, run `bashly generate` (or `bashly g` for short) and
+run:
+
+```
+$ ./download a --force
+downloading a with --force
+```
 
-Examples
---------------------------------------------------
+## Examples
 
 The `bashly.yml` file can be set up to generate two types of scripts:
 
@@ -129,8 +180,7 @@ See the [examples](examples) folder for more examples.
 
 
 
-Configuration Reference
---------------------------------------------------
+## Configuration Reference
 
 The `bashly.yml` configuration file consists of these types:
 
@@ -210,16 +260,14 @@ set.
 `required` | Specify if this variable is required.
 
 
-Real World Examples
---------------------------------------------------
+## Real World Examples
 
 - [Rush][rush] - a Personal Package Manager
 - [Alf][alf] - a generator for bash aliases and sub-aliases
 - [git-changelog][git-changelog] - a change log generator
 
 
-Contributing / Support
---------------------------------------------------
+## Contributing / Support
 
 If you experience any issue, have a question or a suggestion, or if you wish
 to contribute, feel free to [open an issue][issues].