FileUtils plugin for Take Command / TCC / 4NT

beta version 0.27.6     2018-01-04

Charles Dye

Purpose:

This plugin adds a few file- and drive-related features.

Installation:

To use this plugin, copy FileUtils.dll to some known location on your hard drive. (If you are using the 64-bit version of Take Command, take FileUtils-x64.dll instead of FileUtils.dll.) Load the .DLL file with a PLUGIN /L command, for example:

plugin /l c:\bin\tcmd\test\fileutils.dll

If you copy this file to a subdirectory named PlugIns within your Take Command program directory, the plugin will be loaded automatically when TCC starts.

Plugin Features:

New commands: BOTTOMUP, DIRCMP, FILEINFO, RENCASE, SWAPNAMES

New functions: @CMPTIME, @CMPVER, @DDEPTH, @FILEVER, @FINDDRIVE, @ISABATCH, @RANDFILE

New variables: _FWDRIVES, _K32VER, _USBDRIVES

Syntax Note:

The syntax definitions in the following text use these conventions for clarity:

BOLD CODEindicates text which must be typed exactly as shown.
CODEindicates optional text, which may be typed as shown or omitted.
Bold italicnames a required argument; a value must be supplied.
Regular italicnames an optional argument.
ellipsis…after an argument means that more than one may be given.

New Commands:

BOTTOMUP — Visit subdirectories recursively, deepest first, and run a command in each.

Syntax:
BOTTOMUP /B /H /I /N /P /Q /S:dir command

/Bbare directory display
/Hinclude hidden directories
/Iignore exit codes
/Ndo not visit or search junctions
/Pprompt before running the command
/Qdo not display directory names
/S:dirspecify the top-level directory

This command works much like GLOBAL, only inside-out. It visits subdirectories recusively, deepest first, and runs the specified command in each. It ends up — and runs the command a final time — in the original current directory.

TCC expands the command line before BOTTOMUP sees it. You will need to double any percent signs, and use escapes or strong quotes to protect any problem characters in the command. This is different than GLOBAL, but unavoidable — I cannot prevent TCC from performing variable expansion before the plugin command is called.

The command is required. If you want to do nothing recursively, use REM.

By default, BOTTOMUP will abort if the command returns a nonzero exit code, or if it cannot change the current directory to any subdirectory in the tree. If /I is specified, both of these situations will be ignored and processing will continue.


rem    Trivial demo:
bottomup /q echo Now I'm in "%%_cwd" !

rem    An inside-out directory listing:
bottomup /i /q dir /f /h /ne



DIRCMP — Compare two directories.

Syntax:
DIRCMP /A /C /M /P /R /S /T /X dir1 dir2

/Acompare attributes of items which exist in both dir1 and dir2
/Ccompare file contents
/Mdo not display the footers
/Ppage output
/Rcompare directories recursively
/Scompare sizes of files which exist in both directories
/Tcompare time stamps of files which exist in both directories
/Xreverse operation — reports only items which exist in both directories
dir1the first directory; directory aliases are supported
dir2the second directory

dir1 and dir2 are both required. Wildcards are not allowed; you must name two unambiguous directories.

/A compares attributes when a file or subdirectory exists in both dir1 and dir2. Only the read-only, archive, hidden, and system attributes are compared. The more exotic attributes will be ignored.

/C compares the contents of files which appear in both directories. Both files are opened, then data is read and compared, byte-for-byte. This option can slow DIRCMP down considerably! If the command is unable to read from either file, the files are considered the same.

/S compares file sizes when a file exists in both locations. Only files are tested. The relevant Windows APIs do not report sizes for subdirectories.

/T compares time stamps when a file exists in both locations. Only the last-write time stamp is compared, and the comparison is fuzzy; differences of less than two seconds may be ignored. Only time stamps of files are compared; this option does not test subdirectories.

/X reverses DIRCMP’s operation and reports only items which exist in both locations. If you combine /X with /A, /C, etc. then only items with matching attributes, contents, and so on will be listed.

Note that /R, not /S, controls recursion. Recursion is only performed where subdirectories with the exact same name exist in both dir1 and dir2.

Mismatches are reported with a note in brackets:

[1]The item exists in dir1 but not in dir2.
[2]The item exists in dir2 but not in dir1.
[A]The item has different attributes in dir1 and dir2.
[S]The file has different sizes in dir1 and dir2.
[T]The item has different time stamps in dir1 and dir2.

The letters may be combined; e.g. [ST] would mean that the items have different sizes and time stamps.

Items which exist in one directory, but not the other, are always reported. There is no option to suppress this feature.

If a file exists in dir1 and a subdirectory of the same name exists in dir2 — or vice versa — then both will be reported as mismatches.


dircmp /r /s "%userprofile\Documents" d:\backup\docs\



FILEINFO — Display information about files.

Syntax:
FILEINFO /A:attribs /N:flags /O:flags /P /S /[range] file…

/A:attribsfilter by attributes
/N:flagsD no hidden directories, J no junctions
/O:flagsomit features; see below
/Ppage output
/Slook in subdirectories for matching files
/[range]many range options are supported
filewildcards, directory aliases, and include lists are supported

