bashly 0.6.7 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c47271e43a775ff08c071428540301ed1fa0656c7d58020c9825dfbc492804ef
-  data.tar.gz: fdc8ac40f1d18c2bc90ae4700fd0757e55132852bbdf8700a2829a02dd3be61c
+  metadata.gz: 53a5744ae1746cdd47de191ea91539ab7336aca894f583384ef0b170c03a746e
+  data.tar.gz: 0e1e9bc417d3947bcce84c3c6f44df87521dfeeae2329cc736a53816cb66cba3
 SHA512:
-  metadata.gz: aff1e0723cdfdc10c409697cb2c715a37382dc7dbef3da3afe3b0e45fc8c91255ffeda153d24a25aa3bdcdf67ff863cfa7bec4558f79fced3d3ff33dc720b4d1
-  data.tar.gz: 54aa504a25003ddf1331e39de9b68612d2fff39bedc93dfc09bc961254c6b4ba7beacadf90412af6d76f9159bffb48456b6d6e85e5c805864372221f2edfbe2e
+  metadata.gz: 72154aafdc3c3787b4d23a2935192a92c21b94b830d7fb01c22057ed839d30120d8a31a8962b7b075110551d034b2c971b92010e55c88a17d4e9041ecb309ad7
+  data.tar.gz: a02638101b685d5e9de575fe4537991c558c462dc030355b5e8ab6ffe4f32b8018c510afb516f51c02d4412a20c21a3703b5dc5872a0f377baa343345f045605

data/README.md

