na 1.1.20 → 1.1.22

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cca7f5724f71b44df5ad9ac04646a26b9258cb2fb491b0e93b15b6c1f29c68d2
-  data.tar.gz: 249da515ff5d4b44928b8401f691e337440f0abd60d78b7155a1e5490b981519
+  metadata.gz: 584d55c84c26fddeb65bf537b4743b5cac4308f39d796d336d95c900fc966deb
+  data.tar.gz: 73ea4289a1e43ce0b67f66f803a0db07359fe3f077358328a58c172c06daa107
 SHA512:
-  metadata.gz: eb3e8285512ba4091326d3c20c5d69e671d7a2f310b6d11f3f7b36ba6b3b19ab237059b12aa091158515eff675d8f6df0e10436119714a5de718e1f8f45a84bb
-  data.tar.gz: 1244b815b5666fb758c0b6359a584a5a11e493ce4f30a8c7e325cd9438b1d8ebaee638115d3765954cf9335947648105447941603a168c53aeaeb1ed5a7e5031
+  metadata.gz: 89945d2a8df1c1ea11360da4258c09f9b5c8ad38f41ca5ef98a68b99c33b41fb0b718919cc680eb356903f284cef8dd4271acea94af7f8c4adca031d445a6a26
+  data.tar.gz: 7c3f8c30bf5a4c69270641aadfb036303c42ee8678a09c2e8b5faad7883aff0ac0139caf465f9d37b84cf170ed4ee072ad20d4872b8c760b97d0e2ca1f3b6e2e

data/.travis.yml

@@ -0,0 +1,11 @@
+---
+language: ruby
+sudo: required
+dist: trusty
+cache: bundler
+rvm:
+  - ruby-3.0.1
+install:
+  - gem install bundler --version '2.2.29'
+  - bundle install
+script: "bundle exec rake test"

data/CHANGELOG.md

@@ -1,3 +1,32 @@
+### 1.1.22
+
+2022-10-07 05:58
+
+#### IMPROVED
+
+- Help output and code documentation
+- Allow wildcards (* and ?) when matching todo history
+- Allow multiple todo queries separated by comma
+
+#### FIXED
+
+- Remove file extension when matching todo history
+- Todo history query failed on exact match
+
+### 1.1.21
+
+2022-10-07 04:26
+
+#### NEW
+
+- `na todos` will list (and optionally search) known todo files from history
+
+#### IMPROVED
+
+- Fuzzier matching of todo file history
+- Help output fixes
+- Code documentation
+
 ### 1.1.20
 
 2022-10-07 03:16

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    na (1.1.20)
+    na (1.1.22)
       chronic (~> 0.10, >= 0.10.2)
       gli (~> 2.21.0)
       tty-reader (~> 0.9, >= 0.9.0)

data/README.md

@@ -9,7 +9,7 @@
 _If you're one of the rare people like me who find this useful, feel free to
 [buy me some coffee][donate]._
 
-The current version of `na` is 1.1.20
+The current version of `na` is 1.1.22
 .
 
 `na` ("next action") is a command line tool designed to make it easy to see what your next actions are for any project, right from the command line. It works with TaskPaper-formatted files (but any plain text format will do), looking for `@na` tags (or whatever you specify) in todo files in your current folder. 
@@ -59,7 +59,7 @@ SYNOPSIS
     na [global options] command [command options] [arguments...]
 
 VERSION
-    1.1.19
+    1.1.22
 
 GLOBAL OPTIONS
     -a, --[no-]add          - Add a next action (deprecated, for backwards compatibility)
@@ -83,6 +83,7 @@ COMMANDS
     next, show   - Show next actions
     prompt       - Show or install prompt hooks for the current shell
     tagged       - Find actions matching a tag
