nvremind

FYI, this project is listed as "retired." It may no longer function or I may just not be updating it anymore.

A scheduled background task to scan nvALT notes for @reminder() tags and trigger notifications based on dates. It’s grown to work with any folder of text or Markdown files, TaskPaper files and Day One entries.

Yes, it’s pronounced “never mind.”

Quick start

This tool will search for @remind() tags in the specified notes folder.

  • nvremind searches “.md”, “.txt”, “.ft”, “.taskpaper” and Day One entry files
  • Remind tags are placed in the document in the format @remind(2013-05-06 08:00) for a reminder on May 6th, 2013 at 8am
    • Remind tags can use any prefix (not just “@”), as long as there is a character before “remind”
    • Tags on their own line will cause the entire document to become a reminder, with the filename as the title and the content as the note (if the notification method supports notes)
    • Tags on a line with other text will use that text as the reminder. The title can always be overwritten with the format @remind(2013-05-05 "Override title")

Then the script is run on the folder. Basic usage from the command line (Terminal):

/usr/local/bin/nvremind.rb -z ~/Dropbox/nvALT

Where ~/Dropbox/nvALT is the location of your nvALT notes or other collection of text files. This command will output the results to the Terminal without other notifications, and will not modify the @remind tags (-z argument).

Set this up to run at intervals with your notification method of choice. I prefer launchd for this (via LaunchControl), but you can schedule it any way you like.

Dependencies

Mountain Lion notifications require the ‘terminal-notifier’ Ruby gem:

sudo gem install 'terminal-notifier'

Sending HTML emails (including special Taskpaper processing) requires that MultiMarkdown be installed at /usr/local/bin/multimarkdown. Download an installer package here.

Details

nvremind expects an ISO 8601 format date (2013-05-01) with optional 24-hour time (2013-05-01 15:30). Put @remind(2013-05-01 06:00) anywhere in a note to have a reminder go off on the first run following that time. A quick TextExpander snippet can make adding them a breeze.

By default the script will replace found @remind tags with @reminded tags containing the date the reminder was sent. Use the -z option to prevent any changes from being made to your file, although this can result in reminders being sent multiple times. You’d need to manually update the files after handling the reminder.

A document can contain multiple reminders with different dates. The script will check all of them and only modify the ones that are triggered. Future reminders in the same document will still be active after the run.

Reminders on their own line with no other text will send the entire note as the reminder with the filename being the subject line. If a @reminder tag is on a line with other text, only that line will be used as the title and the content.

If you include a double-quoted string at the end of the remind tag value, it will override the default reminder title. @remind(2013-05-24 "This is the override") would create a reminder called “This is the override”, ignoring any other text on the line or the name of the file. Additional text on the line or the entire note (in the case of a @remind tag on its own line) will still be included in the note, if the notification method supports that.

Notification types

Notification Center

Use the -n option to send Mountain Lion notifications instead of terminal output. Clicking a notification will open the related file in nvALT. Notifications require that the ‘terminal-notifier’ gem be installed.

Email

Use the -e ADDRESS option to send an email with the title of the note as the subject and the contents of the note as the body to the specified address. Separate multiple emails with commas. The contents of the note can be rendered with MultiMarkdown, if it exists at /usr/local/bin/multimarkdown.

If the file to be emailed has a “.taskpaper” extension, it will be converted to Markdown for formatting before processing with MultiMarkdown (if MultiMarkdown is installed). [[Links]] and @tags will be linked and can be clicked from Mail.app.

Reminders.app

The -m option will add a reminder to Reminders.app in Mountain Lion, due immediately, which will show up on iCloud-synced iOS devices as well. Specify a list (default “Reminders” or the first list available) using --reminder-list "List name".

File

The -f FOLDER option allows you to specify a directory where a file named with the reminder title will be saved. The note for the reminder will be the file contents. This is useful, for example, with IFTTT.com. You can save a file to a public Dropbox folder, have IFTTT notice it and take any number of actions on it.

Usage

nvremind.rb [options] notes_folder

For help use nvremind.rb -h. For even more help, use nvremind.rb -H.

Examples

Output to Terminal:

nvremind.rb ~/Dropbox/nvALT

Other examples:

