Merge pull request #530 from DannyBen/add/show-examples-on-error

Add `show_examples_on_error` setting

examples/README.md

@@ -38,6 +38,7 @@ Each of these examples demonstrates one aspect or feature of bashly.
 - [filters](filters#readme) - preventing commands from running unless custom conditions are met
 - [commands-expose](commands-expose#readme) - showing sub-commands in the parent's help
 - [key-value-pairs](key-value-pairs#readme) - parsing key=value arguments and flags
+- [command-examples-on-error](command-examples-on-error#readme) - showing examples on error
 
 ## Customization
 

examples/command-examples-on-error/.gitignore

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

examples/command-examples-on-error/README.md

@@ -0,0 +1,119 @@
+# Command Examples on Error Example
+
+Demonstrates how to show examples whenever the user does not provide all the
+required arguments.
+
+This example was generated with:
+
+```bash
+$ bashly init
+# ... now edit src/bashly.yml to match the example ...
+$ bashly add settings
+# ... now edit settings.yml to match the example ...
+$ bashly generate
+```
+
+<!-- include: settings.yml -->
+
+-----
+
+## `bashly.yml`
+
+````yaml
+name: cli
+help: Sample application
+version: 0.1.0
+
+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 can be provided either as an array, or as a string.
+  # The array form is convenient when you just want to provide one-liner
+  # examples.
+  examples:
+  - cli download example.com
+  - cli download example.com ./output -f
+
+- 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
+
+  # The string form examples is useful when you wish to have more control
+  # over how the examples are displayed. Note the use of the '|-' marker
+  # that tells YAML to use the string as is, including the newlines it contains.
+  examples: |-
+    Upload a file
+    $ cli upload profile.png -u admin -p s3cr3t
+
+    Upload a file (you will be prompted to provide a password)
+    $ cli upload profile.png --user admin
+````
+
+## `settings.yml`
+
+````yaml
+show_examples_on_error: true
+
+````
+
+
+## Output
+
+### `$ ./cli download`
+
+````shell
+missing required argument: SOURCE
+usage: cli download SOURCE [TARGET] [OPTIONS]
+examples:
+  cli download example.com
+  cli download example.com ./output -f
+
+
+````
+
+### `$ ./cli upload`
+
+````shell
+missing required argument: SOURCE
+usage: cli upload SOURCE [OPTIONS]
+examples:
+  Upload a file
+  $ cli upload profile.png -u admin -p s3cr3t
+
+  Upload a file (you will be prompted to provide a password)
+  $ cli upload profile.png --user admin
+
+
+````
+
+
+

examples/command-examples-on-error/settings.yml

@@ -0,0 +1 @@
+show_examples_on_error: true

examples/command-examples-on-error/src/bashly.yml

@@ -0,0 +1,58 @@
+name: cli
+help: Sample application
+version: 0.1.0
+
+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 can be provided either as an array, or as a string.
+  # The array form is convenient when you just want to provide one-liner
+  # examples.
+  examples:
+  - cli download example.com
+  - cli download example.com ./output -f
+
+- 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
+
+  # The string form examples is useful when you wish to have more control
+  # over how the examples are displayed. Note the use of the '|-' marker
+  # that tells YAML to use the string as is, including the newlines it contains.
+  examples: |-
+    Upload a file
+    $ cli upload profile.png -u admin -p s3cr3t
+
+    Upload a file (you will be prompted to provide a password)
+    $ cli upload profile.png --user admin
+
+    

examples/command-examples-on-error/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/command-examples-on-error/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/command-examples-on-error/test.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+
+rm -f ./src/*.sh
+
+set -x
+
+bashly generate
+
+### Try Me ###
+
+./cli download
+./cli upload

lib/bashly/libraries/settings/settings.yml

@@ -55,6 +55,10 @@ env: development
 # The extension to use when reading/writing partial script snippets
 partials_extension: sh
 
+# Show command examples (if any) whenever the user does not provide the
+# required arguments
+show_examples_on_error: false
+
 # 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`.

lib/bashly/libraries/strings/strings.yml

@@ -33,6 +33,7 @@ missing_required_argument: "missing required argument: %{arg}\\nusage: %{usage}"
 missing_required_flag: "missing required flag: %{usage}"
 missing_required_environment_variable: "missing required environment variable: %{var}"
 missing_dependency: "missing dependency: %{dependency}"
+examples_caption_on_error: 'examples:'
 disallowed_flag: "%{name} must be one of: %{allowed}"
 disallowed_argument: "%{name} must be one of: %{allowed}"
 disallowed_environment_variable: "%{name} environment variable must be one of: %{allowed}"

lib/bashly/settings.rb

@@ -10,6 +10,7 @@ class << self
         :config_path,
         :lib_dir,
         :partials_extension,
+        :show_examples_on_error,
         :source_dir,
         :strict,
         :tab_indent,
@@ -57,6 +58,10 @@ def production?
         env == :production
       end
 
+      def show_examples_on_error
+        @show_examples_on_error ||= get :show_examples_on_error
+      end
+
       def source_dir
         @source_dir ||= get :source_dir
       end

lib/bashly/views/command/examples_on_error.gtx

@@ -0,0 +1,8 @@
+if Settings.show_examples_on_error && examples.any? 
+  = view_marker
+
+  > printf "{{ strings[:examples_caption_on_error] }}\n" >&2
+  examples.each do |example|
+    > printf "{{ example.wrap(78).indent(2).sanitize_for_print }}\n" >&2
+  end
+end

lib/bashly/views/command/required_args_filter.gtx

@@ -4,10 +4,10 @@ if required_args.any?
   required_args.each do |arg|
     > if [[ -z ${args['{{ arg.name }}']+x} ]]; then
     >   printf "{{ strings[:missing_required_argument] % { arg: arg.name.upcase, usage: usage_string } }}\n" >&2
+    = render(:examples_on_error).indent 2
     >   exit 1
     > fi
   end
 
   >
-
-end
+end

schemas/settings.json

@@ -97,7 +97,7 @@
         },
         "tab_indent": {
             "title": "tab indent",
-            "description": "Whether to use tabs or spaces in the the generated script\nhttps://bashly.dannyb.co/usage/settings/#tab_indent",
+            "description": "Whether to use tabs or spaces in the generated script\nhttps://bashly.dannyb.co/usage/settings/#tab_indent",
             "type": "boolean",
             "default": false
         },
@@ -113,6 +113,12 @@
             "type": "boolean",
             "default": true
         },
+        "show_examples_on_error": {
+            "title": "show examples on error",
+            "description": "Whether to show command examples when the input line is missing required arguments\nhttps://bashly.dannyb.co/usage/settings/#show_examples_on_error",
+            "type": "boolean",
+            "default": true
+        },
         "env": {
             "title": "env",
             "description": "Whether to include development related comments in the generated script\nhttps://bashly.dannyb.co/usage/settings/#env",

schemas/strings.json

@@ -102,6 +102,13 @@
             "minLength": 1,
             "default": "Allowed: %{values}"
         },
+        "examples_caption_on_error": {
+            "title": "examples caption on error",
+            "description": "The string to show before the examples when show_examples_on_error is enabled\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
+            "type": "string",
+            "minLength": 1,
+            "default": "examples:"
+        },
         "help_flag_text": {
             "title": "help flag text",
             "description": "The help message for --help\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",

spec/approvals/examples/command-examples-on-error

@@ -0,0 +1,21 @@
++ bashly generate
+creating user files in src
+created src/download_command.sh
+created src/upload_command.sh
+created ./cli
+run ./cli --help to test your bash script
++ ./cli download
+missing required argument: SOURCE
+usage: cli download SOURCE [TARGET] [OPTIONS]
+examples:
+  cli download example.com
+  cli download example.com ./output -f
++ ./cli upload
+missing required argument: SOURCE
+usage: cli upload SOURCE [OPTIONS]
+examples:
+  Upload a file
+  $ cli upload profile.png -u admin -p s3cr3t
+
+  Upload a file (you will be prompted to provide a password)
+  $ cli upload profile.png --user admin

spec/bashly/script/command_spec.rb

@@ -627,7 +627,6 @@
         expect(subject.default_command.usage_string).to eq 'cli [get]'
       end
     end
-
   end
 
   describe '#user_file_path' do