bashly 1.0.7 → 1.1.0

data/lib/bashly/libraries/render/mandoc/mandoc.gtx

@@ -0,0 +1,196 @@
+# Reference: https://linux.die.net/man/5/pandoc_markdown
+
+if version
+  > % {{ full_name.to_hyphen }}(1) Version {{ version }} | {{ summary }}
+else
+  > % {{ full_name.to_hyphen }}(1) | {{ summary }}
+end
+
+> % {{ x_mandoc_authors&.for_manpage }}
+> % {{ Date.today.strftime "%B %Y" }}
+>
+
+> NAME
+> ==================================================
+> 
+> **{{ full_name }}** - {{ summary }}
+>
+
+> SYNOPSIS
+> ==================================================
+> 
+> {{ usage_string.gsub(/^#{full_name}/, "**#{full_name}**") }}
+>
+
+> DESCRIPTION
+> ==================================================
+> 
+> {{ help.for_manpage }}
+>
+
+if default
+  > - *Default Command*
+end
+if alt.any?
+  > - Alias: **{{ alt.join ', ' }}**
+end
+if extensible
+  if extensible.is_a? String
+    > - Extensible: **{{ extensible }}**
+  else
+    > - *Extensible*
+  end
+end
+>
+
+if public_commands.any?
+  grouped_commands.each do |group, commands|
+    > {{ group.gsub(/:$/, '').upcase }}
+    > ==================================================
+    >
+    commands.each do |subcommand|
+      > {{ subcommand.full_name }}
+      > --------------------------------------------------
+      >
+      > {{ subcommand.summary.for_manpage }}
+      >
+    end
+    >
+  end
+end
+
+if args.any?
+  > ARGUMENTS
+  > ==================================================
+  > 
+  args.each do |arg|
+    > {{ arg.name.upcase }}
+    > --------------------------------------------------
+    >
+    > {{ arg.help.for_manpage }}
+    >
+    if arg.required
+      > - *Required*
+    end
+    if arg.repeatable
+      > - *Repeatable*
+    end
+    if arg.default
+      > - Default Value: **{{ arg.default }}**
+    end
+    if arg.allowed
+      > - Allowed Values: **{{ arg.allowed.join(', ') }}**
+    end    
+    >
+  end
+
+  if catch_all.label && catch_all.help
+    > {{ catch_all.label }}
+    > --------------------------------------------------
+    >
+    if catch_all.help
+      > {{ catch_all.help.for_manpage }}
+      >
+    end
+    >
+
+    if catch_all.required?
+      > - *Required*
+      >
+    end
+  end
+end
+
+if flags.any?
+  > OPTIONS
+  > ==================================================
+  > 
+  flags.each do |flag|
+    > {{ flag.usage_string }}
+    > --------------------------------------------------
+    >
+    > {{ flag.help.for_manpage }}
+    >
+
+    if flag.required
+      > - *Required*
+    end
+    if flag.repeatable
+      > - *Repeatable*
+    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
+    >
+  end
+end
+
+if dependencies.any?
+  > DEPENDENCIES
+  > ==================================================
+  >
+  dependencies.each do |dependency|
+    > {{ dependency.commands.join ', ' }}
+    > --------------------------------------------------
+    >
+    if dependency.help
+      > {{ dependency.help.for_manpage }}
+      >
+    end
+    >
+  end
+end
+
+if public_environment_variables.any?
+  > ENVIRONMENT VARIABLES
+  > ==================================================
+  >
+  public_environment_variables.each do |environment_variable|
+    > {{ environment_variable.name.upcase }}
+    > --------------------------------------------------
+    >
+    > {{ environment_variable.help.for_manpage }}
+    >
+
+    if environment_variable.required
+      > - *Required*
+    end
+    if environment_variable.default
+      > - Default Value: **{{ environment_variable.default }}**
+    end
+    >
+  end
+end
+
+if examples
+  > EXAMPLES
+  > ==================================================
+  >
+  > ~~~
+  examples.each do |example|
+    > {{ example.for_manpage }}
+    >
+  end
+  > ~~~
+  >
+end
+
+if public_commands.any? || parents.any?
+  > SEE ALSO
+  > ==================================================
+  >
+  if parents.any?
+    > **{{ parents.first }}**(1)
+  end
+  = public_commands.map { |x| "**#{x.full_name.to_hyphen}**(1)" }.join ', '
+  >
+end
+
+= x_mandoc_footer&.for_manpage
+>

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

@@ -0,0 +1,34 @@
+# render script - mandoc
+require 'gtx'
+
+# Load the GTX template
+template = "#{source}/mandoc.gtx"
+gtx = GTX.load_file template
+
+# Define a reusable code block for rendering a man page for a command
+save_manpage = lambda { |command|
+  mdfile = "#{target}/#{command.full_name.tr(' ', '-')}.md"
+  manfile = "#{target}/#{command.full_name.tr(' ', '-')}.1"
+  save mdfile, gtx.parse(command)
+
+  # The pandoc command that creates a manpage from markdown
+  cmd = %[pandoc -f markdown-smart -s --to man "#{mdfile}" > "#{manfile}"]
+  success = system cmd
+  raise "Failed running pandoc\nMake sure the following command succeeds and try again:\n\n  #{cmd}" unless success
+
+  say "g`saved` #{manfile}"
+}
+
+# Render the main command
+save_manpage.call command
+
+# Render all subcommands
+command.deep_commands.reject(&:private).each do |subcommand|
+  save_manpage.call subcommand
+end
+
+# Show one of the files if requested
+if show
+  file = "#{target}/#{show}"
+  system "man #{file}" if File.exist?(file)
+end

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

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

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

@@ -0,0 +1,42 @@
+# Render markdown
+
+Render markdown documents for your script.
+
+## Usage
+
+```bash
+# Generate all documents to the ./docs directory
+$ bashly render :markdown docs
+
+# Generate on change, and show one of the files
+$ bashly render :markdown docs --watch --show 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>
+```
+
+## Markdown server
+
+In order to view your markdown files in a browser, you can use the
+[Madness markdown server](https://madness.dannyb.co/):
+
+```bash
+$ gem install madness
+$ madness server docs
+```

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

@@ -0,0 +1,186 @@
+# === 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 public_environment_variables.any?
+  > ## Environment Variables
+  >
+  public_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') }}) - {{ 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.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
+      >
+    end
+  end
+end
+
+= x_markdown_footer&.for_manpage
+>

data/lib/bashly/libraries/render/markdown/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}/index.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/summary.txt

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

data/lib/bashly/refinements/compose_refinements.rb

@@ -1,5 +1,3 @@
-require 'yaml'
-
 module ComposeRefinements
   refine Hash do
     def compose(keyword = 'import')

data/lib/bashly/render_context.rb

@@ -0,0 +1,30 @@
+require 'date'    # for use by template render scripts
+require 'colsole'
+
+module Bashly
+  class RenderContext
+    include Colsole
+
+    attr_reader :source, :target, :show
+    attr_writer :config
+
+    def initialize(source:, target:, show: nil)
+      @source = source
+      @target = target
+      @show = show
+    end
+
+    def config
+      @config ||= Config.new Settings.config_path
+    end
+
+    def command
+      @command ||= Script::Command.new config
+    end
+
+    def save(filename, content)
+      File.deep_write filename, content
+      say "g`saved` #{filename}"
+    end
+  end
+end

data/lib/bashly/render_source.rb

@@ -0,0 +1,71 @@
+module Bashly
+  class RenderSource
+    attr_reader :selector
+
+    class << self
+      include AssetHelper
+
+      def internal
+        @internal ||= internal_dirs.to_h do |dir|
+          selector = File.basename(dir).to_sym
+          [selector, new(selector)]
+        end
+      end
+
+      def internal_dirs
+        @internal_dirs ||= Dir["#{internal_root}/*"].select { |x| File.directory? x }
+      end
+
+      def internal_root
+        asset('libraries/render')
+      end
+    end
+
+    def initialize(selector)
+      @selector = selector
+    end
+
+    def render(target, show: nil)
+      context = RenderContext.new source: path, target: target, show: show
+      context.instance_eval render_script
+    end
+
+    def internal?
+      selector.is_a? Symbol
+    end
+
+    def path
+      internal? ? "#{internal_root}/#{selector}" : selector
+    end
+
+    def exist?
+      Dir.exist? path
+    end
+
+    def summary
+      File.readlines(summary_file)[0].chomp
+    end
+
+    def readme
+      File.read readme_file if File.exist? readme_file
+    end
+
+  private
+
+    def render_script
+      @render_script ||= File.read "#{path}/render.rb"
+    end
+
+    def internal_root
+      self.class.internal_root
+    end
+
+    def summary_file
+      "#{path}/summary.txt"
+    end
+
+    def readme_file
+      "#{path}/README.md"
+    end
+  end
+end

data/lib/bashly/script/base.rb

@@ -35,7 +35,8 @@ module Bashly
       end
 
       def respond_to_missing?(method_name, include_private = false)
-        self.class.option_keys.include?(method_name) || super
+        self.class.option_keys.include?(method_name) ||
+          method_name.to_s.start_with?('x_') || super
       end
     end
   end

data/lib/bashly/script/command.rb

@@ -200,6 +200,23 @@ module Bashly
         end
       end
 
+      # Returns subcommands by group
+      def grouped_commands
+        result = {}
+
+        public_commands.each do |command|
+          result[command.group_string] ||= []
+          result[command.group_string] << command
+          next unless command.expose
+
+          command.public_commands.each do |subcommand|
+            result[command.group_string] << subcommand
+          end
+        end
+
+        result
+      end
+
       # Returns a mode identifier
       def mode
         @mode ||= if global_flags?    then :global_flags

data/lib/bashly/version.rb

@@ -1,3 +1,3 @@
 module Bashly
-  VERSION = '1.0.7'
+  VERSION = '1.1.0'
 end

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

@@ -7,7 +7,7 @@ if dependencies.any?
     > else
     >   printf "{{ strings[:missing_dependency] % { dependency: dependency.name } }}\n" >&2
     if dependency.help
-      >   printf "%s\n" "{{ dependency.help }}" >&2
+      >   printf "%s\n" "{{ dependency.help.sanitize_for_print }}" >&2
     end
     >   exit 1
     > fi

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

@@ -1,5 +1,5 @@
 = view_marker
 
-> printf "{{ footer.gsub("\n", '\n').gsub('"', '\"') }}\n"
+> printf "{{ footer.sanitize_for_print }}\n"
 > echo
 >

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

@@ -27,7 +27,7 @@ if catch_all.enabled?
   >       ;;
 
 else
-  >       printf "<%= strings[:invalid_flag] %>\n" "$key" >&2
+  >       printf "{{ strings[:invalid_flag] }}\n" "$key" >&2
   >       exit 1
   >       ;;
 

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

@@ -4,7 +4,7 @@
 >   if [[ -n $long_usage ]]; then
 
 if summary == help
-  >     printf "{{ caption_string }}\n"
+  >     printf "{{ caption_string.sanitize_for_print }}\n"
   >     echo 
 else
   >     printf "{{ full_name }}\n"
@@ -14,7 +14,7 @@ else
 end
 
 >   else
->     printf "{{ caption_string }}\n"
+>     printf "{{ caption_string.sanitize_for_print }}\n"
 >     echo 
 >   fi
 > 

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

@@ -7,9 +7,9 @@ command_help_data.each do |group, commands|
 
   commands.each do |command, info|
     if info[:help_only]
-      > [[ -n $long_usage ]] && printf "  %s   {{ info[:summary] }}\n" "{{ command.ljust(maxlen).color(:command) }}"
+      > [[ -n $long_usage ]] && printf "  %s   {{ info[:summary].sanitize_for_print }}\n" "{{ command.ljust(maxlen).color(:command) }}"
     else
-      > printf "  %s   {{ info[:summary] }}\n" "{{ command.ljust(maxlen).color(:command) }}"
+      > printf "  %s   {{ info[:summary].sanitize_for_print }}\n" "{{ command.ljust(maxlen).color(:command) }}"
     end
   end