howzit 2.0.9 → 2.0.12

data/lib/howzit/stringutils.rb

@@ -3,7 +3,37 @@
 module Howzit
   # String Extensions
   module StringUtils
+    ##
+    ## Test if the filename matches the conditions to be a build note
+    ##
+    ## @return     [Boolean] true if filename passes test
+    ##
+    def build_note?
+      return false if downcase !~ /^(howzit[^.]*|build[^.]+)/
+
+      return false if Howzit.config.should_ignore(self)
+
+      true
+    end
+
+    ##
+    ## Replace slash escaped characters in a string with a
+    ## zero-width space that will prevent a shell from
+    ## interpreting them when output to console
+    ##
+    ## @return     [String] new string
+    ##
+    def preserve_escapes
+      gsub(/\\([a-z])/, '\​\1')
+    end
+
     # Convert a string to a valid YAML value
+    #
+    # @param      orig_value  The original value from which
+    #                         type will be determined
+    #
+    # @return     coerced value
+    #
     def to_config_value(orig_value = nil)
       if orig_value
         case orig_value.class.to_s
@@ -28,10 +58,21 @@ module Howzit
       end
     end
 
+    ##
+    ## Shortcut for calling Color.template
+    ##
+    ## @return     [String] colorized string
+    ##
     def c
       Color.template(self)
     end
 
+
+    ##
+    ## Convert a string to a regex object based on matching settings
+    ##
+    ## @return     [Regexp] Receive regex representation of the object.
+    ##
     def to_rx
       case Howzit.options[:matching]
       when 'exact'
@@ -50,9 +91,17 @@ module Howzit
       gsub(/\e\[[\d;]+m/, '').gsub(/\e\]1337;SetMark/,'')
     end
 
+    # Wrap text at a specified width.
+    #
     # Adapted from https://github.com/pazdera/word_wrap/,
-    # copyright (c) 2014, 2015  Radek Pazdera
-    # Distributed under the MIT License
+    # copyright (c) 2014, 2015  Radek Pazdera Distributed
+    # under the MIT License
+    #
+    # @param      width  [Integer] The width at which to
+    #                    wrap lines
+    #
+    # @return     [String] wrapped string
+    #
     def wrap(width)
       width ||= 80
       output = []
@@ -84,12 +133,19 @@ module Howzit
       output.join("\n")
     end
 
+    ##
+    ## Wrap string in place (destructive)
+    ##
+    ## @param      width  [Integer] The width at which to wrap
+    ##
     def wrap!(width)
       replace(wrap(width))
     end
 
     # Truncate string to nearest word
-    # @param len <number> max length of string
+    #
+    # @param      len   [Integer] max length of string
+    #
     def trunc(len)
       split(/ /).each_with_object([]) do |x, ob|
         break ob unless ob.join(' ').length + ' '.length + x.length <= len
@@ -98,10 +154,21 @@ module Howzit
       end.join(' ').strip
     end
 
+    ##
+    ## Truncate string in place (destructive)
+    ##
+    ## @param      len   [Integer] The length to truncate at
+    ##
     def trunc!(len)
       replace trunc(len)
     end
 
+    ##
+    ## Splits a line at nearest word break
+    ##
+    ## @param      width   [Integer] The width of the first segment
+    ## @param      indent  [String] The indent string
+    ##
     def split_line(width, indent = '')
       line = dup
       at = line.index(/\s/)
@@ -119,10 +186,23 @@ module Howzit
       end
     end
 
+    ##
+    ## Test if an executable is available on the system
+    ##
+    ## @return     [Boolean] executable is available
+    ##
     def available?
       Util.valid_command?(self)
     end
 
