bashly 1.0.7 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a333ce419f5ba64e38000497f245fc5baf822243cd2765c1805ebdf6de2e3b46
-  data.tar.gz: 0c9ab24cc2cecd88cbd20a06ab11028740ce3000aec75080ca9a12c6769110c1
+  metadata.gz: d333139a3555fdc50cdb3ddf21119712fcada4ab837f5703f29529f346c6ad24
+  data.tar.gz: 0a40e42bfa542ed5d4f8d59792aa2a19518ae1c9098db0309f9349db391c74b2
 SHA512:
-  metadata.gz: ff95fd919a29a16d610d8f3c069f2de17b9984a41251de56e484a5dc49e86dd4114934c47ccb2274521f7f8bd5078287a54ef10478c5e18b6c8a93f462f1c503
-  data.tar.gz: 65a1be57601cc7a560a19ef48dc75b09647244fe477327f23ae52a37f8114afca4ee3871a1f72e1b046589e252a57701956a93e9015907bf76fd24455da341ff
+  metadata.gz: e601e098208e0a5de186279e67c001ff58c44536f09e5cea6815722e9bef3ec3dc1b257c1b9ca2267e94977f05514916a66f03721c88c5a795cab93e8eadb20d
+  data.tar.gz: 670bcae80903cdabc5d76b5139b1c6d80b1ee3ca33af03078a340a847c4ef1385ca74ca08b2b0a274845f0be5ecfc7ecd9822575b8f8ea8cb3592b821df22760

data/README.md

@@ -71,7 +71,8 @@ Bashly is responsible for:
   - **Config file management** (INI format).
   - **YAML parsing**.
   - **Bash completions**.
-  - and more.
+  - *and more*.
+- Auto-generating **markdown and man page documentation** for your script.
 
 ## Contributing / Support
 

data/lib/bashly/cli.rb

@@ -16,6 +16,7 @@ module Bashly
       runner.route 'add',         to: Commands::Add
       runner.route 'doc',         to: Commands::Doc
       runner.route 'completions', to: Commands::Completions
+      runner.route 'render',      to: Commands::Render
       runner.route 'shell',       to: Commands::Shell unless ENV['BASHLY_SHELL']
 
       runner

data/lib/bashly/commands/completions.rb

@@ -4,7 +4,7 @@ module Bashly
       summary 'Install bash completions for bashly itself'
       help 'Display the bash completions script or install it directly to your bash completions directory'
 
-      usage 'bashly completions [--install --uninstall]'
+      usage 'bashly completions [--install|--uninstall]'
       usage 'bashly completions (-h|--help)'
 
       option '-i --install', 'Install the completions script to your bash completions directory'

data/lib/bashly/commands/render.rb

