Add support for color usage elements

Runfile

@@ -59,6 +59,9 @@ end
 
 help   "Append the content of bashly.yml to all example READMEs"
 action :examples do
+  # Disable color output (for the color examples)
+  ENV['NO_COLOR']='1'
+
   # Patch the PATH to allow the extensible example to run properly
   ENV['PATH']="#{Dir.pwd}/examples/extensible:#{ENV['PATH']}"
   Example.all.each do |example|

examples/README.md

@@ -39,6 +39,7 @@ Each of these examples demonstrates one aspect or feature of bashly.
 
 ## Customization
 
+- [colors-usage](colors-usage#readme) - adding colors to the usage text
 - [command-groups](command-groups#readme) - grouping sub-commands in logical sections
 - [custom-strings](custom-strings#readme) - configuring the script's error and usage texts
 - [custom-includes](custom-includes#readme) - adding and organizing your custom functions

examples/colors-usage/.gitignore

@@ -0,0 +1 @@
+cli

examples/colors-usage/README.md

@@ -0,0 +1,189 @@
+# Colors Usage Example
+
+This example demonstrates how to apply colors to various usage elements.
+
+This example was generated with:
+
+```bash
+$ bashly init
+$ bashly add colors
+$ bashly add settings
+# ... now edit settings.yml to match the example ...
+$ bashly generate
+```
+
+The `bashly add colors` command, simply created the [src/lib/colors.sh]
+(src/lib/colors.sh) file, with useful color functions that will be
+automatically included in the generated script.
+
+The manually modified `settings.yml` file specifies which color function is
+used for which usage element.
+
+Note that the output displayed in this README is not colored.
+
+<!-- include: settings.yml -->
+
+-----
+
+## `bashly.yml`
+
+```yaml
+name: cli
+help: Sample application
+version: 0.1.0
+
+environment_variables:
+- name: api_key
+  help: Set your API key
+
+commands:
+- name: download
+  alias: d
+  help: Download a file
+
+  args:
+  - name: source
+    required: true
+    help: URL to download from
+  - name: target
+    help: "Target filename (default: same as source)"
+
+  flags:
+  - long: --force
+    short: -f
+    help: Overwrite existing files
+
+  examples:
+  - cli download example.com
+  - cli download example.com ./output -f
+
+  environment_variables:
+  - name: default_target_location
+    help: Set the default location to download to
+
+- name: upload
+  alias: u
+  help: Upload a file
+  args:
+  - name: source
+    required: true
+    help: File to upload
+
+  flags:
+  - long: --user
+    short: -u
+    arg: user
+    help: Username to use for logging in
+    required: true
+  - long: --password
+    short: -p
+    arg: password
+    help: Password to use for logging in
+```
+
+## `settings.yml`
+
+```yaml
+# Display various usage elements in color by providing the name of the color
+# function. The value for each property is a name of a function that is
+# available in your script, for example: `green` or `bold`.
+# You can run `bashly add colors` to add a standard colors library.
+# This option cannot be set via environment variables.
+usage_colors:
+  caption: bold
+  command: green
+  arg: blue
+  flag: magenta
+  environment_variable: cyan
+
+```
+
+
+## Generated script output
+
+### `$ ./cli`
+
+```shell
+cli - Sample application
+
+Usage:
+  cli COMMAND
+  cli [COMMAND] --help | -h
+  cli --version | -v
+
+Commands:
+  download   Download a file
+  upload     Upload a file
+
+
+
+```
+
+### `$ ./cli -h`
+
+```shell
+cli - Sample application
+
+Usage:
+  cli COMMAND
+  cli [COMMAND] --help | -h
+  cli --version | -v
+
+Commands:
+  download   Download a file
+  upload     Upload a file
+
+Options:
+  --help, -h
+    Show this help
+
+  --version, -v
+    Show version number
+
+Environment Variables:
+  API_KEY
+    Set your API key
+
+
+
+```
+
+### `$ ./cli download -h`
+
+```shell
+cli download - Download a file
+
+Alias: d
+
+Usage:
+  cli download SOURCE [TARGET] [OPTIONS]
+  cli download --help | -h
+
+Options:
+  --help, -h
+    Show this help
+
+  --force, -f
+    Overwrite existing files
+
+Arguments:
+  SOURCE
+    URL to download from
+
+  TARGET
+    Target filename (default: same as source)
+
+Environment Variables:
+  DEFAULT_TARGET_LOCATION
+    Set the default location to download to
+
+Examples:
+  cli download example.com
+  cli download example.com ./output -f
+
+
+
+```
+
+
+

examples/colors-usage/settings.yml

@@ -0,0 +1,11 @@
+# Display various usage elements in color by providing the name of the color
+# function. The value for each property is a name of a function that is
+# available in your script, for example: `green` or `bold`.
+# You can run `bashly add colors` to add a standard colors library.
+# This option cannot be set via environment variables.
+usage_colors:
+  caption: bold
+  command: green
+  arg: blue
+  flag: magenta
+  environment_variable: cyan

examples/colors-usage/src/bashly.yml

@@ -0,0 +1,51 @@
+name: cli
+help: Sample application
+version: 0.1.0
+
+environment_variables:
+- name: api_key
+  help: Set your API key
+
+commands:
+- name: download
+  alias: d
+  help: Download a file
+
+  args:
+  - name: source
+    required: true
+    help: URL to download from
+  - name: target
+    help: "Target filename (default: same as source)"
+
+  flags:
+  - long: --force
+    short: -f
+    help: Overwrite existing files
+
+  examples:
+  - cli download example.com
+  - cli download example.com ./output -f
+
+  environment_variables:
+  - name: default_target_location
+    help: Set the default location to download to
+
+- name: upload
+  alias: u
+  help: Upload a file
+  args:
+  - name: source
+    required: true
+    help: File to upload
+
+  flags:
+  - long: --user
+    short: -u
+    arg: user
+    help: Username to use for logging in
+    required: true
+  - long: --password
+    short: -p
+    arg: password
+    help: Password to use for logging in

examples/colors-usage/src/download_command.sh

@@ -0,0 +1,4 @@
+echo "# this file is located in 'src/download_command.sh'"
+echo "# code for 'cli download' goes here"
+echo "# you can edit it freely and regenerate (it will not be overwritten)"
+inspect_args

examples/colors-usage/src/initialize.sh

@@ -0,0 +1,6 @@
+## Code here runs inside the initialize() function
+## Use it for anything that you need to run before any other function, like
+## setting environment variables:
+## CONFIG_FILE=settings.ini
+##
+## Feel free to empty (but not delete) this file.

examples/colors-usage/src/lib/colors.sh

@@ -0,0 +1,42 @@
+## Color functions [@bashly-upgrade colors]
+## This file is a part of Bashly standard library
+##
+## Usage:
+## Use any of the functions below to color or format a portion of a string.
+##
+##   echo "before $(red this is red) after"
+##   echo "before $(green_bold this is green_bold) after"
+##
+## Color output will be disabled if `NO_COLOR` environment variable is set
+## in compliance with https://no-color.org/
+##
+print_in_color() {
+  local color="$1"
+  shift
+  if [[ -z ${NO_COLOR+x} ]]; then
+    printf "$color%b\e[0m\n" "$*"
+  else
+    printf "%b\n" "$*"
+  fi
+}
+
+red() { print_in_color "\e[31m" "$*"; }
+green() { print_in_color "\e[32m" "$*"; }
+yellow() { print_in_color "\e[33m" "$*"; }
+blue() { print_in_color "\e[34m" "$*"; }
+magenta() { print_in_color "\e[35m" "$*"; }
+cyan() { print_in_color "\e[36m" "$*"; }
+bold() { print_in_color "\e[1m" "$*"; }
+underlined() { print_in_color "\e[4m" "$*"; }
+red_bold() { print_in_color "\e[1;31m" "$*"; }
+green_bold() { print_in_color "\e[1;32m" "$*"; }
+yellow_bold() { print_in_color "\e[1;33m" "$*"; }
+blue_bold() { print_in_color "\e[1;34m" "$*"; }
+magenta_bold() { print_in_color "\e[1;35m" "$*"; }
+cyan_bold() { print_in_color "\e[1;36m" "$*"; }
+red_underlined() { print_in_color "\e[4;31m" "$*"; }
+green_underlined() { print_in_color "\e[4;32m" "$*"; }
+yellow_underlined() { print_in_color "\e[4;33m" "$*"; }
+blue_underlined() { print_in_color "\e[4;34m" "$*"; }
+magenta_underlined() { print_in_color "\e[4;35m" "$*"; }
+cyan_underlined() { print_in_color "\e[4;36m" "$*"; }

examples/colors-usage/src/upload_command.sh

@@ -0,0 +1,4 @@
+echo "# this file is located in 'src/upload_command.sh'"
+echo "# code for 'cli upload' goes here"
+echo "# you can edit it freely and regenerate (it will not be overwritten)"
+inspect_args

examples/colors-usage/test.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+
+set -x
+
+bashly generate
+
+### Try Me ###
+
+./cli
+./cli -h
+./cli download -h
+

examples/colors/README.md

@@ -56,11 +56,11 @@ echo
 ### `$ ./colorly`
 
 ```shell
-Message Recevied:
+Message Recevied:
 
-  => hello colors
-  ==> hello colors
-  ===> hello colors
+  => hello colors
+  ==> hello colors
+  ===> hello colors
 
 
 

examples/conflicts/README.md

@@ -59,7 +59,7 @@ Options:
     Enable cache
 
   --no-cache
-    Diisable cache
+    Disable cache
 
   --fast
     Run faster