@@ -40,7 +40,7 @@ a [docker image](https://hub.docker.com/r/dannyben/bashly).
    file for you ([example](https://github.com/DannyBen/bashly/tree/master/examples/minimal#bashlyyml)).
 2. Bashly then automatically generates a bash script (when you run
    `bashly generate`) that can parse and validate user input, provide help
-   messages, and run your code for each command ([example](https://github.com/DannyBen/bashly/blob/master/examples/minimal/download)).
+   messages, and run your code for each command.
 3. Your code for each command is kept in a separate file, and can be merged
    again if you change it ([example](https://github.com/DannyBen/bashly/blob/master/examples/minimal/src/root_command.sh)).
 
@@ -67,11 +67,13 @@ Bashly is responsible for:
 ## Contributing / Support
 
 If you experience any issue, have a question or a suggestion, or if you wish
-to contribute, feel free to [open an issue][issues].
+to contribute, feel free to [open an issue][issues] or
+[start a discussion][discussions].
 
 
 
 [issues]: https://github.com/DannyBen/bashly/issues
+[discussions]: https://github.com/DannyBen/bashly/discussions
 [docs]: https://bashly.dannyb.co/
 [examples]: https://github.com/DannyBen/bashly/tree/master/examples#bashly-examples
 

data/lib/bashly/cli.rb

@@ -10,6 +10,7 @@ module Bashly
 
       runner.route 'init',      to: Commands::Init
       runner.route 'preview',   to: Commands::Preview
+      runner.route 'validate',  to: Commands::Validate
       runner.route 'generate',  to: Commands::Generate
       runner.route 'add',       to: Commands::Add
 

data/lib/bashly/commands/add.rb

@@ -8,7 +8,8 @@ module Bashly
       usage "bashly add config [--force]"
       usage "bashly add colors [--force]"
       usage "bashly add yaml [--force]"
-      usage "bashly add comp FORMAT [OUTPUT]"
+      usage "bashly add validations [--force]"
+      usage "bashly add comp FORMAT [OUTPUT --force]"
       usage "bashly add (-h|--help)"
 
       option "-f --force", "Overwrite existing files"
@@ -21,6 +22,7 @@ module Bashly
       command "config", "Add standard functions for handling INI files to the lib directory."
       command "colors", "Add standard functions for printing colorful and formatted text to the lib directory."
       command "yaml", "Add standard functions for reading YAML files to the lib directory."
+      command "validations", "Add argument validation functions to the lib directory."
       command "comp", "Generate a bash completions script or function."
 
       example "bashly add strings --force"
@@ -30,119 +32,70 @@ module Bashly
       environment "BASHLY_SOURCE_DIR", "The path containing the bashly configuration and source files [default: src]"
 
       def strings_command
-        safe_copy asset("templates/strings.yml"), "#{Settings.source_dir}/bashly-strings.yml"
+        add_lib 'strings'
       end
 
       def lib_command
-        safe_copy_lib "sample_function.sh"
+        add_lib 'lib'
       end
 
       def config_command
-        safe_copy_lib "config.sh"
+        add_lib 'config'
       end
 
       def colors_command
-        safe_copy_lib "colors.sh"
+        add_lib 'colors'
       end
 
       def yaml_command
-        safe_copy_lib "yaml.sh"
+        add_lib 'yaml'
+      end
+
+      def validations_command
+        add_lib 'validations'
       end
 
       def comp_command
         format = args['FORMAT']
         output = args['OUTPUT']
-        
+
         case format
-        when "function"
-          save_comp_function output
-        when "yaml"
-          save_comp_yaml output
-        when "script"
-          save_comp_script output
-        else
-          raise Error, "Unrecognized format: #{format}"
+        when "script"   then add_lib 'completions_script', output
+        when "function" then add_lib 'completions', output
+        when "yaml"     then add_lib 'completions_yaml', output
+        else            raise Error, "Unrecognized format: #{format}"
         end
 
       end
 
     private
 
-      def safe_copy_lib(libfile)
-        safe_copy asset("templates/lib/#{libfile}"), "#{Settings.source_dir}/lib/#{libfile}"
+      def add_lib(name, *args)
+        library = Bashly::Library.new name, *args
+        files_created = 0
+        library.files.each do |file|
+          created = safe_write file[:path], file[:content]
+          files_created += 1 if created
+        end
+        message = library.post_install_message
+        say "\n#{message}" if message and files_created > 0
       end
 
-      def safe_copy(source, target)
+      def safe_write(path, content)
         if !Dir.exist? Settings.source_dir
           raise InitError, "Directory !txtgrn!#{Settings.source_dir}!txtrst! does not exist\nRun !txtpur!bashly init!txtrst! first"
         end
 
-        if File.exist? target and !args['--force']
-          say "skipped !txtgrn!#{target}!txtrst! (exists)"
+        if File.exist? path and !args['--force']
+          say "!txtblu!skipped!txtrst! #{path} (exists)"
+          false
+        
         else
-          deep_copy source, target
-          say "created !txtgrn!#{target}"
-        end
-      end
-
-      def deep_copy(source, target)
-        target_dir = File.dirname target
-        FileUtils.mkdir_p target_dir unless Dir.exist? target_dir
-        FileUtils.cp source, target
-      end
-
-      def config
-        @config ||= Config.new "#{Settings.source_dir}/bashly.yml"
-      end
-
-      def command
-        @command ||= Models::Command.new config
-      end
-
-      def completions
-        @completions ||= command.completion_data
-      end
-
-      def completions_script
-        @completions_script ||= command.completion_script
-      end
-
-      def completions_function
-        @completions_function ||= command.completion_function
-      end
-
-      def save_comp_yaml(filename = nil)
-        filename ||= "#{Settings.target_dir}/completions.yml"
-        File.write filename, completions.to_yaml
-        say "created !txtgrn!#{filename}"
-        say ""
-        say "This file can be converted to a completions script using the !txtgrn!completely!txtrst! gem."
-      end
-
-      def save_comp_script(filename = nil)
-        filename ||= "#{Settings.target_dir}/completions.bash"
-        File.write filename, completions_script
-        say "created !txtgrn!#{filename}"
-        say ""
-        say "In order to enable completions, run:"
-        say ""
-        say "  !txtpur!$ source #{filename}"
-      end
-
-      def save_comp_function(name = nil)
-        name ||= "send_completions"
-        target_dir = "#{Settings.source_dir}/lib"
-        filename = "#{target_dir}/#{name}.sh"
+          File.deep_write path, content
+          say "!txtgrn!created!txtrst! #{path}"
+          true
         
-        FileUtils.mkdir_p target_dir unless Dir.exist? target_dir
-        File.write filename, completions_function
-
-        say "created !txtgrn!#{filename}"
-        say ""
-        say "In order to use it in your script, create a command or a flag (for example: !txtgrn!#{command.name} completions!txtrst! or !txtgrn!#{command.name} --completions!txtrst!) that calls the !txtgrn!#{name}!txtrst! function."
-        say "Your users can then run something like this to enable completions:"
-        say ""
-        say "  !txtpur!$ eval \"$(#{command.name} completions)\""
+        end
       end
 
     end

data/lib/bashly/commands/generate.rb

@@ -1,30 +1,76 @@
 module Bashly
   module Commands
     class Generate < Base
+      using ComposeRefinements
+
       help "Generate the bash script and required files"
 
-      usage "bashly generate [--force --wrap FUNCTION]"
+      usage "bashly generate [--force --quiet --upgrade --wrap FUNCTION]"
       usage "bashly generate (-h|--help)"
 
       option "-f --force", "Overwrite existing files"
+      option "-q --quiet", "Disable on-screen progress report"
+      option "-u --upgrade", "Upgrade all added library functions"
       option "-w --wrap FUNCTION", "Wrap the entire script in a function so it can also be sourced"
 
       environment "BASHLY_SOURCE_DIR", "The path containing the bashly configuration and source files [default: src]"
       environment "BASHLY_TARGET_DIR", "The path to use for creating the bash script [default: .]"
+      environment "BASHLY_STRICT", "When not empty, enable bash strict mode (set -euo pipefail)"
 
       example "bashly generate --force"
       example "bashly generate --wrap my_function"
 
       def run
         create_user_files
+        upgrade_libs if args['--upgrade']
         create_master_script
-        say "run !txtpur!#{master_script_path} --help!txtrst! to test your bash script"
+        quiet_say "run !txtpur!#{master_script_path} --help!txtrst! to test your bash script"
       end
 
     private
 
+      def quiet_say(message)
+        say message unless args['--quiet']
+      end
+
+      def upgrade_libs
+        generated_files.each do |file|
+          content = File.read file
+          
+          if content =~ /\[@bashly-upgrade (.+)\]/
+            args = $1.split ' '
+            library_name = args.shift
+            upgrade file, library_name, *args
+          end
+        end
+      end
+
+      def generated_files
+        Dir["#{Settings.source_dir}/**/*.*"].sort
+      end
+
+      def upgrade(existing_file, library_name, *args)
+        if Library.exist? library_name
+          upgrade! existing_file, library_name, *args
+        else
+          quiet_say "!txtred!warning!txtrst! not upgrading !txtcyn!#{existing_file}!txtrst!, unknown library '#{library_name}'"
+        end
+      end
+
+      def upgrade!(existing_file, library_name, *args)
+        library = Bashly::Library.new library_name, *args
+        file = library.find_file existing_file
+
+        if file
+          File.deep_write file[:path], file[:content]
+          quiet_say "!txtcyn!updated!txtrst! #{file[:path]}"
+        else
+          quiet_say "!txtred!warning!txtrst! not upgrading !txtcyn!#{existing_file}!txtrst!, path mismatch"
+        end
+      end
+
       def create_user_files
-        say "creating user files in !txtgrn!#{Settings.source_dir}"
+        quiet_say "creating user files in !txtgrn!#{Settings.source_dir}"
 
         create_file "#{Settings.source_dir}/initialize.sh", command.render(:default_initialize_script)
 
@@ -50,21 +96,21 @@ module Bashly
 
       def create_file(file, content)
         if File.exist? file and !args['--force']
-          say "skipped !txtgrn!#{file}!txtrst! (exists)"
+          quiet_say "!txtblu!skipped!txtrst! #{file} (exists)"
         else
           File.write file, content
-          say "created !txtgrn!#{file}"
+          quiet_say "!txtgrn!created!txtrst! #{file}"
         end
       end
 
       def create_master_script
         File.write master_script_path, script.code
         FileUtils.chmod "+x", master_script_path
-        say "created !txtgrn!#{master_script_path}"
+        quiet_say "!txtgrn!created!txtrst! #{master_script_path}"
       end
 
       def script
-        @script ||= Models::Script.new(command, args['--wrap'])
+        @script ||= Script::Wrapper.new(command, args['--wrap'])
       end
 
       def master_script_path
@@ -72,11 +118,11 @@ module Bashly
       end
 
       def config
-        @config ||= Config.new "#{Settings.source_dir}/bashly.yml"
+        @config ||= Config.new("#{Settings.source_dir}/bashly.yml").compose
       end
 
       def command
-        @command ||= Models::Command.new config
+        @command ||= Script::Command.new config
       end
 
     end

data/lib/bashly/commands/init.rb

@@ -17,7 +17,7 @@ module Bashly
         end
         Dir.mkdir target_dir unless Dir.exist? target_dir
         File.write "#{target_dir}/bashly.yml", yaml_content
-        say "created !txtgrn!#{target_dir}/bashly.yml"
+        say "!txtgrn!created!txtrst! #{target_dir}/bashly.yml"
         say "run !txtpur!bashly generate!txtrst! to create the bash script"
       end
 

data/lib/bashly/commands/preview.rb

@@ -10,8 +10,8 @@ module Bashly
 
       def run
         config = Config.new "#{Settings.source_dir}/bashly.yml"
-        command = Models::Command.new(config)
-        script = Models::Script.new command
+        command = Script::Command.new(config)
+        script = Script::Wrapper.new command
         puts script.code
       end
     end

data/lib/bashly/commands/validate.rb

@@ -0,0 +1,19 @@
+module Bashly
+  module Commands
+    class Validate < Base
+      help "Scan the configuration file for errors"
+
+      usage "bashly validate"
+      usage "bashly validate (-h|--help)"
+
+      environment "BASHLY_SOURCE_DIR", "The path containing the bashly configuration and source files [default: src]"
+
+      def run
+        config = Config.new "#{Settings.source_dir}/bashly.yml"
+        validator = ConfigValidator.new config
+        validator.validate
+        say "!txtgrn!OK"
+      end
+    end
+  end
+end

data/lib/bashly/concerns/asset_helper.rb

@@ -3,5 +3,9 @@ module Bashly
     def asset(path)
       File.expand_path "../#{path}", __dir__
     end
+
+    def asset_content(path)
+      File.read asset(path)
+    end
   end
 end

data/lib/bashly/concerns/completions.rb

@@ -31,12 +31,16 @@ module Bashly
       flags.map(&:name) + flags.map(&:short)
     end
 
+    def completion_allowed_args
+      flags.map(&:allowed).flatten + 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 = (
         command_names + trivial_flags +
-        completion_flag_names
+        completion_flag_names + completion_allowed_args
       )
 
       all += completions if completions

data/lib/bashly/config_validator.rb

@@ -0,0 +1,135 @@
+module Bashly
+  class ConfigValidator
+    attr_reader :data
+
+    def initialize(data)
+      @data = data
+    end
+
+    def validate
+      assert_command "root", data
+    end
+
+  private
+
+    def assert(valid, message)
+      raise ConfigurationError, message unless valid
+    end
+
+    def refute(invalid, message)
+      assert !invalid, message
+    end
+
+    def assert_string(key, value)
+      assert value.is_a?(String), "#{key} must be a string"
+    end
+
+    def assert_optional_string(key, value)
+      assert_string key, value if value
+    end
+
+    def assert_boolean(key, value)
+      assert [true, false, nil].include?(value), "#{key} must be a boolean" 
+    end
+
+    def assert_array(key, value, of: nil)
+      return unless value
+      assert value.is_a?(Array), "#{key} must be an array"
+      if of
+        value.each_with_index do |val, i|
+          send "assert_#{of}".to_sym, "#{key}[#{i}]", val
+        end
+      end
+    end
+
+    def assert_hash(key, value)
+      assert value.is_a?(Hash), "#{key} must be a hash"
+    end
+
+    def assert_version(key, value)
+      return unless value
+      assert [String, Integer, Float].include?(value.class),
+        "#{key} must be a string or a number" 
+    end
+
+    def assert_catch_all(key, value)
+      return unless value
+      assert [TrueClass, String, Hash].include?(value.class),
+        "#{key} must be a boolean, a string or a hash" 
+
+      assert_catch_all_hash key, value if value.is_a? Hash
+    end
+
+    def assert_catch_all_hash(key, value)
+      assert_string "#{key}.label", value['label']
+      assert_optional_string "#{key}.help", value['help']
+      assert_boolean "#{key}.required", value['required']
+    end
+
+    def assert_extensible(key, value)
+      return unless value
+      assert [TrueClass, String].include?(value.class),
+        "#{key} must be a boolean or a string" 
+    end
+
+    def assert_arg(key, value)
+      assert_hash key, value
+      assert_string "#{key}.name", value['name']
+      assert_optional_string "#{key}.help", value['help']
+      assert_optional_string "#{key}.default", value['default']
+      assert_optional_string "#{key}.validate", value['validate']
+      assert_boolean "#{key}.required", value['required']
+      
+      assert_array "#{key}.allowed", value['allowed'], of: :string
+    end
+
+    def assert_flag(key, value)
+      assert_hash key, value
+      assert value['short'] || value['long'], "#{key} must have at least one of long or short name"
+
+      assert_optional_string "#{key}.long", value['long']
+      assert_optional_string "#{key}.short", value['short']
+      assert_optional_string "#{key}.help", value['help']
+      assert_optional_string "#{key}.arg", value['arg']
+      assert_optional_string "#{key}.default", value['default']
+      assert_optional_string "#{key}.validate", value['validate']
+      
+      assert_boolean "#{key}.required", value['required']
+      assert_array "#{key}.allowed", value['allowed'], of: :string
+    end
+
+    def assert_env_var(key, value)
+      assert_hash key, value
+      assert_string "#{key}.name", value['name']
+      assert_optional_string "#{key}.help", value['help']
+      assert_optional_string "#{key}.default", value['default']
+      assert_boolean "#{key}.required", value['required']
+    end
+
+    def assert_command(key, value)
+      assert_hash key, value
+
+      refute value['commands'] && value['args'], "#{key} cannot have both commands and args"
+      refute value['commands'] && value['flags'], "#{key} cannot have both commands and flags"
+      
+      assert_string "#{key}.name", value['name']
+      assert_optional_string "#{key}.short", value['short']
+      assert_optional_string "#{key}.help", value['help']
+      assert_optional_string "#{key}.footer", value['footer']
+      assert_optional_string "#{key}.group", value['group']
+
+      assert_boolean "#{key}.default", value['default']
+      assert_version "#{key}.version", value['version']
+      assert_catch_all "#{key}.catch_all", value['catch_all']
+      assert_extensible "#{key}.extensible", value['extensible']
+      
+      assert_array "#{key}.args", value['args'], of: :arg
+      assert_array "#{key}.flags", value['flags'] , of: :flag
+      assert_array "#{key}.commands", value['commands'], of: :command
+      assert_array "#{key}.completions", value['completions'], of: :string
+      assert_array "#{key}.dependencies", value['dependencies'], of: :string
+      assert_array "#{key}.environment_variables", value['environment_variables'], of: :env_var
+      assert_array "#{key}.examples", value['examples'], of: :string
+    end
+  end
+end

data/lib/bashly/extensions/file.rb

@@ -0,0 +1,13 @@
+require "fileutils"
+
+class File
+  def self.deep_write(file, content)
+    dir = File.dirname file
+    FileUtils.mkdir_p dir unless Dir.exist? dir
+    File.write file, content
+  end
+
+  def self.append(path, content)
+    File.open(path, "a") { |f| f << content }
+  end
+end

data/lib/bashly/extensions/string.rb

@@ -24,7 +24,11 @@ class String
   end
 
   def lint
-    gsub(/\n{2,}/, "\n\n")
+    gsub(/\s+\n/m, "\n\n").lines.reject { |l| l =~ /^\s*##/ }.join ""
+  end
+
+  def remove_front_matter
+    split(/^---\s*/).last
   end
 
 end

data/lib/bashly/libraries/base.rb

@@ -0,0 +1,19 @@
+module Bashly
+  module Libraries
+    class Base
+      attr_reader :args
+
+      def initialize(*args)
+        @args = args
+      end
+
+      def files
+        raise NotImplementedError, "Please implement #files"
+      end
+
+      def post_install_message
+        nil
+      end
+    end
+  end
+end

data/lib/bashly/libraries/completions.rb

@@ -0,0 +1,14 @@
+module Bashly
+  module Libraries
+    class Completions < Base
+    protected
+      def command
+        @command ||= Script::Command.new config
+      end
+
+      def config
+        @config ||= Bashly::Config.new "#{Settings.source_dir}/bashly.yml"
+      end
+    end
+  end
+end

data/lib/bashly/libraries/completions_function.rb

@@ -0,0 +1,38 @@
+module Bashly
+  module Libraries
+    class CompletionsFunction < Completions
+      def files
+        [
+          {
+            path: "#{Settings.source_dir}/lib/#{function_name}.sh",
+            content: completions_function_code(function_name)
+          }
+        ]
+      end
+
+      def post_install_message
+        <<~EOF
+          In order to enable completions in your script, create a command or a flag (for example: !txtgrn!#{command.name} completions!txtrst! or !txtgrn!#{command.name} --completions!txtrst!) that calls the !txtgrn!#{function_name}!txtrst! function.
+
+          Your users can then run something like this to enable completions:
+
+            !txtpur!$ eval \"$(#{command.name} completions)\"
+        EOF
+      end
+
+    private
+
+      def function_name
+        @function_name ||= args[0] || 'send_completions'
+      end
+
+      def completions_function_code(function_name)
+        [
+          "## [@bashly-upgrade completions #{function_name}]",
+          command.completion_function(function_name)
+        ].join "\n"
+      end
+
+    end
+  end
+end

data/lib/bashly/libraries/completions_script.rb

@@ -0,0 +1,29 @@
+module Bashly
+  module Libraries
+    class CompletionsScript < Completions
+      def files
+        [
+          {
+            path: target_path,
+            content: command.completion_script
+          }
+        ]
+      end
+
+      def post_install_message
+        <<~EOF
+          In order to enable completions, run:
+
+            !txtpur!$ source #{target_path}
+        EOF
+      end
+
+    private
+
+      def target_path
+        @target_path ||= args[0] || "#{Settings.target_dir}/completions.bash"
+      end
+
+    end
+  end
+end