Adding more comrehensive documentaition regaring issue types and properties.

pit.nimble

@@ -1,6 +1,6 @@
 # Package
 
-version       = "4.11.1"
+version       = "4.14.0"
 author        = "Jonathan Bernard"
 description   = "Personal issue tracker."
 license       = "MIT"
@@ -15,10 +15,11 @@ requires @[
   "jester 0.5.0",
   "uuids 0.1.10",
 
-  "https://git.jdb-labs.com/jdb/nim-cli-utils.git >= 0.6.4",
+  "https://git.jdb-software.com/jdb/nim-cli-utils.git >= 0.6.4",
-  "https://git.jdb-labs.com/jdb/nim-lang-utils.git >= 0.4.0",
+  "https://git.jdb-software.com/jdb/nim-lang-utils.git >= 0.4.0",
-  "https://git.jdb-labs.com/jdb/nim-time-utils.git >= 0.4.0",
+  "https://git.jdb-software.com/jdb/nim-time-utils.git >= 0.4.0",
-  "https://git.jdb-labs.com/jdb/update-nim-package-version"
+  "https://git.jdb-software.com/jdb/nim-data-uri.git >= 1.0.0",
+  "https://git.jdb-software.com/jdb/update-nim-package-version"
 ]
 
 task updateVersion, "Update the version of this package.":

src/pit.nim

@@ -1,8 +1,8 @@
 ## Personal Issue Tracker CLI interface
 ## ====================================
 
-import algorithm, cliutils, docopt, json, logging, options, os, sequtils,
+import algorithm, cliutils, data_uri, docopt, json, logging, options, os,
-  std/wordwrap, tables, terminal, times, timeutils, unicode, uuids
+  sequtils, std/wordwrap, tables, terminal, times, timeutils, unicode, uuids
 
 from nre import re
 import strutils except alignLeft, capitalize, strip, toUpper, toLower
@@ -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:
+      ctx.loadIssues(state)
       if filter.isSome: ctx.filterIssues(filter.get)
-    if state.get == Done and showToday:
+      if state == Done and showToday:
         ctx.issues[Done] = ctx.issues[Done].filterIt(
           it.hasProp("completed") and
           sameDay(getTime().local, it.getDateTime("completed")))
-    stdout.write ctx.formatSection(ctx.issues[state.get], state.get, "", verbose)
+      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)
 
@@ -233,27 +234,34 @@ proc list(ctx: CliContext, filter: Option[IssueFilter], state: Option[IssueState
 
     for s in [Pending, Todo]:
       if ctx.issues.hasKey(s) and ctx.issues[s].len > 0:
-        stdout.write ctx.formatSection(ctx.issues[s], s, indent, verbose)
+        let visibleIssues = ctx.issues[s].filterIt(
+          not (it.hasProp("hide-until") and
+               it.getDateTime("hide-until") > getTime().local))
+
+        stdout.write ctx.formatSection(visibleIssues, s, indent, verbose)
 
 when isMainModule:
 
  try:
-  let doc = """
+  let usage = """
 Usage:
   pit ( new | add) <summary> [<state>] [options]
-  pit list contexts
+  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>...
+  pit edit <ref>... [options]
   pit tag <id>... [options]
   pit untag <id>... [options]
-  pit reorder <state>
+  pit reorder <state> [options]
   pit delegate <id> <delegated-to>
-  pit ( delete | rm ) <id>...
+  pit hide-until <id> <date> [options]
+  pit ( delete | rm ) <id>... [options]
+  pit add-binary-property <id> <propName> <propSource> [options]
+  pit get-binary-property <id> <propName> <propDest> [options]
 
 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
@@ -290,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)
@@ -421,6 +496,13 @@ Options:
       elif targetState == Done or targetState == Pending:
         discard execShellCmd("ptk stop")
 
+  elif args["hide-until"]:
+
+    let issue = ctx.tasksDir.loadIssueById($(args["<id>"]))
+    issue.setDateTime("hide-until", parseDate($args["<date>"]))
+
+    issue.store()
+
   elif args["delegate"]:
 
     let issue = ctx.tasksDir.loadIssueById($(args["<id>"]))
@@ -476,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:
@@ -502,17 +584,45 @@ 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:
+        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)
 
+  elif args["add-binary-property"]:
+    let issue = ctx.tasksDir.loadIssueById($(args["<id>"]))
+
+    let propIn =
+      if $(args["<propSource>"]) == "-": stdin
+      else: open($(args["<propSource>"]))
+
+    try: issue[$(args["<propName>"])] = encodeAsDataUri(readAll(propIn))
+    finally: close(propIn)
+
+    issue.store()
+
+  elif args["get-binary-property"]:
+    let issue = ctx.tasksDir.loadIssueById($(args["<id>"]))
+
+    if not issue.hasProp($(args["<propName>"])):
+      raise newException(Exception,
+        "issue " & ($issue.id)[0..<6] & " has no property name '" &
+        $(args["<propName>"]) & "'")
+
+    let propOut =
+      if $(args["<propDest>"]) == "-": stdout
+      else: open($(args["<propDest>"]), fmWrite)
+
+    try: write(propOut, decodeDataUri(issue[$(args["<propName>"])]))
+    finally: close(propOut)
+
  except:
   fatal "pit: " & getCurrentExceptionMsg()
   #raise getCurrentException()

src/pit_api.nim

@@ -20,7 +20,7 @@ proc raiseEx(reason: string): void = raise newException(Exception, reason)
 
 template halt(code: HttpCode,
               headers: RawHeaders,
-              content: string): typed =
+              content: string): void =
   ## Immediately replies with the specified request. This means any further
   ## code will not be executed after calling this template in the current
   ## route.

src/pitpkg/private/libpit.nim

@@ -105,6 +105,23 @@ proc groupBy*(issues: seq[Issue], propertyKey: string): TableRef[string, seq[Iss
     result[key].add(i)
 
 
+## Parse and format dates
+const DATE_FORMATS = [
+  "MM/dd",
+  "MM-dd",
+  "yyyy-MM-dd",
+  "yyyy/MM/dd",
+  "yyyy-MM-dd'T'hh:mm:ss"
+]
+proc parseDate*(d: string): DateTime =
+  var errMsg = ""
+  for df in DATE_FORMATS:
+    try: return d.parse(df)
+    except:
+      errMsg &= "\n\tTried " & df & " with " & d
+      continue
+  raise newException(ValueError, "Unable to parse input as a date: " & d & errMsg)
+
 ## Parse and format issues
 proc fromStorageFormat*(id: string, issueTxt: string): Issue =
   type ParseState = enum ReadingSummary, ReadingProps, ReadingDetails

src/pitpkg/version.nim

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