The user may need the help to solve any fatal error that appears while todo.sh isn't properly set up. As the help actions do not depend on any setting that the fatal errors check, we can still invoke them.
Factor out dieWithHelp() and use that for printing the fatal errors.
POSIX sed doesn't support regex branches; I don't want to switch to modern regexp (via -E), since that makes more characters special. Rather, expand the alternatives into two sed commands.
Usually (i.e. when a pager is available), the help() output is piped through the pager, and then the return code will be the one of the pager. So the exit 1 at the end of help() doesn't make much sense, and should be abolished for consistency.
Currently, the only way to get usage help for a custom action is to use "todo.sh help" and scroll / search for the action name. (Or try to call the action without / with invalid parameters to hopefully get a one-line syntax summary.)
This extends the help command to print the usage of optionally passed custom action names.
For ls / _list(), custom add-ons can use post_filter_command for additional filtering before the highlighting is applied. Let's allow that for listall and listpri, too, although they employ post_filter_command themselves.
The todo_completion had the problem that it didn't consider the todo.cfg itself for the location of TODO_ACTIONS_DIR, it just tried the default location or a globally exported config value. With the injection of custom configuration now in place, we can actually delegate the listing to todo.sh itself.
The added built-in "listaddons" command is used for that; it may also be helpful for troubleshooting or to find out about available add-ons. (But the help / shorthelp commands offer more information.)
Additionally, completion is now more precise; only executable actions and no subdirs are listed now; this is also covered by the enhanced test.
The last bonus: The custom add-on actions are now only determined when there's actually completion of commands.
Extract a new function _format() (and getPadding(), both also exported for add-ons) from _list(), which includes the main formatting and filtering pipeline, without the file handling and verbose summary. This can receive the todo file via stdin, so the listall action is able to format the concatenated files without going through a temporary file.
Eventually, after further refactorings, _format() could be used for actual formatted verbose messages in all commands; currently, the raw, unformatted task is printed.
After the recent refactorings, the temporary file is only needed for the listall action. Therefore, the creation-checks and eventual cleanup can be restricted to the listall action, which should slightly speed up the overall script execution.
So far, the listpri action only supports a single priority. Allowing priority ranges (e.g. todo.sh listpri A-C @work) is a simple but useful enhancement.
Note: The syntax extension only clashes with the [TERM] filtering in a few corner cases, and this can be worked around (e.g. "todo.sh listpri A-Z A-Z" lists all prioritized tasks containing the text A-Z).
No need to spawn off another process for this; we can do this inside the sed command that joins the task numbers with the task text.
Note: The sed on OS X does not understand the \+ bound, only in the form of + when used with -E. Instead, I chose to fall back to the \{1,\} basic regexp, in the hope that it is very portable, and to avoid introducing extended regexps to the script.
The sed command of BSD / OS X doesn't like { command } blocks in a single expression. So move the (dynamic) deduplicate sed command(s) to the end, and use a label to access them. This also makes the entire sed script somewhat easier to understand.
When the last reported values are identical to the current values, do not append the same information (just with a new timestamp) to the report. Instead, just print the last report line.
With this, the report action can be scheduled periodically (e.g. via cron) without artificially inflating the report file.
This was meant to write a report header on the initial report run, but as it mistakenly used TODO_FILE instead of REPORT_FILE, it was inactive, and also missing in the tests. Let's just remove it; the format is simple, anyway.
The report action should delegate to archive; it previously (half) did this via duplicated code (and forgot to defragment empty lines, so the tally could be off, and kept silent about the archiving).
The do action directly invoked archive(); if the user had extended / modified the archive action via an eponymous custom action, it would not run. Therefore, always invoke archive through another call of todo.sh, so that a possible custom action is considered.
As per discussion on the mailing list (http://tech.groups.yahoo.com/group/todotxt/message/3775), the automatic deduplication during archiving is unexpected and difficult to enforce in other implementations. Rather, make this a separate (optional) action.
* 'Quotes optional.' doesn't make sense for 'addm', because without quotes, 'addm' is 'add'.
* There are no projects that don't start with a +.
* Don't tell people to type uppercase when the software takes care of it.
* Mention actions, mention filtering *out* terms.
* Fix link to wiki in the README
Closes#60
Add-ons or users may want to hide parts of the task text from the output.
Though this can already be solved through TODOTXT_FINAL_FILTER, augmenting the configured value is not trivial, and it introduces another SED command into the already long _list() pipeline. Putting an additional HIDE_CUSTOM_SUBSTITUTION into the existing pipeline has hardly any performance implications, and makes the realization of this use case trivial.
This error only occurs when add-ons override either HIDE_PROJECTS_SUBSTITUTION or HIDE_CONTEXTS_SUBSTITUTION with a pattern that contains whitespace, not with the values used within todo.sh. But correcting the sloppy quoting doesn't hurt, neither.
The regexp syntax and quoting rules aren't known to many who are not well versed in the Bash shell, and difficult to get right even for people in the know. This question came up just recently on the mailing list, too.
The simplistic "listall" action implementation just uses _list() on the concatenation of active and done task lists. This has the following shortcomings:
- Task numbers shown for archived tasks from done.txt are invalid.
- As the number of done tasks likely greatly outnumbers the number of active tasks, the task number padding is often larger than expected (e.g. 0005 instead of 05).
- Verbose output lists all tasks as originating from TODO, whereas it should differentiate between TODO: and DONE: sources.
The main challenge is to keep processing all tasks through a single pass of _list(), so that there is a single, unified sorting applied to all tasks. A custom AWK script sets all (originally invalid) task numbers from done.txt to "0", meaning "archived task".
The verbose message from _list() is replaced with a custom message that shows the tasks from todo.txt, done.txt, and totals.
Oh, and added tests for the previously untested "listall" action.
I think that the error on the "move dest src" action should be given like "SRC: No task 42" instead of "TODO: No task 42 in /path/to/src.txt", to be consistent with the addto and listfile actions. Extracted and exposed getPrefix(), again to remove a bit of duplication, and because this can be useful in custom add-ons, too.
The retrieval of a task text for $item and associated error handling so far was scattered around the individual actions. This is now consolidated in two new utility functions, which directly set $todo or $newtodo, respectively. (Inconsistent variable names like $NEWTODO have been adapted.) This ensures that all actions perform the same error checking, reduces a bit of duplication, and allows custom add-ons to benefit from these exported functions. Ah, and the error messages for the "move" action is now more in line with the other errors; unfortunately, this isn't yet covered by a test.
Note that the check whether $item is numeric must not use the +([0-9]) extglob any more, as such functions cannot be exported; a new Bash doesn't have the "shopt -s extglob" and complains with a syntax error. Fortunately, it is possible to perform the same check via standard Bash mechanisms.
