Sift plugin for Take Command / TCC

beta version 0.71.2.3     2024-10-09

Charles Dye

Purpose:

This plugin provides a quick way to find the n largest, smallest, oldest, or newest files in one or more directories or directory trees, and sort them into an array variable. It adds one new command, SIFT; one new internal variable, _SIFT; and one function, @SIFT.

Note that because this plugin returns results in an array variable, it is incompatible with the free TCC/LE. TCC/LE does not support array variables; trying to load this plugin will fail with an error message.

Installation:

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

plugin /l c:\bin\tcmd\sift\sift.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 command: SIFT

New variable: _SIFT

New function: @SIFT

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 Command:

SIFT — Returns a sorted list of files in an array.

Syntax:
SIFT /A:attribs /C:sep /I /R /T:stamp /U /V /Z n criterion array filespec…

/A:attribs	select files by attributes (the default is all files):
	A - not Archived
	C - Compressed
	E - Encrypted
	H - Hidden
	I - not Indexed
	O - Offline
	R - Read-only
	S - System
	- - a hyphen inverts attributes which follow
/C:sep	Character separating the time from the date
/I	return date stamps in ISO 8601 format, YYYY-MM-DD
/R	recurse into subdirectories
/T:stamp	selects which date stamp to use:
	A - last Access
	C - Creation
	W - last Write (the default)
/U	return date stamps as UTC (not localized)
/V	dump the array to stdout when done
/Z	localize date stamps dumbly, like DIR and Explorer
n	the number of files to return, 1 — 4096; defaults to 10
criterion	the quality used to find and sort files:
	/L or LARGEST — find the largest n files (the default)
	/S or SMALLEST — find the smallest n files
	/O or OLDEST — find the oldest n files
	/N or NEWEST — find the newest n files
array	name of the array to create and fill
filespec…	wildcard filespecs to match
/F	return fully qualified filenames
/NC	do not insert commas in file sizes
/ND	do not recurse into hidden directories; only useful with /R
/NI	do not include Descript.ion files
/NJ	do not recurse into junctions; only useful with /R

filespecs may use directory aliases, wildcards including character sets in square brackets, and include lists. If you do not specify any filespec, then * (all files in the current directory) will be supplied by default.

An n-by-3 array will be created to hold the resulting list. (If an array by the same name already exists, that array will be lost.) Column 0 of the array holds filenames, column 1 holds the files’ sizes, and column 2 holds their date stamps. The filenames returned in column 0 will be fully qualified if either /F or /R was specified, or if more than one filespec was supplied; otherwise filenames are stored without paths. The date stamp selected by /T: is returned in column 2, and is also used for sorting if OLDEST or NEWEST is specified.

If LARGEST is specified or there is no criterion, files will be stored in the array in decreasing order of size, i.e. row 0 will hold the largest file, row 1 will hold the next-largest, and so on. If SMALLEST is specified, then files will be stored in increasing order by size. If OLDEST is used, then files will be sorted into chronological order; and NEWEST, in reverse chronological order. If multiple files have the same size or the same date stamp, then the first one discovered “wins” — which one is found first depends on the filesystem.

sift 20 largest bigdlls c:\windows\system32\*.dll

… finds the 20 largest .DLL files in C:\Windows\System32, and sorts them into a 20-by-3 array named BIGDLLS.

Only the array name is mandatory:

sift big


… is legal, and will sort the 10 largest files in the current directory into a 10-by-3 array named BIG.

New Variable:

_SIFT — Returns the number of files found by the last successful SIFT command.

Syntax:
%_SIFT

If SIFT has not yet been called, _SIFT returns -1. If SIFT fails for some reason (bad syntax?) then the value returned by _SIFT is unchanged.

New Function:

@SIFT — Returns the full name of the single largest (smallest, etc.) matching file.

Syntax:
%@SIFT[filespec,criterion,attribs,flags,stamp]

criterion	L, S, O, or N for largest, smallest, oldest, newest; defaults to L
attribs	supported attributes are -ACEHIORS
flags	bitmapped: 1 recurse, 2 no junctions, 4 no hidden directories, 128 exclude Descript.ion files
stamp	A, C, or W for last access, creation, or last write; defaults to W

The @SIFT function provides an easy way to find the single largest, smallest, oldest, or newest matching file in a directory or directory tree, without the overhead of an array. It returns a fully-qualified filename. (It only returns a filename; if you want to get the size or time stamps of the file, call TCC’s internal @FILEDATE, @FILESIZE, and @FILETIME functions as usual. This function is potentially very slow, so calling it multiple times to retrieve different information about the same file would be a bad plan.)

You must supply a filespec; it may include a directory alias.

If no matching files are found, this function returns an empty string.

• Note: While this particular function does not use an array, you still cannot load this plugin in TCC/LE or in older shells which don’t support arrays.

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 bugs, you can report them in the JP Software support forum.

Sift 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 https://charlesdye.net/dl/sift.zip.