Merge pull request #318 from DannyBen/add/bashly-doc

Add `bashly doc` command to show reference in the terminal

Author: DannyBen

lib/bashly/cli.rb

@@ -14,6 +14,7 @@ def self.runner
       runner.route 'validate',  to: Commands::Validate
       runner.route 'generate',  to: Commands::Generate
       runner.route 'add',       to: Commands::Add
+      runner.route 'doc',       to: Commands::Doc
 
       runner
     end

lib/bashly/commands/doc.rb

@@ -0,0 +1,90 @@
+module Bashly
+  module Commands
+    class Doc < Base
+      summary 'Show bashly reference documentation'
+      help 'This command displays bite-sized help for all the bashly configuration options in the terminal.'
+
+      usage 'bashly doc [SEARCH] [--index]'
+      usage 'bashly doc (-h|--help)'
+
+      option '-i --index', 'Show option keys only'
+      param 'SEARCH', 'Search for options that match this text'
+
+      example 'bashly doc command'
+      example 'bashly doc command.flags'
+      example 'bashly doc flag. -i'
+      example 'bashly doc catch_all'
+
+      def run
+        if args['--index']
+          puts data.keys
+        else
+          show
+        end
+      end
+
+    private
+
+      def show
+        data.each do |key, info|
+          show_key key
+          show_help info['help']
+          show_example info['example'] if info['example']
+          show_url info['url'] if info['url']
+        end
+      end
+
+      def show_key(key)
+        say "!txtgrn!#{key}"
+        say ''
+      end
+
+      def show_url(url)
+        say "  See !undblu!#{url}"
+        say ''
+      end
+
+      def show_example(example)
+        example = word_wrap "    #{example}"
+        example.gsub!(/^(\s*- )?(\s*\w+):/, '\1!txtblu!\2!txtrst!:')
+        example.gsub!(/^(\s*- )/, '!txtylw!\1!txtrst!')
+        example.gsub!(/^(\s*#.+)/, '!txtpur!\1!txtrst!')
+        say example
+        say ''
+      end
+
+      def show_help(help)
+        help = word_wrap "  #{help}"
+        help.gsub!(/`([^`]+)`/, '!txtgrn!\1!txtrst!')
+        say help
+        say ''
+      end
+
+      def data
+        return raw_data unless args['SEARCH']
+
+        result = raw_data.select { |k, _v| k.== args['SEARCH'] }
+        return result if result.any?
+
+        result = raw_data.select { |k, _v| k.include? args['SEARCH'] }
+        return result if result.any?
+
+        raise Error, "No match"
+      end
+
+      def raw_data
+        @raw_data ||= begin
+          result = {}
+          Dir["#{docs_dir}/*.yml"].sort.each do |path|
+            result.merge! YAML.load_file(path)
+          end
+          result
+        end
+      end
+
+      def docs_dir
+        @docs_dir ||= File.expand_path '../docs', __dir__
+      end
+    end
+  end
+end

lib/bashly/docs/arg.yml

@@ -0,0 +1,94 @@
+arg:
+  help: Define positional arguments.
+  url: https://bashly.dannyb.co/configuration/argument/
+  example: |-
+    args:
+    - name: user
+      help: AWS Username.
+      required: true
+
+    - name: role
+      help: User role.
+      default: admin
+      allowed:
+      - admin
+      - guest
+
+arg.allowed:
+  help: Specify a list of allowed values. Can be used in conjunction with `default` and `required`.
+  url: https://bashly.dannyb.co/configuration/argument/#allowed
+  example: |-
+    args:
+    - name: region
+      help: Region to connect to
+      
+      # allowed + required
+      allowed: [eu, us]
+      required: true
+
+    - name: environment
+      help: Environment to connect to
+      
+      # allowed + default
+      allowed: [stage, production, development]
+      default: development
+
+arg.default:
+  help: Specify the value to apply when not provided by the user.
+  url: https://bashly.dannyb.co/configuration/argument/#default
+  example: |-
+    args:
+    - name: images
+      help: Image files to convert.
+      default: "*.jpg"
+
+arg.help:
+  help: Specify the help message for this argument.
+  url: https://bashly.dannyb.co/configuration/argument/#help
+  example: |-
+    args:
+    - name: user
+      help: AWS Username.
+      required: true
+
+arg.name:
+  help: Specify the lowercase name of the argument.
+  url: https://bashly.dannyb.co/configuration/argument/#name
+  example: |-
+    args:
+    - name: user
+      help: AWS Username.
+      required: true
+
+arg.repeatable:
+  help: |-
+    Specify that this argument can be provided multiple times.
+
+    The argument below will be received as a space-delimited string which needs to be converted to an array with:
+    `eval "data=(${args[file]})"`
+
+  url: https://bashly.dannyb.co/configuration/argument/#repeatable
+  example: |-
+    args:
+    - name: file
+      help: One or more files to process
+      required: true
+      repeatable: true
+
+arg.required:
+  help: Specify that this argument is required.
+  url: https://bashly.dannyb.co/configuration/argument/#required
+  example: |-
+    args:
+    - name: region
+      help: Region to connect to
+      required: true
+
+arg.validate:
+  help: Apply custom validation functions.
+
+  url: https://bashly.dannyb.co/configuration/argument/#validate
+  example: |-
+    args:
+    - name: path
+      validate: file_exists