FILEINFO displays information about files; go figure. By default, the information shown includes the full, canonical filename; any version information; any TCC file description; the file size, date and time stamps, and attributes; CRC32 and MD5 checksums; and document summary information.

/O: omits some information. These flags can be combined:

Aomit attributes
Comit checksums
Domit file descriptions
Homit file version header
Somit document summary information
Tomit time stamps
Vomit version information
Zomit sizes

Omitting checksums, document summaries, and version info can make the command faster — especially if the files are very large.


fileinfo "%_cmdspec"



RENCASE — Change the case of filenames.

Syntax:
RENCASE /A:attribs /L /N /N:flags /S /U /W /X:luw /[range] file…

/A:attribsfilter by attributes
/Lchange the base name (all but the extension) to lowercase
/Nnot really
/N:flagsD no hidden directories, J no junctions, E no error messages
/Slook in subdirectories for matching files
/Uchange the base name (all but the extension) to uppercase
/Wchange the base name (all but the extension) to word case
/X:luwchange the extension to upper/lower/word case
/[range]many range options are supported
file…wildcards, directory aliases, etc. supported

RENCASE renames files, changing the case of letters. Filenames are handled as two parts: the base name (everything before the last period), and the extension (everything after). Options /L, /U, and /W affect the base name, and /X: affects the extension.

If no action is specified (none of /L, /U, /W, or /X:), the default is /L.

rencase /l /x:l *.html



SWAPNAMES — Exchange two files.

Syntax:
SWAPNAMES /D /Q /X file1 file2

/Dfile1 and file2 are directories, not files
/Qquietly
/Xcheck that file1 and file2 have the same file type
file1, file2required; wildcards not allowed

This command does a double rename. It renames file1 as file2, and vice versa. It only renames one pair of files; wildcards are not supported.

/X gets both files’ extensions, and reads their default handlers from the registry. It allows the rename only if both extensions are the same, or if both have the same handler. For example, you can swap a .txt file with a .log file only if they have the same handler. /X is ignored with /D.

swapnames myfile.cpp myfile.bak



New Functions:

@CMPTIME — Compares timestamps of two files.

Syntax:
%@CMPTIME[file1,file2,which]

file1the first file to examine
file2the second file to examine
whichA, C, or W; the default is W

Both files must exist. Directory aliases are supported.

Return values:

-1if file1 is older than file2,
0if both files are the same age,
1if file1 is newer than file2.

if %@cmpfile[%_cmdspec,%_ininame] == 1 echo %_cmdspec is newer than %_ininame!



@CMPVER — Compares version numbers of two files.

Syntax:
%@CMPVER[file1,file2,flags]

file1the first file to examine
file2the second file to examine
flags1: do not assume 0.0.0.0

Both files must exist. Directory aliases are supported. If either file does not contain version information, this function will assume 0.0.0.0 — unless flags is 1, in which case the function will give an error instead.

Return values:

-1if file1 has a lower version number than file2,
0if both files are the same version,
1if file1 has a higher version number than file2.

echo %@cmpver[%@search[notepad.exe],%@search[ping.exe]]



@DDEPTH — Returns the depth of a file or subdirectory.

Syntax:
@DDEPTH[file]

filedirectory aliases and relative paths are okay

Returns 0 for items in the root directory, 1 for items in a subdirectory, 2 for items in a sub-subdirectory, and so on. File need not actually exist.

echo %@ddepth[c:\foo\bar\readme.txt]



@FILEVER — Returns the version number of a file.

Syntax:
%@FILEVER[file,flags]

filethe first file to examine
flags1: do not assume 0.0.0.0

File must exist. Directory aliases are supported. The version number will be returned in the format major.minor.build.private. If the file does not contain version information, the return value will be 0.0.0.0 — unless flags is 1, in which case the function will give an error instead.

This value is always four integers, separated by periods (not your local decimal character) and without leading zeroes or spaces. It’s a more consistent format than the version strings returned by @VERINFO, which may contain whatever the programmer fancies.

echo %@filever[%_cmdspec]



@FINDDRIVE — Finds a drive matching the given criteria.

Syntax:
%@FINDDRIVE[label,serial,minsize,maxsize,bus]

labelwildcards are supported
serialup to 8 hex digits
minsizesuffixes k, K, m, M, etc. supported
maxsizesuffixes k, K, m, M, etc. supported
bus4 IEEE 1394, 7 USB, etc.

@FINDDRIVE returns the drive letter (with a colon) of the first drive it finds which meets all of the specified criteria. You must specify at least one.



@ISABATCH — Looks for a matching batch file.

Syntax:
%@ISABATCH[file,path,flags]

filethe command to search for; no path, no extension, no wildcards
pathdirectories to search; defaults to %PATH
flagsbitmapped: 1: search current dir before path; 2: also search AppPaths; 128: return filename

@ISABATCH searches for a matching command, and returns a numeric value:

0no matching command was found
0the first matching command is not a batch (.com or .exe)
1the first matching command is a .btm
2the first matching command is a .cmd
3the first matching command is a .bat