+    todos        - Show list of known todo files
 ```
 
 #### Commands
@@ -102,7 +103,7 @@ SYNOPSIS
     na [global options] add [command options] ACTION
 
 DESCRIPTION
-    Provides an easy way to store todos while you work. Add quick reminders and (if you set up Prompt Hooks)   they'll automatically display next time you enter the directory.   If multiple todo files are found in the current directory, a menu will allow you to pick to which   file the action gets added. 
+    Provides an easy way to store todos while you work. Add quick   reminders and (if you set up Prompt Hooks) they'll automatically display   next time you enter the directory.   If multiple todo files are found in the current directory, a menu will   allow you to pick to which file the action gets added. 
 
 COMMAND OPTIONS
     -d, --depth=DEPTH   - Search for files X directories deep (default: 1)
@@ -170,7 +171,7 @@ DESCRIPTION
 COMMAND OPTIONS
     -d, --depth=DEPTH                      - Recurse to depth (default: none)
     -e, --regex                            - Interpret search pattern as regular expression
-    --in=TODO_PATH                         - Show actions from a specific todo file in history (default: none)
+    --in=TODO_PATH                         - Show actions from a specific todo file in history. May use wildcards (* and ?) (default: none)
     -o, --or                               - Combine search tokens with OR, displaying actions matching ANY of the terms
     --proj, --project=PROJECT[/SUBPROJECT] - Show actions from a specific project (default: none)
     -v, --invert                           - Show actions not matching search pattern
@@ -206,11 +207,11 @@ EXAMPLES
 
 ##### next, show
 
-Examples: 
+Examples:
 
-- `na show` (list all next actions in the current directory)
-- `na show -d 3` (list all next actions in the current directory and look for additional files 3 levels deep from there)
-- `na show marked2` (show next actions from another directory you've previously used na on)
+- `na next` (list all next actions in the current directory)
+- `na next -d 3` (list all next actions in the current directory and look for additional files 3 levels deep from there)
+- `na next marked2` (show next actions from another directory you've previously used na on)
 
 ```
 NAME
@@ -218,7 +219,10 @@ NAME
 
 SYNOPSIS
 
-    na [global options] next [command options] OPTIONAL_QUERY
+    na [global options] next [command options] [QUERY]
+
+DESCRIPTION
+    Next actions are actions which contain the next action tag (default @na),   do not contain @done, and are not in the Archive project.   Arguments will target a todo file from history, whether it's in the current   directory or not. Todo file queries can include path components separated by /   or :, and may use wildcards (`*` to match any text, `?` to match a single character). Multiple queries allowed (separate arguments or separated by comma). 
 
 COMMAND OPTIONS
     -d, --depth=DEPTH                      - Recurse to depth (default: 2)
@@ -245,38 +249,30 @@ Separate multiple tags with spaces or commas. By default tags are combined with
 
 ```
 NAME
-    tagged - Find actions matching a tag
+    next - Show next actions
 
 SYNOPSIS
 
-    na [global options] tagged [command options] TAG [VALUE]
+    na [global options] next [command options] [QUERY]
 
 DESCRIPTION
-    Finds actions with tags matching the arguments. An action is shown if it              contains all of the tags listed. Add a + before a tag to make it required              and others optional. You can specify values using TAG=VALUE pairs.              Use <, >, and = for numeric comparisons, and *=, ^=, and $= for text comparisons.              Date comparisons use natural language (`na tagged "due<=today"`) and              are detected automatically. 
+    Next actions are actions which contain the next action tag (default @na),   do not contain @done, and are not in the Archive project.   Arguments will target a todo file from history, whether it's in the current   directory or not. Todo file queries can include path components separated by /   or :, and may use wildcards (`*` to match any text, `?` to match a single character). Multiple queries allowed (separate arguments or separated by comma). 
 
 COMMAND OPTIONS
-    -d, --depth=DEPTH                      - Recurse to depth (default: 1)
-    --in=TODO_PATH                         - Show actions from a specific todo file in history (default: none)
-    -o, --or                               - Combine tags with OR, displaying actions matching ANY of the tags
+    -d, --depth=DEPTH                      - Recurse to depth (default: 2)
     --proj, --project=PROJECT[/SUBPROJECT] - Show actions from a specific project (default: none)
-    -v, --invert                           - Show actions not matching tags
+    -t, --tag=TAG                          - Alternate tag to search for (default: none)
 
 EXAMPLES
 
-    # Show all actions tagged @maybe
-    na tagged maybe
-
-    # Show all actions tagged @feature AND @idea, recurse 3 levels
-    na tagged -d 3 "feature, idea"
-
-    # Show all actions tagged @feature OR @idea
-    na tagged --or "feature, idea"
+    # display the next actions from any todo files in the current directory
+    na next
 
-    # Show actions with @priority(4) or @priority(5)
-    na tagged "priority>=4"
+    # display the next actions from the current directory, traversing 3 levels deep
+    na next -d 3
 
-    # Show actions with a due date coming up in the next 2 days
-    na tagged "due<in 2 days"
+    # display next actions for a project you visited in the past
+    na next marked
 ```
 
 ### Configuration

data/bin/na

@@ -54,7 +54,13 @@ class App
   switch %i[debug]
 
   desc 'Show next actions'
-  arg_name 'OPTIONAL_QUERY'
+  long_desc 'Next actions are actions which contain the next action tag (default @na),
+  do not contain @done, and are not in the Archive project.
+
+  Arguments will target a todo file from history, whether it\'s in the current
+  directory or not. Todo file queries can include path components separated by /
+  or :, and may use wildcards (`*` to match any text, `?` to match a single character). Multiple queries allowed (separate arguments or separated by comma).'
+  arg_name 'QUERY', optional: true
   command %i[next show] do |c|
     c.example 'na next', desc: 'display the next actions from any todo files in the current directory'
     c.example 'na next -d 3', desc: 'display the next actions from the current directory, traversing 3 levels deep'
