Fortune plugin for Take Command / TCC / 4NT

Version 1.2.3     2016-01-22

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 using the 64-bit version of Take Command, take Fortune-x64.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, the plugin will be loaded automatically when TCC starts.

Syntax Note:

The syntax definitions in the following text use these conventions for clarity:

BOLD CODEindicates text which must be typed exactly as shown.
CODEindicates optional text, which may be typed as shown or omitted.
Bold italicnames a required argument; a value must be supplied.
Regular italicnames an optional argument.
ellipsis…after an argument means that more than one may be given.

Plugin Features:

New command: FORTUNE

New function: @FORTUNE

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

/BBiased (earlier lines are more likely)
/HHide attributions
/N:nNumber of previous fortunes to remember
/NBdo not write a Byte Order Mark at the start
/T:sizewidth of Tab stops
/Qreplace Quote marks and apostrophes
/W:widthdesired columns for word-wrap
filenamethe 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]

filenamethe file from which to pick a line; this parameter is required
nthe number of previous fortunes to remember; defaults to 4
flags1 = 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:


VersionDateChanges
1.0.02011-05-04first release
1.0.12011-05-09check that the specified filename refers to an actual disk file
1.0.22011-05-12do 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.32011-05-24internal changes
1.0.42011-05-28minor tweak to device-file detection
1.0.52011-06-07added _LASTFORTUNE; changed attributions to not use tab characters; minor tweak to fallback RNG
1.0.62011-06-08do not disable bias for very short files
1.0.62011-06-15no changes to the code; compress 32-bit DLL with UPX instead of MPRESS
1.0.72011-08-02added /Q to FORTUNE
1.0.82011-08-03added _LASTFLINE variable
1.0.92011-08-05tweaks to FORTUNE /Q
1.0.102011-09-13more tweaks to /Q; now double hyphens are replaced with em dashes
1.0.112011-11-14/Q recognizes two-digit year abbreviations
1.1.02012-03-05hacks to handle UTF-8, Windows-1252
1.1.12012-03-08attempts to detect UTF-8 without a BOM
1.1.22012-03-13documents the environment variables which affect quote replacement
1.1.32012-04-16adds a kludge to support ‘okinas
1.1.42012-08-27tiny tweak to /Q
1.2.02012-10-18moved pilcrow and attribution support out of the line-wrap routine; write a BOM when Unicode output is redirected; added /NB
1.2.12013-02-26fix for 4NT 8
1.2.22013-04-24updated the plugin’s web address
1.2.32016-01-22added an undocumented /LF (a stupid workaround for a stupid issue)

Status and Licensing:

This plugin is Copyright © 2016, 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://prospero.unm.edu/dl/fortune.zip or ftp://prospero.unm.edu/fortune.zip.