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] --describe[=FORMAT] use FORMAT for descriptions -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. For «--describe» 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 %d :: description of the record %f :: name of file, in which record was found %l :: number of line in source file 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»). 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. 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.