Add start as an alias for add.

Something depends on isaac 0.1.0, but that version doesn't compile on Nim 0.16
and above. Until the transitive dependancy is updated, ask for at least 0.1.2.

private/ptkutil.nim

@@ -0,0 +1,8 @@
+template first*(a: openarray): auto = a[0]
+
+template last*(a: openarray): auto = a[len(a)-1]
+
+proc flatten*[T](a: seq[seq[T]]): seq[T] =
+  result = @[]
+  for subseq in a:
+    result.add(subseq)

ptk.nim

@@ -6,11 +6,14 @@
 import algorithm, docopt, json, langutils, logging, os, nre, sequtils,
   sets, strutils, tempfile, terminal, times, timeutils, uuids
 
-import ptkutil
+import private/ptkutil
 
 type
   Mark* = tuple[id: UUID, time: TimeInfo, summary: string, notes: string, tags: seq[string]]
+    ## Representation of a single mark on the timeline.
+
   Timeline* = tuple[name: string, marks: seq[Mark]]
+    ## Representation of a timeline: a name and sequence of Marks.
 
 const STOP_MSG = "STOP"
 
@@ -19,12 +22,16 @@ let NO_MARK: Mark = (
   time: fromSeconds(0).getLocalTime,
   summary: "", notes: "", tags: @[])
 
-const ISO_TIME_FORMAT = "yyyy:MM:dd'T'HH:mm:ss"
+const ISO_TIME_FORMAT = "yyyy-MM-dd'T'HH:mm:ss"
+  ## The canonical time format used by PTK.
 
 const TIME_FORMATS = @[
-    "H:mm", "HH:mm", "H:mm:ss", "HH:mm:ss",
+    "yyyy-MM-dd'T'HH:mm:ss", "yyyy-MM-dd HH:mm:ss",
-    "yyyy:MM:dd'T'HH:mm:ss", "yyyy:MM:dd'T'HH:mm",
+    "yyyy-MM-dd'T'HH:mm", "yyyy-MM-dd HH:mm",
-    "yyyy:MM:dd HH:mm:ss", "yyyy:MM:dd HH:mm"]
+    "MM-dd'T'HH:mm:ss", "MM-dd HH:mm:ss",
+    "MM-dd'T'HH:mm", "MM-dd HH:mm",
+    "HH:mm:ss", "H:mm:ss", "H:mm", "HH:mm" ]
+  ## Other time formats that PTK will accept as input.
 
 #proc `$`*(mark: Mark): string =
   #return (($mark.uuid)[
@@ -34,6 +41,7 @@ proc exitErr(msg: string): void =
   quit(QuitFailure)
 
 proc parseTime(timeStr: string): TimeInfo =
+  ## Helper to parse time strings trying multiple known formats. 
   for fmt in TIME_FORMATS:
     try: return parse(timeStr, fmt)
     except: discard nil
@@ -53,6 +61,10 @@ template `%`(timeline: Timeline): JsonNode =
   %* { "name": timeline.name, "marks": timeline.marks }
 
 proc loadTimeline(filename: string): Timeline =
+  ## Load a timeline from a file. Expects a path to a file (can be relative or
+  ## absolute) and returns a Timeline. The marks in the timeline are guaranteed
+  ## to be ordered by time.
+
   var timelineJson: JsonNode
   try: timelineJson = parseFile(filename)
   except:
@@ -62,9 +74,17 @@ proc loadTimeline(filename: string): Timeline =
   var timeline: Timeline = (name: timelineJson["name"].getStr(), marks: @[])
 
   for markJson in timelineJson["marks"]:
+
+    # TODO: an incorrect time format that was used in version 0.6 and prior.
+    # Version 0.7 between 1.0 support this format on read only and will write
+    # out the correct  format (so they can be used to convert older timelines).
+    var time: TimeInfo
+    try: time = parse(markJson["time"].getStr(), ISO_TIME_FORMAT)
+    except: time = parse(markJson["time"].getStr(), "yyyy:MM:dd'T'HH:mm:ss")
+
     timeline.marks.add((
       id: parseUUID(markJson["id"].getStr()),
-      time: parse(markJson["time"].getStr(), ISO_TIME_FORMAT),
+      time: time, #parse(markJson["time"].getStr(), ISO_TIME_FORMAT),
       summary: markJson["summary"].getStr(),
       notes: markJson["notes"].getStr(),
       tags: markJson["tags"].getElems(@[]).map(proc (t: JsonNode): string = t.getStr())))
@@ -75,6 +95,8 @@ proc loadTimeline(filename: string): Timeline =
   return timeline
 
 proc saveTimeline(timeline: Timeline, location: string): void =
+  ## Write the timeline to disk at the file location given.
+
   var timelineFile: File
   try:
     timelineFile = open(location, fmWrite)
@@ -83,6 +105,8 @@ proc saveTimeline(timeline: Timeline, location: string): void =
   finally: close(timelineFile)
 
 proc flexFormat(i: TimeInterval): string =