The flags value lets you alter the function’s operation:

1search the current directory before the search path
2search AppPaths after the search path
128return the first matching filename, not a numeric value

If flags is not specified, it defaults to 1.

You can specify a different list of directories to search with path. Separate directories with semicolons (not commas!) and quote any directory which contains a space, comma, semicolon, or other troublesome character.


iff %@isabatch[empire] == 0 then
    echo Empire is not a batch file.
else
    echo Empire is a batch file:  %@isabatch[empire,,128]
endiff



@RANDFILE — Picks a file at random and returns its filename.

Syntax:
%@RANDFILE[/A:attribs /S /[range] wildspec]

wildspecrequired; directory aliases are supported
/A:attribsfilter by attributes; use /A:D to find subdirectories instead of files
/Ssearch for matching files in subdirectories
/[range]many range options are supported
wildspecrequired; directory aliases are supported

@RANDFILE makes a list of files matching the given wildspec, picks one at random, and returns a complete pathname. If no files match the wildspec, this function returns an empty string.

•  Note: Enumerating all matching files can take a long time, especially if you use /S.



New Variables:

_FWDRIVES — Returns a list of drives connected to IEEE 1394 ports.

Syntax:
%_FWDRIVES

If more than one drive is returned, they will be separated with spaces.

for %drive in ( %_fwdrives ) do vol %_drive



_K32VER — Returns the version number of Kernel32.dll.

Syntax:
%_K32VER

This convenience function is equivalent to @FILEVER[%_winsysdir\Kernel32.dll]. You can use it as an alternate way to get the Windows version. The value will be returned as four decimal values, separated by periods, without spaces or leading zeroes.



_USBDRIVES — Returns a list of drives connected to USB ports.

Syntax:
%_USBDRIVES

If more than one drive is returned, they will be separated with spaces.

for %drive in ( %_usbdrives ) do vol %_drive



Ranges:

This plugin supports the following range syntax:


Size range:  /[Ssmallest,largest]

You may omit either smallest or largest. You may qualify either with a trailing letter: lowercase k, m, g, etc. to multiply by one thousand, one million, one billion, and so on; or uppercase K, M, G, etc. to multiply by 210, 220, 230, and so on. If largest begins with a + sign, it is an increment over smallest. Use /![Ssmallest,largest] to invert the test and return only files not in the given size range.

Date range:  /[D[acw]:earliest,latest]

You may omit either earliest or latest; either defaults to the current date. The optional [acw] argument selects the date stamp to check. (If you want to check more than one date stamp, you must supply more than one date range option.) The colon after the [acw] is optional.

Dates may be given in the local date format, or in yyyy-mm-dd format (with a four-digit year). You may also specify a date as an offset preceded with a + or - sign; the offset is in days relative to today’s date (for earliest) or relative to earliest (in the case of latest). If earliest turns out to be later than latest then the two are exchanged.

You may also give a specific time on either date, preceded by an @ sign. The time may be in either 24-hour format, or 12-hour format with a trailing A or P.

Use /![D[acw]:earliest,latest] to invert the test and return only files not in the given date range.

Time range:  /[T[acw]:earliest,latest]

You may omit either earliest or latest. The optional [acw] argument selects the time stamp to check. (If you want to check more than one time stamp, you must supply more than one time range option.) The colon after the [acw] is optional. Times may be in either 24-hour format, or 12-hour format with a trailing A or P.

Use /![T[acw]:earliest,latest] to invert the test and return only files not in the given time range.

Exclusion range:  /[!wildspec]

Filenames matching the wildspec will be excluded. You can supply more than one wildspec by separating them with (unquoted) spaces.

Owner range:  /[Owildspec]

Files whose owners (in domain\user format) do not match the wildspec will be skipped. Use /![Owildspec] to invert the test and return only files which do not match the owner wildspec.

Description range:  /Iwildspec or (alternate syntax) /[Iwildspec]

If a file’s description does not match the wildspec, it will be skipped. Use /!Iwildspec to invert the test, returning only files which do not match the description wildspec.

Day-of-the-week range:  /[W[acw]:days]

You may specify multiple days separated by commas, e.g. /[W:MON,WED,FRI]. You can also give a range, for example /[W:TUE-FRI]. WEEKENDS is accepted as a synonym for SAT,SUN; WEEKDAYS is a synonym for MON-FRI. The colon in this syntax is required.

You may supply multiple ranges. A file must match all given ranges or it will be skipped.

Startup Message:

This plugin displays an informational line when it initializes. The message will be suppressed in transient or pipe shells. You can disable it for all shells by defining an environment variable named NOLOADMSG, for example:

set /e /u noloadmsg=1

Status and Licensing:

Consider this beta software. It may well have issues. Try it at your own risk. If you find a problem, you can report it in the JP Software support forum.

FileUtils is currently licensed only for testing purposes. I may make binaries and source code available under some free license once I consider it ready for use.

Download:

You can download the current version of the plugin from http://prospero.unm.edu/dl/fileutils.zip or ftp://prospero.unm.edu/fileutils.zip.