@@ -91,11 +97,13 @@ class App
       if args.count.positive?
         tokens = []
         args.each do |arg|
-          m = arg.match(/^(?<req>\+)?(?<tok>.*?)$/)
-          tokens.push({
-                        token: m['tok'],
-                        required: !m['req'].nil?
-                      })
+          arg.split(/ *, */).each do |a|
+            m = a.match(/^(?<req>\+)?(?<tok>.*?)$/)
+            tokens.push({
+                          token: m['tok'],
+                          required: !m['req'].nil?
+                        })
+          end
         end
       end
 
@@ -114,11 +122,12 @@ class App
   end
 
   desc 'Add a new next action'
-  long_desc 'Provides an easy way to store todos while you work. Add quick reminders and (if you set up Prompt Hooks)
-  they\'ll automatically display next time you enter the directory.
+  long_desc 'Provides an easy way to store todos while you work. Add quick
+  reminders and (if you set up Prompt Hooks) they\'ll automatically display
+  next time you enter the directory.
 
-  If multiple todo files are found in the current directory, a menu will allow you to pick to which
-  file the action gets added.'
+  If multiple todo files are found in the current directory, a menu will
+  allow you to pick to which file the action gets added.'
   arg_name 'ACTION'
   command :add do |c|
     c.example 'na add "A cool feature I thought of @idea"', desc: 'Add a new action to the Inbox, including a tag'
@@ -248,7 +257,7 @@ class App
     c.arg_name 'DEPTH'
     c.flag %i[d depth], type: :integer, must_match: /^\d+$/
 
-    c.desc 'Show actions from a specific todo file in history'
+    c.desc 'Show actions from a specific todo file in history. May use wildcards (* and ?)'
     c.arg_name 'TODO_PATH'
     c.flag %i[in]
 
@@ -289,10 +298,14 @@ class App
 
       todo = nil
       if options[:in]
