FileUtils plugin for Take Command / TCC / TCC/LE

beta version 0.35.2     2022-06-09

Charles Dye

Purpose:

This plugin adds a few file- and drive-related features. BOTTOMUP visits directories recursively, from innermost to outermost, and runs a command in each — like an inside-out GLOBAL. DIRCMP compares two directories and list items which appear in one but not the other. It can optionally also compare files’ sizes, time stamps, attributes, and contents. EMPTIES lists, and optionally removes, empty subdirectories. FILEINFO displays lots of information about matching files, including checksums, version information, image file information, and Windows properties. RENCASE changes the case of filenames. SWAPNAMES exchanges two files.

@IMGINFO returns information about an image file. @WINPROP returns a Windows property of a file.

Installation:

To use this plugin, copy FileUtils.dll and FileUtils.chm to some known location on your hard drive. (If you are still using the 32-bit version of Take Command, take FileUtils-x32.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 these files to a subdirectory named PlugIns within your Take Command program directory, the plugin will be loaded automatically when TCC starts.

Plugin Features:

New commands:
BOTTOMUPDIRCMPEMPTIESFILEINFORENCASE
SWAPNAMES
New functions:
@CMPTIME@CMPVER@DDEPTH@DIREMPTY@DIRREADABLE
@DIRWRITABLE@DRIVEBUS@FILEVER@FINDDRIVE@IMGINFO
@ISABATCH@RANDFILE@WINPROP
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 /D /M /P /R /S /T /X dir1 dir2

/Acompare attributes of items which exist in both dir1 and dir2
/Ccompare file contents
/Ddisable highlight
/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\



EMPTIES — List or remove empty subdirectories.

Syntax:
EMPTIES /J /M /P /Q /R /Y dirname…

/Jallow recursion into reparse points
/Mno footers
/Ppage output
/Qquietly (only useful with /R)
/Rremove empty directories
/Yyes to all prompts
dirname…directory aliases are supported

If no directory names are given, EMPTIES searches the current directory by default.

See also: the @DIREMPTY function.



FILEINFO — Display information about files.

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

/A:attribsfilter by attributes
/Ddisable highlight
/N:flagsD no hidden directories, J no junctions, Z no system directories
/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
Iomit image file info
Pomit Windows properties
Somit document summary information
Tomit time stamps
Vomit version information
Zomit sizes

Omitting checksums, document summaries, image file info, Windows properties, 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 /E /L /N /N:flags /S /U /W /X:luw /[range] file…

/A:attribsfilter by attributes
/Eno error messages
/Lchange the base name (all but the extension) to lowercase
/Nnot really
/N:flagsD no hidden directories, J no junctions, Z no system directories
/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]



@DIREMPTY — Checks whether a directory is empty.

Syntax:
@DIREMPTY[dirname]

dirnamethe directory to check

If dirname is a directory and it is empty, @DIRNAME returns 1. If dirname is not a directory, if it isn’t readable, or if it contains anything other than . and .., then @DIRNAME returns 0.

See also: the EMPTIES command.



@DIRREADABLE — Tests whether the current user can read from a directory.

Syntax:
@DIRREADABLE[dirname]

dirnamethe directory to test

Returns 1 if you can read from the specified directory, 0 if not.

See also: the @DIRWRITABLE function.



@DIRWRITABLE — Tests whether the current user can write a directory.

Syntax:
@DIRWRITABLE[dirname]

dirnamethe directory to test

Returns 1 if you can write to the specified directory, 0 if not.

See also: the @DIRREADABLE function.



@DRIVEBUS — Returns the bus type of a given local drive.

Syntax:
%@DRIVEBUS[drive]

drivethe drive letter; the colon is optional

@DRIVEBUS returns an integer bus type: 4 IEEE 1394, 7 USB, etc.



@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.



@IMGINFO — Returns information about an image file.

Syntax:
%@IMGINFO[n,filename]

nwhich information to return; see below
filenamethe image file to examine

If filename does not exist, is not an image file, or cannot be read, you’ll get an error message. If you request EXIF data which is not present in the file, @IMGINFO will return the string N/A.


n:Returns:
0image resolution, width × height
1image width (pixels)
2image height (pixels)
3horizontal resolution (DPI)
4vertical resolution (DPI)
5bits per pixel
6image format (string)
EXIF data:
10image orientation
11date and time
12date and time (original)
13date and time (digitized)
14author
15description
16copyright
17software
18camera make
19camera model


@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.



@WINPROP — Returns a Windows property for a file.

Syntax:
%@WINPROP[n,filename]

nwhich property to return
filenamethe file to examine

If filename does not exist, you’ll get an error message. If the file cannot be read or the specified property does not exist, @WINPROP will return an empty string.

nReturns:
Core properties
0System.Author
1System.Comment
2System.Copyright
3System.FileDescription
4System.FileVersion
5System.ItemAuthors
6System.ItemNameDisplay
7System.Keywords
8System.Rating
9System.Subject
10System.Title
11System.Trademarks
Media properties
20System.Media.AuthorUrl
21System.Media.CreatorApplication
22System.Media.CreatorApplicationVersion
23System.Media.DateEncoded
24System.Media.DateReleased
25System.Media.Duration
26System.Media.Producer
27System.Media.Publisher
28System.Media.SubTitle
29System.Media.Year
Music properties
40System.Music.AlbumArtist
41System.Music.AlbumID
42System.Music.AlbumTitle
43System.Music.Artist
44System.Music.Composer
45System.Music.Conductor
46System.Music.DisplayArtist
47System.Music.Genre
48System.Music.Mood
49System.Music.Period
50System.Music.TrackNumber
Audio properties
60System.Audio.ChannelCount
62System.Audio.EncodingBitrate
66System.Audio.SampleRate
67System.Audio.SampleSize


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.

Highlight Variable:

A few of the commands in this plugin feature highlighted output. You can customize this feature by setting an environment variable Highlight:

rem  Disable highlight:
set highlight=none

rem  Set the highlight foreground:
set highlight=bright cyan

rem  Set both foreground and background:
set highlight=bri whi on blu

rem  Numbers are also supported:
set highlight=46

Many commands also have a /D or /NC option to disable highlighting.

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.