na 1.0.1 → 1.0.3

data/src/README.md

@@ -0,0 +1,276 @@
+<!--README--><!--GITHUB--># na
+
+[![Gem](https://img.shields.io/gem/v/na.svg)](https://rubygems.org/gems/na)
+[![Travis](https://app.travis-ci.com/ttscoff/na_gem.svg?branch=main)](https://travis-ci.org/makenew/na_gem)
+[![GitHub license](https://img.shields.io/github/license/ttscoff/na_gem.svg)](./LICENSE.txt)<!--END GITHUB-->
+
+**A command line tool for adding and listing per-project todos.**
+
+_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.0.2<!--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. 
+
+Used with Taskpaper files, it can add new todo items quickly from the command line, automatically tagging them as next actions.
+
+It can also auto-display next actions when you enter a project directory, automatically locating any todo files and listing their next actions when you `cd` to the project (optionally recursive). See the [Prompt Hooks](#prompt-hooks) section for details.
+
+### Features
+
+You can list next actions in files in the current directory by typing `na`. By default, `na` looks for `*.taskpaper` files and extracts items tagged `@na` and not `@done`. All of these can be changed in the configuration.
+
+#### Easy matching
+
+`na` features intelligent project matching. Every time it locates a todo file, it adds the project to the database. Once a project is recorded, you can list its actions by using any portion of the parent directories or file names. If your project is in `~/Sites/dev/markedapp`, you could quickly list its next actions by typing `na dev mark`. It will always look for the shortest match.
+
+#### Recursion
+
+`na` can also recurse subdirectories to find all todo files in child folders as well. Use the `-d X` to search X levels deep from the current directory. `na -r` with no arguments will recurse from your current location, looking for todo files 3 directories deep.
+
+#### Adding todos
+
+You can also quickly add todo items from the command line with the `add` subcommand. The script will look for a file in the current directory with a `.taskpaper` extension (configurable). 
+
+If found, it will try to locate an `Inbox:` project, or create one if it doesn't exist. Any arguments after `add` will be combined to create a new task in TaskPaper format. They will automatically be assigned as next actions (tagged `@na`) and will show up when `na` lists the tasks for the project.
+
+### Installation
+
+Assuming you have Ruby and RubyGems installed, you can just run `gem install na`. If you run into errors, use `sudo gem install na`.
+
+If you don't have Ruby/RubyGems, you can install them pretty easily with Homebrew, rvm, or asdf. I can't swear this tool is worth the time, but there _are_ a lot of great gems available...
+
+<!--JEKYLL> You can find the na source code (MIT license) on [GitHub][].-->
+
+### Usage
+
+```
+NAME
+    na - Add and list next actions for the current project
+
+
+SYNOPSIS
+    na [global options] command [command options] [arguments...]
+
+
+VERSION
+    1.0.2
+
+
+
+GLOBAL OPTIONS
+    -a, --[no-]add          - Add a next action (deprecated, for backwards compatibility)
+    -d, --depth=DEPTH       - Recurse to depth (default: 1)
+    --ext=FILE_EXTENSION    - File extension to consider a todo file (default: taskpaper)
+    --help                  - Show this message
+    -n, --[no-]note         - Prompt for additional notes (deprecated, for backwards compatibility)
+    --na_tag=TAG            - Tag to consider a next action (default: na)
+    -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)
+    --version               - Display the program version
+
+
+
+COMMANDS
+    add        - Add a new next action
+    find       - Find actions matching a search pattern
+    help       - Shows a list of commands or help for one command
+    initconfig - Initialize the config file using current global options
+    next, show - Show next actions
+    tagged     - Find actions matching a tag
+```
+
+#### Commands
+
+##### add
+
+Example: `na add This feature @idea I have`
+
+```
+NAME
+    add - Add a new next action
+
+SYNOPSIS
+
+    na [global options] add [command options] TASK
+
+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
+    -f, --file=PATH    - Specify the file to which the task should be added (default: none)
+    -n, --[no-]note    - Prompt for additional notes
+    -p, --priority=arg - Add a priority level 1-5 (default: 0)
+    -t, --tag=TAG      - Use a tag other than the default next action tag (default: none)
+
+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
+```
+
+##### find
+
+Example: `na find cool feature idea`
+
+```
+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 any token 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: 1)
+    -x, --[no-]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
+
+    # Find all actions 3 directories deep containing either swift or obj-c
+    na find -d 3 swift obj-c
+```
+
+##### next, show
+
+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)
+
+```
+NAME
+    next - Show next actions
+
+SYNOPSIS
+
+    na [global options] next [command options] OPTIONAL_QUERY
+
+COMMAND OPTIONS
+    -d, --depth=DEPTH - Recurse to depth (default: none)
+    -t, --tag=arg     - Alternate tag to search for (default: na)
+
+EXAMPLES
+
+    # display the next actions from any todo files in the current directory
+    doing next
+
+    # display the next actions from the current directory and its children, 3 levels deep
+    doing next -d 3
+```
+
+##### tagged
+
+Example: `na tagged feature +maybe`
+
+```
+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 any of the tags listed. Add a + before a tag to make it required,   e.g. `na tagged feature +maybe` 
+
+COMMAND OPTIONS
+    -d, --depth=DEPTH - Recurse to depth (default: 1)
+
+EXAMPLES
+
+    # Show all actions tagged @maybe
+    na tagged +maybe
+
+    # Show all actions tagged either @feature or @idea, recurse 3 levels
+    na tagged -d 3 feature idea
+```
+
+### Configuration
+
+Global options such as todo extension and default next action tag can be stored permanently by using the `na initconfig` command. Run na with the global options you'd like to set, and add `initconfig` at the end of the command. A file will be written to `~/.na.rc`. You can edit this manually, or just update it using the `initconfig --force` command to overwrite it with new settings.
+
+Example: `na --ext md --na_tag next initconfig --force`
+
+When this command is run, it doesn't include options for subcommands, but inserts placeholders for them. If you want to permanently set an option for a subcommand, you'll need to edit `~/.na.rc`. For example, if you wanted the `next` command to always recurse 2 levels deep, you could edit it to look like this:
+
+```yaml
+---
+:ext: taskpaper
+:na_tag: na
+:d: 1
+commands:
+  :next:
+    :depth: 2
+  :add: {}
+  :find: {}
+  :tagged: {}
+```
+
+Note that I created a new YAML dictionary inside of the `:next:` command, and added a `:depth:` key that matches the setting I want to make permanent.
+
+> **WARNING** Don't touch most of the settings at the top of the auto-generated file. Setting any of them to true will alter the way na interprets the commands you're running. Most of those options are there for backwards compatibility with the bash version of this tool and will eventually be removed.
+<!--JEKYLL{:.warn}-->
+
+### Prompt Hooks
+
+You can add a prompt command to your shell to have na automatically list your next actions when you `cd` into a directory. Add the appropriate command to your login file for your shell:
+
+_(You can add `-r` to any of these calls to na to automatically recurse 3 directories deep)_
+
+Bash (in ~/.bash_profile):
+
+```bash
+last_command_was_cd() {
+	[[ $(history 1|sed -e "s/^[ ]*[0-9]*[ ]*//") =~ ^((cd|z|j|jump|g|f|pushd|popd|exit)([ ]|$)) ]] && na
+}
+if [[ -z "$PROMPT_COMMAND" ]]; then
+	PROMPT_COMMAND="eval 'last_command_was_cd'"
+else
+	echo $PROMPT_COMMAND | grep -v -q "last_command_was_cd" && PROMPT_COMMAND="$PROMPT_COMMAND;"'eval "last_command_was_cd"'
+fi
+```
+
+Fish (in ~/.config/fish/conf.d/*.fish):
+
+```fish
+function __should_na --on-variable PWD
+	# function __should_na --on-event fish_prompt
+	test -s (basename $PWD)".taskpaper" && na
+end
+```
+
+Zsh (in ~/.zshrc):
+
+```zsh
+chpwd() { na }
+```
+
+
+### Misc
+
+If you have [gum][] installed, na will use it for command line input when adding tasks and notes.
+
+[gum]: https://github.com/charmbracelet/gum
+[donate]: http://brettterpstra.com/donate/
+[github]: https://github.com/ttscoff/na_gem/
+
+<!--GITHUB-->PayPal link: [paypal.me/ttscoff](https://paypal.me/ttscoff)<!--END GITHUB-->
+<!--END README-->
+## Changelog
+
+See [CHANGELOG.md](https://github.com/ttscoff/na_gem/blob/master/CHANGELOG.md)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: na
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.3
 platform: ruby
 authors:
 - Brett Terpstra
@@ -106,6 +106,26 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 0.9.0
+- !ruby/object:Gem::Dependency
+  name: tty-screen
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.8.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.8.1
 - !ruby/object:Gem::Dependency
   name: tty-which
   requirement: !ruby/object:Gem::Requirement
@@ -126,13 +146,16 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 0.5.0
-description:
+description: A tool for managing a TaskPaper file of project todos for the current
+  directory. Easily create "next actions" to come back to, add tags and priorities,
+  and notes. Add prompt hooks to display your next actions automatically when cd'ing
+  into a directory.
 email: me@brettterpstra.com
 executables:
 - na
 extensions: []
 extra_rdoc_files:
-- README.rdoc
+- README.md
 - na.rdoc
 files:
 - CHANGELOG.md
@@ -143,56 +166,6 @@ files:
 - README.rdoc
 - Rakefile
 - bin/na
-- html/App.html
-- html/NA.html
-- html/NA/Action.html
-- html/NA/Color.html
-- html/README_rdoc.html
-- html/String.html
-- html/created.rid
-- html/css/fonts.css
-- html/css/rdoc.css
-- html/fonts/Lato-Light.ttf
-- html/fonts/Lato-LightItalic.ttf
-- html/fonts/Lato-Regular.ttf
-- html/fonts/Lato-RegularItalic.ttf
-- html/fonts/SourceCodePro-Bold.ttf
-- html/fonts/SourceCodePro-Regular.ttf
-- html/images/add.png
-- html/images/arrow_up.png
-- html/images/brick.png
-- html/images/brick_link.png
-- html/images/bug.png
-- html/images/bullet_black.png
-- html/images/bullet_toggle_minus.png
-- html/images/bullet_toggle_plus.png
-- html/images/date.png
-- html/images/delete.png
-- html/images/find.png
-- html/images/loadingAnimation.gif
-- html/images/macFFBgHack.png
-- html/images/package.png
-- html/images/page_green.png
-- html/images/page_white_text.png
-- html/images/page_white_width.png
-- html/images/plugin.png
-- html/images/ruby.png
-- html/images/tag_blue.png
-- html/images/tag_green.png
-- html/images/transparent.png
-- html/images/wrench.png
-- html/images/wrench_orange.png
-- html/images/zoom.png
-- html/index.html
-- html/js/darkfish.js
-- html/js/navigation.js
-- html/js/navigation.js.gz
-- html/js/search.js
-- html/js/search_index.js
-- html/js/search_index.js.gz
-- html/js/searcher.js
-- html/js/searcher.js.gz
-- html/table_of_contents.html
 - lib/na.rb
 - lib/na/action.rb
 - lib/na/colors.rb
@@ -201,7 +174,9 @@ files:
 - lib/na/version.rb
 - na.gemspec
 - na.rdoc
-homepage: https://brettterpstra.com
+- scripts/fixreadme.rb
+- src/README.md
+homepage: https://brettterpstra.com/projects/na/
 licenses:
 - MIT
 metadata: {}
@@ -210,8 +185,9 @@ rdoc_options:
 - "--title"
 - na
 - "--main"
-- README.rdoc
-- "-ri"
+- README.md
+- "--markup"
+- markdown
 require_paths:
 - lib
 - lib

data/html/App.html

@@ -1,105 +0,0 @@
-<!DOCTYPE html>
-
-<html>
-<head>
-<meta charset="UTF-8">
-
-<title>class App - Your application title</title>
-
-<script type="text/javascript">
-  var rdoc_rel_prefix = "./";
-  var index_rel_prefix = "./";
-</script>
-
-<script src="./js/navigation.js" defer></script>
-<script src="./js/search.js" defer></script>
-<script src="./js/search_index.js" defer></script>
-<script src="./js/searcher.js" defer></script>
-<script src="./js/darkfish.js" defer></script>
-
-<link href="./css/fonts.css" rel="stylesheet">
-<link href="./css/rdoc.css" rel="stylesheet">
-
-
-<body id="top" role="document" class="class">
-<nav role="navigation">
-  <div id="project-navigation">
-    <div id="home-section" role="region" title="Quick navigation" class="nav-section">
-  <h2>
-    <a href="./index.html" rel="home">Home</a>
-  </h2>
-
-  <div id="table-of-contents-navigation">
-    <a href="./table_of_contents.html#pages">Pages</a>
-    <a href="./table_of_contents.html#classes">Classes</a>
-    <a href="./table_of_contents.html#methods">Methods</a>
-  </div>
-</div>
-
-    <div id="search-section" role="search" class="project-section initially-hidden">
-  <form action="#" method="get" accept-charset="utf-8">
-    <div id="search-field-wrapper">
-      <input id="search-field" role="combobox" aria-label="Search"
-             aria-autocomplete="list" aria-controls="search-results"
-             type="text" name="search" placeholder="Search" spellcheck="false"
-             title="Type to search, Up and Down to navigate, Enter to load">
-    </div>
-
-    <ul id="search-results" aria-label="Search Results"
-        aria-busy="false" aria-expanded="false"
-        aria-atomic="false" class="initially-hidden"></ul>
-  </form>
-</div>
-
-  </div>
-
-  
-
-  <div id="class-metadata">
-    
-    
-<div id="parent-class-section" class="nav-section">
-  <h3>Parent</h3>
-
-  <p class="link">Object
-</div>
-
-    
-    
-<div id="extends-section" class="nav-section">
-  <h3>Extended With Modules</h3>
-
-  <ul class="link-list">
-    <li><span class="extend">GLI::App</span>
-  </ul>
-</div>
-
-    
-  </div>
-</nav>
-
-<main role="main" aria-labelledby="class-App">
-  <h1 id="class-App" class="class">
-    class App
-  </h1>
-
-  <section class="description">
-    
-  </section>
-
-  <section id="5Buntitled-5D" class="documentation-section">
-
-
-
-
-
-  </section>
-</main>
-
-
-<footer id="validator-badges" role="contentinfo">
-  <p><a href="https://validator.w3.org/check/referer">Validate</a>
-  <p>Generated by <a href="https://ruby.github.io/rdoc/">RDoc</a> 6.3.3.
-  <p>Based on <a href="http://deveiate.org/projects/Darkfish-RDoc/">Darkfish</a> by <a href="http://deveiate.org">Michael Granger</a>.
-</footer>
-