+  ## Pretty-format a time interval.
+
   let fmt =
     if i > 1.days: "d'd' H'h' m'm'"
     elif i >= 1.hours: "H'h' m'm'"
@@ -94,6 +118,8 @@ proc flexFormat(i: TimeInterval): string =
 type WriteData = tuple[idx: int, mark: Mark, prefixLen: int, interval: TimeInterval]
 
 proc writeMarks(timeline: Timeline, indices: seq[int], includeNotes = false): void =
+  ## Write a nicely-formatted list of Marks to stdout.
+
   let marks = timeline.marks
   let now = getLocalTime(getTime())
 
@@ -128,6 +154,9 @@ proc writeMarks(timeline: Timeline, indices: seq[int], includeNotes = false): vo
 
     if prefix.len > longestPrefix: longestPrefix = prefix.len
 
+  let colWidth = 80
+  let notesPrefixLen = 4
+
   for w in toWrite:
     if w.mark.summary == STOP_MSG: continue
 
@@ -148,10 +177,17 @@ proc writeMarks(timeline: Timeline, indices: seq[int], includeNotes = false): vo
     writeLine(stdout, "")
 
     if includeNotes and len(w.mark.notes.strip) > 0:
-      writeLine(stdout, spaces(longestPrefix) & w.mark.notes)
+      writeLine(stdout, "")
+      let wrappedNotes = wordWrap(s = w.mark.notes,
+                                  maxLineWidth = colWidth)
+      for line in splitLines(wrappedNotes):
+        writeLine(stdout, spaces(notesPrefixLen) & line)
       writeLine(stdout, "")
 
 proc formatMark(mark: Mark, nextMark = NO_MARK, timeFormat = ISO_TIME_FORMAT, includeNotes = false): string =
+  ## Pretty-format a Mark, optionally taking the next Mark in the timeline (to
+  ## compute duration) and a time format string, and conditionally including
+  ## the Mark's notes in the output.
 
   let nextTime =
     if nextMark == NO_MARK: getLocalTime(getTime())
