2006-10-29 Steve Huntley <stephen.huntley@alum.mit.edu>

	Added comments and license info:
	* library/template/globfind.tcl
	* library/template/tdelta.tcl

diff --git a/ChangeLog b/ChangeLog
index bf95deec556e44a64d1baef180052e4f54fef3df..c172502525010443a769506f7e97d195410b8391 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2006-10-29  Steve Huntley  <stephen.huntley@alum.mit.edu>
+
+       Added comments and license info:
+       * library/template/globfind.tcl
+       * library/template/tdelta.tcl
+
 2006-10-23  Steve Huntley  <stephen.huntley@alum.mit.edu>
 
        Initial upload of template virtual filesystems in new subfolder:

diff --git a/library/template/globfind.tcl b/library/template/globfind.tcl
index ad2e78a3c5d5b7cebe6482517f62faf8df7423e7..1d698e895b74912733a862d1522c945b76ee9256 100644 (file)
--- a/library/template/globfind.tcl
+++ b/library/template/globfind.tcl
@@ -1,3 +1,55 @@
+if 0 {
+########################
+
+globfind.tcl --
+
+Written by Stephen Huntley (stephen.huntley@alum.mit.edu)
+License: Tcl license
+Version 1.0
+
+The proc globfind is a replacement for tcllib's fileutil::find
+
+Usage: globfind ?basedir ?filtercmd??
+
+Options:
+
+basedir - the directory from which to start the search.  Defaults to current directory.
+
+filtercmd - Tcl command; for each file found in the basedir, the filename will be
+appended to filtercmd and the result will be evaluated.  The evaluation should return
+0 or 1; only files whose return code is 1 will be included in the final return result.
+
+----
+
+The proc fileutil::find is useful, but it has several deficiencies:
+
+    * On Windows, hidden files are mishandled.
+    * On Windows, checks to avoid infinite loops due to nested 
+       symbolic links are not done.
+    * On Unix, nested loop checking requires a "file stat" of each 
+       file/dir encountered, a significant performance hit.
+    * The basedir from which the search starts is not included in the 
+       results, as it is with GNU find.
+    * If the basedir is a file, it is returned in the result not as a 
+       list element (like glob) but as a string.
+    * The proc calls itself recursively, and thus risks running into 
+       interp recursion limits for very large systems.
+    * fileutil.tcl contains three separate instantiations of proc 
+       find for varying os's/versions. Maintenance nightmare.
+
+The proc globfind eliminates all the above deficiencies. It checks for 
+nested symbolic links in a platform-independent way, and scans 
+directory hierarchies without recursion.
+
+For speed and simplicity, it takes advantage of glob's ability to use 
+multiple patterns to scan deeply into a directory structure in a single 
+command, hence the name. Its calling syntax is the same as fileutil::find, 
+so with a name change it could be used as a drop-in replacement:
+
+########################
+}
+
+
 package provide globfind 1.0
 
 namespace eval ::globfind {
@@ -134,6 +186,8 @@ proc globfind {{basedir .} {filtercmd {}}} {
        return $filterFiles
 }
 
+# scfind: a command suitable for use as a filtercmd with globfind, arguments
+# duplicate a subset of GNU find args.
 
 proc scfind {args} {
        set filename [file join [pwd] [lindex $args end]]
@@ -211,6 +265,8 @@ proc scfind {args} {
        return 1
 }
 
+# find: example use of globfind and scfind to duplicate a subset of the
+# command line interface of GNU find.
 proc find {args} {
        globfind [lindex $args 0] [list [subst "scfind $args"]]
 }
@@ -221,4 +277,3 @@ namespace export -clear globfind
 # end namespace globfind
 
 
-

diff --git a/library/template/tdelta.tcl b/library/template/tdelta.tcl
index b8ac11bfee6f0537da89c36cb0cf271981f905cc..d8ad6f91f00a9ba48cdcbd765e00f54a89aa1b46 100644 (file)
--- a/library/template/tdelta.tcl
+++ b/library/template/tdelta.tcl
@@ -4,6 +4,8 @@
 #      and re-create one file by applying the delta to the other.
 #
 # Written by Stephen Huntley (stephen.huntley@alum.mit.edu)
+# License: Tcl license
+# Version 1.0
 #
 # Usage:
 #