howzit 2.0.14 → 2.0.17

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a4ce43666235573b6b74c77d0dcb6e1f4c1a45fb8b9cd516747698f56cc3723d
-  data.tar.gz: c13702a3d4b7b2ad707890d3f9d8c2a75e92fba1c732689f1930b511254db742
+  metadata.gz: fa788ff480288582a4473e2bb2fa9388afc98165c9c78b2c90a1bb9b964d7919
+  data.tar.gz: e3012f8ed229832f7cefa29b1ff9a4d971858886c8c9778ec7fe6a3b74faa181
 SHA512:
-  metadata.gz: 586fcb6d9e5bfd901a3e4d33ff9044c57ae50a97cb0a19e8c2d9e5b57dec6771b432e0dc83e28a924824cc04a758ce4397d0f74b7efb2d343181c262f92c636b
-  data.tar.gz: 5f0eac9f6e53ed64ea159630e0f979f9cc8d8734b95186316b924e1e75e752b7a189d02eb1c178c15050676988356b391cfbc19f3da9eacb61d21051b474188e
+  metadata.gz: 893cc81a4db7d7297f8a3d195f6a02bec4a0e419c56ca6a76e97bfbbe49636ef6e6162457f83f914422bb42d5906df8f38a375309d9d5a1b6844d57d488c2e55
+  data.tar.gz: e286bd61f5d4d4dd9632691c3486a9daa51701aac8c4facd3f5a62d01e871ec0cd06d7ff4ac1f19c0f9ff7d24d6ef1d3b9f812d68aa6d62877c99b5bfed7b261

data/.travis.yml

@@ -13,4 +13,4 @@ install:
 script: "bundle exec rspec spec --exclude-pattern 'cli*'"
 branches:
   only:
-  - master
+  - main

data/CHANGELOG.md

@@ -1,3 +1,36 @@
+### 2.0.17
+
+2022-08-07 06:09
+
+### 2.0.16
+
+2022-08-07 06:05
+
+#### NEW
+
+- --edit-template NAME will open a template in your editor, offering to create it if missing
+
+#### FIXED
+
+- If --show-code is given (or :show_all_code: is set to true), show content of @directives instead of title
+
+### 2.0.15
+
+2022-08-05 17:16
+
+#### IMPROVED
+
+- -R can take an argument to filter results
+- Show a topic preview when using fzf to select from available topics
+- Paginate help output
+- Refactor Topic.run
+
+#### FIXED
+
+- Invalid options for more pager
+- Error running grep command
+- Show method not accepting paginate option
+
 ### 2.0.14
 
 2022-08-05 13:24

data/bin/howzit

@@ -49,7 +49,8 @@ OptionParser.new do |opts|
     Howzit.options[:list_topics] = true
   end
 
-  opts.on('-R', '--list-runnable', 'List topics containing @ directives (verbose)') do
+  opts.on('-R', '--list-runnable [PATTERN]', 'List topics containing @ directives (verbose)') do |pat|
+    Howzit.options[:for_topic] = pat
     Howzit.options[:list_runnable] = true
   end
 
@@ -93,6 +94,11 @@ OptionParser.new do |opts|
     Process.exit 0
   end
 
+  opts.on('--edit-template NAME', 'Create or edit a template') do |template|
+    Howzit.buildnote.edit_template(template)
+    Process.exit 0
+  end
+
   opts.on('--config-get [KEY]', 'Display the configuration settings or setting for a specific key') do |k|
     if k.nil?
       Howzit::Config::DEFAULTS.sort_by { |key, _| key }.each do |key, _|
@@ -201,7 +207,7 @@ OptionParser.new do |opts|
   opts.separator("\n  Misc:\n\n") #=================================================================== MISC
 
   opts.on('-h', '--help', 'Display this screen') do
-    puts opts
+    Howzit::Util.page opts.to_s
     Process.exit 0
   end
 

data/lib/howzit/buildnote.rb

@@ -11,27 +11,24 @@ module Howzit
     ## Initialize a build note
     ##
     ## @param      file  [String] The path to the build note file
-    ## @param      args  [Array] additional args
     ##
-    def initialize(file: nil, args: [])
+    def initialize(file: nil)
       @topics = []
-      if note_file.nil?
-        res = Prompt.yn('No build notes file found, create one?', default: true)
+      create_note(prompt: true) if note_file.nil?
 
-        create_note if res
-        Process.exit 0
-      end
       content = Util.read_file(note_file)
