Monday, December 13, 2010

List File Plugin for Vim

A while back, I had a post about managing lists in vim. Since then, I've found greater and greater use for the script and have invested more time into it. I've decided to put it on vim.org.

I'm going to reproduce the documentation in the plugin itself with the addition of some in-depth explanation.

Check this post often, as I will keep the documentation up-to-date with the latest features and tweaks.



The plugin helps me manage a plain-text file of nested lists. I use it to manage to-do lists, shopping lists, URLs---all in the same file. It manages priority, status, date, custom folding, among other things. It supports tagging, timestamping and searching with vim's quickfix list. Aside from the shortcuts and commands below, indentation and folding are managed by the standard vim mappings.


First Step

:Lcreate <name> - create new list file in current buffer with <name> (".list" is added automagically)


Creating Items

,n - create new item
<enter> - (insert or normal) create new item
,s - create sub item
<tab> - (insert or normal) create sub-item
,u - create super item


Marking Items

:Lmark <mark> - (normal or visual line) mark item(s) with <mark>
,p - mark item with '=' (in progress)
,x - mark item with 'x' (completed)
,o - mark item with 'o'
,? - mark item with '?'
,- - mark item with '-' (default, incomplete)
,N - set priority as N, where N is 1-5


Tagging Items

:Ltag <tag> [tag ...] - (normal or visual line) add tag(s) to line(s) (has auto complete)
:Ltagr <tag> [tag ...] - (normal or visual line) remove tag(s) from line(s) (has auto complete)


Searching For Items

:Lsearch mark <mark> - find all items with <mark> (e.g.: =, 1, -, etc.) using location list
tag <tag> - find all items with <tag> using location list
due [date] - find all items due on [date]. Today is the default.


Setting Due Dates

:Ldue [date] - (normal or visual line) set due date. Today is the default.
:Lduer - (normal or visual line) remove due date
Due dates are in the format YY-MM-DD or any of: yesterday, today, tomorrow,
N day[s], N week[s] (where N is a number)
N:M day[s], N:M week[s] (where N and M are numbers and N <= M)
E.g.: To see all items due this week or next week: :Lsearch due 0:1 week
To see all items due next week: :Lsearch due 1:1 week
To see all items due last, this, or next weeks: :Lsearch due -1:1 week
To see all items due tomorrow or the next day: :Lsearch due 1:2 day
To make an item due end of next week: :Ldue 1:1 week
To make an item due one week from today: :Ldue 1 week
To see all items due in exactly four days: :Lsearch due 4 days


Sorting Items

,r - (visual line) sort highlighted items
,r - (normal) sort entire file


Et Cetera

,t - add/update last-modified timestamp on item


Configuration

listFile_timestamp = 0
Should timestamps be added to each item by default? Set to 1 to show a timestamp by default.

listFile_indent = 4
Standard indent for nesting.

listFile_ranks = ['=','1','2','3','4','5','o','-','?','x']
Rank of marks for sorting. Note that your own, custom marks can be added to this list and used with the :Lmark command above.

listFile_mark = '-'
Default mark for new items.

listFile_dateFormat = '%y-%m-%d'
Default format for due dates.



Advanced Configuration

Here's an example of something you may put in your .vimrc file:

" add new "!" mark to ranking
let g:listFile_ranks = ['=','1','2','3','4','5','!','o','-','?','x']

" open local projects list file
nmap <Leader>l :60vsplit ~/projects.list

" add my mappings when a list file is loaded
autocmd BufNewFile,BufRead *.list call MyListFileStuff()
fun! MyListFileStuff()
" add "!" mark for normal and visual modes
nmap <buffer> ,! :Lmark !<CR>
vmap <buffer> ,! :Lmark !<CR>

" tag lines with "quick" tag
nmap <buffer> ,tq :Ltag quick<CR>
vmap <buffer> ,tq :Ltag quick<CR>

" find all lines tagged as "quick"
nmap <buffer> ,sq :Lsearch tag quick<CR>

" set an item as due today
nmap <buffer> ,dt :Ldue today

" find all items due this week
nmap <buffer> ,sw :Lsearch due 0:0 weeks
endfunction

In this example, I've added a new mark for me to use: "!". I've also added it to the mark ranks so that sorting will put "!" items in their proper order. I created a shortcut ("\l") to open my projects.list file in a narrow sidebar in vim. I added some things to help me manage items that are quick tasks---a mapping to easily tag items as "quick" and another to search for them. I also added a way to set a due date of today and to find all items due this week.


If you'd like this simple tool in your belt, go get it.