Adding more comrehensive documentaition regaring issue types and properties.

pit.nimble

@@ -1,6 +1,6 @@
 # Package
 
-version       = "4.13.0"
+version       = "4.14.0"
 author        = "Jonathan Bernard"
 description   = "Personal issue tracker."
 license       = "MIT"

src/pit.nim

@@ -196,22 +196,23 @@ proc edit(issue: Issue) =
       getCurrentExceptionMsg()
     issue.store()
 
-proc list(ctx: CliContext, filter: Option[IssueFilter], state: Option[IssueState], showToday, showFuture, verbose: bool) =
+proc list(ctx: CliContext, filter: Option[IssueFilter], states: Option[seq[IssueState]], showToday, showFuture, verbose: bool) =
 
-  if state.isSome:
+  if states.isSome:
-    ctx.loadIssues(state.get)
+    for state in states.get:
-    if filter.isSome: ctx.filterIssues(filter.get)
+      ctx.loadIssues(state)
-    if state.get == Done and showToday:
+      if filter.isSome: ctx.filterIssues(filter.get)
-      ctx.issues[Done] = ctx.issues[Done].filterIt(
+      if state == Done and showToday:
-        it.hasProp("completed") and
+        ctx.issues[Done] = ctx.issues[Done].filterIt(
-        sameDay(getTime().local, it.getDateTime("completed")))
+          it.hasProp("completed") and
-    stdout.write ctx.formatSection(ctx.issues[state.get], state.get, "", verbose)
+          sameDay(getTime().local, it.getDateTime("completed")))
+      stdout.write ctx.formatSection(ctx.issues[state], state, "", verbose)
     return
 
   ctx.loadAllIssues()
   if filter.isSome: ctx.filterIssues(filter.get)
 
-  let today = showToday and [Current, TodoToday].anyIt(
+  let today = showToday and [Current, TodoToday, Pending].anyIt(
     ctx.issues.hasKey(it) and ctx.issues[it].len > 0)
 
   let future = showFuture and [Pending, Todo].anyIt(
@@ -223,7 +224,7 @@ proc list(ctx: CliContext, filter: Option[IssueFilter], state: Option[IssueState
   if today:
     if future: ctx.writeHeader("Today")
 
-    for s in [Current, TodoToday]:
+    for s in [Current, TodoToday, Pending]:
       if ctx.issues.hasKey(s) and ctx.issues[s].len > 0:
         stdout.write ctx.formatSection(ctx.issues[s], s, indent, verbose)
 
@@ -242,11 +243,11 @@ proc list(ctx: CliContext, filter: Option[IssueFilter], state: Option[IssueState
 when isMainModule:
 
  try:
-  let doc = """
+  let usage = """
 Usage:
   pit ( new | add) <summary> [<state>] [options]
   pit list contexts [options]
-  pit list [<stateOrId>] [options]
+  pit list [<stateOrId>...] [options]
   pit ( start | done | pending | todo-today | todo | suspend ) <id>... [options]
   pit edit <ref>... [options]
   pit tag <id>... [options]
@@ -260,7 +261,7 @@ Usage:
 
 Options:
 
-  -h, --help                Print this usage information.
+  -h, --help                Print this usage and help information.
 
   -p, --properties <props>  Specify properties. Formatted as "key:val;key:val"
                             When used with the list command this option applies
@@ -297,17 +298,84 @@ Options:
   --term-width <width>      Manually set the terminal width to use.
 
   --ptk                     Enable PTK integration for this command.
+
+"""
+
+  let onlineHelp = """
+Issue States
+
+  PIT organizes issues around their state, which is one of:
+
+    current     - issues actively being worked
+    todo-today  - issues planned for today
+    pending     - issues that are blocked by some third-party
+    done        - issues that have been completely resolved
+    todo        - issues that need to be done in the future
+    dormant     - issues that are low-priority, to be tracked, but hidden
+                  by default
+
+Issue Properties
+
+  PIT supports adding arbitrary properties to any issue to track any metadata
+  about the issue the user may wish. There are several properties that have
+  special behavior attached to them. They are:
+
+    created
+
+      If present, expected to be an ISO 8601-formatted date that represents the
+      time when the issue was created.
+
+    completed
+
+      If present, expected to be an ISO 8601-formatted date that represents the
+      time when the issue moved to the "done" state.  PIT will add this
+      property automatically when you use the "done" command, and can filter on
+      this value.
+
+    context
+
+      Allows issues to be organized into contexts. The -c option is short-hand
+      for '-p context:<context-name>' and the 'list contexts' command will show
+      all values of 'context' set in existing issues.
+
+    delegated-to
+
+      When an issue now belongs to someone else, but needs to be monitored for
+      completion, this allows you to keep the issue in its current state but
+      note how it has been delegated. When present PIT will prepend this value
+      to the issue summary with an accent color.
+
+    hide-until
+
+      When present, expected to be an ISO 8601-formatted date and used to
+      supress the display of the issue until on or after the given date.
+
+    pending
+
+      When an issue is blocked by a third party, this property can be used to
+      capture details about the dependency When present PIT will display this
+      value after the issue summary.
+
+    recurrence
+
+      TODO, not yet implemented.
+
+    tags
+
+      If present, expected to be a comma-delimited list of text tags. The -g
+      option is a short-hand for '-p tags:<tags-value>'.
 """
 
   logging.addHandler(newConsoleLogger())
 
   # Parse arguments
-  let args = docopt(doc, version = PIT_VERSION)
+  let args = docopt(usage, version = PIT_VERSION)
 
   if args["--echo-args"]: stderr.writeLine($args)
 
   if args["--help"]:
-    stderr.writeLine(doc)
+    stderr.writeLine(usage)
+    stderr.writeLine(onlineHelp)
     quit()
 
   let ctx = initContext(args)
@@ -490,13 +558,13 @@ Options:
       filter.properties.del("context")
 
     var listContexts = false
-    var stateOption = none(IssueState)
+    var statesOption = none(seq[IssueState])
-    var issueIdOption = none(string)
+    var issueIdsOption = none(seq[string])
 
     if args["contexts"]: listContexts = true
     elif args["<stateOrId>"]:
-      try: stateOption = some(parseEnum[IssueState]($args["<stateOrId>"]))
+      try: statesOption = some(args["<stateOrId>"].mapIt(parseEnum[IssueState]($it)))
-      except: issueIdOption = some($args["<stateOrId>"])
+      except: issueIdsOption = some(args["<stateOrId>"].mapIt($it))
 
     # List the known contexts
     if listContexts:
@@ -516,14 +584,15 @@ Options:
         stdout.writeLine(c.alignLeft(maxLen+2) & ctx.getIssueContextDisplayName(c))
 
     # List a specific issue
-    elif issueIdOption.isSome:
+    elif issueIdsOption.isSome:
-      let issue = ctx.tasksDir.loadIssueById(issueIdOption.get)
+      for issueId in issueIdsOption.get:
-      stdout.writeLine ctx.formatIssue(issue)
+        let issue = ctx.tasksDir.loadIssueById(issueId)
+        stdout.writeLine ctx.formatIssue(issue)
 
     # List all issues
     else:
       let showBoth = args["--today"] == args["--future"]
-      ctx.list(filterOption, stateOption, showBoth or args["--today"],
+      ctx.list(filterOption, statesOption, showBoth or args["--today"],
                                           showBoth or args["--future"],
                                           ctx.verbose)
 

src/pitpkg/version.nim

@@ -1 +1 @@
-const PIT_VERSION* = "4.13.0"
+const PIT_VERSION* = "4.15.0"