TimeStamp plugin for Take Command / TCC / TCC/LE
beta version 0.93.1 2025-04-22
Charles Dye
Purpose:
This plugin reimplements the TS command and
the @DATEFMT function. It can be used
in older versions of TCC which do not provide TS or @DATEFMT,
including TCC/LE.
TS is very similar to TCC’s internal
TS command, but makes an attempt to identify the encoding of the
incoming (piped) text. There are a few other minor improvements, including
support for incremental times, cumulative times, and UTC time stamps.
@DATEFMT is, again, quite similar to
TCC’s, but it supports a much broader range of dates, plus a few new
tokens and
modifiers, and C-style
character escapes.
Note that the TS command is almost always used to receive
text from a pipe, and pipe commands run in a new shell. If you want to pipe
to TS, you must ensure that this plugin is loaded in the new
shell, e.g. by copying TimeStamp.dll
to TCC’s PlugIns directory.
Installation:
To use this plugin, copy TimeStamp.dll and
TimeStamp.chm to some known location on your hard
drive. (If you are still using the 32-bit version of Take Command, take
TimeStamp-x86.dll instead of
TimeStamp.dll.) Load the .DLL file with a
PLUGIN /L command, for example:
plugin /l c:\bin\tcmd\test\timestamp.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 Command: | ||||
|---|---|---|---|---|
TS | ||||
| New Function: | ||||
@DATEFMT | ||||
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. |
Examples are shown in a gray box:
rem This is an example:
ping localhost | ts
Some command options take an argument. These are shown with a colon between the
option and its argument: /A:arg
If you like, you may substitute an equals sign for the colon: /A=arg
This is handy if the arg is a filename, and you want to use tab completion to
enter the filename.
Or you can omit the colon: /Aarg
New Command:
TS — Add time stamps to lines from
a pipe.
Syntax:
TS /CP:n /D /F /I /S /T /U "format"
/CP:n | code page (for non-Unicode text) |
/D | include the date |
/F | add a final footer line |
/I | show incremental times (since the previous line) |
/S | show cumulative times (since the start time) |
/T | include the time |
/U or /UTC | Coordinated Universal Time |
| format | format string, as in @DATEFMT; quote it and double all percent signs |
TS reads lines from a pipe, and prepends the current time
to each.
If you give a format string, any /D
or /T will be ignored.
If you do not specify any of /D /T /I /S or format,
the default behavior is to include both the date and the time.
• Important: Remember that pipe commands run in a new shell! To pipe to this command, you must ensure that this plugin is loaded in the new shell, e.g. by copying the plugin .DLL to TCC’s PlugIns directory.
• Note: All options except
/D, /T, and format
are new, and not supported by TCC’s internal TS command.
To be compatible with TCC, do not use any option other than /D,
/T, or format.
/CP:n
lets you specify a code page for non-Unicode text. You can give a code page
number, e.g. /CP:1252, or else the letter A
for the current ANSI (Windows) code page, or O for the current
OEM (console) code page. If you do not specify any /CP: code
page option, the default is the current OEM code page.
/F adds a final footer line when the
pipe closes. This would be useful to measure any delay between the last line
printed, and completion of the input command.
New Function:
@DATEFMT — Writes a date and time
using a format string.
Syntax:
%@DATEFMT[date time,format]
| date time | the date and time to format |
| format | string with format specifiers |
Enter the date in ISO 8601 format, and the time in 24-hour format. Use an asterisk for the current date and time. The time is optional. If you specify a date without a time, the default time is midnight.
The supported range of dates is 1601-01-01 through 9999-12-31.
| Enter the date as: | |
|---|---|
yyyy-mm-dd | ISO 8601 format |
yyyy-Www-d | ISO 8601 week-day format |
yyyy-nnn | ISO 8601 ordinal format |
+0 | today |
+1 | tomorrow |
+2 | the day after tomorrow |
-1 | yesterday |
-2 | the day before yesterday, etc. |
| Enter the time as: | |
hh:mm:ss.ddd | 24-hour format, using only the separators shown |
hh:mm:ss | milliseconds are optional |
hh:mm | seconds and milliseconds are optional |
| Optionally followed by: | |
Z | to indicate Coordinated Universal Time |
| (otherwise it’s local) | |
| Or else: | |
* | for the current date and time |
** | for the current date and time UTC |
The format string may include:
| Token: | # | O | Expands to: | Example: |
|---|---|---|---|---|
%A | local day-of-the-week name, full | Saturday | ||
%a | local day-of-the-week name, abbreviated | Sat | ||
%B | local month name, full | November | ||
%b | local month name, abbreviated | Nov | ||
%C | ✓ | century (year / 100) | 19 | |
%c | local short date and time, as per Control Panel | 11/5/1955 6:15:00 AM | ||
%#c | local long date and time, as per Control Panel | Saturday, November 5, 1955 6:15:00 AM | ||
%D | ✓ | date in US format; same as %m/%d/%y | 11/05/55 | |
%d | ✓ | ✓ | day of the month (integer) | 05 |
%e | ✓ | ✓ | day of the month (leading space if 1 digit) | 5 |
%F | ✓ | date in ISO 8601 format, %Y-%m-%d | 1955-11-05 | |
%G | ✓ | ISO 8601 week-numbering year 1 | 1955 | |
%g | last two digits of ISO week-numbering year 1 | 55 | ||
%H | ✓ | ✓ | hour (24-hour format) | 06 |
%h | local month name, abbreviated (same as %b) | Nov | ||
%I | ✓ | ✓ | hour (12-hour format) | 06 |
%J | day number (1 = January 1, 1601) | 129604 | ||
%j | ✓ | ✓ | day of the year | 309 |
%K | ✓ | day of the week, 1 (Sunday) — 7 (Saturday) | 7 | |
%k | ✓ | ✓ | hour (24-hour format, leading space if 1 digit) | 6 |
%L | ✓ | milliseconds | 000 | |
%l | ✓ | ✓ | hour (12-hour format, leading space if 1 digit) | 6 |
%M | ✓ | minute (integer) | 15 | |
%m | ✓ | ✓ | month (integer) | 11 |
%N | ✓ | conventional century: (year + 99) / 100 | 20 | |
%n | newline character | |||
%P | local AM or PM indicator (lowercase) | am | ||
%p | local AM or PM indicator | AM | ||
%Q | ISO year-day format; same as %Y-%j | 1955-309 | ||
%#Q | ISO week-day format; same as %G-W%V-%u | 1955-W44-6 | ||
%R | ✓ | time in 24-hour format, without seconds | 06:15 | |
%r | time in 12-hour format | 06:15:00 AM | ||
%S | ✓ | seconds (integer) | 00 | |
%s | seconds after the Unix epoch | -446726700 | ||
%T | ✓ | time in 24-hour format | 06:15:00 | |
%t | tab character | |||
%U | ✓ | Sunday-based week number 2 | 44 | |
%u | ✓ | ISO 8601 day of the week 1 | 6 | |
%V | ✓ | ✓ | ISO 8601 week number 1 | 44 |
%v | ✓ | date in VMS format; same as %e-%b-%Y | 5-Nov-1955 | |
%W | ✓ | Monday-based week number 2 | 44 | |
%w | day of the week, 0 (Sunday) — 6 (Saturday) | 6 | ||
%X | time in local format, as per Control Panel | 6:15:00 AM | ||
%#X | time in local 24-hour format | 06:15:00 | ||
%x | date in local short format, as per Control Panel | 11/5/1955 | ||
%#x | date in local long format, as per Control Panel | Saturday, November 5, 1955 | ||
%Y | ✓ | year | 1955 | |
%y | ✓ | year modulo 100 | 55 | |
%Z | time zone name | Pacific Standard Time | ||
%#Z | time zone one-letter code 3 | U | ||
%z | time zone offset from UTC, HHMM | -0800 |
Note that you will need to double the percent signs to prevent variable expansion from eating them. Other characters in format will be included as-is.
1 These follow the ISO 8601 week-numbering scheme: every week begins on Monday, ends on Sunday, and belongs to the year in which the majority of its days fall. Monday is day 1, Sunday is day 7.
2 %U and %W count
weeks beginning with Sunday (%U) or Monday (%W). Week
1 begins with the first Sunday (Monday) in the year. If the year does not begin
with a Sunday (Monday), then days before the first Sunday (Monday) return a
week number of 0.
3 %#Z returns a letter code
for the time zone, ranging from Y for UTC-12 through M
for UTC+12. UTC returns Z. If the current time zone is more than
12 hours ahead of or behind UTC, or if it is not an even hour offset, this token
returns -.
There are also several modifier characters which may be included in a token, between the percent sign and the letter:
| Modifier: | Effect: | When returning: |
|---|---|---|
# | suppress leading zeros or spaces | numeric values |
O | roman numerals | numeric values limited to 1 — 9999 |
? | append an English ordinal suffix | numeric values |
E | English | names of months and days only |
! | force uppercase | strings containing letters |
, | force lowercase | strings containing letters |
~ | use local digit forms | any value containing ASCII digits |
If a token is marked with a ✓ in the second column,
you can include a number sign between the percent sign and the letter to suppress leading
zeros or spaces. For example, %H may return the hour with a leading zero;
%#H returns the hour with no leading zero.
In a few cases, e.g. %#c, %#X, and %#x,
the number sign does not suppress leading zeros but instead changes the meaning of the token.
These special cases have separate lines in the list of tokens
above.
If a token is marked with a ✓ in the third column,
you can add an uppercase letter O between the percent sign and the letter
to return a value using Roman numerals. This format only works with a few tokens: those
which return a numeric value always greater than zero and less than ten thousand.
%H and %k are a special case, as the hour can be zero. If
the hour is 0 (midnight), then %OH and %Ok will return
XXIV.
Occasionally you may want an ordinal number. Put a question mark between the percent sign and the letter to append an (English) ordinal suffix:
%B %d | March 08 | |
%B %?d | March 08th | |
%B %#?d | March 8th | You can combine modifiers; |
%B %?#d | March 8th | the order is not significant. |
%B %O?d | March VIIIth |
You can get English names, rather than local names,
for months and days with E. This modifier only works with
%a, %A, %b, %h, and
%B.
If a token returns a string, you can also use an exclamation point to make the string all uppercase, or a comma to make it all lowercase:
%B | March |
%!B | MARCH |
%,B | march |
%B %O,d | March viii |
You can use the ~ modifier
to replace ASCII digits with local digit forms. This will only be useful
if (A) your locale specifies alternate digits forms, and (B) your font
includes the appropriate glyphs. I’m not aware of any region in
western Europe or the Americas where the first is true. This feature
might be useful with Arabic or Thai:
echo %@datefmt[*,%%#c]
الخميس، 8 مارس 2001 6:22:00 ص
echo %@datefmt[*,%%#~c]
الخميس، ٨ مارس ٢٠٠١ ٦:٢٢:٠٠ ص
You can use backslash escapes to include special characters in the format string:
| Escape: | To insert: | Example: |
|---|---|---|
\nnn | octal character, up to 777 | \101 → A |
\xhhhh | hexadecimal character, up to FFFF | \x41 → A |
\a | \x07 alert (bell) | |
\b | \x08 backspace | |
\e | \x1b ASCII escape | |
\f | \x0c form feed | |
\n | \x0a newline | |
\p | \x25 percent sign | |
\q | \x22 double quote | |
\r | \x0d carriage return | |
\t | \x09 tab | |
\v | \x0b vertical tab | |
\uxxxx | Unicode character, up to U+FFFF | \u03a3 → Σ |
\Uxxxxxxxx | Unicode character, up to U+10FFFF | \U1f63a → 😺 |
\\ | \x5c backslash | |
\- | nothing (empty string) | |
\char | any other character: use it literally |
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.
TimeStamp 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 this plugin from https://charlesdye.net/dl/timestamp.zip.