Add Nim documentation, parameterize ProgressWrapper output destination.

build.gradle

@@ -3,7 +3,7 @@ apply plugin: "application"
 apply plugin: "maven"
 
 group = "com.jdblabs"
-version = "1.4.1"
+version = "1.4.2"
 mainClassName = "com.jdblabs.file.treediff.TreeDiff"
 
 repositories {

src/main/groovy/com/jdblabs/file/treediff/TreeDiff.groovy

@@ -8,7 +8,7 @@ import org.apache.commons.codec.digest.DigestUtils
 
 public class TreeDiff {
 
-    public static final String VERSION = "1.4.1"
+    public static final String VERSION = "1.4.2"
 
     private ObjectMapper objectMapper = new ObjectMapper()
     private PrintStream stdout

src/main/nim/treediff.nim

@@ -1,14 +1,27 @@
+## Tree Diff
+## =========
+##
+## Utility to compare the file contents of two directory trees.
+
 import os, tables, streams, sequtils, strutils, docopt, marshal
 import incremental_md5, console_progress
 
+
+
 type
-  Verbosity* = enum very_quiet, quiet, normal
-  FileEntry* = tuple[relPath: string, checksum: string]
-  DirAnalysis* = tuple[allEntries: seq[ref FileEntry],
-                       byRelPath: ref Table[string, ref FileEntry],
-                       byChecksum: ref Table[string, seq[ref FileEntry]]]
   ProgressWrapper* = tuple[impl: Progress, verbosity: Verbosity]
-  DisplayOptions = tuple[left, right, same, content, path: bool]
+    ## Wrapper around a console_progress.Progress.
+
+  Verbosity* = enum ## Enum representing the level of output verbosity the tool will emit.
+    very_quiet, ## suppress all output including the progress indicator
+    quiet,      ## suppress all output except the progress indicator
+    normal      ## emit all output
+
+proc newProgressWrapper*(outFile = stdout, verbosity = normal): ProgressWrapper =
+  ## Create a new ProgressWrapper for the given verbosity.
+  if verbosity > very_quiet:
+    result = (impl: newProgress(outFile, 0), verbosity: verbosity)
+  else: result = (impl: nil, verbosity: verbosity)
 
 proc init(p: ProgressWrapper, root: string, fileCount: int): void =
   if p.verbosity == normal: echo "-- ", root.expandFilename
@@ -23,11 +36,16 @@ proc finish(p: ProgressWrapper): void =
     p.impl.erase
   if p.verbosity == normal: echo "  ", p.impl.getMax, " files.\L"
 
+
+
 proc countFiles(root: string): int =
-  for file in walkDirRec(root):
-    result += 1
+  for file in walkDirRec(root): result += 1
 
 proc getRelPath(ancestor, child: string): string =
+  ## Given a ancestor path and a child path, assuming the child path is
+  ## contained within the ancestor path, return the relative path from the
+  ## ancestor to the child.
+
   let ancestorPath = ancestor.expandFilename.split({DirSep, AltSep})
   let childPath = child.expandFilename.split({DirSep, AltSep})
 
@@ -45,12 +63,25 @@ proc getRelPath(ancestor, child: string): string =
   if idx != ancestorPath.len: return ""
   return foldl(@["."] & childPath[idx..childPath.high], joinPath(a, b))
   
-proc newProgressWrapper*(verbosity: Verbosity): ProgressWrapper =
-  if verbosity > very_quiet:
-    result = (impl: newProgress(stdout, 0), verbosity: verbosity)
-  else: result = (impl: nil, verbosity: verbosity)
+
+
+
+type
+  FileEntry* = tuple[relPath: string, checksum: string]
+    ## Data about one file that has been analyzed
+
+  DirAnalysis* = ## Analysis data about one directory tree.
+    tuple[allEntries: seq[ref FileEntry],
+          byRelPath: ref Table[string, ref FileEntry],
+          byChecksum: ref Table[string, seq[ref FileEntry]]]
+
+
+  DisplayOptions = tuple[left, right, same, content, path: bool]
+    ## Consolidated description of which types of results to display.
 
 proc analyzeDir*(root: string, progress: ProgressWrapper): DirAnalysis =
+  ## Inspect a directory and analyze all files, noting their relative paths and
+  ## checksum of their contents.
   let fileCount = countFiles(root)
 
   progress.init(root, fileCount)
@@ -67,13 +98,10 @@ proc analyzeDir*(root: string, progress: ProgressWrapper): DirAnalysis =
     var fileEntry: ref FileEntry = new(ref FileEntry)
     fileEntry[] = (relPath: getRelPath(root, file), checksum: md5sum )
 
-    # Add to allEntries list
+    # Add to allEntries list, byRelPath table, and byChecksum table
     result.allEntries.add(fileEntry)
-
-    # Add to byRelPath table
     result.byRelPath[fileEntry.relPath] = fileEntry
 
-    # Add to the byChecksum table
     if not result.byChecksum.hasKey(fileEntry.relPath):
       result.byChecksum[fileEntry.checksum] = newSeq[ref FileEntry]()
 
@@ -85,30 +113,41 @@ proc analyzeDir*(root: string, progress: ProgressWrapper): DirAnalysis =
   progress.finish()
 
 proc loadAnalysis*(path: string, analysis: var DirAnalysis) =
+  ## Load a previously performed directory analysis.
   let inStream: Stream = newFileStream(path, fmRead)
   load(inStream, analysis)
 
 proc saveAnalysis*(path: string, analysis: DirAnalysis): void =
+  ## Save a completed analysis.
   let outStream = newFileStream(path, fmWrite)
   store(outStream, analysis)
 
 proc intersection*(left, right: DirAnalysis): seq[ref FileEntry] =
+  ## Find all ``FileEntry`` that are the same on both sides: matching contents
+  ## and paths.
   return left.allEntries.filter do (item: ref FileEntry) -> bool:
     if not right.byRelPath.hasKey(item.relPath): return false
     let match = right.byRelPath[item.relPath]
     return item.checksum == match.checksum
 
 proc difference*(left, right: DirAnalysis): seq[ref FileEntry] =
+  ## Find all ``FileEntry`` that are present in the left but not present in
+  ## the right.
   return left.allEntries.filter do (item: ref FileEntry) -> bool:
     return not right.byRelPath.hasKey(item.relPath) and
            not right.byChecksum.hasKey(item.checksum)
 
 proc `*`*(left, right: DirAnalysis): seq[ref FileEntry] {.inline.} =
+  ## Alias for `intersection(left, right) <#intersection>`_
   return intersection(left, right)
+
 proc `-`*(left, right: DirAnalysis): seq[ref FileEntry] {.inline.} =
+  ## Alias for `difference(left, right) <#difference>`_
   return difference(left, right)
 
 proc samePathDifferentContents*(left, right: DirAnalysis): seq[string] =
+  ## Find all ``FileEntry`` that have the same paths in both trees but whose
+  ## contents differ.
   let matchingEntries = left.allEntries.filter do (item: ref FileEntry) -> bool:
     if not right.byRelPath.hasKey(item.relPath): return false
     let match = right.byRelPath[item.relPath]
@@ -116,18 +155,20 @@ proc samePathDifferentContents*(left, right: DirAnalysis): seq[string] =
   return matchingEntries.map(proc(item: ref FileEntry): string = return item.relPath)
 
 proc sameContentsDifferentPaths*(left, right: DirAnalysis): seq[tuple[left, right: ref FileEntry]] =
+  ## Find all ``FileEntry`` whose contents are the same in both trees but
+  ## which are located at differenc paths.
   result = @[]
   for item in left.allEntries:
     if not right.byChecksum.hasKey(item.checksum): continue
     for match in right.byChecksum[item.checksum]:
       if item.relPath != match.relPath: result.add((left: item, right:match))
 
-proc quitWithError(error: string): void =
-  stderr.writeLine("treediff: " & error)
-  quit(QuitFailure)
-
 when isMainModule:
 
+  let quitWithError = proc (error: string): void =
+    stderr.writeLine("treediff: " & error)
+    quit(QuitFailure)
+
   let doc = """
 Usage:
   treediff <left> [<right>] [options]
@@ -190,12 +231,12 @@ Options:
 
 """
 
-  let args = docopt(doc, version = "treediff v1.4.1")
+  let args = docopt(doc, version = "treediff v1.4.2")
 
   var verbosity = normal
   if args["--quiet"]: verbosity = quiet
   if args["--very-quiet"]: verbosity = very_quiet
-  let progressWrapper = newProgressWrapper(verbosity)
+  let progressWrapper = newProgressWrapper(verbosity = verbosity)
 
   # Load or perform analysis
   if not args["<left>"]:

treediff.nimble

@@ -1,5 +1,5 @@
 # Package
-version       = "1.4.1"
+version       = "1.4.2"
 author        = "Jonathan Bernard (jdb@jdb-labs.com)"
 description   = "Utility to generate diffs of full directory trees."
 license       = "BSD"