Fortune plugin for Take Command / TCC / TCC/LE
Version 1.2.4.2 2023-10-16
Charles Dye
Purpose:
This plugin provides an easy way to grab a random line from a text file.
This kind of feature is most often used to display silly messages at the
command line (from a “fortune-cookie” file), but it can also be
used for more serious tasks such as grabbing a new password from a dictionary.
This functionality is available through either a FORTUNE
command which displays a random line to standard output, or a
@FORTUNE function which returns text to
be used in any command. Provisions are made for not repeating the last n
lines retrieved, and for biasing the selection to make some lines more likely
than others.
Installation:
To use this plugin, copy Fortune.dll to
some known location on your hard drive. (If you are still using the 32-bit
version of Take Command, take Fortune-x86.dll
instead of Fortune.dll.) Load the plugin
with a PLUGIN /L command, for example:
plugin /l c:\bin\tcmd\test\fortune.dll
If you copy this file to a subdirectory named PlugIns within your Take Command program directory, TCC will load it automatically at startup.
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. |
Plugin Features:
New variables: _LASTFLINE,
_LASTFORTUNE
New Command:
FORTUNE — Display a random
line from a text file.
Syntax:
FORTUNE /B /H /N:n /NB /Q /T:size /W:width filename
/B | Biased (earlier lines are more likely) |
/H | Hide attributions |
/N:n | Number of previous fortunes to remember |
/NB | do not write a Byte Order Mark at the start |
/T:size | width of Tab stops |
/Q | replace Quote marks and apostrophes |
/W:width | desired columns for word-wrap |
| filename | the file from which to pick a line |
The FORTUNE command will display a line from the specified
file to standard output. Blank lines will not be included.
If the filename is not specified,
FORTUNE will look for an environment variable named
FORTUNE and use its value as a filename. If
you don’t supply a filename and there is no
FORTUNE variable set, you will get an error message.
If you prefix an @ sign to the filename,
it will be treated as a list of fortune-cookie files, one per line.
FORTUNE will open the original filename,
retrieve a random line, and use that as the new filename. In this way, you
can maintain several different fortune-cookie files and return a random
fortune from any of them.
FORTUNE stores the line numbers of the last few lines it
has displayed, and attempts to avoid repeating lines. By default, the
last ten line numbers will be saved; once you have seen a line, it should
not recur in the next ten invocations. You can use /N:n
to store more (or fewer) past line numbers. If you specify /N:0,
then past line numbers will not be remembered, and lines can repeat
immediately. Up to 256 recent line numbers can be retained for each of
sixteen files.
(Note that you will see repeated lines in fewer than n calls if the text file is too short. To avoid repeats, the file should have at least n + 4 lines.)
If output is to the screen, FORTUNE attempts to wrap long
lines to fit the console width. If output is redirected, then long lines
will not be wrapped. You can override this default behavior with
/W:width. The
width may be 0 or 40 — 256, where
0 disables word wrap.
By default, any tab characters in the selected line will be replaced
with enough spaces to reach the next tab stop. Tab stops are every four
columns by default. You can change the default tab stop width using
/T:size. For example,
/T:8 will use tab stops every eight columns. If you specify
/T:0, tab expansion is disabled and tabs are treated like any
other whitespace character; note that doing this can confuse line
wrapping.
If /H is specified, any text following a section mark §
(character 167) in the line will be discarded. If the line does not contain a
section mark, then /H has no effect. See
Special Characters for more information.
If /Q is specified, generic ASCII apostrophes ( ' )
and quotation marks ( " ) will be replaced with
Unicode open and close quote marks ( ‘ ’
and “ ” ). The
modified string may or may not look different from the original, depending on
how you use it and the font used to display it. If it is redirected to a file
and //UnicodeOutput=No, then the fancy Unicode quotes will be smashed right
back into ASCII. (Worse yet, under some versions of Windows the Unicode single
open-quote character may be mangled to a grave accent….) If the
modified string is ECHOed to the console and the console font doesn’t
support the relevant Unicode characters, then again the Unicode quotes will be
lost. In Take Command, curly quotes must be supported by both the tab-window
font (Options / Configure Take Command / Tabs / Font) and also
the underlying console font (detach a tab to check this.)
fortune quotes.txt
rem Make this file the default:
set fortune=%@truename[quotes.txt]
fortune
rem Define a key alias:
alias @@f12=`@cls %+ if plugin fortune fortune /q`
option //normalkey=f12
New Function:
@FORTUNE — Return a
random line from a text file.
Syntax:
%@FORTUNE[filename,n,flags]
| filename | the file from which to pick a line; this parameter is required |
| n | the number of previous fortunes to remember; defaults to 4 |
| flags | 1 = biased (earlier lines are more likely) |
| 128 = hide attributions |
The @FORTUNE function returns a line from the specified
file. Blank lines will not be included.
@FORTUNE stores the line numbers of the last few lines it
has returned, and attempts to avoid repeating lines. By default, the
last ten line numbers will be saved; once a line has been returned, it should
not recur in the next ten invocations. You can use the n
parameter to store more (or fewer) past line numbers. If you specify 0 for
the second parameter, then past line numbers will not be remembered and
lines can repeat immediately. Up to 256 recent line numbers can be
retained for each of sixteen files.
(Note that you will get repeated lines in fewer than n calls if the text file is too short. To avoid repeats, the file should have at least n + 4 lines.)
If bit 7 of flags is set, any text after a section mark § (character 167) will be discarded. If the line does not contain a section mark, then bit 7 has no effect. See Special Characters for more information.
set newpass=%@fortune[passwords.txt,20]
say %@fortune[paranoid.txt]
New Variables:
_LASTFLINE — Returns the
line number of the last line returned by either FORTUNE
or @FORTUNE.
The line number is zero-based. If neither FORTUNE
nor @FORTUNE has returned a line yet,
_LASTFLINE returns -1.
_LASTFORTUNE — Repeats
the last line displayed by the FORTUNE
command.
The entire line will be returned as is; no word-wrapping, tab expansion,
or other character substitution is performed. If the
FORTUNE command has not yet displayed
a line in the current session, this variable is set to an empty string. (Note
that the @FORTUNE function does
not set this value — only the command affects it.)
Special Characters:
FORTUNE handles two characters specially. The pilcrow ¶
forces a line break. The section mark § indicates an attribution; the
following text will be displayed two lines down, indented and set off with a
dash. See the included text file quotes.txt for
an example of how to use these characters.
In most Windows text editors, you can type a pilcrow by holding down the Alt key and typing 0182 on the numeric keypad; you can insert a section mark with Alt-0167. (These characters may look different in your text file, depending on the font and character set in use.)
Environment Variables:
These environment variables may be used to change the plugin’s default behavior:
FORTUNE: | the default filename for the FORTUNE command |
NOLOADMSG: | if defined, suppresses the startup message |
The following variables specify a Unicode character used to replace an ASCII
quote character in the FORTUNE command when
/Q is specified. The value of the variable may be a single
character; a decimal value 32 through 65535; or a hexadecimal value 0x20
through 0xFFFF.
OPENQUOTE: | replaces the ASCII double-quote ( " ) at the start of a quotation; the default is 0x201C ( “ ). |
CLOSEQUOTE: | replaces the ASCII double-quote ( " ) at the end of a quotation; the default is 0x201D ( ” ). |
OPENSQUOTE: | replaces the ASCII apostrophe ( ' ) at the start of a quotation; the default is 0x2018 ( ‘ ). |
CLOSESQUOTE: | replaces the ASCII apostrophe ( ' ) at the end of a quotation; the default is 0x2019 ( ’ ). |
APOSTROPHE: | replaces the ASCII apostrophe ( ' ) within a word; the default is 0x2019 ( ’ ). |
'OKINA: | replaces the ASCII apostrophe ( ' ) between two vowels; the default is 0x2018 ( ‘ ). |
Note that the variable name 'OKINA begins, ironically enough, with
an apostrophe. To disable ‘okinas, SET 'OKINA=0X2019
(or the same value as the apostrophe).
Registry Use:
This plugin keeps history information in the registry under
HKCU\Software\JPPlugins\Fortune. This information is used to
avoid repeating recent lines too quickly. This history is common to both
the FORTUNE command and the
@FORTUNE function; a line recently
returned by one will be avoided by the other. Since it’s stored in
the registry, the history will persist across TCC sessions and even
reboots.
Up to 256 recent lines may be stored, for up to sixteen files.
Size Limits:
This plugin can handle text files of up to 131,072 lines. If a file contains more lines, only the first 131,072 lines can be returned; later lines will be ignored. Lines may be up to 8,191 characters long.
Input arguments to commands and functions are limited to 8,191 characters. Filenames, after expansion, may be up to 16,383 characters long.
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
Changes:
| Version | Date | Changes |
|---|---|---|
| 1.2.4.2 | 2023-10-16 | Tweaked version output to include VER_PATCH. |
| 1.2.4.1 | 2023-10-12 | Updated the plugin’s web address. |
| 1.2.4 | 2021-07-31 | Switched the filenames; now Fortune.dll is the x64 build. Tweaked the version info resource to include the platform (x64 or x86). Use UPX to compress both builds. |
| 1.2.3 | 2016-01-22 | Added an undocumented /LF (a stupid workaround for a stupid issue). |
| 1.2.2 | 2013-04-24 | Updated the plugin’s web address. |
| 1.2.1 | 2013-02-26 | Fix for 4NT 8. |
| 1.2.0 | 2012-10-18 | Moved pilcrow and attribution support out of the line-wrap routine; write a BOM when Unicode output is redirected; added /NB. |
| 1.1.4 | 2012-08-27 | Tiny tweak to /Q. |
| 1.1.3 | 2012-04-16 | Adds a kludge to support ‘okinas. |
| 1.1.2 | 2012-03-13 | Documents the environment variables which affect quote replacement. |
| 1.1.1 | 2012-03-08 | Attempts to detect UTF-8 without a BOM. |
| 1.1.0 | 2012-03-05 | Hacks to handle UTF-8, Windows-1252. |
| 1.0.11 | 2011-11-14 | /Q recognizes two-digit year abbreviations. |
| 1.0.10 | 2011-09-13 | More tweaks to /Q; now double hyphens are replaced with em dashes. |
| 1.0.9 | 2011-08-05 | Tweaks to FORTUNE /Q. |
| 1.0.8 | 2011-08-03 | Added _LASTFLINE variable. |
| 1.0.7 | 2011-08-02 | Added /Q to FORTUNE. |
| 1.0.6 | 2011-06-15 | No changes to the code; compress 32-bit DLL with UPX instead of MPRESS. |
| 1.0.6 | 2011-06-08 | Do not disable bias for very short files. |
| 1.0.5 | 2011-06-07 | Added _LASTFORTUNE; changed attributions to not use tab characters; minor tweak to fallback RNG. |
| 1.0.4 | 2011-05-28 | Minor tweak to device-file detection. |
| 1.0.3 | 2011-05-24 | Internal changes. |
| 1.0.2 | 2011-05-12 | Do not strip whitespace from the start of the line; improved handling of tab characters; increased maximum number of lines, size of MRU list. |
| 1.0.1 | 2011-05-09 | Check that the specified filename refers to an actual disk file. |
| 1.0.0 | 2011-05-04 | First release. |
Status and Licensing:
This plugin is Copyright © 2023, Charles Dye. Unaltered copies of the binary and documentation files may be freely distributed without restriction. I make no guarantee and give no warranty for its operation. Use it at your own risk. If you do find a problem, you can report it in the JP Software support forum.
I claim no copyright on the demonstration text files included. Do with them as you will — but removing or changing the authors’ names would be in poor taste.
Download:
You can download the current version of the plugin from http://charlesdye.net/dl/fortune.zip.