todos

todos README
============
Ilya V. Portnov <portnov84@rambler.ru>

todos is a simple TODO manager. TODO records theirself are described in
plain-text file, and todos allows you to show only needed of them. So, todos
works as specialized `grep' utility.

By default, output format is the same as input; so, you can combine several
`todos' instances into unix pipes.

If source files are not given in the commandline, file with name "TODO" in
current directory is used. If "-" is given as file name, todos will read
standart input.

todos supports two formats of input files. In first case, file contains TODOS
records and only them. In «alternative» format, source files can contain any
text, but it's ignored; only lines starting with given prefix ("TODO: " by
default) are parsed. So, alternative format enable you to grep TODO records
from any files, for example, program source files.

Following is format of TODO record:

[spaces]status (dates) [TAGS] title (depends) description

Here [spaces] is optional indent with spaces, «status» — is status of record
(for example, URGENT or DONE; can be any word), «dates» give info about dates
(see below), «TAGS» is a comma-separated list of tags in brackets, «title» is
title of record, «depends» — comma-separated list of depends (titles of other
records) in parenthesis, «description» is description of the record. All fields
except status and title are optional. If «-w» option is specified, status field
is not read (it's optional; when it's present, it will be part of title).
Description is separated from title with not less than 2 spaces.

Using different indents one can create sub-records (and, so, trees of records).
Moreover, depends are interpreted in same way as sub-records. So, one can
create not only trees of records, but arbitrary graphs of records (even
cycled). When cycled graphs are used, user should control for rational level of
hierarchy (for example, one can bound height of output tree using -p option).

Dates information is described in parenthesis, as not more than 3 records,
separated with semicolon. Each records has format «date type: date». Date type
can be one of: start, end, deadline. For dates, many formats are supported; for
example, «18 Feb», or «02/18/2010», «2010/02/18» are all valid dates. One can
even use relative dates specification here, such as «in 2 weeks» or «2 days
ago», but there is no point to this: all dates are counted from program start
date.

Next commandline options are supported:

-1 --only-first show only first matching entry
-c --color show colored output
-H --highlight instead of filtering TODOs, just highlight matching the query
-I --show-ids show IDs of todos
-A[PREFIX] --prefix[=PREFIX] use alternate parser: read only lines starting with PREFIX
--dot output entries in DOT (graphviz) format
-D FORMAT --format=FORMAT use FORMAT to format items
-k[STRING] --indent-with[=STRING] use STRING instead of two spaces for items indentation
-w --no-status do not read status field from TODOs
--set-status=STRING force all TODOs status to be equal to STRING
--set-root-status=STRING force statuses of root TODOs to be equal to STRING
-F --by-file group TODOs by source file
-T --by-tag group TODOs by tag
-Z --by-status group TODOs by status
-p N --prune=N limit tree height to N
-m N --min-depth=N show first N levels of tree unconditionally
-t TAG --tag=TAG find items marked with TAG
-g PATTERN --grep=PATTERN find items with PATTERN in name
-G PATTERN --description=PATTERN find items with PATTERN in description
-s STRING --status=STRING find items with status equal to STRING
-i STRING --id=STRING find items with ID equal to STRING
-a --and logical AND
-o --or logical OR
-n --not logical NOT
--sort=FIELD specify sorting
-e[COMMAND] --exec[=COMMAND] run COMMAND on each matching entry
-S DATE --start-date=DATE find items with start date bounded with DATE
-E DATE --end-date=DATE find items with end date bounded with DATE
-d DATE --deadline=DATE find items with deadline bounded with DATE
-h --help display this help

Dates in the commandline are specified in any of supported formats. There
relative dates specifications are useful: how about something like «todos
--deadline=yesterday»? ;)

When «-H» option is specified, items are not filtered at all (all items will be
printed). Instead, items matching to your query will be highlighted. This works
only with «-c» option.

When «-I» option is specified, for each TODO it's unique identifier is shown.
That ID is simply hash from item's title, status, tags and description, so
only identical items will have identical ID. One can ask todos to show item
with specified ID using «-i» option.

With «-k» option one can specify another indentation string instead of default
two spaces. For example, `todos -k"| "` will print vertical lines between items
of same level. «-k» option without argument will force todos to not use
indentation at all.

For «--format» and «--exec» options, printf-style format strings should be
specified. Following substitution sequences are supported:

%n :: title of the record
%t :: list of record's tags
%s :: status of the record
%p :: prefix before record in source file
%d :: description of the record
%f :: name of file, in which record was found
%l :: number of line in source file
%D :: dates of item

Backslash-escaping is supported too. Supported sequences are: `\t \n \v \b`.

For example, «todos -tBUG -e"vi %f +%l"» command for each record with «BUG» tag
will open vi with corresponding file on corresponding line.

When «--dot» option is specified, todos will output a graph definition for DOT
(graphviz), instead of normal output. For example, you can try

todos --dot | dot -Tpng -o todos.png

and then see the file todos.png. Items with status «GROUP» will become DOT's
clusters. More precisely, if one item have «GROUP» status, it will become a
cluster, and all it's children will be inside that cluster. There is a
limitation in DOT: it can not draw graphs where one item is in several clusters
properly, it will draw such item only in one cluster.

todos can read configuration files: `~/.config/todos/todos.conf` («global») and
`./.todos.conf` («local»). Also, if there is not `./.todos.conf`, todos looks
for file named `.todos.conf` in all ancestor directories. For example, if
current directory is `/home/user/work/projects`, these files are checked:

* `/home/user/work/projects/.todos.conf`
* `/home/user/work/.todos.conf`
* `/home/user/.todos.conf`
* `/home/.todos.conf`
* `/.todos.conf`

If one of these files is found, todos checks if it starts with «%» (single
percent character) word. If so, options from «ancestor» config file are
prepended to options from this file. Otherwise, ancestor config is not read.

Config files contain command line options, in the same format as in the
commandline. Resulting commandline is composed as: (options in global config)
+ (options in local config) + (options in the actual command line). If there is
no one of configs, todos will ignore it.

For example, if `/home/user/work/projects/.todos.conf` file contents is `% --dot`,
and `/home/user/work/.todos.conf` contains `-A -F`, «effective command line» would be
`-A -F --dot`.

Config files might be specified in the command line. `@path/to/file.conf`
option will force todos to read options from `path/to/file.conf`, and add them
to «effective command line» before other command line options.
`@@path/to/file.conf` is almost the same, but here todos will not read «global»
and «local» configs at all. Specifying only `@@` in the command line, one can
disable reading config files at all.

Moreover, todos could be customized in «xmonad way». You write file
`~/.config/todos/todos.hs` and run todos. todos will compile and run that file.
Simplest example of `todos.hs` possible is `todos.hs` in this directory. A bit
more complex example:

.................................................................
import System.Console.ANSI

import Todos

main :: IO ()
main = todos $ defaultConfig {
itemConsoleColor = myItemColor
}

myItemColor item =
if itemStatus item == ":"
then Just (Dull, Blue)
else Nothing
.................................................................

So, items with ":" status will be printed in blue color.