bashly 1.2.13 → 1.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b7352576231f786aa54762d8ae255d5599da89b8a5c1eb98d39bee4f8826cf40
-  data.tar.gz: 847a535d109089a3296b4dfce8477f1c3d40cd62183a4aeb662e396efe9a5f95
+  metadata.gz: 4ac473fa7be8511393fdc443f632ee359f044083935f1db09e28382ade67a132
+  data.tar.gz: 2fdc90bedee600c6a5be795a48580f9db672116f90b8ce1d97c068d932161522
 SHA512:
-  metadata.gz: 3b2c74316bd4d9d37a22e58ed20c4986a7ca86e7b74b7222e8f7adcad966f83b29d39b915ca7607f1d3655ef1653390aadcdcea173b9c9818ba475f861d8bbba
-  data.tar.gz: 89517c698abb34ec83e04590cd4919f59492fc0b999b3baade304dfde859c7aca231db77a9d469df0fcb7d98634913cb6d2321b6a791732f06c2cf608d962cc8
+  metadata.gz: d1573a20f34fb2e5651be13ff24bc8af687ab81a53750a97fd411d18cf08320af85d6480dccaf2f786fff82394803dbdfaead78ac5a2cc200ccd7e338d6b6b55
+  data.tar.gz: 630d815115bfdb10796621795c800594cf1a7953f74e9c6bafda8baad47f54bf57095c1dda34fbea9fbe4d3eede6ccdb32aa056b3da9fe15bd5839026af5cbef

data/README.md

@@ -5,10 +5,6 @@
 
 Create feature-rich bash scripts using simple YAML configuration
 
