FileUtils plugin for Take Command / TCC / TCC/LE

beta version 0.39.4.1 2024-04-03

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. BSPLIT splits files into smaller files. 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. @RPTARGET returns the target of a reparse point. @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:
`APPPATHS`	`BOTTOMUP`	`BSPLIT`	`DIRCMP`	`EMPTIES`
`FILEINFO`	`FILEUTILSHELP`	`RENCASE`	`SWAPNAMES`
New functions:
`@CMPTIME`	`@CMPVER`	`@DDEPTH`	`@DIREMPTY`	`@DIRREADABLE`
`@DIRWRITABLE`	`@DRIVEBUS`	`@FILEVER`	`@FINDDRIVE`	`@IMGINFO`
`@ISABATCH`	`@RANDFILE`	`@RPTARGET`	`@WINPROP`
New variables:
`_FWDRIVES`	`_K32VER`	`_USBDRIVES`

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:

APPPATHS — List, set, or remove AppPaths entries.

Syntax:
APPPATHS /D:dir /E /K /M /N:flags /P /Q /R:file /U /X /Y app.exe=fullpath

`/D:`dir	specify the default directory for app.exe
`/E`	suppress error messages
`/K`	show counts
`/M`	in `HKEY_LOCAL_MACHINE` (system-wide)
`/N:`flags	disable features:
	`C` — disable highlight
	`E` — suppress error messages
	`H` — don’t show hive tags
	`W` — don’t check existence of files and directories
`/P`	page output
`/Q`	quietly
`/R:`file	read entries from a text file
`/U`	in `HKEY_CURRENT_USER` (per-user)
`/X`	expand `REG_EXPAND_SZ` values
`/Y`	yes to all prompts
app.exe	the program to list/set/delete an entry for
fullpath	the complete pathname to the .EXE file

Any options must come before any app.exe on the command line.

This command can be used in four different ways: to list existing AppPaths entries, to create or change an entry, to remove an AppPaths entry, or to read and set entries from a file. Different options make sense in each of these modes.

To list AppPaths entries:

APPPATHS /K /M /P /U /X app.exe

The app.exe should end in .EXE; it may contain wildcards. If you do not specify an app.exe, APPPATHS will list all entries. If you do not specify either /M or /U, the default is to list entries from both keys.

To set an AppPaths entry:

APPPATHS /D:dir /E /M /Q /U /X /Y app.exe=fullpath

app.exe is required; it should end in .EXE. If you do not specify either /M or /U, the default is /M.

If you do not specify a /D:dir, the default is the program’s directory from fullpath.

Strings are written as type REG_SZ, unless you specify /X. With /X, if either your fullpath or your /D:dir contains at least one percent sign, then the string(s) with percent signs will be written as type REG_EXPAND_SZ.

To remove an AppPaths entry:

APPPATHS /E /M /Q /U /Y app.exe=

app.exe is required; it should end in .EXE. If you do not specify either /M or /U, the default is /M.

To read and set AppPaths entries from a file:

APPPATHS /E /M /Q /R:file /U /X /Y

The file should contain one entry per line, in the format:

app1.exe = fullname1 app2.exe = fullname2 app3.exe = fullname3 …

Blank lines and lines beginning with a semicolon are ignored. All other lines must be in app.exe=fullname format, or they will be flagged as errors.

When setting entries from a file, no attempt is made to canonicalize file and directory names, or to check whether they actually exist. Filenames are simply written to the registry as is.

All entries will be made in the same registry hive, according to /M or /U; if neither is specified, the default is /M. There is no provision for specifying default directories; the default directory for each entry will be fullname’s directory.

Strings are written as type REG_SZ, unless you specify /X. With /X, strings containing percent signs will be written as REG_EXPAND_SZ; strings without percent signs will still be created as REG_SZ.

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

BSPLIT — Split files into smaller files.

Syntax:
BSPLIT /D:dir /E /F:n /N:n /O /P /Q /S:size /X:prefix filename…

`/D:`dir	output directory
`/E`	no error messages
`/F:`n	extension numbering format
`/N:`n	number of splits
`/O`	overwrite existing files
`/P`	output to source file’s path
`/Q`	quietly
`/S:`size	split size
`/X:`prefix	extension prefix
filename…	files to split

BSPLIT divides a file into multiple smaller files. You can split at a specified size (/S:), or into a specified number of files (/N:). You cannot combine /N: and /S:.

You must supply a filename. Wildcards and directory aliases are supported, and you may have more than one filename on the command line. The output directory defaults to the current directory.

BSPLIT is short for “binary split”. It splits files by byte size. It does not support splitting by lines or characters. If the input file contains text it may be divided within a line, or possibly even within a character.

