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 lentil
The executable is located in .cabal/bin/
; to make it available
everywhere add this line to your .bashrc
:
export PATH=$PATH:~/.cabal/bin
To 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 package
You 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 */
-- FIXME
You 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 parsed
User 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%js
but 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 urgent
As 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 urgent
Orphan (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 -R
This will allow you to browse the issues in a pager without losing ANSI colour formatting.