howzit 2.0.8 → 2.0.11

data/lib/howzit/prompt.rb

@@ -4,34 +4,61 @@ module Howzit
   # Command line prompt utils
   module Prompt
     class << self
-    	def yn(prompt, default: true)
+
+      ##
+      ## Display and read a Yes/No prompt
+      ##
+      ## @param      prompt   [String] The prompt string
+      ## @param      default  [Boolean] default value if
+      ##                      return is pressed or prompt is
+      ##                      skipped
+      ##
+      ## @return     [Boolean] result
+      ##
+      def yn(prompt, default: true)
         return default unless $stdout.isatty
 
         return default if Howzit.options[:default]
 
-        system 'stty cbreak'
+        tty_state = `stty -g`
+        system 'stty raw -echo cbreak isig'
         yn = color_single_options(default ? %w[Y n] : %w[y N])
         $stdout.syswrite "\e[1;37m#{prompt} #{yn}\e[1;37m? \e[0m"
         res = $stdin.sysread 1
         res.chomp!
         puts
         system 'stty cooked'
+        system "stty #{tty_state}"
         res.empty? ? default : res =~ /y/i
       end
 
+      ##
+      ## Helper function to colorize the Y/N prompt
+      ##
+      ## @param      choices  [Array] The choices with
+      ##                      default capitalized
+      ##
+      ## @return     [String] colorized string
+      ##
       def color_single_options(choices = %w[y n])
         out = []
         choices.each do |choice|
           case choice
           when /[A-Z]/
-            out.push(Color.template("{bg}#{choice}{xg}"))
+            out.push(Color.template("{bw}#{choice}{x}"))
           else
-            out.push(Color.template("{w}#{choice}"))
+            out.push(Color.template("{dw}#{choice}{xg}"))
           end
         end
-        Color.template("{g}[#{out.join('/')}{g}]{x}")
+        Color.template("{xg}[#{out.join('/')}{xg}]{x}")
       end
 
+      ##
+      ## Create a numbered list of options. Outputs directly
+      ## to console, returns nothing
+      ##
+      ## @param      matches  [Array] The list items
+      ##
       def options_list(matches)
         counter = 1
         puts
@@ -42,6 +69,15 @@ module Howzit
         puts
       end
 
+      ##
+      ## Choose from a list of items. If fzf is available,
+      ## uses that, otherwise generates its own list of
+      ## options and accepts a numeric response
+      ##
+      ## @param      matches  [Array] The options list
+      ##
+      ## @return     [Array] the selected results
+      ##
       def choose(matches)
         if Util.command_exist?('fzf')
           settings = [
@@ -79,7 +115,7 @@ module Howzit
             end
             line = line == '' ? 1 : line.to_i
 
-            return matches[line - 1] if line.positive? && line <= matches.length
+            return [matches[line - 1]] if line.positive? && line <= matches.length
 
             puts 'Out of range'
             options_list(matches)

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,15 +235,27 @@ 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 = IO.read(self).split(/^#/)[0].strip
+        leader = Util.read_file(self).split(/^#/)[0].strip
         leader.length > 0 ? leader.get_metadata : {}
       else
         {}
       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

@@ -9,6 +9,12 @@ module Howzit
 
     attr_reader :title, :tasks, :prereqs, :postreqs
 
+    ##
+    ## Initialize a topic object
+    ##
+    ## @param      title    [String] The topic title
+    ## @param      content  [String] The raw topic content
+    ##
     def initialize(title, content)
       @title = title
       @content = content
@@ -17,18 +23,29 @@ module Howzit
       @tasks = gather_tasks
     end
 
+    ##
+    ## Search title and contents for a pattern
+    ##
+    ## @param      term  [String] the search pattern
+    ##
     def grep(term)
       @title =~ /#{term}/i || @content =~ /#{term}/i
     end
 
-    # Handle run command, execute directives
+    # Handle run command, execute directives in topic
     def run(nested: false)
       output = []
       tasks = 0
+      cols = begin
+        TTY::Screen.columns > 60 ? 60 : TTY::Screen.columns
+      rescue StandardError
+        60
+      end
+
       if @tasks.count.positive?
         unless @prereqs.empty?
-          puts @prereqs.join("\n\n")
-          res = Prompt.yn('This topic has prerequisites, have they been met?', default: true)
+          puts TTY::Box.frame("{by}#{@prereqs.join("\n\n").wrap(cols - 4)}{x}".c, width: cols)
+          res = Prompt.yn('Have the above prerequisites been met?', default: true)
           Process.exit 1 unless res
 
         end
@@ -85,11 +102,16 @@ module Howzit
       end
       output.push("{bm}Ran #{tasks} #{tasks == 1 ? 'task' : 'tasks'}{x}".c) if Howzit.options[:log_level] < 2 && !nested
 
-      puts postreqs.join("\n\n") unless postreqs.empty?
+      puts TTY::Box.frame("{bw}#{@postreqs.join("\n\n").wrap(cols - 4)}{x}".c, width: cols) unless @postreqs.empty?
 
       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
@@ -114,6 +136,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
@@ -136,6 +163,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)
@@ -206,7 +238,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
@@ -239,6 +271,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)
@@ -258,7 +295,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
@@ -277,15 +319,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

@@ -1,21 +1,51 @@
+# frozen_string_literal: true
+
 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?
-          ::File.exist?(command) ||
-            exts.any? { |ext| ::File.exist?("#{command}#{ext}") }
+          ::File.exist?(command) || exts.any? { |ext| ::File.exist?("#{command}#{ext}") }
         else
           ENV.fetch('PATH', '').split(::File::PATH_SEPARATOR).any? do |dir|
             file = ::File.join(dir, command)
-            ::File.exist?(file) ||
-              exts.any? { |ext| ::File.exist?("#{file}#{ext}") }
+            ::File.exist?(file) || exts.any? { |ext| ::File.exist?("#{file}#{ext}") }
           end
         end
       end

data/lib/howzit/version.rb

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

data/lib/howzit.rb

@@ -21,15 +21,28 @@ require 'tempfile'
 require 'yaml'
 
 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
 module Howzit
   class << self
     attr_accessor :arguments, :cli_args

data/spec/cli_spec.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+# https://github.com/thoiberg/cli-test
+describe 'CLI' do
+  include CliTest
+
+  it 'executes successfully' do
+    execute_script('bin/howzit', use_bundler: true)
+    expect(last_execution).to be_successful
+  end
+
+  it 'lists available topics' do
+    execute_script('bin/howzit', use_bundler: true, args: %w[-L])
+    expect(last_execution).to be_successful
+    expect(last_execution.stdout).to match(/Topic Balogna/)
+    expect(last_execution.stdout.split(/\n/).count).to eq 3
+  end
+
+  it 'lists available tasks' do
+    execute_script('bin/howzit', use_bundler: true, args: %w[-T])
+    expect(last_execution).to be_successful
+    expect(last_execution.stdout).to match(/Topic Balogna/)
+    expect(last_execution.stdout.split(/\n/).count).to eq 2
+  end
+end

data/spec/spec_helper.rb

@@ -10,6 +10,7 @@
 # end
 
 require 'howzit'
+require 'cli-test'
 
 RSpec.configure do |c|
   c.expect_with(:rspec) { |e| e.syntax = :expect }

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