@@ -161,13 +197,12 @@ proc formatMark(mark: Mark, nextMark = NO_MARK, timeFormat = ISO_TIME_FORMAT, in
   # TODO: pick up here calculating the time between marks
 
   let prefix = ($mark.id)[0..<8] & "  " & mark.time.format(timeFormat) & " (" & duration & ") -- "
-  let prefixLen = len(($mark.id)[0..<8] & "  " & mark.time.format(timeFormat) & " (" & duration & ") -- ")
 
   result = prefix & mark.summary
   if includeNotes and len(mark.notes.strip()) > 0:
-    let wrappedNotes = wordWrap(s = mark.notes, maxLineWidth = 80 - prefixLen)
+    let wrappedNotes = wordWrap(s = mark.notes, maxLineWidth = 80 - prefix.len)
     for line in splitLines(wrappedNotes):
-      result &= "\x0D\x0A" & spaces(prefixLen) & line
+      result &= "\x0D\x0A" & spaces(prefix.len) & line
     result &= "\x0D\x0A"
 
 proc findById(marks: seq[Mark], id: string): int =
@@ -178,7 +213,17 @@ proc findById(marks: seq[Mark], id: string): int =
 
   return -1
 
+proc getLastIndex(marks: seq[Mark]): int =
+  ## Find and return the index of the last Mark that was not a STOP mark.
+  ## Returns -1 if there is no such last mark.
+
+  var idx = marks.len - 1
+  while idx >= 0 and marks[idx].summary == STOP_MSG: idx -= 1
+  if idx < 0: result = -1
+  else: result = idx
+
 proc doInit(timelineLocation: string): void =
+  ## Interactively initialize a new timeline at the given file path.
 
   stdout.write "Time log name [New Timeline]: "
   let name = stdin.readLine()
@@ -197,6 +242,9 @@ proc doInit(timelineLocation: string): void =
 type ExpectedMarkPart = enum Time, Summary, Tags, Notes
 
 proc edit(mark: var Mark): void =
+  ## Interactively edit a mark using the editor named in the environment
+  ## variable "EDITOR"
+
   var
     tempFile: File
     tempFileName: string
@@ -231,6 +279,9 @@ proc edit(mark: var Mark): void =
   finally: close(tempFile)
 
 proc filterMarkIndices(timeline: Timeline, args: Table[string, Value]): seq[int] =
+  ## Filter down a set of marks according to options provided in command line
+  ## arguments.
+
   let marks = timeline.marks
   result = sequtils.toSeq(0..<marks.len).filterIt(marks[it].summary != STOP_MSG)
 
@@ -293,14 +344,17 @@ when isMainModule:
   let doc = """
 Usage:
   ptk init [options]
-  ptk add [options]
+  ptk (add | start) [options]
-  ptk add [options] <summary>
+  ptk (add | start) [options] <summary>
-  ptk amend [options] <id> [<summary>]
+  ptk resume [options] [<id>]
+  ptk amend [options] [<id>] [<summary>]
   ptk merge <timeline> [<timeline>...]
   ptk stop [options]
   ptk continue
   ptk delete <id>
   ptk (list | ls) [options]
+  ptk (list | ls) tags
+  ptk current
   ptk sum-time --ids <ids>...
   ptk sum-time [options] [<firstId>] [<lastId>]
   ptk (-V | --version)
@@ -333,7 +387,7 @@ Options:
   let now = getLocalTime(getTime())
 
   # Parse arguments
-  let args = docopt(doc, version = "ptk 0.6.0")
+  let args = docopt(doc, version = "ptk 0.11.2")
 
   if args["--echo-args"]: echo $args
 
@@ -453,7 +507,7 @@ Options:
 
       saveTimeline(timeline, timelineLocation)
 
-    if args["add"]:
+    if args["add"] or args["start"]:
 
       var newMark: Mark = (
         id: genUUID(),
@@ -464,17 +518,55 @@ Options:
 
       if args["--edit"]: edit(newMark)
 
+      let prevLastIdx = timeline.marks.getLastIndex()
       timeline.marks.add(newMark)
       timeline.writeMarks(
-        indices = @[timeline.marks.len - 1],
+        indices = if prevLastIdx < 0: @[0]
+                  else: @[prevLastIdx, timeline.marks.len - 1],
         includeNotes = args["--verbose"])
 
       saveTimeline(timeline, timelineLocation)
 
+    if args["resume"]:
+
+      var markToResumeIdx: int
+
+      if args["<id>"]:
+        markToResumeIdx = timeline.marks.findById($args["<id>"])
+        if markToResumeIdx == -1: exitErr "Cannot find a mark matching " & $args["<id>"]
+      else:
+        markToResumeIdx = timeline.marks.getLastIndex()
+        if markToResumeIdx < 0: exitErr "No mark to resume."
+      var markToResume = timeline.marks[markToResumeIdx]
+      
+      var newMark: Mark = (
+        id: genUUID(),
+        time: if args["--time"]: parseTime($args["--time"]) else: now,
+        summary: markToResume.summary,
+        notes: markToResume.notes,
+        tags: markToResume.tags)
+
+      if args["--edit"]: edit(newMark)
+
+      timeline.marks.add(newMark)
+      timeline.writeMarks(
+        indices = sequtils.toSeq(markToResumeIdx..<timeline.marks.len),
+        includeNotes = args["--verbose"])
+        
+      saveTimeline(timeline, timelineLocation)
+
     if args["amend"]:
 
       # Note, this returns a copy, not a reference to the mark in the seq.
-      let markIdx = timeline.marks.findById($args["<id>"])
+      var markIdx: int
+
+      if args["<id>"]:
+        markIdx = timeline.marks.findById($args["<id>"])
+        if markIdx == -1: exitErr "Cannot find a mark matching " & $args["<id>"]
+      else:
+        markIdx = timeline.marks.getLastIndex()
+        if markIdx < 0: exitErr "No mark to amend."
+
       var mark = timeline.marks[markIdx]
       
       if args["<summary>"]: mark.summary = $args["<summary>"]
@@ -511,11 +603,27 @@ Options:
 
     if args["list"] or args["ls"]:
 
-      var selectedIndices = timeline.filterMarkIndices(args)
+      if args["tags"]:
 
-      timeline.writeMarks(
+        echo $(timeline.marks.mapIt(it.tags)
-        indices = selectedIndices,
+                .flatten().deduplicate().sorted(system.cmp).join("\n"))
-        includeNotes = args["--version"])
+
+      else:
+        var selectedIndices = timeline.filterMarkIndices(args)
+
+        timeline.writeMarks(
+          indices = selectedIndices,
+          includeNotes = args["--verbose"])
+
+    if args["current"]:
+
+      let idx = timeline.marks.len - 1
+      if timeline.marks[idx].summary == STOP_MSG:
+        echo "ptk: no current task"
+      else:
+        timeline.writeMarks(
+          indices = @[idx],
+          includeNotes = true)
 
     if args["sum-time"]:
     

ptk.nimble

@@ -1,6 +1,6 @@
 # Package
 
-version       = "0.6.0"
+version       = "0.11.2"
 author        = "Jonathan Bernard"
 description   = "Personal Time Keeper"
 license       = "MIT"
@@ -8,5 +8,5 @@ bin           = @["ptk"]
 
 # Dependencies
 
-requires @["nim >= 0.15.0", "docopt >= 0.6.4", "uuids", "langutils", "tempfile", "timeutils >= 0.2.0"]
+requires @["nim >= 0.18.0", "docopt >= 0.6.4", "uuids", "langutils", "tempfile", "timeutils >= 0.2.2", "isaac >= 0.1.2"]
 

ptkutil.nim

@@ -1,3 +0,0 @@
-template first*(a: openarray): auto = a[0]
-
-template last*(a: openarray): auto = a[len(a)-1]