bashly 1.3.7 → 1.4.0.rc1

data/lib/bashly/completions/completely.yaml

@@ -1,155 +1,141 @@
-bashly:
-- --help
-- -h
-- --version
-- -v
-- init
-- preview
-- validate
-- generate
-- add
-- doc
-- completions
-- shell
-
-bashly init: &init
-- --help
-- -h
-- --minimal
-- -m
-
-bashly i: *init
-
-bashly preview: &preview
-- --help
-- -h
-
-bashly p: *preview
-
-bashly validate: &validate
-- --help
-- -h
-- --verbose
-- -v
-
-bashly v: *validate
-
-bashly generate: &generate
-- --help
-- -h
-- --env
-- --force
-- --quiet
-- --upgrade
-- --watch
-- --wrap
-- -e
-- -f
-- -q
-- -r
-- -u
-- -w
-
-bashly g: *generate
-
-bashly generate*--env: &env
-- development
-- production
-
-bashly generate*-e: *env
-bashly g*--env: *env
-bashly g*-e: *env
-
-bashly add: &add
-- --help
-- -h
-- --force
-- --list
-- --source
-- -f
-- -l
-- -s
-- colors
-- completions
-- completions_script
-- completions_yaml
-- config
-- help
-- hooks
-- lib
-- settings
-- strings
-- test
-- validations
-- yaml
-
-bashly a: *add
-
-bashly doc: &doc
-- --help
-- -h
-- --index
-- -i
-- arg
-- arg.allowed
-- arg.default
-- arg.help
-- arg.name
-- arg.repeatable
-- arg.required
-- arg.validate
-- command
-- command.alias
-- command.args
-- command.catch_all
-- command.commands
-- command.completions
-- command.default
-- command.dependencies
-- command.environment_variables
-- command.examples
-- command.expose
-- command.extensible
-- command.filename
-- command.filters
-- command.flags
-- command.footer
-- command.function
-- command.group
-- command.help
-- command.name
-- command.private
-- command.version
-- environment_variable
-- environment_variable.default
-- environment_variable.help
-- environment_variable.name
-- environment_variable.private
-- environment_variable.required
-- flag
-- flag.allowed
-- flag.arg
-- flag.completions
-- flag.conflicts
-- flag.default
-- flag.help
-- flag.long
-- flag.private
-- flag.repeatable
-- flag.required
-- flag.short
-- flag.validate
-
-bashly completions: &completions
-- --help
-- -h
-- --install
-- -i
-
-bashly c: *completions
-
-bashly shell: &shell
-- --help
-- -h
-
-bashly s: *shell
+patterns:
+- bashly [root options]
+- bashly init|i [init options]
+- bashly preview|p [preview options]
+- bashly validate|v [validate options]
+- bashly generate|build|g [generate options]
+- bashly add|a [add options] <library>
+- bashly doc [doc options] <doc>
+- bashly completions|c [completions options]
+- bashly render [render options] <render_source>
+- bashly shell|s [shell options]
+
+options:
+  root:
+    - --help|-h
+    - --version|-v
+  init:
+    - --help|-h
+    - --minimal|-m
+  preview:
+    - --help|-h
+  validate:
+    - --help|-h
+    - --verbose|-v
+  generate:
+    - --help|-h
+    - --env|-e <env>
+    - --force|-f
+    - --quiet|-q
+    - --upgrade|-u
+    - --watch|-w
+    - --wrap|-r <function>
+  add:
+    - --help|-h
+    - --force|-f
+    - --list|-l
+    - --source|-s <source>
+  doc:
+    - --help|-h
+    - --index|-i
+  completions:
+    - --help|-h
+    - --install|-i
+    - --uninstall|-u
+  render:
+    - --help|-h
+    - --watch|-w
+    - --show|-s <path>
+    - --list|-l
+    - --about|-a
+  shell:
+    - --help|-h
+
+tokens:
+  env:
+    - development
+    - production
+  function:
+  source:
+  path:
+  library:
+    - colors
+    - completions
+    - completions_script
+    - completions_yaml
+    - config
+    - help
+    - hooks
+    - ini
+    - lib
+    - render_markdown
+    - render_markdown_github
+    - render_mandoc
+    - settings
+    - stacktrace
+    - strings
+    - validations
+    - yaml
+  doc:
+    - arg
+    - arg.allowed
+    - arg.completions
+    - arg.default
+    - arg.help
+    - arg.name
+    - arg.repeatable
+    - arg.required
+    - arg.validate
+    - command
+    - command.alias
+    - command.args
+    - command.catch_all
+    - command.commands
+    - command.completions
+    - command.default
+    - command.dependencies
+    - command.environment_variables
+    - command.examples
+    - command.expose
+    - command.extensible
+    - command.filename
+    - command.filters
+    - command.flags
+    - command.footer
+    - command.function
+    - command.group
+    - command.help
+    - command.help_header_override
+    - command.name
+    - command.private
+    - command.variables
+    - command.version
+    - environment_variable
+    - environment_variable.default
+    - environment_variable.help
+    - environment_variable.name
+    - environment_variable.private
+    - environment_variable.required
+    - environment_variable.validate
+    - flag
+    - flag.allowed
+    - flag.arg
+    - flag.completions
+    - flag.conflicts
+    - flag.default
+    - flag.help
+    - flag.long
+    - flag.needs
+    - flag.private
+    - flag.repeatable
+    - flag.required
+    - flag.short
+    - flag.unique
+    - flag.validate
+    - variable
+    - variable.name
+    - variable.value
+  render_source:
+    - ":mandoc"
+    - ":markdown"
+    - ":markdown_github"

