- Add show_examples_on_error setting

Author: DannyBen

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",