DateFmt plugin for Take Command / TCC / TCC/LE
beta version 0.90.21 2023-10-12
Charles Dye
Purpose:
This plugin implements a replacement for TCC’s internal
@DATEFMT function. It adds a few new tokens and features
which do not exist in the TCC function, and supports a much broader
range of dates.
Note that this plugin does not affect those internal commands which
call @DATEFMT internally: DATE, TIME,
PROMPT, TS. These commands will continue to use
TCC’s built-in time formatting code, not the function provided by
this plugin.
Installation:
To use this plugin, copy DateFmt.dll to
some known location on your hard drive. (If you are still using the 32-bit
version of Take Command, take DateFmt-x86.dll
instead of DateFmt.dll.) Load the .DLL file
with a PLUGIN /L command, for example:
plugin /l c:\bin\tcmd\test\datefmt.dll
If you copy these files to a subdirectory named PlugIns within your Take Command program directory, it will be loaded automatically when TCC starts.
Syntax Note:
The syntax definitions in this help file 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 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 | Thursday | ||
%a | local day-of-the-week name, abbreviated | Thu | ||
%B | local month name, full | March | ||
%b | local month name, abbreviated | Mar | ||
%C | ✓ | century (year / 100) | 20 | |
%c | local short date and time, as per Control Panel | 3/8/2001 6:22:00 AM | ||
%#c | local long date and time, as per Control Panel | Thursday, March 8, 2001 6:22:00 AM | ||
%D | ✓ | date in US format; same as %m/%d/%y | 03/08/01 | |
%d | ✓ | ✓ | day of the month (integer) | 08 |
%e | ✓ | ✓ | day of the month (leading space if 1 digit) | 8 |
%F | ✓ | date in ISO 8601 format, %Y-%m-%d | 2001-03-08 | |
%G | ✓ | ISO 8601 week-numbering year 1 | 2001 | |
%g | last two digits of ISO week-numbering year 1 | 01 | ||
%H | ✓ | ✓ | hour (24-hour format) | 06 |
%h | local month name, abbreviated (same as %b) | Mar | ||
%I | ✓ | ✓ | hour (12-hour format) | 06 |
%J | day number (1 = January 1, 1601) | 146164 | ||
%j | ✓ | ✓ | day of the year | 067 |
%K | ✓ | day of the week, 1 (Sunday) — 7 (Saturday) | 5 | |
%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) | 22 | |
%m | ✓ | ✓ | month (integer) | 03 |
%N | ✓ | conventional century: (year + 99) / 100 | 21 | |
%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 | 2001-067 | ||
%#Q | ISO week-day format; same as %G-W%V-%u | 2001-W10-4 | ||
%R | ✓ | time in 24-hour format, without seconds | 06:22 | |
%r | time in 12-hour format | 06:22:00 AM | ||
%S | ✓ | seconds (integer) | 00 | |
%s | seconds after the Unix epoch | 984054120 | ||
%T | ✓ | time in 24-hour format | 06:22:00 | |
%t | tab character | |||
%U | ✓ | Sunday-based week number 2 | 09 | |
%u | ✓ | ISO 8601 day of the week 1 | 4 | |
%V | ✓ | ✓ | ISO 8601 week number 1 | 10 |
%v | ✓ | date in VMS format; same as %e-%b-%Y | 8-Mar-2001 | |
%W | ✓ | Monday-based week number 2 | 10 | |
%w | day of the week, 0 (Sunday) — 6 (Saturday) | 4 | ||
%X | time in local format, as per Control Panel | 6:22:00 AM | ||
%#X | time in local 24-hour format | 06:22:00 | ||
%x | date in local short format, as per Control Panel | 3/8/2001 | ||
%#x | date in local long format, as per Control Panel | Thursday, March 8, 2001 | ||
%Y | ✓ | year | 2001 | |
%y | ✓ | year modulo 100 | 01 | |
%Z | time zone name | Mountain Standard Time | ||
%#Z | time zone one-letter code 3 | T | ||
%z | time zone offset from UTC, HHMM | -0700 | ||
%@ | one-letter day of week; Sun = U, Thu = R | R |
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]
الخميس، ٨ مارس ٢٠٠١ ٦:٢٢:٠٠ ص
This plugin adds syntax to pad or truncate returned values to a specified number of characters:
| Append: | To: |
|---|---|
{{n.a}} | left-pad the value |
{{-n.a}} | right-pad the value |
{{~n.a}} | center the value |
{{n.a:c}} | left-pad the value with character c |
{{-n.a:c}} | right-pad the value with character c |
{{~n.a:c}} | center the value using character c |
n is the minimum number of characters, 1 to 1023. Values shorter than n characters will be padded.
a is the maximum number of characters, 1 to 1023. Values longer than a characters will be truncated.
n and a are both optional. If a is less than n, a will be ignored.
c may be given in either decimal, or hex with
a leading 0x. It should be in the range of 32 to 65535, or (hex)
0x20 to 0xffff. If it’s missing or invalid, the default value is 32
(space).
echo %@datefmt[*,%%A, %%B %%d]
Tuesday, July 06
echo %@datefmt[*,%%A{{10}}, %%B{{10}} %%d]
Tuesday, July 06
echo %@datefmt[*,%%A{{-10}}, %%B{{-10}} %%d]
Tuesday , July 06
echo %@datefmt[*,%%A{{5.5}}, %%B{{5.5}} %%d]
Tuesd, July 06
echo %@datefmt[*,%%A{{10:95}}, %%B{{10:95}} %%d]
___Tuesday, ______July 06
echo %@datefmt[*,%%A{{10:0xb7}}, %%B{{10:0xb7}} %%d]
···Tuesday, ······July 06
echo %@datefmt[*,%%A{{~10:0xb7}}, %%B{{~10:0xb7}} %%d]
·Tuesday··, ···July··· 06
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.
DateFmt 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/datefmt.zip.