data/lib/bashly/completions/completely.yaml.gtx

@@ -1,85 +1,72 @@
-> bashly:
+> patterns:
+> - bashly [root options]
+> - bashly init|i [init options]
+> - bashly preview|p [preview options]
+> - bashly validate|v [validate options]
+> - bashly generate|build|g [generate options]
+> - bashly add|a [add options] <library>
+> - bashly doc [doc options] <doc>
+> - bashly completions|c [completions options]
+> - bashly render [render options] <render_source>
+> - bashly shell|s [shell options]
+>
+> options:
+>   root:
 = help_flags
-> - --version
-> - -v
-commands.each do |command|
-  = "- #{command}"
-end
-> 
-> bashly init: &init
+>     - --version|-v
+>   init:
+= help_flags
+>     - --minimal|-m
+>   preview:
+= help_flags
+>   validate:
 = help_flags
-> - --minimal
-> - -m
-> 
-> bashly i: *init
-> 
-> bashly preview: &preview
+>     - --verbose|-v
+>   generate:
 = help_flags
-> 
-> bashly p: *preview
-> 
-> bashly validate: &validate
+>     - --env|-e <env>
+>     - --force|-f
+>     - --quiet|-q
+>     - --upgrade|-u
+>     - --watch|-w
+>     - --wrap|-r <function>
+>   add:
 = help_flags
-> - --verbose
-> - -v
-> 
-> bashly v: *validate
-> 
-> bashly generate: &generate
+>     - --force|-f
+>     - --list|-l
+>     - --source|-s <source>
+>   doc:
 = help_flags
-> - --env
-> - --force
-> - --quiet
-> - --upgrade
-> - --watch
-> - --wrap
-> - -e
-> - -f
-> - -q
-> - -r
-> - -u
-> - -w
-> 
-> bashly g: *generate
-> 
-> bashly generate*--env: &env
-> - development
-> - production
-> 
-> bashly generate*-e: *env
-> bashly g*--env: *env
-> bashly g*-e: *env
-> 
-> bashly add: &add
+>     - --index|-i
+>   completions:
 = help_flags
-> - --force
-> - --list
-> - --source
-> - -f
-> - -l
-> - -s
+>     - --install|-i
+>     - --uninstall|-u
+>   render:
+= help_flags
+>     - --watch|-w
+>     - --show|-s <path>
+>     - --list|-l
+>     - --about|-a
+>   shell:
+= help_flags
+>
+> tokens:
+>   env:
+>     - development
+>     - production
+>   function:
+>   source:
+>   path:
+>   library:
 libs.each do |lib|
