When I start a new project I litter my code with:
-- TODO: does outPop work with b/w terminals? [ansi]Dealing with these is easy at first (with some help from unix utilities), but it becomes more and more unwieldy as the project expands. Migrating takes time and effort and I like the convenience of having bug reports detailed near the offending functions.
lentil helps you with housekeeping, querying, exporting issues without having to modify a single line of code.
(If you don’t want to compile it yourself, these binaries are available: linux ◊ windows ◊ signed hashes.)
lentil is written in Haskell, which you can easily grab from your OS repository (e.g. for Debian users apt-get install haskell-platform). Once you do that, installing lentil is as easy as:
cabal update # this might take a few minutes!
cabal install lentilThe executable is located in .cabal/bin/; to make it available everywhere add this line to your .bashrc:
export PATH=$PATH:~/.cabal/binTo test lentil, fetch the example repository, unzip it, enter the folder and type:
lentil .This should output a basic list of issues:
alpha.hs
4 add prompt before getline, or the user might complain! [interface]
11 add a type signature to replace [lint]
subfolder/beta.hs
3 make export list explicit in Beta [lint]
5 I think constants should not be exposed here, but imported from
another packageYou can specify more than one folder/path with lentil foldera folderb ... or exclude folders/paths with lentil . -x foldera/sub.
lentil scans directory recursively, not following symlinks, hidden folders (.git, .cabal, etc.) or folders starting with an underscore (_). Current working directory is indicated by a single dot (.).
lentil parses basic TODO issues. The precise syntax is: keyword (one of todo, fixme, xxx), optional semicolon, followed by a space, followed by free-form text (text can be multiline). In so many words, it is quite liberal in what it accepts:
-- These will all be accepted
// TODO: explanatory issue
// todo ehy you left an assert out there!
//Fixme bad coding style
/* Xxx: add to version control.
Ask Timothy */
-- FIXMEYou can optionally put tags at the end or at the beginning of your issue, like this:
// FIXME: Mr. Burns should enter from the *right* side of the
// nuclear station [script] [priority:1]
-- todo: [rhyme] [magic] double trouble... I always forget the
-- words :s [memory]Tags are single words which are useful to catalogue and identify issues. Use them aplenty as they will make slicing and dicing your issue-base a breeze. Since the semantic of FIXME and XXX is specific (in respect to the usual TODO), they are automatically added as a tag.
You can specify custom flag-words too, by using the -w option, e.g.:
lentil . -w hack
// HACK this issue will be parsedUser provided flagwords will have a tag automaticaly added (like FIXME and XXX).
As now lentil parses:
.hs, .lhs, .chs, .hsc, .cabal).elm).purs).c, .h), C++ (.cpp, .hpp), Java (.java).js).ts).coffee).pas, .pp, .inc).py).rb).pl, .pm, .t).sh).nix).xml, .html).erl, .hrl, .escript) including YECC (.yrl) and LEEX (.xrl).ml, .mli).scala).rs, .rlib).sml).glsl).. ::todo directives (.rst).org), both TODO and list-like items.md).r, .R).fs, .fth, .4th).yaml, .yml).tex).txt)If you want a file type .xyz to be recognised as one in the list above, invoke lentil with an extension alias:
lentil . -a xyz%cpp
# multiple aliases
lentil . -a xyz%cpp -a qkw%jsbut please please please contact me to have the extension(s) included in lentil natively, as this will make the program more convenient to use (if you want to speed up the process, please include a description of the comment syntax and string/character syntax too).
You can filter the issues to be displayed:
-t EXPR filters by issue tag-p EXPR filters by issue filepath-d EXPR filters by descriptionwhere EXPR is a valid regular expression. Examples:
# lists all issues with tag containing the string "bug"
lentil . -t bug
# lists all issues in files which name contains the
# string "ACME" or "foo"
lentil . -p "(ACME|foo)"
# lists all issues with tag containing the string "bug" and
# with "urgent" in the description
lentil . -t bug -d urgentAs the last example highlight, if you use these options together, they will be chained using a boolean AND.
To negate an EXPR use the corresponding capitalised option flags -T, -P, -D:
# lists all issues *without* the word "urgent" in their description
lentil . -D urgentOrphan (tagless) issues are sometimes a nuisance, a handy way to list them is:
lentil . -T .The -f TYPE option modifies the output format, with pretty being the default.
-f csv exports issues to CSV (RFC 4180).
-f xml exports issues to XML.
-f tagpop, lists tags by their popularity (reverse order), useful to get a summary of open issues:
lentil . -x test/test-files/ -f tagpop
Tags popularity:
8 [feature:intermediate]
6 [test]
5 [feature:advanced]
3 [bug]
2 [refactor]
2 [lint]
2 [feature:basic]
1 [urgency:3]
1 [design]-f comp displays issues in a format similar to the one emitted by compilers (GCC, GHC, etc.):
alpha.hs:4:
add prompt before getline, or the user might complain! [interface]
alpha.hs:11:
add a type signature to replace [lint]This is useful because it is recognised by editors like Emacs, which can turn them into active links to the relevant file/position.
-f file exports a list of files where issues are present:
src/Lentil/Export.hs
src/Lentil/File.hs
src/Lentil/Parse/Run.hs
src/Lentil/Parse/Syntaxes.hs
src/Main.hs--output FILE is used to output the report to a file instead of stdout.
-v outputs the program version.
--help displays cheatsheet option help.
When output gets too big for a single screen, call lentil as:
lentil . | less -RThis will allow you to browse the issues in a pager without losing ANSI colour formatting.