+    ##
+    ## Render [%variable] placeholders in a templated string
+    ##
+    ## @param      vars  [Hash] Key/value pairs of variable
+    ##                   values
+    ##
+    ## @return     [String] Rendered string
+    ##
     def render_template(vars)
       vars.each do |k, v|
         gsub!(/\[%#{k}(:.*?)?\]/, v)
@@ -131,10 +211,20 @@ module Howzit
       gsub(/\[%(.*?):(.*?)\]/, '\2')
     end
 
+    ##
+    ## Render [%variable] placeholders in place
+    ##
+    ## @param      vars  [Hash] Key/value pairs of variable values
+    ##
     def render_template!(vars)
       replace render_template(vars)
     end
 
+    ##
+    ## Render $X placeholders based on positional arguments
+    ##
+    ## @return     [String] rendered string
+    ##
     def render_arguments
       return self if Howzit.arguments.nil? || Howzit.arguments.empty?
 
@@ -145,6 +235,13 @@ module Howzit
       gsub(/\$[@*]/, Shellwords.join(Howzit.arguments))
     end
 
+    ##
+    ## Split the content at the first top-level header and
+    ## assume everything before it is metadata. Passes to
+    ## #get_metadata for processing
+    ##
+    ## @return     [Hash] key/value pairs
+    ##
     def extract_metadata
       if File.exist?(self)
         leader = Util.read_file(self).split(/^#/)[0].strip
@@ -154,6 +251,11 @@ module Howzit
       end
     end
 
+    ##
+    ## Examine text for multimarkdown-style metadata and return key/value pairs
+    ##
+    ## @return     [Hash] The metadata as key/value pairs
+    ##
     def get_metadata
       data = {}
       scan(/(?mi)^(\S[\s\S]+?): ([\s\S]*?)(?=\n\S[\s\S]*?:|\Z)/).each do |m|
@@ -162,6 +264,13 @@ module Howzit
       normalize_metadata(data)
     end
 
+    ##
+    ## Autocorrect some keys
+    ##
+    ## @param      meta  [Hash] The metadata
+    ##
+    ## @return     [Hash] corrected metadata
+    ##
     def normalize_metadata(meta)
       data = {}
       meta.each do |k, v|
@@ -177,15 +286,33 @@ module Howzit
       data
     end
 
+    ##
+    ## Test if iTerm markers should be output. Requires that
+    ## the $TERM_PROGRAM be iTerm and howzit is not running
+    ## directives or paginating output
+    ##
+    ## @return     [Boolean] should mark?
+    ##
     def should_mark_iterm?
       ENV['TERM_PROGRAM'] =~ /^iTerm/ && !Howzit.options[:run] && !Howzit.options[:paginate]
     end
 
+    ##
+    ## Output an iTerm marker
+    ##
+    ## @return     [String] ANSI escape sequence for iTerm
+    ##             marker
+    ##
     def iterm_marker
       "\e]1337;SetMark\a" if should_mark_iterm?
     end
 
     # Make a fancy title line for the topic
+    #
+    # @param      opts  [Hash] options
+    #
+    # @return     [String] formatted string
+    #
     def format_header(opts = {})
       title = dup
       options = {

data/lib/howzit/task.rb

@@ -1,14 +1,18 @@
 # frozen_string_literal: true
 
 module Howzit
+  # Task object
   class Task
     attr_reader :type, :title, :action, :parent, :optional, :default
 
-    def initialize(type, title, action, parent = nil, optional: false, default: true)
-      @type = type
-      @title = title
-      @action = action.render_arguments
-      @parent = parent
+    ##
+    ## Initialize a Task object
+    ##
+    def initialize(params, optional: false, default: true)
+      @type = params[:type]
+      @title = params[:title]
+      @action = params[:action].render_arguments
+      @parent = params[:parent] || nil
       @optional = optional
       @default = default
     end
@@ -22,7 +26,7 @@ module Howzit
     end
 
     def to_list
-      "    * #{@type}: #{@title.gsub(/\\n/, '\​n')}"
+      "    * #{@type}: #{@title.preserve_escapes}"
     end
   end
 end

data/lib/howzit/topic.rb

@@ -52,7 +52,13 @@ module Howzit
 
         @tasks.each do |task|
           if task.optional
-            q = %({bg}#{task.type.to_s.capitalize} {xw}"{bw}#{task.title}{xw}"{x}).c
+            note = if task.type == :include
+                     task_count = Howzit.buildnote.find_topic(task.action)[0].tasks.count
+                     " (#{task_count} tasks)"
+                   else
+                     ""
+                   end
+            q = %({bg}#{task.type.to_s.capitalize} {xw}"{bw}#{task.title}{xw}"#{note}{x}).c
             res = Prompt.yn(q, default: task.default)
             next unless res
 
@@ -81,7 +87,7 @@ module Howzit
 
               $stderr.puts "{by}Running tasks from {bw}#{matches[0].title}{x}".c if Howzit.options[:log_level] < 2
               output.push(matches[0].run(nested: true))
-              $stderr.puts "{by}End include: #{matches[0].tasks.count} tasks".c if Howzit.options[:log_level] < 2
+              $stderr.puts "{by}End include: #{matches[0].tasks.count} tasks{x}".c if Howzit.options[:log_level] < 2
               tasks += matches[0].tasks.count
             when :run
               $stderr.puts "{bg}Running {bw}#{title}{x}".c if Howzit.options[:log_level] < 2
@@ -107,6 +113,11 @@ module Howzit
       output
     end
 
+    ##
+    ## Platform-agnostic copy-to-clipboard
+    ##
+    ## @param      string  [String] The string to copy
+    ##
     def os_copy(string)
       os = RbConfig::CONFIG['target_os']
       out = "{bg}Copying {bw}#{string}".c
@@ -131,6 +142,11 @@ module Howzit
       end
     end
 
+    ##
+    ## Platform-agnostic open command
+    ##
+    ## @param      command  [String] The command
+    ##
     def os_open(command)
       os = RbConfig::CONFIG['target_os']
       out = "{bg}Opening {bw}#{command}".c
@@ -153,6 +169,11 @@ module Howzit
     end
 
     # Output a topic with fancy title and bright white text.
+    #
+    # @param      options  [Hash] The options
+    #
+    # @return     [Array] array of formatted lines
+    #
     def print_out(options = {})
       defaults = { single: false, header: true }
       opt = defaults.merge(options)
@@ -223,7 +244,7 @@ module Howzit
                    "\u{279A}"
                  end
 
-          output.push("{bmK}#{icon} {bwK}#{title.gsub(/\\n/, '\​n')}{x}#{option}".c)
+          output.push("{bmK}#{icon} {bwK}#{title.preserve_escapes}{x}#{option}".c)
         when /(?<fence>`{3,})run(?<optional>[!?]{1,2})? *(?<title>.*?)$/i
           m = Regexp.last_match.named_captures.symbolize_keys
           optional = m[:optional] =~ /[?!]+/ ? true : false
@@ -256,6 +277,11 @@ module Howzit
 
     private
 
+    ##
+    ## Collect all directives in the topic content
+    ##
+    ## @return     [Array] array of Task objects
+    ##
     def gather_tasks
       runnable = []
       @prereqs = @content.scan(/(?<=@before\n).*?(?=\n@end)/im).map(&:strip)
@@ -275,7 +301,12 @@ module Howzit
           default = c[:optional2] =~ /!/ ? false : true
           title = c[:title2].nil? ? '' : c[:title2].strip
           block = c[:block]&.strip
-          runnable << Howzit::Task.new(:block, title, block, optional: optional, default: default)
+          runnable << Howzit::Task.new({ type: :block,
+                                         title: title,
+                                         action: block,
+                                         parent: nil },
+                                       optional: optional,
+                                       default: default)
         else
           cmd = c[:cmd]
           optional = c[:optional] =~ /[?!]{1,2}/ ? true : false
@@ -294,15 +325,35 @@ module Howzit
             #   end
             #   runnable.concat(tasks)
             # end
-            runnable << Howzit::Task.new(:include, title, obj, optional: optional, default: default)
+            runnable << Howzit::Task.new({ type: :include,
+                                           title: title,
+                                           action: obj,
+                                           parent: nil },
+                                         optional: optional,
+                                         default: default)
           when /run/i
             # warn "{bg}Running {bw}#{obj}{x}".c if Howzit.options[:log_level] < 2
-            runnable << Howzit::Task.new(:run, title, obj, optional: optional, default: default)
+            runnable << Howzit::Task.new({ type: :run,
+                                           title: title,
+                                           action: obj,
+                                           parent: nil },
+                                         optional: optional,
+                                         default: default)
           when /copy/i
             # warn "{bg}Copied {bw}#{obj}{bg} to clipboard{x}".c if Howzit.options[:log_level] < 2
-            runnable << Howzit::Task.new(:copy, title, Shellwords.escape(obj), optional: optional, default: default)
+            runnable << Howzit::Task.new({ type: :copy,
+                                           title: title,
+                                           action: Shellwords.escape(obj),
+                                           parent: nil },
+                                         optional: optional,
+                                         default: default)
           when /open|url/i
-            runnable << Howzit::Task.new(:open, title, obj, optional: optional, default: default)
+            runnable << Howzit::Task.new({ type: :open,
+                                           title: title,
+                                           action: obj,
+                                           parent: nil },
+                                         optional: optional,
+                                         default: default)
           end
         end
       end

data/lib/howzit/util.rb

@@ -4,15 +4,40 @@ module Howzit
   # Util class
   module Util
     class << self
+
+      ##
+      ## Read a file with UTF-8 encoding and
+      ## leading/trailing whitespace removed
+      ##
+      ## @param      path  [String] The path to read
+      ##
+      ## @return     [String] UTF-8 encoded string
+      ##
       def read_file(path)
         IO.read(path).force_encoding('utf-8').strip
       end
 
+      ##
+      ## Test if an external command exists and is
+      ## executable. Removes additional arguments and passes
+      ## just the executable to #command_exist?
+      ##
+      ## @param      command  [String] The command
+      ##
+      ## @return     [Boolean] command is valid
+      ##
       def valid_command?(command)
         cmd = command.split(' ')[0]
         command_exist?(cmd)
       end
 
+      ##
+      ## Test if external command exists
+      ##
+      ## @param      command  [String] The command
+      ##
+      ## @return     [Boolean] command exists
+      ##
       def command_exist?(command)
         exts = ENV.fetch('PATHEXT', '').split(::File::PATH_SEPARATOR)
         if Pathname.new(command).absolute?

data/lib/howzit/version.rb

@@ -3,5 +3,5 @@
 # Primary module for this gem.
 module Howzit
   # Current Howzit version.
-  VERSION = '2.0.9'
+  VERSION = '2.0.12'
 end

data/lib/howzit.rb

@@ -24,11 +24,22 @@ require 'tty/screen'
 require 'tty/box'
 # require 'tty/prompt'
 
+# Main config dir
 CONFIG_DIR = '~/.config/howzit'
+
+# Config file name
 CONFIG_FILE = 'howzit.yaml'
+
+# Ignore file name
 IGNORE_FILE = 'ignore.yaml'
+
+# Available options for matching method
 MATCHING_OPTIONS = %w[partial exact fuzzy beginswith].freeze
+
+# Available options for multiple_matches method
 MULTIPLE_OPTIONS = %w[first best all choose].freeze
+
+# Available options for header formatting
 HEADER_FORMAT_OPTIONS = %w[border block].freeze
 
 # Main module for howzit

data/spec/task_spec.rb

@@ -3,7 +3,12 @@
 require 'spec_helper'
 
 describe Howzit::Task do
-  subject(:task) { Howzit::Task.new(:run, 'List Directory', 'ls') }
+  subject(:task) do
+    Howzit::Task.new({ type: :run,
+                       title: 'List Directory',
+                       action: 'ls',
+                       parent: nil })
+  end
 
   describe ".new" do
     it "makes a new task instance" do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: howzit
 version: !ruby/object:Gem::Version
-  version: 2.0.9
+  version: 2.0.12
 platform: ruby
 authors:
 - Brett Terpstra
@@ -297,7 +297,6 @@ files:
 - lib/.rubocop.yml
 - lib/howzit.rb
 - lib/howzit/buildnote.rb
-- lib/howzit/buildnotes.rb
 - lib/howzit/colors.rb
 - lib/howzit/config.rb
 - lib/howzit/console_logger.rb
@@ -310,7 +309,6 @@ files:
 - lib/howzit/version.rb
 - spec/.rubocop.yml
 - spec/buildnote_spec.rb
-- spec/buildnotes.md.bak
 - spec/cli_spec.rb
 - spec/ruby_gem_spec.rb
 - spec/spec_helper.rb
@@ -344,7 +342,6 @@ summary: Provides a way to access Markdown project notes by topic with query cap
 test_files:
 - spec/.rubocop.yml
 - spec/buildnote_spec.rb
-- spec/buildnotes.md.bak
 - spec/cli_spec.rb
 - spec/ruby_gem_spec.rb
 - spec/spec_helper.rb