remove line breaks to use editor line wraps

Author: ataxexe

README.md

@@ -4,15 +4,11 @@ SODA is a simple platform to help writing and executing tasks in shell script.
 
 ## How It Works
 
-SODA works by loading any scripts in a specific directory and calling a function
-passed by the command line. Only functions exposes through the builtin **task** function
-may be called.
+SODA works by loading any scripts in a specific directory and calling a function passed by the command line. Only functions exposes through the builtin **task** function may be called.
 
 ## How To Install
 
-Just clone the git repo and place the *soda* file in your path (a symlinks works well to).
-After that, ensure you have a **$SODA_HOME** pointing to the place you clone the repo and you're
-done.
+Just clone the git repo and place the *soda* file in your path (a symlinks works well to). After that, ensure you have a **$SODA_HOME** pointing to the place you clone the repo and you're done.
 
 ## How To Use
 
@@ -22,11 +18,9 @@ Create a *~/.soda* directory with the following structure:
 * _config_ - directory to put the configuration files organized by namespaces
 * Any other directory you like, still organized by namespaces
 
-You can also use the same directory you install soda without configure the user directory. You can
-access any file in that directories by using the **exists** function.
+You can also use the same directory you install soda without configure the user directory. You can access any file in that directories by using the **exists** function.
 
