# FileUtils plugin for Take Command / TCC / TCC/LE

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

#### Syntax Note:

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

 BOLD CODE indicates text which must be typed exactly as shown. CODE indicates optional text, which may be typed as shown or omitted. Bold italic names a required argument; a value must be supplied. Regular italic names 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

 /B bare directory display /H include hidden directories /I ignore exit codes /N do not visit or search junctions /P prompt before running the command /Q do not display directory names /S:dir specify 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

 /A compare attributes of items which exist in both dir1 and dir2 /C compare file contents /D disable highlight /M do not display the footers /P page output /R compare directories recursively /S compare sizes of files which exist in both directories /T compare time stamps of files which exist in both directories /X reverse operation — reports only items which exist in both directories dir1 the first directory; directory aliases are supported dir2 the 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…

 /J allow recursion into reparse points /M no footers /P page output /Q quietly (only useful with /R) /R remove empty directories /Y yes 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:attribs filter by attributes /D disable highlight /N:flags D no hidden directories, J no junctions, Z no system directories /O:flags omit features; see below /P page output /S look in subdirectories for matching files /[range] many range options are supported file wildcards, 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:

 A omit attributes C omit checksums D omit file descriptions H omit file version header I omit image file info P omit Windows properties S omit document summary information T omit time stamps V omit version information Z omit 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:attribs filter by attributes /E no error messages /L change the base name (all but the extension) to lowercase /N not really /N:flags D no hidden directories, J no junctions, Z no system directories /S look in subdirectories for matching files /U change the base name (all but the extension) to uppercase /W change the base name (all but the extension) to word case /X:luw change 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

 /D file1 and file2 are directories, not files /Q quietly /X check that file1 and file2 have the same file type file1, file2 required; 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]

 file1 the first file to examine file2 the second file to examine which A, C, or W; the default is W

Both files must exist. Directory aliases are supported.

Return values:

 -1 if file1 is older than file2, 0 if both files are the same age, 1 if 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]

 file1 the first file to examine file2 the second file to examine flags 1: 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:

 -1 if file1 has a lower version number than file2, 0 if both files are the same version, 1 if 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]

 file directory 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]

 dirname the 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]

 dirname the 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]

 dirname the 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]

 drive the 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]

 file the first file to examine flags 1: 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]

 label wildcards are supported serial up to 8 hex digits minsize suffixes k, K, m, M, etc. supported maxsize suffixes k, K, m, M, etc. supported bus 4 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]

 n which information to return; see below filename the 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: 0 image resolution, width × height 1 image width (pixels) 2 image height (pixels) 3 horizontal resolution (DPI) 4 vertical resolution (DPI) 5 bits per pixel 6 image format (string) EXIF data: 10 image orientation 11 date and time 12 date and time (original) 13 date and time (digitized) 14 author 15 description 16 copyright 17 software 18 camera make 19 camera model

@ISABATCH — Looks for a matching batch file.

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

 file the command to search for; no path, no extension, no wildcards path directories to search; defaults to %PATH flags bitmapped: 1: search current dir before path; 2: also search AppPaths; 128: return filename

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

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

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

 1 search the current directory before the search path 2 search AppPaths after the search path 128 return 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]

 wildspec required; directory aliases are supported /A:attribs filter by attributes; use /A:D to find subdirectories instead of files /S search for matching files in subdirectories /[range] many range options are supported wildspec required; 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]

 n which property to return filename the 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.

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