-[![Gem Version](https://badge.fury.io/rb/bashly.svg)](https://badge.fury.io/rb/bashly)
-[![Build Status](https://github.com/DannyBen/bashly/workflows/Test/badge.svg)](https://github.com/DannyBen/bashly/actions?query=workflow%3ATest)
-[![Maintainability](https://api.codeclimate.com/v1/badges/8cf89047e50ca601e431/maintainability)](https://codeclimate.com/github/DannyBen/bashly/maintainability)
-
 ## [bashly.dev](https://bashly.dev)
 
 ---
@@ -36,12 +32,12 @@ a [docker image](https://hub.docker.com/r/dannyben/bashly).
 
 1. You provide a YAML configuration file, describing commands, sub-commands,
    arguments, and flags. Running `bashly init` creates an initial sample YAML
-   file for you ([example](https://github.com/DannyBen/bashly/tree/master/examples/minimal#bashlyyml)).
+   file for you ([example](https://github.com/bashly-framework/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.
 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)).
+   again if you change it ([example](https://github.com/bashly-framework/bashly/blob/master/examples/minimal/src/root_command.sh)).
 
 ## Features
 
@@ -74,8 +70,8 @@ to contribute, feel free to [open an issue][issues] or
 Visit the *[How to contribute][contributing]* page for more information.
 
 
-[issues]: https://github.com/DannyBen/bashly/issues
-[discussions]: https://github.com/DannyBen/bashly/discussions
+[issues]: https://github.com/bashly-framework/bashly/issues
+[discussions]: https://github.com/bashly-framework/bashly/discussions
 [docs]: https://bashly.dev/
-[examples]: https://github.com/DannyBen/bashly/tree/master/examples#bashly-examples
-[contributing]: https://github.com/DannyBen/bashly/blob/master/CONTRIBUTING.md#how-to-contribute
+[examples]: https://github.com/bashly-framework/bashly/tree/master/examples#bashly-examples
+[contributing]: https://github.com/bashly-framework/bashly/blob/master/CONTRIBUTING.md#how-to-contribute

data/lib/bashly/commands/render.rb

@@ -34,7 +34,8 @@ module Bashly
       example 'bashly render --list'
       example 'bashly render :markdown --about'
       example 'bashly render :markdown docs --watch'
-      example 'bashly render :markdown docs --show "cli-download.1"'
+      example 'bashly render :markdown docs --show "cli download.md'
+      example 'bashly render :mandoc docs --show cli-download.1'
       example 'bashly render /path/to/templates ./out_path'
 
       attr_reader :watching, :target, :source
@@ -51,7 +52,7 @@ module Bashly
 
       def show_list
         RenderSource.internal.each_value do |source|
-          say "g`:#{source.selector.to_s.ljust 10}`  #{source.summary}"
+          say "g`:#{source.selector.to_s.ljust 16}`  #{source.summary}"
         end
       end
 

data/lib/bashly/completions/bashly-completions.bash

@@ -1,7 +1,7 @@
 # bashly completion                                        -*- shell-script -*-
 
 # This bash completions script was generated by
-# completely (https://github.com/dannyben/completely)
+# completely (https://github.com/bashly-framework/completely)
 # Modifying it manually is not recommended
 
 _bashly_completions_filter() {

data/lib/bashly/extensions/string.rb

@@ -44,8 +44,8 @@ class String
     end * "\n"
   end
 
-  def lint
-    gsub(/\s+\n/m, "\n\n").lines.grep_v(/^\s*##/).join
+  def remove_private_comments
+    lines.grep_v(/^\s*##/).join
   end
 
   def remove_front_matter

data/lib/bashly/libraries/hooks/before.sh

@@ -1,8 +1,11 @@
 ## before hook
 ##
-## Any code here will be placed inside a `before_hook()` function and called
-## before running any command (but after processing its arguments).
+## Any code here will be placed inside the `before_hook()` function and called
+## before running any command (but after argument processing is complete).
+##
+## - The processed args are available to you here as `args` and `extra_args`
+## - The raw input array is also available in read-only mode as `input`
 ##
 ## You can safely delete this file if you do not need it.
 echo "==[ Before Hook Called ]=="
-inspect_args
+inspect_args

data/lib/bashly/libraries/hooks/initialize.sh

@@ -3,4 +3,8 @@
 ## Any code here will be placed inside the `initialize()` function and called
 ## before running anything else.
 ##
+## The original command line arguments are available in the `command_line_args`
+## array. You can modify or override the input before it is processed further,
+## though this is usually only needed for advanced use cases.
+##
 ## You can safely delete this file if you do not need it.

data/lib/bashly/libraries/render/mandoc/summary.txt

@@ -1 +1 @@
-Render man pages for your script
+Render man pages

data/lib/bashly/libraries/render/markdown/summary.txt

@@ -1 +1 @@
-Render markdown documents for your script
+Render markdown documents

data/lib/bashly/libraries/render/markdown_github/README.md

@@ -0,0 +1,37 @@
+# Render GitHub markdown
+
+Render GitHub-compatible markdown documents for your script.
+
+## Usage
+
+```bash
+# Generate all documents to the ./docs directory
+$ bashly render :markdown_github docs
+
+# Generate on change, and show one of the files
+$ bashly render :markdown_github docs --watch --show index.md
+```
+
+The differences between this template and the `:markdown` template are:
+
+- Links to sub-command files include the `.md` extension.
+- The main file is named `README.md` instead of `index.md`.
+
+## Supported custom definitions
+
+Add these definitions to your `bashly.yml` to render them in your
+markdown:
+
+### Footer: `x_markdown_footer`
+
+Add additional sections to your man pages. This field is expected
+to be in markdown format.
+
+#### Example
+
+```yaml
+x_markdown_footer: |-
+  # ISSUE TRACKER
+
+  Report issues at <https://github.com/lanalang/smallville>
+```

data/lib/bashly/libraries/render/markdown_github/markdown.gtx

@@ -0,0 +1,190 @@
+# === Header
+
+> # {{ full_name }}
+>
+> {{ help.for_markdown }}
+>
+
+attributes = version || alt.any? || default || extensible
+
+if attributes
+  > | Attributes       |  
+  > |------------------|-------------
+  if version
+    > | Version:         | {{ version }}
+  end
+  if alt.any?
+    > | Alias:           | {{ alt.join ', ' }}
+  end
+  if default
+    > | Default Command: | ✓ Yes
+  end
+  if extensible
+    > | Extensible:      | {{ extensible.is_a?(String) ? extensible : "✓ Yes" }}
+  end
+  >
+end
+
+# === Usage
+
+> ## Usage
+>
+> ```bash
+> {{ usage_string.for_markdown }}
+> ```
+>
+
+# === Examples
+
+if examples
+  > ## Examples
+  >
+  examples.each do |example|
+    > ```bash
+    > {{ example }}
+    > ```
+    >
+  end
+end
+
+# === Dependencies
+
+if dependencies.any?
+  > ## Dependencies
+  >
+  dependencies.each do |dependency|
+    > #### *{{ dependency.commands.join ', ' }}*
+    >
+    > {{ dependency.help&.for_markdown }}
+    >
+  end
+end
+
+# === Environment Variables
+
+if visible_environment_variables.any?
+  > ## Environment Variables
+  >
+  visible_environment_variables.each do |environment_variable|
+    attributes = environment_variable.required || environment_variable.default
+
+    > #### *{{ environment_variable.name.upcase }}*
+    >
+    > {{ environment_variable.help.for_markdown }}
+    >
+
+    if attributes
+      > | Attributes      |  
+      > |-----------------|-------------
+      if environment_variable.required
+        > | Required:       | ✓ Yes
+      end
+      if environment_variable.default
+        > | Default Value:  | {{ environment_variable.default }}
+      end
+      >
+    end
+  end
+end
+
+# === Commands
+
+if commands.any?
+  grouped_commands.each do |group, commands|
+    > ## {{ group.gsub(/:$/, '') }}
+    >
+    commands.each do |subcommand|
+      > - [{{ subcommand.name }}]({{ subcommand.full_name.gsub(' ', '%20') }}.md) - {{ subcommand.summary.for_markdown }}
+    end
+    >
+  end
+end
+
+# === Arguments
+
+if args.any?
+  > ## Arguments
+  >
+  args.each do |arg|
+    attributes = arg.required || arg.repeatable || arg.default || arg.allowed
+
+    > #### *{{ arg.name.upcase }}*
+    >
+    > {{ arg.help.for_markdown }}
+    >
+
+    if attributes
+      > | Attributes      |  
+      > |-----------------|-------------
+      if arg.required
+        > | Required:       | ✓ Yes
+      end
+      if arg.repeatable
+        > | Repeatable:     |  ✓ Yes
+      end
+      if arg.default
+        > | Default Value:  | {{ arg.default }}
+      end
+      if arg.allowed
+        > | Allowed Values: | {{ arg.allowed.join(', ') }}
+      end
+      >
+    end
+  end
+
+  if catch_all.label && catch_all.help
+    > #### *{{ catch_all.label }}*
+    >
+    > {{ catch_all.help&.for_markdown }}
+    >
+    if catch_all.required?
+      > | Attributes |  
+      > |------------|-------------
+      > | Required:  | ✓ Yes
+      >
+    end
+  end
+end
+
+# === Flags
+
+if flags.any?
+  > ## Options
+  >
+  flags.each do |flag|
+    attributes = flag.required || flag.repeatable || flag.default ||
+      flag.allowed || flag.conflicts || flag.needs
+
+    > #### *{{ flag.usage_string }}*
+    >
+    > {{ flag.help.for_markdown }}
+    >
+
+    if attributes
+      > | Attributes      |  
+      > |-----------------|-------------
+      if flag.required
+        > | Required:       | ✓ Yes
+      end
+      if flag.repeatable
+        > | Repeatable:     |  ✓ Yes
+      end
+      if flag.default
+        > | Default Value:  | {{ flag.default }}
+      end
+      if flag.allowed
+        > | Allowed Values: | {{ flag.allowed.join(', ') }}
+      end
+      if flag.conflicts
+        > | Conflicts With: | *{{ flag.conflicts.join(', ') }}*
+      end
+      if flag.needs
+        > | Needs: | *{{ flag.needs.join(', ') }}*
+      end
+      >
+    end
+  end
+end
+
+= x_markdown_footer&.for_manpage
+>

data/lib/bashly/libraries/render/markdown_github/render.rb

@@ -0,0 +1,23 @@
+# render script - markdown
+require 'gtx'
+
+# for previewing only (not needed for rendering)
+require 'tty-markdown'
+
+# Load the GTX template
+template = "#{source}/markdown.gtx"
+gtx = GTX.load_file template
+
+# Render the file for the main command
+save "#{target}/README.md", gtx.parse(command)
+
+# Render a file for each subcommand
+command.deep_commands.reject(&:private).each do |subcommand|
+  save "#{target}/#{subcommand.full_name}.md", gtx.parse(subcommand)
+end
+
+# Show one of the files if requested
+if show
+  file = "#{target}/#{show}"
+  puts TTY::Markdown.parse_file(file) if File.exist?(file)
+end

data/lib/bashly/libraries/render/markdown_github/summary.txt

@@ -0,0 +1 @@
+Render GitHub-compatible markdown documents

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

@@ -41,16 +41,26 @@ partials_extension: sh
 #-------------------------------------------------------------------------------
 
 # Configure the bash options that will be added to the initialize function:
-# strict: true       Bash strict mode (set -euo pipefail)
-# strict: false      Only exit on errors (set -e)
-# strict: ''         Do not add any 'set' directive
-# strict: <string>   Add any other custom 'set' directive
+# strict: true       # Bash strict mode (set -euo pipefail)
+# strict: false      # Only exit on errors (set -e)
+# strict: ''         # Do not add any 'set' directive
+# strict: <string>   # Add any other custom 'set' directive
 strict: false
 
 # When true, the generated script will use tab indentation instead of spaces
 # (every 2 leading spaces will be converted to a tab character)
 tab_indent: false
 
+# Choose a post-processor for the generated script:
+# formatter: internal     # Use Bashly's internal formatter (compacts newlines)
+# formatter: external     # Run the external command `shfmt --case-indent --indent 2`
+# formatter: none         # Disable formatting entirely
+# formatter: <string>     # Use a custom shell command to format the script.
+#                         # The command will receive the script via stdin and
+#                         # must output the result to stdout.
+#                         # Example: shfmt --minify
+formatter: internal
+
 
 #-------------------------------------------------------------------------------
 # INTERFACE OPTIONS
@@ -100,10 +110,10 @@ env: development
 
 # Tweak the script output by enabling or disabling some script output.
 # These options accept one of the following strings:
-# - production      render this feature only when env == production
-# - development     render this feature only when env == development
-# - always          render this feature in any environment
-# - never           do not render this feature
+# - production      # render this feature only when env == production
+# - development     # render this feature only when env == development
+# - always          # render this feature in any environment
+# - never           # do not render this feature
 enable_header_comment: always
 enable_bash3_bouncer: always
 enable_view_markers: development

data/lib/bashly/libraries/strings/strings.yml

@@ -40,6 +40,6 @@ 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}"
-unsupported_bash_version: "bash version 4 or higher is required"
+unsupported_bash_version: "bash version 4.2 or higher is required"
 validation_error: "validation error in %s:\\n%s"
 environment_variable_validation_error: "validation error in environment variable %s:\\n%s"

data/lib/bashly/script/formatter.rb

@@ -0,0 +1,44 @@
+require 'open3'
+require 'shellwords'
+
+module Bashly
+  module Script
+    class Formatter
+      attr_reader :script, :mode
+
+      def initialize(script, mode: nil)
+        @script = script
+        @mode = mode&.to_s || 'internal'
+      end
+
+      def formatted_script
+        case mode
+        when 'internal' then script.gsub(/\s+\n/m, "\n\n")
+        when 'external' then shfmt_result
+        when 'none' then script
+        else custom_formatter_result mode
+        end
+      end
+
+    private
+
+      def shfmt_result
+        custom_formatter_result %w[shfmt --case-indent --indent 2]
+      end
+
+      def custom_formatter_result(command)
+        command = Shellwords.split command if command.is_a? String
+
+        begin
+          output, error, status = Open3.capture3(*command, stdin_data: script)
+        rescue Errno::ENOENT
+          raise Error, "Command not found: g`#{command.first}`"
+        end
+
+        raise Error, "Failed running g`#{Shellwords.join command}`:\n\n#{error}" unless status.success?
+
+        output
+      end
+    end
+  end
+end

data/lib/bashly/script/wrapper.rb

@@ -23,7 +23,13 @@ module Bashly
           [header, body]
         end
 
-        result.join("\n").lint
+        clean_code result.join("\n")
+      end
+
+      def clean_code(script)
+        result = script.remove_private_comments
+        formatter = Formatter.new result, mode: Settings.formatter
+        formatter.formatted_script
       end
 
       def header

data/lib/bashly/settings.rb

@@ -15,6 +15,7 @@ module Bashly
         :enable_inspect_args,
         :enable_sourcing,
         :enable_view_markers,
+        :formatter,
         :function_names,
         :lib_dir,
         :partials_extension,
@@ -86,6 +87,10 @@ module Bashly
         @env = value&.to_sym
       end
 
+      def formatter
+        @formatter ||= get :formatter
+      end
+
       def full_lib_dir
         "#{source_dir}/#{lib_dir}"
       end

data/lib/bashly/version.rb

@@ -1,3 +1,3 @@
 module Bashly
-  VERSION = '1.2.13'
+  VERSION = '1.3.1'
 end

data/lib/bashly/views/README.md

@@ -1,6 +1,6 @@
 # View Templates
 
-These are [GTX](https://github.com/dannyben/gtx) templates.
+These are [GTX](https://github.com/bashly-framework/gtx) templates.
 
 For syntax highlighting, set up your editor to treat `*.gtx` files as Ruby
 source code.

data/lib/bashly/views/argument/validations.gtx

@@ -6,15 +6,17 @@ if validate
     >   values=''
     >   eval "values=(${args['{{ name }}']})"
     >   for value in "${values[@]}"; do
-    >     if [[ -n $(validate_{{ validate }} "$value") ]]; then
-    >       printf "{{ strings[:validation_error] }}\n" "{{ name.upcase }}" "$(validate_{{ validate }} "$value")" >&2
+    >     validation_output="$(validate_{{ validate }} "$value")"
+    >     if [[ -n "$validation_output" ]]; then
+    >       printf "{{ strings[:validation_error] }}\n" "{{ name.upcase }}" "$validation_output" >&2
     >       exit 1
     >     fi
     >   done
     > fi
   else
-    > if [[ -v args['{{ name }}'] && -n $(validate_{{ validate }} "${args['{{ name }}']:-}") ]]; then
-    >   printf "{{ strings[:validation_error] }}\n" "{{ name.upcase }}" "$(validate_{{ validate }} "${args['{{ name }}']:-}")" >&2
+    > validation_output="$(validate_{{ validate }} "${args['{{ name }}']:-}")"
+    > if [[ -v args['{{ name }}'] && -n "$validation_output" ]]; then
+    >   printf "{{ strings[:validation_error] }}\n" "{{ name.upcase }}" "$validation_output" >&2
     >   exit 1
     > fi
     >

data/lib/bashly/views/command/master_script.gtx

@@ -15,11 +15,9 @@
 > 
 if Settings.enabled? :sourcing
   > if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
-  >   {{ Settings.function_name :initialize }}
-  >   {{ Settings.function_name :run }} "$@"
+  = render(:start).indent 2
   > fi
 else
-  > {{ Settings.function_name :initialize }}
-  > {{ Settings.function_name :run }} "$@"
+  = render :start
 end
 > 

data/lib/bashly/views/command/start.gtx

@@ -0,0 +1,5 @@
+= view_marker
+
+> command_line_args=("$@")
+> {{ Settings.function_name :initialize }}
+> {{ Settings.function_name :run }} "${command_line_args[@]}"

data/lib/bashly/views/wrapper/bash3_bouncer.gtx

@@ -1,7 +1,10 @@
 = view_marker
 
-> if [[ "${BASH_VERSINFO:-0}" -lt 4 ]]; then
+> if ((BASH_VERSINFO[0] < 4 || (BASH_VERSINFO[0] == 4 && BASH_VERSINFO[1] < 2))); then
 >   printf "{{ strings[:unsupported_bash_version] }}\n" >&2
 >   exit 1
 > fi
-> 
+> 
+
+
+

data/lib/bashly.rb

@@ -22,7 +22,7 @@ module Bashly
   module Script
     autoloads 'bashly/script', %i[
       Argument Base CatchAll Command Dependency EnvironmentVariable Flag
-      Variable Wrapper
+      Formatter Variable Wrapper
     ]
 
     module Introspection

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bashly
 version: !ruby/object:Gem::Version
-  version: 1.2.13
+  version: 1.3.1
 platform: ruby
 authors:
 - Danny Ben Shitrit
@@ -225,6 +225,10 @@ files:
 - lib/bashly/libraries/render/markdown/markdown.gtx
 - lib/bashly/libraries/render/markdown/render.rb
 - lib/bashly/libraries/render/markdown/summary.txt
+- lib/bashly/libraries/render/markdown_github/README.md
+- lib/bashly/libraries/render/markdown_github/markdown.gtx
+- lib/bashly/libraries/render/markdown_github/render.rb
+- lib/bashly/libraries/render/markdown_github/summary.txt
 - lib/bashly/libraries/settings/settings.yml
 - lib/bashly/libraries/stacktrace/stacktrace.sh
 - lib/bashly/libraries/strings/strings.yml
@@ -249,6 +253,7 @@ files:
 - lib/bashly/script/dependency.rb
 - lib/bashly/script/environment_variable.rb
 - lib/bashly/script/flag.rb
+- lib/bashly/script/formatter.rb
 - lib/bashly/script/introspection/arguments.rb
 - lib/bashly/script/introspection/commands.rb
 - lib/bashly/script/introspection/dependencies.rb
@@ -300,6 +305,7 @@ files:
 - lib/bashly/views/command/required_flags_filter.gtx
 - lib/bashly/views/command/root_command.gtx
 - lib/bashly/views/command/run.gtx
+- lib/bashly/views/command/start.gtx
 - lib/bashly/views/command/usage.gtx
 - lib/bashly/views/command/usage_args.gtx
 - lib/bashly/views/command/usage_commands.gtx
@@ -328,14 +334,14 @@ files:
 - lib/bashly/views/wrapper/bash3_bouncer.gtx
 - lib/bashly/views/wrapper/header.gtx
 - lib/bashly/views/wrapper/wrapper.gtx
-homepage: https://github.com/dannyben/bashly
+homepage: https://github.com/bashly-framework/bashly
 licenses:
 - MIT
 metadata:
-  bug_tracker_uri: https://github.com/DannyBen/bashly/issues
-  changelog_uri: https://github.com/DannyBen/bashly/blob/master/CHANGELOG.md
+  bug_tracker_uri: https://github.com/bashly-framework/bashly/issues
+  changelog_uri: https://github.com/bashly-framework/bashly/blob/master/CHANGELOG.md
   homepage_uri: https://bashly.dev/
-  source_code_uri: https://github.com/DannyBen/bashly
+  source_code_uri: https://github.com/bashly-framework/bashly
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: