npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

taskparser

v1.0.0-beta.6

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

607

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

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.