nvremind.rb ~/Dropbox/nvALT
nvremind.rb -n ~/Dropbox/nvALT
nvremind.rb -e me@gmail.com ~/Dropbox/nvALT
nvremind.rb -mn -e me@gmail.com ~/Dropbox/nvALT
nvremind.rb -f ~/Dropbox/Public/ifttt ~/Dropbox/nvALT

Testing/debugging example (verbose output, no changes to file, output to terminal)

nvremind.rb -Vz ~/Dropbox/nvALT

Options

-h, --help            Displays help message
-H                    No, really help
-v, --version         Display the version, then exit
-V, --verbose         Verbose output
-z, --no-replace      Don't updated @remind() tags with @reminded() after notification
-n, --notify          Use terminal-notifier to post Mountain Lion notifications
-m, --reminders       Add an item to the Reminders list in Reminders.app (due immediately)
--reminder-list LIST  List to use in Reminders.app (default "Reminders")
-f folder             Save a file to FOLDER named with the task title, note as contents
-e EMAIL[,EMAIL], --email EMAIL[,EMAIL] Send an email with note contents to the specified address

Download/Install

nvremind v1.0.6

A background utility to scan text files for reminder tags with timestamps and generate a variety of notifications for them.

Published 01/15/14.

Updated 01/15/14. Changelog

DonateMore info…

Install “nvremind.rb” wherever you like (/usr/local/bin works well) and set up a launchd task to run the nvremind.rb /path/notes/folder command at regular intervals with whatever reminder options you choose. Use Lingon or LaunchControl to schedule, or write your own PLIST and store it at ~/Library/LaunchAgents/com.brettterpstra.nvremind.plist:

EXAMPLE ONLY:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.brettterpstra.nvremind</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/bin/ruby</string>
        <string>/usr/local/bin/nvremind.rb</string>
        <string>-m</string>
        <string>-e</string>
        <string>your@emailaddress.com</string>
        <string>~/Dropbox/nvALT2.2</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>StartInterval</key>
    <integer>1800</integer>
</dict>
</plist>

This assumes you put the script in “/usr/local/bin/nvremind.rb,” but you can edit that to point anywhere. The “-m” will trigger Reminders.app, the “-e” address option enables emails and the final argument should be the folder where you store your nvALT notes as text files.

Changelog

Click to expand

1.0.6

  • Fixed UTF-8 and Ruby 2.0 issues
  • Added File notification method for use with IFTTT, etc.

1.0

  • Works with any prefix, not just “@”. To allow use in apps like Day One that have different uses for @tags. Any character will work (!remind, $remind), there just has to be something immediately before “remind”
  • Works with Day One, just pass it the path to the entries folder within your Journal
    • In Day One, if a reminder is on its own line and has no override title, the first 30 characters of the first line of the entry will be used as the reminder title.

      This is necessary because Day One entries don’t have titles and the filenames are just UUID strings.

  • If the tag is inside of quotes or brackets, those will be stripped from the reminder title
  • If you include a double-quoted string at the end of the remind tag value, it will override the default reminder title. @reminded(2013-06-06 09:52 “This is the override”) would create a reminder called “This is the override”, ignoring any other text on the line or the name of the file.

    Additional text on the line or the entire note (in the case of a @remind tag on its own line) will still be included in the note, if the notification method supports that.

  • You can specify a list for Reminders.app (default “Reminders” or the first list available) using ‘–reminder-list “List name”’
  • Won’t schedule the reminder if the same line contains @done or @canceled (also recognizes @cancelled)
  • Remove leading -, * or + so you can use it within Markdown lists and still get nicely-formatted reminder messages
  • Don’t include line number in file link (that just breaks it for 90% of the population)
  • Use a remind date 1 minute in the future to allow iOS notifications when using Reminders.app

0.2.2

  • Allow title override with double quoted string at end of tag
  • Allow specification of an alternate Reminders.app list (--reminder-list LIST)
  • Remove list markers from captured line notes
  • Remove line number from file link

0.2.1

  • Add FoldingText extension
  • Handle multiple reminders per file

0.2.0

  • Reminders.app integration

Author

Brett Terpstra

Copyright (c) 2013 Brett Terpstra. Licensed under the MIT License:
http://www.opensource.org/licenses/mit-license.php

Speaking of nvremind…

Related Projects