taskparser
v1.0.0-beta.9
Published
A CLI tool to parse tasks and worklogs out of Markdown documents and print them to standard output, either in tabular of CSV format. Supports tag-based sorting and filtering operating on both inline tags and frontmatter metadata.
Downloads
171
Maintainers
Readme
taskparser
A CLI tool to parse tasks and worklogs out of Markdown documents and print them to standard output in the format of a Markdown table, CSV or JSON. Supports sorting and filtering based on metadata encoded in tags, inline and/or as YAML frontmatter.
Introduction
See the post on the rationale behind taskparser on my blog.
Status
taskparser
is currently in beta. Feedback from others would be invaluable to
further shape its evolution. I consider it a bootstrapped task management app
in that I use taskparser
to manage taskparser
's own development.
Example
Given directory /foo/bar
with a 20241010-baz.md
file having the following
contents:
## Todos
- [ ] a pending task
- [X] a completed task
taskparser
will output the following:
$ taskparser /foo/bar
text | done | file | date
--- | --- | --- | ---
a pending task | false | 20241010-baz.md | 20241010
a completed task | true | 20241010-baz.md | 20241010
Install
npm i -g taskparser
Usage
$ taskparser -h
usage: taskparser [-h] [-t TAGS] [-f FILTER] [-s SORT] [-w] [-l] [-C] [-U] [-o {table,csv,json}] [-c COLUMNS] [-v] path
A CLI tool to parse, sort and filter tasks and worklogs out of Markdown documents and print them to standard output, either in tabular of CSV format.
positional arguments:
path working directory
optional arguments:
-h, --help show this help message and exit
-t TAGS, --tags TAGS comma-separated list of tags to show
-f FILTER, --filter FILTER
filtering expression such as: foo(=bar)
-s SORT, --sort SORT sorting expression such as: foo(asc)
-w, --watch enable watch mode
-l, --worklogs enable worklogs mode
-C, --checked only show checked tasks
-U, --unchecked only show unchecked tasks
-o {table,csv,json}, --out {table,csv,json}
set output format
-c COLUMNS, --columns COLUMNS
override detected terminal width (in character columns)
-v, --version show program's version number and exit
Tags
taskparser
uses the concept of tag as the unit of information that
describes tasks and worklogs.
Choosing which tags to show
The -t
flag may be used to change which tags are displayed:
$ taskparser -t text,project,client,file,date /foo/bar
Autogenerated tags
When parsing tasks, taskparser
auto-generates the following tags:
| tag | description | internal |
| --- | --- | --- |
| text
| the textual content of the task (first line only) | yes |
| file
| the file that contains the task | yes |
| date
| the date of creation of the task | no |
| checked
| whether the task is checked as done | yes |
Auto-genereated tags considered internal cannot be overridden via YAML frontmatter or inline tags.
When rendering to a Markdown table (i.e. the default output format table
),
the checked
tag is shortened to c
and rendered with a tick mark for
compactness.
Inline tags
Tasks may be tagged inline:
- [ ] a pending task #project(foo) #client(bar)
- [X] a completed task
$ taskparser -t text,project,client,file,date /foo/bar
text | project | client | file | date
--- | --- | --- | --- | ---
a pending task #project(foo) #client(bar) | foo | bar | 20241010-foo.md | 20241010
a completed task | | | 20241010-foo.md | 20241010
Tags may also be added after a line break (three consecutive spaces) so that
they are not counted as part of the autogenerated text
tag:
- [ ] a pending task
#project(foo) #client(bar)
- [X] a completed task
$ taskparser -t text,project,client,file,date /foo/bar
text | project | client | file | date
--- | --- | --- | --- | ---
a pending task | foo | bar | 20241010-foo.md | 20241010
a completed task | | | 20241010-foo.md | 20241010
Frontmatter tags
Tags will also be inherited from any YAML front-matter:
---
project: foo
client: bar
---
- [ ] a pending task
- [X] a completed task
taskparser
will produce:
$ taskparser -t text,project,client,file,date /foo/bar
text | project | client | file | date
--- | --- | --- | --- | ---
a pending task | foo | bar | 20241010-foo.md | 20241010
a completed task | foo | bar | 20241010-foo.md | 20241010
Metadata file tags
Tags will also be inherited from any per-folder .taskparser.yaml
files
present in the folder hierarchy leading to a markdown file:
Tags must be expressed through a simple, root-level tags
dictionary:
tags:
project: foo
client: bar
Filtering by tag
taskparser
accepts filter expression via the -f
argument:
$ taskparser -f "client(=foo)" /foo/bar
Filtering syntax is as follows:
foo(isnull) matches tasks without tag "foo"
foo(notnull) matches tasks with tag "foo"
foo(=bar) matches tasks with tag "foo" set to "bar"
foo(!=bar) matches tasks with tag "foo" set to anything other than "bar"
foo(^=bar) matches tasks with tag "foo" starting with "bar"
foo($=bar) matches tasks with tag "foo" ending with "bar"
foo(*=bar*) matches tasks with tag "foo" matching the pattern "bar*"
Additionally, the following operators may be used to filter tasks based on the lexicographical ordering of tag values:
foo(>=bar) matches tasks with tag "foo" greater than or equal to "bar"
foo(<=bar) matches tasks with tag "foo" lower than or equal to "bar"
foo(>bar) matches tasks with tag "foo" greater than "bar"
foo(<bar) matches tasks with tag "foo" lower than "bar"
Filtering expressions can be combined:
foo(=bar),foo(!=baz)
Filtering by checked state
While filtering tasks by their checked state requires comparing against
"true"
and "false"
, the -U, --unchecked
and -C, --checked
CLI
arguments make for easy-to-remember shortcuts:
$ taskparser -f "checked(=false),project(=baz)" /foo/bar
$ taskparser -f "checked(=true),project(=baz)" /foo/bar
are equivalent to, respectively:
$ taskparser -U -f "project(=baz)" /foo/bar
$ taskparser -C -f "project(=baz)" /foo/bar
Sorting by tag
taskparser
accepts sorting expressions via the -s
argument:
$ taskparser -s "client(asc)" /foo/bar
Sorting syntax is as follows:
foo(asc) sorts tasks by the "foo" tag in ascending lexicographical order
foo(desc) sorts tasks by the "foo" tag in descending lexicographical order
Sorting expressions can be combined for nested sorting:
foo(asc),bar(desc)
Worklogs
In addition to tasks, taskparser
can also collect and display worklogs.
A worklog is a list item detailing a given amount of hours spent working.
- WL:3h this is a simple worklog
Worklogs can be tagged, filtered and sorted exactly as tasks. For each worklog
it encounters, taskparser
automatically generates the following tags:
| tag | description | internal |
| --- | --- | --- |
| text
| the textual content of the task (first line only) | yes |
| file
| the file that contains the task | yes |
| date
| the date of creation of the task | no |
| hours
| amount of hours logged | yes |
The -l
or --worklogs
flag may be used to enable worklog mode:
taskparser -l -t text,hours,file,date"
When rendering to a Markdown table (i.e. the default output format), the
hours
tag is shortened to h
for compactness.
License
Released under the LGPL v3.0 (LGPL-3.0-only
) license.
See LICENSE.md.