@@ -0,0 +1,103 @@
+require 'filewatcher'
+require 'tty-markdown'
+
+module Bashly
+  module Commands
+    class Render < Base
+      help 'Render the bashly data structure using cutsom templates'
+
+      usage 'bashly render SOURCE TARGET [--watch --show PATH]'
+      usage 'bashly render SOURCE --about'
+      usage 'bashly render --list'
+      usage 'bashly render (-h|--help)'
+
+      param 'SOURCE', <<~HELP
+        An ID to an internal templates source, or a path to a custom templates directory.
+
+        A leading colon (:) denotes an internal ID (see `--list`).
+      HELP
+
+      param 'TARGET', 'Output directory'
+
+      option '-w --watch', 'Watch bashly.yml and the templates source for changes and render on change'
+      option '-s --show PATH', <<~USAGE
+        After rendering, show the result generated in PATH.
+
+        The provided PATH is treated as relative TARGET.
+
+        Note that this works only if the template source supports it.
+      USAGE
+
+      option '-l --list', 'Show list of built-in templates'
+      option '-a --about', 'Show information about a given templates source'
+
+      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 /path/to/templates ./out_path'
+
+      attr_reader :watching, :target, :source
+
+      def run
+        if args['--list'] then show_list
+        elsif args['--about'] then show_about
+        else
+          start_render
+        end
+      end
+
+    private
+
+      def show_list
+        RenderSource.internal.each_value do |source|
+          say "g`:#{source.selector.to_s.ljust 10}`  #{source.summary}"
+        end
+      end
+
+      def show_about
+        puts TTY::Markdown.parse(render_source.readme)
+      end
+
+      def start_render
+        @target = args['TARGET']
+        @watching = args['--watch']
+
+        render
+        watch if watching
+      end
+
+      def render
+        render_source.render target, show: args['--show']
+      end
+
+      def watch
+        say "g`watching`\n"
+
+        Filewatcher.new(watchables).watch do
+          render
+          say "g`waiting`\n"
+        end
+      end
+
+      def render_source
+        @render_source ||= begin
+          source = RenderSource.new selector
+          raise "Invalid render source: #{args['SOURCE']}" unless source.exist?
+
+          source
+        end
+      end
+
+      def selector
+        return args['SOURCE'] unless args['SOURCE'].start_with? ':'
+
+        args['SOURCE'][1..].to_sym
+      end
+
+      def watchables
+        @watchables ||= [Settings.config_path, render_source.path]
+      end
+    end
+  end
+end

data/lib/bashly/concerns/validation_helpers.rb

@@ -40,7 +40,7 @@ module Bashly
 
       return unless keys
 
-      invalid_keys = value.keys.map(&:to_sym) - keys
+      invalid_keys = (value.keys.map(&:to_sym) - keys).reject { |k| k.start_with? 'x_' }
       assert invalid_keys.empty?, "#{key} contains invalid options: #{invalid_keys.join ', '}"
     end
 

data/lib/bashly/config.rb

@@ -1,5 +1,3 @@
-require 'yaml'
-
 module Bashly
   # A convenience class to use either a hash or a filename as a configuration
   # source.

data/lib/bashly/extensions/string.rb

@@ -1,6 +1,18 @@
 class String
   def sanitize_for_print
-    gsub("\n", '\\n').gsub('"', '\"')
+    gsub("\n", '\\n').gsub('"', '\"').gsub('`', '\\\\`')
+  end
+
+  def for_markdown
+    gsub('<', '\\<').gsub('>', '\\>').nl2br
+  end
+
+  def for_manpage
+    gsub('<', '\\<').gsub('>', '\\>').gsub('`', '**').gsub("  \n", "\n\n")
+  end
+
+  def nl2br
+    gsub("\n", "  \n")
   end
 
   def indent(offset)
@@ -13,6 +25,10 @@ class String
     gsub(/(.)([A-Z])/, '\1_\2').gsub(/[- ]/, '_').downcase
   end
 
+  def to_hyphen
+    tr(' ', '-').gsub(/([a-z])([A-Z])/, '\1-\2').downcase
+  end
+
   def to_path
     tr(' ', '/').downcase
   end

data/lib/bashly/extensions/yaml.rb

@@ -1,9 +1,12 @@
+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
+    alias load unsafe_load if YAML.respond_to? :unsafe_load
 
     def load_erb_file(path)
       YAML.load ERB.new(File.read(path)).result

data/lib/bashly/libraries/config/config.sh

@@ -1,128 +1,108 @@
-## Config functions [@bashly-upgrade config]
+## Config (INI) functions [@bashly-upgrade config]
 ## This file is a part of Bashly standard library
 ##
 ## Usage:
-## - In your script, set the CONFIG_FILE variable. For rxample:
-##   CONFIG_FILE=settings.ini.
-##   If it is unset, it will default to 'config.ini'.
-## - Use any of the functions below to access the config file.
 ##
-## Create a new config file.
-## There is normally no need to use this function, it is used by other
-## functions as needed.
+## - Set the global variable CONFIG_FILE to the path of your INI file somewhere
+##   in your script (for example, in src/initialize.sh).
+## - Use any of the following functions to access and manipulate the values.
+## - INI sections are optional (i.e., sectionless key=value pairs are allowed).
 ##