-  = "- #{lib}"
+  = "    - #{lib}"
 end
-> 
-> bashly a: *add
-> 
-> bashly doc: &doc
-= help_flags
-> - --index
-> - -i
+>   doc:
 docs.each do |doc|
-  = "- #{doc}"
+  = "    - #{doc}"
+end
+>   render_source:
+render_sources.each do |source|
+  = "    - #{source.inspect}"
 end
->
-> bashly completions: &completions
-= help_flags
-> - --install
-> - -i
-> 
-> bashly c: *completions
->
-> bashly shell: &shell
-= help_flags
-> 
-> bashly s: *shell

data/lib/bashly/concerns/completions.rb

@@ -1,4 +1,5 @@
 require 'completely'
+require 'bashly/completion_builder'
 
 module Bashly
   # This is a `Command` and `Flag` concern responsible for providing bash
@@ -15,25 +16,18 @@ module Bashly
           ["#{prefix}#{name}",  comps]
         end
       end
+
+      def completion_option_entry(token_name = nil)
+        result = [aliases.join('|')]
+        result << "<#{token_name}>" if token_name
+        result << '(repeatable)' if repeatable
+        result.join ' '
+      end
     end
 
     module Command
       def completion_data(with_version: true)
-        result = {}
-
-        completion_full_names.each do |name|
-          name = "#{name}*" if name.include? '*'
-          result[name] = completion_words with_version: with_version
-          flags.each do |flag|
-            result.merge! flag.completion_data(name)
-          end
-        end
-
-        visible_commands.each do |command|
-          result.merge! command.completion_data(with_version: false)
-        end
-
-        result
+        CompletionBuilder.new(self, with_version: with_version).call
       end
 
       def completion_script
@@ -44,42 +38,11 @@ module Bashly
         completion_generator.wrapper_function name
       end
 
-    protected
-
-      def completion_full_names
-        if parent_command
-          glue = parent_command.global_flags? ? '*' : ' '
-          parent_command.completion_full_names.product(aliases).map { |a| a.join glue }
-        else
-          aliases
-        end
-      end
-
     private
 
       def completion_generator
         Completely::Completions.new completion_data
       end
-
-      def completion_flag_names
-        visible_flags.map(&:name) + visible_flags.map(&:short)
-      end
-
-      def completion_allowed_args
-        args.map(&:allowed).flatten
-      end
-
-      def completion_words(with_version: false)
-        trivial_flags = %w[--help -h]
-        trivial_flags += %w[--version -v] if with_version
-        all = (
-          visible_command_aliases + trivial_flags +
-          completion_flag_names + completion_allowed_args
-        )
-
-        all += completions if completions
-        all.compact.uniq.sort
-      end
     end
   end
 end

data/lib/bashly/config_validator.rb

@@ -90,6 +90,8 @@ module Bashly
 
     def assert_arg(key, value)
       assert_hash key, value, keys: Script::Argument.option_keys
+      refute value['allowed'] && value['completions'], "#{key} cannot have both nub`allowed` and nub`completions`"
+
       assert_string "#{key}.name", value['name']
       assert_optional_string "#{key}.help", value['help']
       assert_string_or_array "#{key}.default", value['default']
@@ -99,6 +101,7 @@ module Bashly
       assert_boolean "#{key}.unique", value['unique']
 
       assert_array "#{key}.allowed", value['allowed'], of: :string
+      assert_array "#{key}.completions", value['completions'], of: :string
 
       refute value['name'].match(/^-/), "#{key}.name must not start with '-'"
 

data/lib/bashly/docs/arg.yml

@@ -33,6 +33,17 @@ arg.allowed:
       allowed: [stage, production, development]
       default: development
 