-        todo = [{
-          token: options[:in],
-          required: true
-        }]
+        todo = []
+        options[:in].split(/ *, */).each do |a|
+          m = a.match(/^(?<req>\+)?(?<tok>.*?)$/)
+          todo.push({
+                        token: m['tok'],
+                        required: !m['req'].nil?
+                      })
+        end
       end
 
       files, actions = NA.parse_actions(depth: depth,
@@ -314,12 +327,12 @@ class App
 
   desc 'Find actions matching a tag'
   long_desc 'Finds actions with tags matching the arguments. An action is shown if it
-             contains all of the tags listed. Add a + before a tag to make it required
-             and others optional. You can specify values using TAG=VALUE pairs.
-             Use <, >, and = for numeric comparisons, and *=, ^=, and $= for text comparisons.
-             Date comparisons use natural language (`na tagged "due<=today"`) and
-             are detected automatically.'
-  arg_name 'TAG [VALUE]'
+  contains all of the tags listed. Add a + before a tag to make it required
+  and others optional. You can specify values using TAG=VALUE pairs.
+  Use <, >, and = for numeric comparisons, and *=, ^=, and $= for text comparisons.
+  Date comparisons use natural language (`na tagged "due<=today"`) and
+  are detected automatically.'
+  arg_name 'TAG[=VALUE]'
   command %i[tagged] do |c|
     c.example 'na tagged maybe', desc: 'Show all actions tagged @maybe'
     c.example 'na tagged -d 3 "feature, idea"', desc: 'Show all actions tagged @feature AND @idea, recurse 3 levels'
@@ -332,7 +345,7 @@ class App
     c.default_value 1
     c.flag %i[d depth], type: :integer, must_match: /^\d+$/
 
-    c.desc 'Show actions from a specific todo file in history'
+    c.desc 'Show actions from a specific todo file in history. May use wildcards (* and ?)'
     c.arg_name 'TODO_PATH'
     c.flag %i[in]
 
@@ -370,10 +383,14 @@ class App
 
       todo = nil
       if options[:in]
-        todo = [{
-          token: options[:in],
-          required: true
-        }]
+        todo = []
+        options[:in].split(/ *, */).each do |a|
+          m = a.match(/^(?<req>\+)?(?<tok>.*?)$/)
+          todo.push({
+                        token: m['tok'],
+                        required: !m['req'].nil?
+                      })
+        end
       end
 
       files, actions = NA.parse_actions(depth: depth,
@@ -388,7 +405,7 @@ class App
   end
 
   desc 'Create a new todo file in the current directory'
-  arg_name '[PROJECT]'
+  arg_name 'PROJECT', optional: true
   command %i[init create] do |c|
     c.example 'na init', desc: 'Generate a new todo file, prompting for project name'
     c.example 'na init warpspeed', desc: 'Generate a new todo for a project called warpspeed'
@@ -456,13 +473,37 @@ class App
     end
   end
 
+  desc 'Show list of known todo files'
+  long_desc 'Arguments will be interpreted as a query against which the
+  list of todos will be fuzzy matched. Separate directories with
+  /, :, or a space, e.g. `na todos code/marked`'
+  arg_name 'QUERY', optional: true
+  command %i[todos] do |c|
+    c.action do |_global_options, _options, args|
+      if args.count.positive?
+        tokens = []
+        args.each do |arg|
+          arg.split(/ *, */).each do |a|
+            m = a.match(/^(?<req>\+)?(?<tok>.*?)$/)
+            tokens.push({
+                          token: m['tok'],
+                          required: !m['req'].nil?
+                        })
+          end
+        end
+      end
+
+      NA.list_todos(query: tokens)
+    end
+  end
+
   desc 'Show or install prompt hooks for the current shell'
   long_desc 'Installing the prompt hook allows you to automatically
   list next actions when you cd into a directory'
   command %i[prompt] do |c|
     c.desc 'Output the prompt hook for the current shell to STDOUT. Pass an argument to
             specify a shell (zsh, bash, fish)'
-    c.arg_name '[SHELL]'
+    c.arg_name 'SHELL', optional: true
     c.command %i[show] do |s|
       s.action do |_global_options, _options, args|
         shell = if args.count.positive?
@@ -483,7 +524,7 @@ class App
     end
 
     c.desc 'Install the hook for the current shell to the appropriate startup file.'
-    c.arg_name '[SHELL]'
+    c.arg_name 'SHELL', optional: true
     c.command %i[install] do |s|
       s.action do |_global_options, _options, args|
         shell = if args.count.positive?

data/lib/na/next_action.rb

@@ -5,13 +5,27 @@ module NA
   class << self
     attr_accessor :verbose, :extension, :na_tag
 
-    def notify(msg, exit_code: false)
+    ##
+    ## Output to STDERR
+    ##
+    ## @param      msg        [String] The message
+    ## @param      exit_code  [Number] The exit code, no exit if false
+    ##
+    def notify(msg, exit_code: false, debug: false)
+      return if debug && !@verbose
+
       $stderr.puts NA::Color.template("{x}#{msg}{x}")
       if exit_code && exit_code.is_a?(Number)
         Process.exit exit_code
       end
     end
 
+    ##
+    ## Create a new todo file
+    ##
+    ## @param      target    [String] The target path
+    ## @param      basename  [String] The project base name
+    ##
     def create_todo(target, basename)
       File.open(target, 'w') do |f|
         content = <<~ENDCONTENT
@@ -32,12 +46,24 @@ module NA
       notify("{y}Created {bw}#{target}")
     end
 
+    ##
+    ## Use the *nix `find` command to locate files matching NA.extension
+    ##
+    ## @param      depth  [Number] The depth at which to search
+    ##
     def find_files(depth: 1)
       files = `find . -name "*.#{NA.extension}" -maxdepth #{depth}`.strip.split("\n")
       files.each { |f| save_working_dir(File.expand_path(f)) }
       files
     end
 
+    ##
+    ## Select from multiple files
+    ##
+    ## @note If `gum` or `fzf` are available, they'll be used (in that order)
+    ##
+    ## @param      files  [Array] The files
+    ##
     def select_file(files)
       if TTY::Which.exist?('gum')
         args = [
@@ -63,12 +89,22 @@ module NA
       end
     end
 
+    ##
+    ## Add an action to a todo file
+    ##
+    ## @param      file     [String] The target file
+    ## @param      project  [String] The project name
+    ## @param      action   [String] The action
+    ## @param      note     [String] The note
+    ##
     def add_action(file, project, action, note = nil)
       content = IO.read(file)
+      # Insert the target project at the top if it doesn't exist
       unless content =~ /^[ \t]*#{project}:/i
         content = "#{project.cap_first}:\n#{content}"
       end
 
+      # Insert the action at the top of the target project
       content.sub!(/^([ \t]*)#{project}:(.*?)$/i) do
         m = Regexp.last_match
         note = note.nil? ? '' : "\n#{m[1]}\t\t#{note.join('').strip}"
@@ -80,6 +116,14 @@ module NA
       notify("{by}Task added to {bw}#{file}")
     end
 
+    ##
+    ## Pretty print a list of actions
+    ##
+    ## @param      actions  [Array] The actions
+    ## @param      depth    [Number] The depth
+    ## @param      files    [Array] The files actions originally came from
+    ## @param      regexes  [Array] The regexes used to gather actions
+    ##
     def output_actions(actions, depth, files: nil, regexes: [])
       return if files.nil?
 
@@ -99,11 +143,23 @@ module NA
                    '%parent%action'
                  end
 
-      files.map { |f| notify("{dw}#{f}") } if files && @verbose
+      files.map { |f| notify("{dw}#{f}", debug: true) } if files
 
       puts(actions.map { |action| action.pretty(template: { output: template }, regexes: regexes) })
     end
 
+    ##
+    ## Read a todo file and create a list of actions
+    ##
+    ## @param      depth       [Number] The directory depth to search for files
+    ## @param      query       [Hash] The project query
+    ## @param      tag         [Hash] Tags to search for
+    ## @param      search      [String] A search string
+    ## @param      negate      [Boolean] Invert results
+    ## @param      regex       [Boolean] Interpret as regular expression
+    ## @param      project     [String] The project
+    ## @param      require_na  [Boolean] Require @na tag
+    ##
     def parse_actions(depth: 1, query: nil, tag: nil, search: nil, negate: false, regex: false, project: nil, require_na: true)
       actions = []
       required = []
@@ -220,6 +276,9 @@ module NA
       end
     end
 
+    ##
+    ## Remove entries from cache database that no longer exist
+    ##
     def weed_cache_file
       db_dir = File.expand_path('~/.local/share/na')
       db_file = 'tdlist.txt'
@@ -231,6 +290,24 @@ module NA
       end
     end
 
+    def list_todos(query: [])
+      if query
+        dirs = match_working_dir(query)
+      else
+        file = database_path
+        content = File.exist?(file) ? IO.read(file).strip : ''
+        notify('{br}Database empty', exit_code: 1) if content.empty?
+
+        dirs = content.split(/\n/)
+      end
+
+      dirs.map! do |dir|
+        "{xg}#{dir.sub(/^#{ENV['HOME']}/, '~').sub(%r{/([^/]+)\.#{NA.extension}$}, '/{xbw}\1{x}')}"
+      end
+
+      puts NA::Color.template(dirs.join("\n"))
+    end
+
     private
 
     ##
@@ -302,29 +379,26 @@ module NA
     ##                       between characters
     ##
     def match_working_dir(search, distance: 1)
-      optional = []
-      required = []
-
-      search&.each do |t|
-        # Make "search" into "s.{0,1}e.{0,1}a.{0,1}r.{0,1}c.{0,1}h"
-        new_rx = t[:token].to_s.split('').join(".{0,#{distance}}")
-
-        optional.push(new_rx)
-        required.push(new_rx) if t[:required]
-      end
-
-      match_dir(optional, required)
-    end
-
-    def match_dir(optional, required)
       file = database_path
       notify('{r}No na database found', exit_code: 1) unless File.exist?(file)
 
       dirs = IO.read(file).split("\n")
-      dirs.delete_if { |d| !d.dir_matches(any: optional, all: required) }
+
+      optional = search.map { |t| t[:token] }
+      required = search.filter { |s| s[:required] }.map { |t| t[:token] }
+
+      NA.notify("{bw}Optional directory regex: {x}#{optional.map(&:dir_to_rx)}", debug: true)
+      NA.notify("{bw}Required directory regex: {x}#{required.map(&:dir_to_rx)}", debug: true)
+
+      dirs.delete_if { |d| !d.sub(/\.#{NA.extension}$/, '').dir_matches(any: optional, all: required) }
       dirs.sort.uniq
     end
 
+    ##
+    ## Save a todo file path to the database
+    ##
+    ## @param      todo_file  The todo file path
+    ##
     def save_working_dir(todo_file)
       file = database_path
       content = File.exist?(file) ? IO.read(file) : ''
@@ -334,6 +408,12 @@ module NA
       File.open(file, 'w') { |f| f.puts dirs.join("\n") }
     end
 
+    ##
+    ## macOS open command
+    ##
+    ## @param      file  The file
+    ## @param      app   The application
+    ##
     def darwin_open(file, app: nil)
       if app
         `open -a "#{app}" #{Shellwords.escape(file)}`
@@ -342,10 +422,20 @@ module NA
       end
     end
 
+    ##
+    ## Windows open command
+    ##
+    ## @param      file  The file
+    ##
     def win_open(file)
       `start #{Shellwords.escape(file)}`
     end
 
+    ##
+    ## Linux open command
+    ##
+    ## @param      file  The file
+    ##
     def linux_open(file)
       if TTY::Which.exist?('xdg-open')
         `xdg-open #{Shellwords.escape(file)}`

data/lib/na/string.rb

@@ -1,6 +1,12 @@
 # frozen_string_literal: true
 
+# String helpers
 class ::String
+  ##
+  ## Determine indentation level of line
+  ##
+  ## @return     [Number] number of indents detected
+  ##
   def indent_level
     prefix = match(/(^[ \t]+)/)
     return 0 if prefix.nil?
@@ -11,7 +17,13 @@ class ::String
   ##
   ## Colorize @tags with ANSI escapes
   ##
-  ## @param      color  [String] color (see #Color)
+  ## @param      color       [String] color (see #Color)
+  ## @param      value       [String] The value color
+  ##                         template
+  ## @param      parens      [String] The parens color
+  ##                         template
+  ## @param      last_color  [String] Color to restore after
+  ##                         tag highlight
   ##
   ## @return     [String] string with @tags highlighted
   ##
@@ -23,6 +35,16 @@ class ::String
          "\\1#{tag_color}\\2#{paren_color}\\3#{value_color}\\4#{paren_color}\\5#{last_color}")
   end
 
+  ##
+  ## Highlight search results
+  ##
+  ## @param      regexes     [Array] The regexes for the
+  ##                         search
+  ## @param      color       [String] The highlight color
+  ##                         template
+  ## @param      last_color  [String] Color to restore after
+  ##                         highlight
+  ##
   def highlight_search(regexes, color: '{y}', last_color: '{xg}')
     string = dup
     color = NA::Color.template(color)
@@ -42,12 +64,13 @@ class ::String
 
   # Returns the last escape sequence from a string.
   #
-  # Actually returns all escape codes, with the assumption
-  # that the result of inserting them will generate the
-  # same color as was set at the end of the string.
-  # Because you can send modifiers like dark and bold
-  # separate from color codes, only using the last code
-  # may not render the same style.
+  # @note       Actually returns all escape codes, with the
+  #             assumption that the result of inserting them
+  #             will generate the same color as was set at
+  #             the end of the string. Because you can send
+  #             modifiers like dark and bold separate from
+  #             color codes, only using the last code may
+  #             not render the same style.
   #
   # @return     [String]  All escape codes in string
   #
@@ -55,8 +78,18 @@ class ::String
     scan(/\e\[[\d;]+m/).join('').gsub(/\e\[0m/, '')
   end
 
-  def dir_to_rx
-    "#{split(%r{[/:]}).join('.*?/.*?')}[^/]+$"
+  ##
+  ## Convert a directory path to a regular expression
+  ##
+  ## @note       Splits at / or :, adds variable distance
+  ##             between characters, joins segments with
+  ##             slashes and requires that last segment
+  ##             match last segment of target path
+  ##
+  ## @param      distance  The distance
+  ##
+  def dir_to_rx(distance: 2)
+    "#{split(%r{[/:]}).map { |comp| comp.split('').join(".{0,#{distance}}").gsub(/\*/, '[^ ]*?') }.join('.*?/.*?')}[^/]*?$"
   end
 
   def dir_matches(any: [], all: [])
@@ -67,6 +100,11 @@ class ::String
     matches_any(any) && matches_all(all) && matches_none(none)
   end
 
+  ##
+  ## Convert wildcard characters to regular expressions
+  ##
+  ## @return     [String] Regex string
+  ##
   def wildcard_to_rx
     gsub(/\./, '\\.').gsub(/\*/, '[^ ]*?').gsub(/\?/, '.')
   end
@@ -75,6 +113,12 @@ class ::String
     replace cap_first
   end
 
+  ##
+  ## Capitalize first character, leaving other
+  ## capitalization in place
+  ##
+  ## @return     [String] capitalized string
+  ##
   def cap_first
     sub(/^([a-z])(.*)$/) do
       m = Regexp.last_match

data/lib/na/version.rb

@@ -1,3 +1,3 @@
 module Na
-  VERSION = '1.1.20'
+  VERSION = '1.1.22'
 end

data/src/README.md

@@ -9,7 +9,7 @@
 _If you're one of the rare people like me who find this useful, feel free to
 [buy me some coffee][donate]._
 
-The current version of `na` is <!--VER-->1.1.19<!--END VER-->.
+The current version of `na` is <!--VER-->1.1.21<!--END VER-->.
 
 `na` ("next action") is a command line tool designed to make it easy to see what your next actions are for any project, right from the command line. It works with TaskPaper-formatted files (but any plain text format will do), looking for `@na` tags (or whatever you specify) in todo files in your current folder. 
 
@@ -51,37 +51,7 @@ If found, it will try to locate an `Inbox:` project, or create one if it doesn't
 ### Usage
 
 ```
-NAME
-    na - Add and list next actions for the current project
-
-SYNOPSIS
-    na [global options] command [command options] [arguments...]
-
-VERSION
-    1.1.19
-
-GLOBAL OPTIONS
-    -a, --[no-]add          - Add a next action (deprecated, for backwards compatibility)
-    -d, --depth=DEPTH       - Recurse to depth (default: 1)
-    --[no-]debug            - Display verbose output
-    --ext=EXT               - File extension to consider a todo file (default: taskpaper)
-    --help                  - Show this message
-    -n, --note              - Prompt for additional notes (deprecated, for backwards compatibility)
-    -p, --priority=PRIORITY - Set a priority 0-5 (deprecated, for backwards compatibility) (default: none)
-    -r, --[no-]recurse      - Recurse 3 directories deep (deprecated, for backwards compatability)
-    -t, --na_tag=TAG        - Tag to consider a next action (default: na)
-    --version               - Display the program version
-
-COMMANDS
-    add          - Add a new next action
-    edit         - Open a todo file in the default editor
-    find, grep   - Find actions matching a search pattern
-    help         - Shows a list of commands or help for one command
-    init, create - Create a new todo file in the current directory
-    initconfig   - Initialize the config file using current global options
-    next, show   - Show next actions
-    prompt       - Show or install prompt hooks for the current shell
-    tagged       - Find actions matching a tag
+@cli(bundle exec bin/na help)
 ```
 
 #### Commands
@@ -93,60 +63,13 @@ Example: `na add This feature @idea I have`
 If you run the `add` command with no arguments, you'll be asked for input on the command line.
 
 ```
-NAME
-    add - Add a new next action
-
-SYNOPSIS
-
-    na [global options] add [command options] ACTION
-
-DESCRIPTION
-    Provides an easy way to store todos while you work. Add quick reminders and (if you set up Prompt Hooks)   they'll automatically display next time you enter the directory.   If multiple todo files are found in the current directory, a menu will allow you to pick to which   file the action gets added. 
-
-COMMAND OPTIONS
-    -d, --depth=DEPTH   - Search for files X directories deep (default: 1)
-    -f, --file=PATH     - Specify the file to which the task should be added (default: none)
-    -n, --note          - Prompt for additional notes
-    -p, --priority=PRIO - Add a priority level 1-5 (default: 0)
-    -t, --tag=TAG       - Use a tag other than the default next action tag (default: none)
-    --to=PROJECT        - Add action to specific project (default: Inbox)
-    -x                  - Don't add next action tag to new entry
-
-EXAMPLES
-
-    # Add a new action to the Inbox, including a tag
-    na add "A cool feature I thought of @idea"
-
-    # Add a new action to the Inbox, set its @priority to 4, and prompt for an additional note
-    na add "A bug I need to fix" -p 4 -n
+@cli(bundle exec bin/na help add)
 ```
 
 ##### edit
 
 ```
-NAME
-    edit - Open a todo file in the default editor
-
-SYNOPSIS
-
-    na [global options] edit [command options] 
-
-DESCRIPTION
-    Let the system choose the defualt, (e.g. TaskPaper), or specify a command line utility (e.g. vim).              If more than one todo file is found, a menu is displayed. 
-
-COMMAND OPTIONS
-    -a, --app=EDITOR    - Specify a Mac app (default: none)
-    -d, --depth=DEPTH   - Recurse to depth (default: 1)
-    -e, --editor=EDITOR - Specify an editor CLI (default: none)
-
-EXAMPLES
-
-    # Open the main todo file in the default editor
-    na edit
-
-    # Display a menu of all todo files three levels deep from the
-               current directory, open selection in vim.
-    na edit -d 3 -a vim
+@cli(bundle exec bin/na help edit)
 ```
 
 ##### find
@@ -156,84 +79,25 @@ Example: `na find cool feature idea`
 Unless `--exact` is specified, search is tokenized and combined with AND, so `na find cool feature idea` translates to `cool AND feature AND idea`, matching any string that contains all of the words. To make a token required and others optional, add a `+` before it (e.g. `cool +feature idea` is `(cool OR idea) AND feature`). Wildcards allowed (`*` and `?`), use `--regex` to interpret the search as a regular expression. Use `-v` to invert the results (display non-matching actions only).
 
 ```
-NAME
-    find - Find actions matching a search pattern
-
-SYNOPSIS
-
-    na [global options] find [command options] PATTERN
-
-DESCRIPTION
-    Search tokens are separated by spaces. Actions matching all tokens in the pattern will be shown   (partial matches allowed). Add a + before a token to make it required, e.g. `na find +feature +maybe` 
-
-COMMAND OPTIONS
-    -d, --depth=DEPTH                      - Recurse to depth (default: none)
-    -e, --regex                            - Interpret search pattern as regular expression
-    --in=TODO_PATH                         - Show actions from a specific todo file in history (default: none)
-    -o, --or                               - Combine search tokens with OR, displaying actions matching ANY of the terms
-    --proj, --project=PROJECT[/SUBPROJECT] - Show actions from a specific project (default: none)
-    -v, --invert                           - Show actions not matching search pattern
-    -x, --exact                            - Match pattern exactly
-
-EXAMPLES
-
-    # Find all actions containing feature, idea, and swift
-    na find feature idea swift
-
-    # Find all actions containing the exact text "feature idea"
-    na find -x feature idea
+@cli(bundle exec bin/na help find)
 ```
 
 ##### init, create
 
 ```
-NAME
-    init - Create a new todo file in the current directory
-
-SYNOPSIS
-
-    na [global options] init [PROJECT]
-
-EXAMPLES
-
-    # Generate a new todo file, prompting for project name
-    na init
-
-    # Generate a new todo for a project called warpspeed
-    na init warpspeed
+@cli(bundle exec bin/na help init)
 ```
 
 ##### next, show
 
-Examples: 
+Examples:
 
-- `na show` (list all next actions in the current directory)
-- `na show -d 3` (list all next actions in the current directory and look for additional files 3 levels deep from there)
-- `na show marked2` (show next actions from another directory you've previously used na on)
+- `na next` (list all next actions in the current directory)
+- `na next -d 3` (list all next actions in the current directory and look for additional files 3 levels deep from there)
+- `na next marked2` (show next actions from another directory you've previously used na on)
 
 ```
-NAME
-    next - Show next actions
-
-SYNOPSIS
-
-    na [global options] next [command options] OPTIONAL_QUERY
-
-COMMAND OPTIONS
-    -d, --depth=DEPTH                      - Recurse to depth (default: 2)
-    --proj, --project=PROJECT[/SUBPROJECT] - Show actions from a specific project (default: none)
-    -t, --tag=TAG                          - Alternate tag to search for (default: none)
-
-EXAMPLES
-
-    # display the next actions from any todo files in the current directory
-    na next
-
-    # display the next actions from the current directory, traversing 3 levels deep
-    na next -d 3
-
-    # display next actions for a project you visited in the past
-    na next marked
+@cli(bundle exec bin/na help next)
 ```
 
 ##### tagged
@@ -243,39 +107,7 @@ Example: `na tagged feature +maybe`.
 Separate multiple tags with spaces or commas. By default tags are combined with AND, so actions matching all of the tags listed will be displayed. Use `+` to make a tag required and `!` to negate a tag (only display if the action does _not_ contain the tag). When `+` and/or `!` are used, undecorated tokens become optional matches. Use `-v` to invert the search and display all actions that _don't_ match.
 
 ```
-NAME
-    tagged - Find actions matching a tag
-
-SYNOPSIS
-
-    na [global options] tagged [command options] TAG [VALUE]
-
-DESCRIPTION
-    Finds actions with tags matching the arguments. An action is shown if it              contains all of the tags listed. Add a + before a tag to make it required              and others optional. You can specify values using TAG=VALUE pairs.              Use <, >, and = for numeric comparisons, and *=, ^=, and $= for text comparisons.              Date comparisons use natural language (`na tagged "due<=today"`) and              are detected automatically. 
-
-COMMAND OPTIONS
-    -d, --depth=DEPTH                      - Recurse to depth (default: 1)
-    --in=TODO_PATH                         - Show actions from a specific todo file in history (default: none)
-    -o, --or                               - Combine tags with OR, displaying actions matching ANY of the tags
-    --proj, --project=PROJECT[/SUBPROJECT] - Show actions from a specific project (default: none)
-    -v, --invert                           - Show actions not matching tags
-
-EXAMPLES
-
-    # Show all actions tagged @maybe
-    na tagged maybe
-
-    # Show all actions tagged @feature AND @idea, recurse 3 levels
-    na tagged -d 3 "feature, idea"
-
-    # Show all actions tagged @feature OR @idea
-    na tagged --or "feature, idea"
-
-    # Show actions with @priority(4) or @priority(5)
-    na tagged "priority>=4"
-
-    # Show actions with a due date coming up in the next 2 days
-    na tagged "due<in 2 days"
+@cli(bundle exec bin/na help show)
 ```
 
 ### Configuration

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: na
 version: !ruby/object:Gem::Version
-  version: 1.1.20
+  version: 1.1.22
 platform: ruby
 authors:
 - Brett Terpstra
@@ -178,6 +178,7 @@ extra_rdoc_files:
 - README.md
 - na.rdoc
 files:
+- ".travis.yml"
 - CHANGELOG.md
 - Gemfile
 - Gemfile.lock