-      if content.nil? || content.empty?
-        Howzit.console.error("{br}No content found in build note (#{note_file}){x}".c)
-        Process.exit 1
-      else
-        @metadata = content.split(/^#/)[0].strip.get_metadata
-      end
+      raise "{br}No content found in build note (#{note_file}){x}".c if content.nil? || content.empty?
+
+      @metadata = content.split(/^#/)[0].strip.get_metadata
 
       read_help(file)
     end
 
+    ##
+    ## Inspect
+    ##
+    ## @return     description
+    ##
     def inspect
       puts "#<Howzit::BuildNote @topics=[#{@topics.count}]>"
     end
@@ -50,12 +47,25 @@ module Howzit
       edit_note
     end
 
+    ##
+    ## Public method to open a template in the editor
+    ##
+    ## @param      template  [String] The template title
+    ##
+    def edit_template(template)
+      file = template.sub(/(\.md)?$/i, '.md')
+      file = File.join(Howzit.config.template_folder, file)
+      edit_template_file(file)
+    end
+
     ##
     ## Find a topic based on a fuzzy match
     ##
     ## @param      term  [String] The search term
     ##
-    def find_topic(term)
+    def find_topic(term = nil)
+      return @topics if term.nil?
+
       @topics.filter do |topic|
         rx = term.to_rx
         topic.title.downcase =~ rx
@@ -127,18 +137,18 @@ module Howzit
     def list_runnable
       output = []
       output.push(%({bg}"Runnable" Topics:{x}\n).c)
-      @topics.each do |topic|
+
+      find_topic(Howzit.options[:for_topic]).each do |topic|
         s_out = []
 
-        topic.tasks.each do |task|
-          s_out.push(task.to_list)
-        end
+        topic.tasks.each { |task| s_out.push(task.to_list) }
 
-        unless s_out.empty?
-          output.push("- {bw}#{topic.title}{x}".c)
-          output.push(s_out.join("\n"))
-        end
+        next if s_out.empty?
+
+        output.push("- {bw}#{topic.title}{x}".c)
+        output.push(s_out.join("\n"))
       end
+
       output.join("\n")
     end
 
@@ -151,22 +161,75 @@ module Howzit
       read_help_file(file)
     end
 
+    ##
+    ## Create a template file
+    ##
+    ## @param      file    [String] file path
+    ## @param      prompt  [Boolean] confirm file creation?
+    ##
+    def create_template_file(file, prompt: false)
+      trap('SIGINT') do
+        Howzit.console.info "\nCancelled"
+        exit!
+      end
+
+      default = !$stdout.isatty || Howzit.options[:default]
+
+      if prompt && !default && !File.exist?(file)
+        res = Prompt.yn("{bg}Template {bw}#{File.basename(file)}{bg} not found, create it?{x}".c, default: true)
+        Process.exit 0 unless res
+      end
+
+      title = File.basename(file, '.md')
+
+      note = <<~EOBUILDNOTES
+        # #{title}
+
+        ## Template Topic
+
+      EOBUILDNOTES
+
+      if File.exist?(file) && !default
+        file = "{by}#{file}".c
+        unless Prompt.yn("Are you sure you want to overwrite #{file}", default: false)
+          puts 'Cancelled'
+          Process.exit 0
+        end
+      end
+
+      File.open(file, 'w') do |f|
+        f.puts note
+        puts "{by}Template {bw}#{title}{by} written to {bw}#{file}{x}".c
+      end
+
+      if File.exist?(file) && !default && Prompt.yn("{bg}Do you want to open {bw}#{file} {bg}for editing?{x}".c,
+                                                     default: false)
+        edit_template_file(file)
+      end
+
+      Process.exit 0
+    end
+
     # Create a buildnotes skeleton
-    def create_note
+    def create_note(prompt: false)
       trap('SIGINT') do
         Howzit.console.info "\nCancelled"
         exit!
       end
+
       default = !$stdout.isatty || Howzit.options[:default]
+
+      if prompt && !default
+        res = Prompt.yn('No build notes file found, create one?', default: true)
+        Process.exit 0 unless res
+      end
+
       # First make sure there isn't already a buildnotes file
       if note_file
         fname = "{by}#{note_file}{bw}".c
         unless default
           res = Prompt.yn("#{fname} exists and appears to be a build note, continue anyway?", default: false)
-          unless res
-            puts 'Canceled'
-            Process.exit 0
-          end
+          Process.exit 0 unless res
         end
       end
 
@@ -221,9 +284,7 @@ module Howzit
 
       if File.exist?(fname) && !default
         file = "{by}#{fname}".c
-        res = Prompt.yn("Are you absolutely sure you want to overwrite #{file}", default: false)
-
-        unless res
+        unless Prompt.yn("Are you absolutely sure you want to overwrite #{file}", default: false)
           puts 'Canceled'
           Process.exit 0
         end
@@ -231,24 +292,161 @@ module Howzit
 
       File.open(fname, 'w') do |f|
         f.puts note
-        puts "{by}Build notes for #{title} written to #{fname}".c
+        puts "{by}Build notes for {bw}#{title}{by} written to {bw}#{fname}{x}".c
       end
 
-      if File.exist?(fname) && !default
-        res = Prompt.yn("{bg}Do you want to open {bw}#{file} {bg}for editing?{x}".c, default: false)
-
-        edit_note if res
+      if File.exist?(fname) && !default && Prompt.yn("{bg}Do you want to open {bw}#{fname} {bg}for editing?{x}".c,
+                                                     default: false)
+        edit_note
       end
 
       Process.exit 0
     end
 
+    ##
+    ## Accessor method for note_file (path to located build note)
+    ##
+    ## @return     [String] path
+    ##
     def note_file
       @note_file ||= find_note_file
     end
 
     private
 
+    ##
+    ## Import the contents of a filename as new topics
+    ##
+    ## @param      mtch  [MatchData] the filename match from
+    ##                   the include directive
+    ##
+    def include_file(mtch)
+      file = File.expand_path(mtch[1])
+
+      return mtch[0] unless File.exist?(file)
+
+      content = Util.read_file(file)
+      home = ENV['HOME']
+      short_path = File.dirname(file.sub(/^#{home}/, '~'))
+      prefix = "#{short_path}/#{File.basename(file)}:"
+      parts = content.split(/^##+/)
+      parts.shift
+      if parts.empty?
+        content
+      else
+        "## #{parts.join('## ')}".gsub(/^(##+ *)(?=\S)/, "\\1#{prefix}")
+      end
+    end
+
+    ##
+    ## Test to ensure that any `required` metadata in a
+    ## template is fulfilled by the build note
+    ##
+    ## @param      template  [String] The template to read
+    ##                       from
+    ##
+    def ensure_requirements(template)
+      t_leader = Util.read_file(template).split(/^#/)[0].strip
+      if t_leader.length > 0
+        t_meta = t_leader.get_metadata
+        if t_meta.key?('required')
+          required = t_meta['required'].strip.split(/\s*,\s*/)
+          required.each do |req|
+            unless @metadata.keys.include?(req.downcase)
+              Howzit.console.error %({bRw}ERROR:{xbr} Missing required metadata key from template '{bw}#{File.basename(template, '.md')}{xr}'{x}).c
+              Howzit.console.error %({br}Please define {by}#{req.downcase}{xr} in build notes{x}).c
+              Process.exit 1
+            end
+          end
+        end
+      end
+    end
+
+    ##
+    ## Test a template string for bracketed subtopics
+    ##
+    ## @param      template  [String] The template name
+    ##
+    ## @return     [Array] [[String] updated template name, [Array]
+    ##             subtopic titles]
+    ##
+    def detect_subtopics(template)
+      subtopics = nil
+
+      if template =~ /\[(.*?)\]$/
+        subtopics = Regexp.last_match[1].split(/\s*\|\s*/).map { |t| t.gsub(/\*/, '.*?')}
+        template.sub!(/\[.*?\]$/, '').strip
+      end
+
+      [template, subtopics]
+    end
+
+    ##
+    ## Enumerate templates and read their associated files
+    ## into topics
+    ##
+    ## @param      templates  [Array] The templates to read
+    ##
+    ## @return     [Array] template topics
+    ##
+    def gather_templates(templates)
+      template_topics = []
+
+      templates.each do |template|
+        template, subtopics = detect_subtopics(template)
+
+        file = template.sub(/(\.md)?$/i, '.md')
+        file = File.join(Howzit.config.template_folder, file)
+
+        next unless File.exist?(file)
+
+        ensure_requirements(file)
+
+        template_topics.concat(read_template(template, file, subtopics))
+      end
+
+      template_topics
+    end
+
+    ##
+    ## Filter topics based on subtopic titles
+    ##
+    ## @param      note       [BuildNote] The note
+    ## @param      subtopics  [Array] The subtopics to
+    ##                        extract
+    ##
+    ## @return     [Array] extracted subtopics
+    ##
+    def extract_subtopics(note, subtopics)
+      template_topics = []
+
+      subtopics.each do |subtopic|
+        note.topics.each { |topic| template_topics.push(topic) if topic.title =~ /^(.*?:)?#{subtopic}$/i }
+      end
+
+      template_topics
+    end
+
+    ##
+    ## Read a template file
+    ##
+    ## @param      template   [String] The template title
+    ## @param      file       [String] The file path
+    ## @param      subtopics  [Array] The subtopics to
+    ##                        extract, nil to return all
+    ##
+    ## @return     [Array] extracted topics
+    ##
+    def read_template(template, file, subtopics = nil)
+      note = BuildNote.new(file: file)
+
+      template_topics = subtopics.nil? ? note.topics : extract_subtopics(note, subtopics)
+      template_topics.map do |topic|
+        topic.parent = template
+        topic
+      end
+    end
+
     ##
     ## Traverse up directory tree looking for build notes
     ##
@@ -329,30 +527,6 @@ module Howzit
       topics_dict
     end
 
-    ##
-    ## Test to ensure that any `required` metadata in a
-    ## template is fulfilled by the build note
-    ##
-    ## @param      template  [String] The template to read
-    ##                       from
-    ##
-    def ensure_requirements(template)
-      t_leader = Util.read_file(template).split(/^#/)[0].strip
-      if t_leader.length > 0
-        t_meta = t_leader.get_metadata
-        if t_meta.key?('required')
-          required = t_meta['required'].strip.split(/\s*,\s*/)
-          required.each do |req|
-            unless @metadata.keys.include?(req.downcase)
-              Howzit.console.error %({bRw}ERROR:{xbr} Missing required metadata key from template '{bw}#{File.basename(template, '.md')}{xr}'{x}).c
-              Howzit.console.error %({br}Please define {by}#{req.downcase}{xr} in build notes{x}).c
-              Process.exit 1
-            end
-          end
-        end
-      end
-    end
-
     ##
     ## Read a list of topics from an included template
     ##
@@ -363,87 +537,17 @@ module Howzit
 
       template_topics = []
 
-      if leader.length > 0
-        data = leader.get_metadata
+      return template_topics if leader.empty?
 
-        if data.key?('template')
-          templates = data['template'].strip.split(/\s*,\s*/)
-          templates.each do |t|
-            tasks = nil
-            if t =~ /\[(.*?)\]$/
-              tasks = Regexp.last_match[1].split(/\s*,\s*/).map {|t| t.gsub(/\*/, '.*?')}
-              t = t.sub(/\[.*?\]$/, '').strip
-            end
+      data = leader.get_metadata
 
-            t_file = t.sub(/(\.md)?$/, '.md')
-            template = File.join(Howzit.config.template_folder, t_file)
-            if File.exist?(template)
-              ensure_requirements(template)
-
-              t_topics = BuildNote.new(file: template)
-              if tasks
-                tasks.each do |task|
-                  t_topics.topics.each do |topic|
-                    if topic.title =~ /^(.*?:)?#{task}$/i
-                      topic.parent = t
-                      template_topics.push(topic)
-                    end
-                  end
-                end
-              else
-                t_topics.topics.map! do |topic|
-                  topic.parent = t
-                  topic
-                end
-
-                template_topics.concat(t_topics.topics)
-              end
-            end
-          end
-        end
-      end
-      template_topics
-    end
+      if data.key?('template')
+        templates = data['template'].strip.split(/\s*,\s*/)
 
-    ##
-    ## Import the contents of a filename as new topics
-    ##
-    ## @param      mtch  [MatchData] the filename match from
-    ##                   the include directive
-    ##
-    def include_file(mtch)
-      file = File.expand_path(mtch[1])
-
-      return mtch[0] unless File.exist?(file)
-
-      content = Util.read_file(file)
-      home = ENV['HOME']
-      short_path = File.dirname(file.sub(/^#{home}/, '~'))
-      prefix = "#{short_path}/#{File.basename(file)}:"
-      parts = content.split(/^##+/)
-      parts.shift
-      if parts.empty?
-        content
-      else
-        "## #{parts.join('## ')}".gsub(/^(##+ *)(?=\S)/, "\\1#{prefix}")
+        template_topics.concat(gather_templates(templates))
       end
-    end
-
-    ##
-    ## Get the title of the build note (top level header)
-    ##
-    ## @param      truncate  [Integer] Truncate to width
-    ##
-    def note_title(truncate = 0)
-      help = Util.read_file(note_file)
-      title = help.match(/(?:^(\S.*?)(?=\n==)|^# ?(.*?)$)/)
-      title = if title
-                title[1].nil? ? title[2] : title[1]
-              else
-                note_file.sub(/(\.\w+)?$/, '')
-              end
 
-      title && truncate.positive? ? title.trunc(truncate) : title
+      template_topics
     end
 
     # Read in the build notes file and output a hash of
@@ -465,7 +569,7 @@ module Howzit
         Process.exit 1
       end
 
-      @title = note_title
+      @title = help.note_title(filename)
 
       help.gsub!(/@include\((.*?)\)/) do
         include_file(Regexp.last_match)
@@ -535,14 +639,33 @@ module Howzit
 
       raise "Invalid editor (#{editor})" unless Util.valid_command?(editor)
 
-      if note_file.nil?
-        res = Prompt.yn('No build notes file found, create one?', default: true)
+      create_note(prompt: true) if note_file.nil?
+      `#{editor} "#{note_file}"`
+    end
 
-        create_note if res
-        edit_note
-      else
-        `#{editor} "#{note_file}"`
-      end
+    ##
+    ## Public method to create a new template
+    ##
+    ## @param      template  [String] The template name
+    ##
+    def create_template(template)
+      file = template.sub(/(\.md)?$/i, '.md')
+      file = File.join(Howzit.config.template_folder, file)
+      create_template_file(file, prompt: false)
+    end
+
+    ##
+    ## Open template in editor
+    ##
+    def edit_template_file(file)
+      editor = Howzit.options.fetch(:editor, ENV['EDITOR'])
+
+      raise 'No editor defined' if editor.nil?
+
+      raise "Invalid editor (#{editor})" unless Util.valid_command?(editor)
+
+      create_template_file(file, prompt: true) unless File.exist?(file)
+      `#{editor} "#{file}"`
     end
 
     ##
@@ -577,17 +700,11 @@ module Howzit
       unless note_file
         Process.exit 0 if Howzit.options[:list_runnable_titles] || Howzit.options[:list_topic_titles]
 
-        # clear the buffer
-        ARGV.length.times do
-          ARGV.shift
-        end
-        res = yn("No build notes file found, create one?", true)
-        create_note if res
-        Process.exit 1
+        create_note(prompt: true)
       end
 
       if Howzit.options[:title_only]
-        out = note_title(20)
+        out = Util.read_file(note_file).note_title(note_file, 20)
         $stdout.print(out.strip)
         Process.exit(0)
       elsif Howzit.options[:output_title] && !Howzit.options[:run]
@@ -620,15 +737,15 @@ module Howzit
 
       topic_matches = []
       if Howzit.options[:grep]
-        matches = grep_topics(Howzit.options[:grep])
+        matches = grep(Howzit.options[:grep])
         case Howzit.options[:multiple_matches]
         when :all
-          topic_matches.concat(matches.sort)
+          topic_matches.concat(matches.sort_by(&:title))
         else
-          topic_matches.concat(Prompt.choose(matches))
+          topic_matches.concat(Prompt.choose(matches.map(&:title), height: :max))
         end
       elsif Howzit.options[:choose]
-        titles = Prompt.choose(list_topics)
+        titles = Prompt.choose(list_topics, height: :max)
         titles.each { |title| topic_matches.push(find_topic(title)[0]) }
       # If there are arguments use those to search for a matching topic
       elsif !Howzit.cli_args.empty?

data/lib/howzit/colors.rb

@@ -243,6 +243,7 @@ module Howzit
 
     ATTRIBUTES.each do |c, v|
       new_method = <<-EOSCRIPT
+        # Color string as #{c}
         def #{c}(string = nil)
           result = ''
           result << "\e[#{v}m" if Howzit::Color.coloring?
@@ -266,6 +267,7 @@ module Howzit
 
       # Accept brightwhite in addition to boldwhite
       new_method = <<-EOSCRIPT
+        # color string as #{c}
         def #{c.to_s.sub(/bold/, 'bright')}(string = nil)
           result = ''
           result << "\e[#{v}m" if Howzit::Color.coloring?
@@ -286,6 +288,13 @@ module Howzit
       module_eval(new_method)
     end
 
+    ##
+    ## Generate escape codes for hex colors
+    ##
+    ## @param      hex   [String] The hexadecimal color code
+    ##
+    ## @return     [String] ANSI escape string
+    ##
     def rgb(hex)
       is_bg = hex.match(/^bg?#/) ? true : false
       hex_string = hex.sub(/^([fb]g?)?#/, '')

data/lib/howzit/config.rb

@@ -89,6 +89,7 @@ module Howzit
       flags = {
         choose: false,
         default: false,
+        for_topic: nil,
         grep: nil,
         list_runnable: false,
         list_runnable_titles: false,