-Inside *scripts*, any function in any script present in *scripts/common* and exposed through
-**task** can be invoked:
+Inside *scripts*, any function in any script present in *scripts/common* and exposed through **task** can be invoked:
 
     task "git-open" "Creates a new branch off master"
     git_open() {
@@ -39,19 +33,15 @@ Inside *scripts*, any function in any script present in *scripts/common* and exp
 
     $ soda git-open work
 
-This will call the *git_open* function passing *work* as the arguments. By convention, you
-may call a function with underscores replacing them by hyphens. To execute the task without
-arguments, just use `soda git-open`.
+This will call the *git_open* function passing *work* as the arguments. By convention, you may call a function with underscores replacing them by hyphens. To execute the task without arguments, just use `soda git-open`.
 
 To see the program usage, type `soda`, `soda help` or `soda --help`.
 
 ## Task Namespaces
 
-The namespaces are simply directories in _scripts_. By default, the *common* and *soda* namespaces
-are always imported. You can include other namespaces using the **import** function.
+The namespaces are simply directories in _scripts_. By default, the *common* and *soda* namespaces are always imported. You can include other namespaces using the **import** function.
 
-Namespaces are useful if you have a set of scripts that you should use only on specific cases. (It
-also keeps your scripts organized.)
+Namespaces are useful if you have a set of scripts that you should use only on specific cases. (It also keeps your scripts organized.)
 
     # Example: script inside ~/.soda/scripts/git
 
@@ -80,15 +70,11 @@ You can call any task in *git* namespace using a **"."**:
 
     $ soda git.push
 
-The **"."** indicates that namespace is the first part and task is the second part. To see a help
-message for only one namespace, use `soda help NAMESPACE` (additionally, you can place a `info` file
-in the scripts folder for a namespace to make its contents appear in the help message).
+The **"."** indicates that namespace is the first part and task is the second part. To see a help message for only one namespace, use `soda help NAMESPACE` (additionally, you can place a `info`  file in the scripts folder for a namespace to make its contents appear in the help message).
 
 ## Task Parameters
 
-If you need to pass a set of parameters, you can use --OPTION_NAME in case of a boolean option or
---OPTION_NAME=OPTION_VALUE. The parameters will be translated replacing hyphens with underscores
-(but ignoring the prefix **--**) **with upper case**.
+If you need to pass a set of parameters, you can use --OPTION_NAME in case of a boolean option or --OPTION_NAME=OPTION_VALUE. The parameters will be translated replacing hyphens with underscores (but ignoring the prefix **--**) **with upper case**.
 
       $ soda --my-option=test
 
@@ -97,8 +83,7 @@ If you need to pass a set of parameters, you can use --OPTION_NAME in case of a
         # some code
       fi
 
-To register a parameter in the program usage, use the *parameter* function (for more details, see
-the documentation bellow). The registered parameters will also be available for bash completion.
+To register a parameter in the program usage, use the *parameter* function (for more details, see the documentation bellow). The registered parameters will also be available for bash completion.
 
 Keep in mind that **any** parameter will be converted to a variable (even those not exposed).
 
@@ -117,8 +102,7 @@ The builtin events are:
 
 * **start** - before the task execution
 * **finish** - after the task execution
-* **fail** *(exit code)* - when a command fails to execute (broadcasted by *execute* and *check*
-functions)
+* **fail** *(exit code)* - when a command fails to execute (broadcasted by *execute* and *check* functions)
 
 ## Quick Tasks
 
@@ -137,10 +121,7 @@ Any directory in the form `bin/$NAMESPACE` in both `$SODA_HOME` or `$SODA_USER_H
 
 ## Bash Completion
 
-SODA supports bash completion by importing all namespaces and searching for defined parameters
-and tasks. To enable bash completion, use the file **soda-bash-completion** (you can source it,
-copy to */etc/bash_completion.d/* or using your preferred way). The default bash completion proposes
-tasks and parameters.
+SODA supports bash completion by importing all namespaces and searching for defined parameters and tasks. To enable bash completion, use the file **soda-bash-completion** (you can source it, copy to */etc/bash_completion.d/* or using your preferred way). The default bash completion proposes tasks and parameters.
 
     $ soda he[TAB]
     $ soda help
@@ -163,8 +144,7 @@ Alternatively, you can use the **suggest** function to map the bash completion f
       echo "bar"
     }
 
-If a parameter is passed after the task declaration in command line, the suggestions will be only
-the parameters for the task namespace.
+If a parameter is passed after the task declaration in command line, the suggestions will be only the parameters for the task namespace.
 
     # namespace my-namespace
 
@@ -177,44 +157,32 @@ the parameters for the task namespace.
     $ soda my-namespace.my-task --[TAB]
     $ soda my-namespace.my-task --option
 
-It is important to remember that logs and event broadcasting are disabled while SODA is in bash
-completion mode.
+It is important to remember that logs and event broadcasting are disabled while SODA is in bash completion mode.
 
 ## Configuration
 
-Every namespace has it own configuration dir in $SODA_USER_HOME/config/NAMESPACE. Any configuration
-file will be loaded in that directory at namespace import **before** loading script files.
+Every namespace has it own configuration dir in $SODA_USER_HOME/config/NAMESPACE. Any configuration file will be loaded in that directory at namespace import **before** loading script files.
 
-You can configure **soda** namespace through a **$SODA_USER_HOME/conf/soda/soda.conf** file (or any
-other name but inside that directory). The supported properties are:
+You can configure **soda** namespace through a **$SODA_USER_HOME/conf/soda/soda.conf** file (or any other name but inside that directory). The supported properties are:
 
 * **LOG_FILE** - The log file  (defaults to *$SODA_HOME/log/soda.log*)
-* **SODA_NAMESPACE_DELIMITER** - The namespace delimiter (defaults to **.**). Changing this also
-affects the bash completion
-* **SODA_TASK_BASH_COMPLETION_SUFFIX** - The suffix to build the function for custom bash completion
-(defaults to *_bash_completion*)
+* **SODA_NAMESPACE_DELIMITER** - The namespace delimiter (defaults to **.**). Changing this also affects the bash completion
+* **SODA_TASK_BASH_COMPLETION_SUFFIX** - The suffix to build the function for custom bash completion (defaults to *_bash_completion*)
 * **SODA_FILE_LOG_PATTERN** - The pattern to format logs that goes in *LOG_FILE*
 * **SODA_CONSOLE_LOG_PATTERN** - The pattern to format logs that goes in console
 * **SODA_FUNCTION_NAME_LENGTH** - The max length to format the function name in the help usage
 * **SODA_PARAMETER_NAME_LENGTH** - The max length to format the parameter names in the help usage
-* **SODA_PARAMETER_NAMESPACE_LENGTH** - The max length to format the parameter namespace in the help
-usage
-* **SODA_DEFAULT_RESOURCE_DIR** - the default directory to search for resources (defaults to 
-*resources*)
+* **SODA_PARAMETER_NAMESPACE_LENGTH** - The max length to format the parameter namespace in the help usage
+* **SODA_DEFAULT_RESOURCE_DIR** - the default directory to search for resources (defaults to *resources*)
 * **SODA_TASK_OPTIONAL_PREFIX** - the optional prefix to map a task function (defaults to *do_*)
 
-Remember that parameters are converted to upper case, so you can call `soda --log-file=path/to/file`
-and the *$LOG_FILE* variable will be set to that value.
+Remember that parameters are converted to upper case, so you can call `soda --log-file=path/to/file` and the *$LOG_FILE* variable will be set to that value.
 
-The parameter **SODA_TASK_OPTIONAL_PREFIX** is very usefull in case of tasks with a name already
-defined by another function or name (*kill* or *status*, for example). To avoid conflicts, prefix
-the function with the SODA_TASK_OPTIONAL_PREFIX value (*do_kill*, *do_status*, ...).
+The parameter **SODA_TASK_OPTIONAL_PREFIX** is very usefull in case of tasks with a name already defined by another function or name (*kill* or *status*, for example). To avoid conflicts, prefix the function with the SODA_TASK_OPTIONAL_PREFIX value (*do_kill*, *do_status*, ...).
 
 ## Logging
 
-To log something, just call the **log** function passing the category and message (optionally, you
-can pass a color for showing in console). There are some aliases for calling log with a predefined
-category:
+To log something, just call the **log** function passing the category and message (optionally, you can pass a color for showing in console). There are some aliases for calling log with a predefined category:
 
 * **log_debug** - uses the DEBUG category
 * **log_info** - uses the INFO category
@@ -235,20 +203,15 @@ If you want to use another log system (a *syslog* or another) just define a **lo
 
 ## Builtin functions
 
-The builtin functions are present in *scripts/soda* dir and the *scripts/core.sh*, the
-most significant are listed below:
+The builtin functions are present in *scripts/soda* dir and the *scripts/core.sh*, the most significant are listed below:
 
 ### task (function_name, [function_args], [description])
 
-Register the given function as a task and enables invoking it. You may pass the function
-args in *$function_name*. If a description is given, expose the given function in the program usage
-and register it for autocompletion.
+Register the given function as a task and enables invoking it. You may pass the function args in *$function_name*. If a description is given, expose the given function in the program usage and register it for autocompletion.
 
 ### parameter (parameter_name, [value_name] ,[default_value], description)
 
-Register the given parameter and returns indicating if the parameter was given. The parameter value
-is accessible through the variable $parameter_name in upper case with hyphens replaced by
-underscores.
+Register the given parameter and returns indicating if the parameter was given. The parameter value is accessible through the variable $parameter_name in upper case with hyphens replaced by underscores.
 
     parameter "help" "Prints this help message" && {
       usage
@@ -260,19 +223,15 @@ underscores.
 
 ### exists ([type] path)
 
-Checks if the file $SODA_USER_HOME/$type/$NAMESPACE/$path exists using the namespace of the invoked
-task or imported namespace. The file path will be stored in the $FILE variable. If the *type* is not
-passed then **resources** will be used.
+Checks if the file $SODA_USER_HOME/$type/$NAMESPACE/$path exists using the namespace of the invoked task or imported namespace. The file path will be stored in the $FILE variable. If the *type* is not passed then **resources** will be used.
 
     exists config "my-config.conf" && {
       source $FILE
     }
 
 ### resource ([type] path)
 
-Returns the file $SODA_USER_HOME/$type/$NAMESPACE/$path using the namespace of the invoked task or
-imported namespace without checking if the file exists. If the *type* is not passed then
-**resources** will be used. For use with the **config** type, use the `config` builtin function.
+Returns the file $SODA_USER_HOME/$type/$NAMESPACE/$path using the namespace of the invoked task or imported namespace without checking if the file exists. If the *type* is not passed then **resources** will be used. For use with the **config** type, use the `config` builtin function. The `config` function redirects to the resource function using *config* as the first parameter and the given parameter as the second parameter.
 
 ### invoke (description, function_name)
 
@@ -288,13 +247,11 @@ Asks user about something and indicates if the answer is **yes** or **no**.
 
 ### check (description)
 
-Checks if the previous command returned successfully and logs the result using the given
-description.
+Checks if the previous command returned successfully and logs the result using the given description.
 
 ### execute (description, command, [*args])
 
-Executes a command and checks if it was sucessfull. The output will be stored in the variable
-*$LAST_EXECUTION_OUTPUT* and the result will be .
+Executes a command and checks if it was sucessfull. The output will be stored in the variable *$LAST_EXECUTION_OUTPUT* and the result will be .
 
     execute "Pushing commits" git push
     # outputs according to exit code:
@@ -303,8 +260,7 @@ Executes a command and checks if it was sucessfull. The output will be stored in
 
 ### input (description, variable, [default_value])
 
-Asks the user to input a value. The value will be stored in the indicated variable. If the variable
-name is in upper case and is already set, the prompt will be skipped.
+Asks the user to input a value. The value will be stored in the indicated variable. If the variable name is in upper case and is already set, the prompt will be skipped.
 
     input "Server address" "SERVER" "localhost"
     input "User name" "USER_NAME" "$(whoami)"
@@ -313,9 +269,7 @@ name is in upper case and is already set, the prompt will be skipped.
 
 ### choose (description, variable, *options)
 
-Asks user to choose a value from a list of options and stores the 0-based index
-of the selected value and the label in the $variable_label var. If the variable name
-is in upper case and is already set, the prompt will be skipped.
+Asks user to choose a value from a list of options and stores the 0-based index of the selected value and the label in the $variable_label var. If the variable name is in upper case and is already set, the prompt will be skipped.
 
     choose "Server Type" "SERVER_TYPE" "Production" "Development"
 
@@ -327,8 +281,7 @@ Maps the given function as the bash completion function to the given tasks.
 
 ### when (event_name subscribers...)
 
-Subscribe the given functions to the specified event name. The subscribers should be notified using
-the *broadcast* function.
+Subscribe the given functions to the specified event name. The subscribers should be notified using the *broadcast* function.
 
 ### broadcast (event_name [args...])