Add support for examples and env vars usage text

README.md

@@ -79,6 +79,10 @@ flags:
 - long: --force
  short: -f
  help: Overwrite existing files
+
+examples:
+- download example.com
+- download example.com ./output -f
 ```
 
 
@@ -91,6 +95,9 @@ name: cli
 help: Sample application
 version: 0.1.0
 
+environment_variables:
+ API_KEY: Set your API key
+
 commands:
 - name: download
  short: d
@@ -108,6 +115,13 @@ commands:
  short: -f
  help: Overwrite existing files
 
+ examples:
+ - cli download example.com
+ - cli download example.com ./output -f
+
+ environment_variables:
+ DEFAULT_TARGET_LOCATION: Set the default location to download to
+
 - name: upload
  short: u
  help: Upload a file
@@ -134,7 +148,7 @@ Configuration Reference
 
 ### Command options
 
-With the exception of `version` and `commands` (shich define subcommands),
+With the exception of `version` and `commands` (which define subcommands),
 everything else in this section is suitable both for the main script, and for
 any subcommand you define using `commands`.
 
@@ -150,6 +164,16 @@ help: a sample script generated with bashly
 # The string to display when using --version
 version: 0.1.0
 
+# Specify an array of examples to show when using --help
+examples:
+- myscript download
+- myscript download --force
+
+# Specify an array of environment variables needed by your script
+# This is used purely for displaying in the help text (when using --help)
+environment_variable:
+ VARIABLE_NAME: Variable help text
+
 # Specify the array of subcommands to generate.
 # Each subcommand will have its own args and flags.
 # If this is provided, then you cannot provide flags or args for the main

examples/custom-strings/download

@@ -49,6 +49,8 @@ download_usage() {
  echo " URL to download from"
  echo
 
+
+
  fi
 }
 

examples/minimal/download

@@ -51,6 +51,12 @@ download_usage() {
  echo " Target filename (default: same as source)"
  echo
 
+ # :command.usage_examples
+ echo -e "Examples:"
+ echo " download example.com"
+ echo " download example.com ./output -f"
+ echo
+
  fi
 }
 

examples/minimal/src/bashly.yml

@@ -14,3 +14,6 @@ flags:
  short: -f
  help: Overwrite existing files
 
+examples:
+- download example.com
+- download example.com ./output -f

examples/subcommands/cli

@@ -32,6 +32,12 @@ cli_usage() {
  echo
 
 
+ # :command.usage_environment_variables
+ echo -e "Environment Variables:"
+ echo " API_KEY"
+ echo " Set your API key"
+ echo
+
 
  fi
 }
@@ -71,6 +77,16 @@ cli_download_usage() {
  echo " TARGET"
  echo " Target filename (default: same as source)"
  echo
+ # :command.usage_environment_variables
+ echo -e "Environment Variables:"
+ echo " DEFAULT_TARGET_LOCATION"
+ echo " Set the default location to download to"
+ echo
+ # :command.usage_examples
+ echo -e "Examples:"
+ echo " cli download example.com"
+ echo " cli download example.com ./output -f"
+ echo
 
  fi
 }
@@ -112,6 +128,8 @@ cli_upload_usage() {
  echo " File to upload"
  echo
 
+
+
  fi
 }
 

examples/subcommands/src/bashly.yml

@@ -2,6 +2,9 @@ name: cli
 help: Sample application
 version: 0.1.0
 
+environment_variables:
+ API_KEY: Set your API key
+
 commands:
 - name: download
  short: d
@@ -19,6 +22,13 @@ commands:
  short: -f
  help: Overwrite existing files
 
+ examples:
+ - cli download example.com
+ - cli download example.com ./output -f
+
+ environment_variables:
+ DEFAULT_TARGET_LOCATION: Set the default location to download to
+
 - name: upload
  short: u
  help: Upload a file

lib/bashly/models/base.rb

@@ -8,6 +8,8 @@ class Base
  OPTION_KEYS = %i[
  arg
  description
+ environment_variables
+ examples
  flags
  help
  long

lib/bashly/templates/bashly.yml

@@ -2,6 +2,9 @@ name: cli
 help: Sample application
 version: 0.1.0
 
+environment_variables:
+ API_KEY: Set your API key
+
 commands:
 - name: download
  short: d
@@ -19,6 +22,13 @@ commands:
  short: -f
  help: Overwrite existing files
 
+ examples:
+ - cli download example.com
+ - cli download example.com ./output -f
+
+ environment_variables:
+ DEFAULT_TARGET_LOCATION: Set the default location to download to
+
 - name: upload
  short: u
  help: Upload a file

lib/bashly/templates/minimal.yml

@@ -14,3 +14,6 @@ flags:
  short: -f
  help: Overwrite existing files
 
+examples:
+- download example.com
+- download example.com ./output -f

lib/bashly/templates/strings.yml

@@ -3,6 +3,8 @@ usage: "Usage:"
 options: "Options:"
 arguments: "Arguments:"
 commands: "Commands:"
+examples: "Examples:"
+environment_variables: "Environment Variables:"
 
 # Fixed flags help text
 show_this_help: Show this help

lib/bashly/views/command/usage.erb

@@ -12,6 +12,8 @@
 <%= render(:usage_fixed_flags).indent 4 %>
 <%= render(:usage_flags).indent 4 if flags.any? %>
 <%= render(:usage_args).indent 4 if args.any? %>
+<%= render(:usage_environment_variables).indent 4 if environment_variables %>
+<%= render(:usage_examples).indent 4 if examples %>
 
  fi
 }

lib/bashly/views/command/usage_environment_variables.erb

@@ -0,0 +1,7 @@
+# :command.usage_environment_variables
+echo -e "<%= strings[:environment_variables] %>"
+<%- environment_variables.each do |name, description| -%>
+echo " <%= name %>"
+echo " <%= description %>"
+<%- end -%>
+echo

lib/bashly/views/command/usage_examples.erb

@@ -0,0 +1,6 @@
+# :command.usage_examples
+echo -e "<%= strings[:examples] %>"
+<%- examples.each do |example| -%>
+echo " <%= example %>"
+<%- end -%>
+echo

spec/approvals/examples/minimal

@@ -30,6 +30,10 @@ Arguments:
  TARGET
  Target filename (default: same as source)
 
+Examples:
+ download example.com
+ download example.com ./output -f
+
 + ./download --version
 0.1.0
 + ./download somesource -f

spec/approvals/examples/subcommands

@@ -32,6 +32,10 @@ Options:
  --version
  Show version number
 
+Environment Variables:
+ API_KEY
+ Set your API key
+
 + ./cli --version
 0.1.0
 + ./cli download -h
@@ -57,6 +61,14 @@ Arguments:
  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
+
 + ./cli download
 missing required argument: SOURCE
 usage: cli download SOURCE [TARGET] [options]