-config_init() {
-  CONFIG_FILE=${CONFIG_FILE:=config.ini}
-  [[ -f "$CONFIG_FILE" ]] || touch "$CONFIG_FILE"
+
+## Show all the key=value pairs from your config file
+config_show() {
+  config_load
+  ini_show
 }
 
-## Get a value from the config.
-## Usage: result=$(config_get hello)
+## Get a single value from the config file:
+##
+##   config_get login.email
+##
+## Get the value or a default one if it is not set:
+##
+##   config_get login.user guest
+##
+## Assign the result to a variable:
+##
+##   theme="$(config_get interface.theme)"
+##
 config_get() {
-  local key=$1
-  local regex="^$key *= *(.+)$"
-  local value=""
-
-  config_init
+  local key="$1"
+  local default_value="$2"
 
-  while IFS= read -r line || [ -n "$line" ]; do
-    if [[ $line =~ $regex ]]; then
-      value="${BASH_REMATCH[1]}"
-      break
-    fi
-  done <"$CONFIG_FILE"
-
-  echo "$value"
+  config_load
+  echo "${ini["$key"]:-$default_value}"
 }
 
-## Add or update a key=value pair in the config.
-## Usage: config_set key value
+## Create/update a key=value pair:
+##
+##   config_set cloud.provider aws
+##
 config_set() {
-  local key=$1
+  local key="$1"
   shift
   local value="$*"
 
-  config_init
-
-  local regex="^($key) *= *.+$"
-  local output=""
-  local found_key=""
-  local newline
-
-  while IFS= read -r line || [ -n "$line" ]; do
-    newline=$line
-    if [[ $line =~ $regex ]]; then
-      found_key="${BASH_REMATCH[1]}"
-      newline="$key = $value"
-      output="$output$newline\n"
-    elif [[ $line ]]; then
-      output="$output$line\n"
-    fi
-  done <"$CONFIG_FILE"
-
-  if [[ -z $found_key ]]; then
-    output="$output$key = $value\n"
-  fi
-
-  printf "%b\n" "$output" >"$CONFIG_FILE"
+  config_load
+  ini["$key"]="$value"
+  config_save
 }
 
-## Delete a key from the config.
-## Usage: config_del key
+## Delete a key=value pair:
+##
+##   config_del login.email
+##
 config_del() {
-  local key=$1
+  local key="$1"
 
-  local regex="^($key) *="
-  local output=""
-
-  config_init
-
-  while IFS= read -r line || [ -n "$line" ]; do
-    if [[ $line ]] && [[ ! $line =~ $regex ]]; then
-      output="$output$line\n"
-    fi
-  done <"$CONFIG_FILE"
-
-  printf "%b\n" "$output" >"$CONFIG_FILE"
-}
-
-## Show the config file
-config_show() {
-  config_init
-  cat "$CONFIG_FILE"
+  config_load
+  unset "ini[$key]"
+  config_save
 }
 
-## Return an array of the keys in the config file.
-## Usage:
+## Get an array of all keys:
 ##
-##   for k in $(config_keys); do
-##     echo "- $k = $(config_get "$k")";
+##   for key in $(config_keys); do
+##     echo "- $key = $(config_get "$key")";
 ##   done
 ##
 config_keys() {
-  local regex="^([a-zA-Z0-9_\-\/\.]+) *="
-
-  config_init
-
-  local keys=()
-  local key
-
-  while IFS= read -r line || [ -n "$line" ]; do
-    if [[ $line =~ $regex ]]; then
-      key="${BASH_REMATCH[1]}"
-      keys+=("$key")
-    fi
-  done <"$CONFIG_FILE"
-  echo "${keys[@]}"
+  config_load
+  ini_keys
 }
 
-## Returns true if the specified key exists in the config file.
-## Usage:
+## Check if a key exists:
 ##
-##   if config_has_key "key"; then
+##   if config_has_key login.password; then
 ##     echo "key exists"
 ##   fi
 ##
 config_has_key() {
   [[ $(config_get "$1") ]]
 }
+
+## Force-load from file
+## This should normally not be called, unless you suspect that the INI file
+## was modified by external means during the run of your script.
+config_reload() {
+  declare -g config_loaded=false
+  config_load
+}
+
+## Load an INI file (unless loaded) and populate the associative array
+## NOTE: Normally there is no need to call this function, it is called as needed
+config_load() {
+  [[ "$config_loaded" == "true" ]] && return
+
+  declare -g CONFIG_FILE=${CONFIG_FILE:=config.ini}
+  declare -g config_loaded=true
+  [[ -f "$CONFIG_FILE" ]] || touch "$CONFIG_FILE"
+  ini_load "$CONFIG_FILE"
+}
+
+## Save the associative array back to a file
+## NOTE: Normally there is no need to call this function, it is called as needed
+config_save() {
+  ini_save "$CONFIG_FILE"
+}

data/lib/bashly/libraries/ini/ini.sh

@@ -0,0 +1,110 @@
+## INI functions [@bashly-upgrade ini]
+## This file is a part of Bashly standard library
+##
+## Usage:
+##
+## - In your script, call `ini_load path/to/config.ini`.
+## - A global associative array named `ini` will become available to you,
+## - When updating any of the associative array's values, call
+##   `ini_save path/to/config.ini` to save the data.
+## - INI sections are optional.
+##
+## Get a value:
+##
+##   ${ini[section1.key1]}  # for keys under a [section]
+##   ${ini[key1]}           # for keys not under a [section]
+##   ${ini[key1]:-default}  # get a default value if the INI key is unset
+##
+## Update/create a value:
+##
+##   ini[section1.key1]="value"
+##   ini_save path/to/config.ini
+##
+## Delete a value
+##
+##   unset ini[section1.key1]
+##   ini_save path/to/config.ini
+##
+
+## Load an INI file and populate the associative array `ini`.
+ini_load() {
+  declare -gA ini
+
+  local ini_file="$1"
+
+  local section=""
+  local key=""
+  local value=""
+  local section_regex="^\[(.+)\]"
+  local key_regex="^([^ =]+) *= *(.*) *$"
+  local comment_regex="^;"
+
+  while IFS= read -r line; do
+    if [[ $line =~ $comment_regex ]]; then
+      continue
+    elif [[ $line =~ $section_regex ]]; then
+      section="${BASH_REMATCH[1]}."
+    elif [[ $line =~ $key_regex ]]; then
+      key="${BASH_REMATCH[1]}"
+      value="${BASH_REMATCH[2]}"
+      ini["${section}${key}"]="$value"
+    fi
+  done <"$ini_file"
+}
+
+## Save the associative array `ini` back to a file
+ini_save() {
+  declare -gA ini
+
+  local ini_file="$1"
+
+  local current_section=""
+  local has_free_keys=false
+
+  rm -f "$ini_file"
+
+  for key in $(ini_keys); do
+    [[ $key == *.* ]] && continue
+    has_free_keys=true
+    value="${ini[$key]}"
+    echo "$key = $value" >>"$ini_file"
+  done
+
+  [[ "${has_free_keys}" == "true" ]] && echo >>"$ini_file"
+
+  for key in $(ini_keys); do
+    [[ $key == *.* ]] || continue
+    value="${ini[$key]}"
+    IFS="." read -r section_name key_name <<<"$key"
+
+    if [[ "$current_section" != "$section_name" ]]; then
+      [[ $current_section ]] && echo >>"$ini_file"
+      echo "[$section_name]" >>"$ini_file"
+      current_section="$section_name"
+    fi
+    
+    echo "$key_name = $value" >>"$ini_file"
+  done
+}
+
+## Show all loaded key-value pairs
+ini_show() {
+  declare -gA ini
+
+  for key in $(ini_keys); do
+    echo "$key = ${ini[$key]}"
+  done
+}
+
+## Get an array of all keys:
+##
+##   for key in $(ini_keys); do
+##     echo "- $key = ${ini[$key]}";
+##   done
+##
+ini_keys() {
+  declare -gA ini
+
+  local keys=("${!ini[@]}")
+  for a in "${keys[@]}"; do echo "$a"; done | sort
+}

data/lib/bashly/libraries/libraries.yml

@@ -20,10 +20,12 @@ completions_yaml:
   handler: Bashly::Libraries::CompletionsYAML
 
 config:
-  help: Add standard functions for handling INI files to the lib directory.
+  help: Add functions for handling INI configuration files to the lib directory.
   files:
     - source: "config/config.sh"
       target: "%{user_lib_dir}/config.%{user_ext}"
+    - source: "ini/ini.sh"
+      target: "%{user_lib_dir}/ini.%{user_ext}"
 
 help:
   help: Add a help command, in addition to the standard --help flag.
@@ -39,6 +41,12 @@ hooks:
     - source: "hooks/after.sh"
       target: "%{user_source_dir}/after.%{user_ext}"
 
+ini:
+  help: Add low level functions for reading/writing INI files to the lib directory.
+  files:
+    - source: "ini/ini.sh"
+      target: "%{user_lib_dir}/ini.%{user_ext}"
+
 lib:
   help: |-
     Create the lib directory for any additional user scripts.
@@ -48,6 +56,37 @@ lib:
     - source: "lib/sample_function.sh"
       target: "%{user_lib_dir}/sample_function.%{user_ext}"
 
+render_markdown:
+  help: Copy the markdown templates to your project, allowing you to customize the markdown documentation output.
+  skip_src_check: true
+  files:
+    - source: "render/markdown/README.md"
+      target: "templates/markdown/README.md"
+    - source: "render/markdown/markdown.gtx"
+      target: "templates/markdown/markdown.gtx"
+    - source: "render/markdown/render.rb"
+      target: "templates/markdown/render.rb"
+  post_install_message: |
+    Generate your markdown documentation by running:
+
+      m`$ bashly render templates/markdown docs`
+
+render_mandoc:
+  help: Copy the mandoc templates to your project, allowing you to customize the man documentation output.
+  skip_src_check: true
+  files:
+    - source: "render/mandoc/README.md"
+      target: "templates/mandoc/README.md"
+    - source: "render/mandoc/mandoc.gtx"
+      target: "templates/mandoc/mandoc.gtx"
+    - source: "render/mandoc/render.rb"
+      target: "templates/mandoc/render.rb"
+  post_install_message: |
+    Note that this template requires pandoc.
+    Generate your man pages by running:
+
+      m`$ bashly render templates/mandoc docs`
+
 settings:
   help: Copy a sample settings.yml file to your project, allowing you to customize some bashly options.
   skip_src_check: true

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

@@ -0,0 +1,45 @@
+# Render mandoc
+
+Render man pages for your script.
+
+Note that this renderer will render specially formatted markdown documents and
+will then use [pandoc](https://command-not-found.com/pandoc) to convert them.
+
+## Usage
+
+```bash
+# Generate all man pages to the ./docs directory
+$ bashly render :mandoc docs
+
+# Generate on change, and show one of the files
+$ bashly render :mandoc docs --watch --show cli-download.1
+```
+
+## Supported custom definitions
+
+Add these definitions to your `bashly.yml` to render them in your
+markdown:
+
+### Footer: `x_mandoc_footer`
+
+Add additional sections to your man pages. This field is expected
+to be in markdown format.
+
+#### Example
+
+```yaml
+x_mandoc_footer: |-
+  # ISSUE TRACKER
+
+  Report issues at <https://github.com/lanalang/smallville>
+```
+
+### Authors: `x_mandoc_authors`
+
+Add an authors string to your man pages.
+
+#### Example
+
+```yaml
+x_mandoc_authors: Lana Lang
+```