+arg.completions:
+  help: Specify a list of additional completion suggestions when used in conjunction with `bashly add completions`.
+  url: https://bashly.dev/configuration/argument/#completions
+  example: |-
+    args:
+    - name: path
+      help: File or directory to process
+      completions:
+      - <file>
+      - <directory>
+
 arg.default:
   help: Specify the value to apply when not provided by the user.
   url: https://bashly.dev/configuration/argument/#default

data/lib/bashly/extensions/yaml.rb

@@ -2,14 +2,21 @@ require 'erb'
 require 'yaml'
 
 module YAML
-  # We trust our loaded YAMLs
-  # This patch is due to https://bugs.ruby-lang.org/issues/17866
-  # StackOverflow: https://stackoverflow.com/questions/71191685/visit-psych-nodes-alias-unknown-alias-default-psychbadalias/71192990#71192990
   class << self
-    alias load unsafe_load if YAML.respond_to? :unsafe_load
+    def trusted_load(content)
+      if YAML.respond_to? :unsafe_load
+        YAML.unsafe_load content
+      else
+        YAML.load content
+      end
+    end
+
+    def trusted_load_file(path)
+      trusted_load File.read(path)
+    end
 
     def load_erb_file(path)
-      YAML.load ERB.new(File.read(path)).result
+      YAML.trusted_load ERB.new(File.read(path)).result
     end
   end
 end

data/lib/bashly/libraries/libraries.yml

@@ -79,6 +79,21 @@ render_markdown:
 
       m`$ bashly render templates/markdown docs`
 
+render_markdown_github:
+  help: Copy the github markdown templates to your project, allowing you to customize the markdown documentation output.
+  skip_src_check: true
+  files:
+    - source: "render/markdown_github/README.md"
+      target: "templates/markdown_github/README.md"
+    - source: "render/markdown_github/markdown.gtx"
+      target: "templates/markdown_github/markdown.gtx"
+    - source: "render/markdown_github/render.rb"
+      target: "templates/markdown_github/render.rb"
+  post_install_message: |
+    Generate your markdown documentation by running:
+
+      m`$ bashly render templates/markdown_github docs`
+
 render_mandoc:
   help: Copy the mandoc templates to your project, allowing you to customize the man documentation output.
   skip_src_check: true

data/lib/bashly/libraries/settings/settings.yml

@@ -120,6 +120,12 @@ show_examples_on_error: false
 # all the private elements in the usage texts, as if they were public.
 private_reveal_key: ~
 
+# When enabling argfile for any command, this setting controls the name of the
+# environment variable that can override or disable argfile loading at runtime.
+# Set the variable to `0`, `off`, `no` or `false` to disable argfile loading,
+# or to a different path to load another argfile instead.
+argfile_var: ARGFILE
+
 # 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`.

data/lib/bashly/library_source_config.rb

@@ -9,7 +9,7 @@ module Bashly
     end
 
     def data
-      @data ||= YAML.load_file path
+      @data ||= YAML.trusted_load_file path
     end
 
     def validated_data

data/lib/bashly/message_strings.rb

@@ -13,7 +13,7 @@ module Bashly
   private
 
     def values!
-      defaults = YAML.load_file asset('libraries/strings/strings.yml')
+      defaults = YAML.trusted_load_file asset('libraries/strings/strings.yml')
       defaults.merge project_strings
     end
 
@@ -23,7 +23,7 @@ module Bashly
 
     def project_strings!
       if File.exist? project_strings_path
-        YAML.load_file project_strings_path
+        YAML.trusted_load_file project_strings_path
       else
         {}
       end

data/lib/bashly/script/argument.rb

@@ -8,7 +8,7 @@ module Bashly
       class << self
         def option_keys
           @option_keys ||= %i[
-            allowed default help name repeatable required unique validate
+            allowed completions default help name repeatable required unique validate
           ]
         end
       end

data/lib/bashly/script/dependency.rb

@@ -27,7 +27,7 @@ module Bashly
       def initialize(label: nil, commands: nil, help: nil)
         @label = label
         @commands = commands.is_a?(String) ? [commands] : commands
-        @help = help&.empty? ? nil : help
+        @help = help && help.empty? ? nil : help
       end
 
       def multi?