/D:dir specifies the directory that the split files will be written to. If this directory does not exist, BSPLIT will attempt to create it for you.

/P writes the split files to the same directory as the original file. It’s like a shorthand for /D:"%@PATH[filename]". If you don’t specify either /D: or /P, the default is to write the split files to the current directory.

/F:n lets you change the way the output files are numbered. The formats are:

`0`	two decimal digits
`1`	three decimal digits
`2`	four decimal digits
`3`	two hexadecimal digits
`4`	three hexadecimal digits
`5`	four hexadecimal digits
`6`	two letters (base-26)
`7`	three letters (base-26)
`8`	four letters (base-26)

Add 32 for uppercase. If you don’t specify a format, the default is three decimal digits. If you specify a prefix with /X:, the prefix will be inserted at the start of the extension.

/S:size specifies the size of the output files. You may give the size as:

n	bytes
n`k`	thousands of bytes
n`K`	kilobytes (1,024 bytes)
n`m`	millions of bytes
n`M`	megabytes (1,048,576 bytes)
n`g`	billions of bytes
n`G`	gigabytes (1,073,741,824 bytes)

/N:n instead splits the file into n more-or-less equally-sized pieces. You cannot combine /N: and /S:.

rem Break BigFile into 500-kilobyte files: bsplit /s:500K bigfile rem Break BigFile into four more-or-less equal files: bsplit /n:4 bigfile

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; directory aliases are supported

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.
`[C]`	The file has different contents 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.

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.

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

Reference Information:

Paging Options	Supported in several commands.
Range Options	Supported in several commands.
The Highlight Variable	Choose your colors.
Startup Message	And how to suppress it.
Status and Licensing

Paging Options:

Many of the commands in this plugin have a /P option to page output. This option supports two suboptions:

/P:time,lines

time	time in seconds, or (with a trailing `M`) milliseconds
lines	number of lines to display before pausing

Both time and lines are optional. The colon is not required, but you must use the comma if you want to specify lines.

rem Scroll every ten seconds: type /p:10 myfile.txt rem Display ten lines at a time: type /p:,10 myfile.txt rem Display twenty lines at a time, and rem scroll every 2.5 seconds: type /p:2500m,20

At the “Press a key to continue” prompt, most keys will advance by another screenful (or lines). But a few keys behave differently:

`A` or `C`	turns off paging, and scrolls continuously
`Esc` or `Ctrl`-`C`	aborts the current command
`/`	scrolls half a screen, or half of lines
`1` to `9`	scrolls that many lines, e.g. `3` scrolls three lines

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 2¹⁰, 2²⁰, 2³⁰, 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

If the Highlight environment variable is not defined, the plugin will check the registry for a value named Highlight of type REG_SZ. The plugin will search, in this order:

• `HKEY_CURRENT_USER\Software\JPPlugins\FileUtils`	(affects this plugin only)
• `HKEY_CURRENT_USER\Software\JPPlugins`	(affects several of my plugins)

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://charlesdye.net/dl/fileutils.zip.

`/A:`attribs	filter by attributes
`/C:`hash	checksum and hash algorithms; see below
`/D`	disable highlight
`/N:`flags	disable features; see below
`/O:`flags	omit features; see below
`/P`	page output
`/S`	look in subdirectories for matching files
`/T:`mode	time display mode; see below
`/[`range`]`	many range options are supported
file	wildcards, directory aliases, include lists, and `@`file lists are supported

`C`	disable highlight
`D`	do not search into hidden directories
`F`	suppress file-not-found errors
`J`	do not search into junctions
`Z`	do not search into system directories

`A`	omit attributes
`C`	omit checksums
`D`	omit file descriptions
`E`	omit text file encoding
`H`	omit file version header
`I`	omit image file info
`L`	omit link targets
`P`	omit Windows properties
`S`	omit document summary information
`T`	omit time stamps
`V`	omit version information
`X`	omit executable information
`Z`	omit sizes

`CRC32`	`CKSUM`	`MD5`
`SHA1`	`SHA256`	`SHA384`
	`SHA512`

`A`	show the last-access time stamp
`C`	show the creation time stamp
`M`	show the last-modified time stamp
`D`	default: localize time stamps as TCC and CMD.EXE do
`L`	local times, taking DST time changes into account
`U`	Coordinated Universal Time

`/C`	select the ‘Contents’ tab
`/F`	select the ‘Favorites’ tab
`/S`	select the ‘Search’ tab
`/S:`text	select the ‘Search’ tab and search for text
`/V`	show detailed plugin version info
topic	the page to display

`/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

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.

n	which information to return; see below
filename	the image file to examine

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

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

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

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

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

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

— Quick Links —