HTags plugin for Take Command / TCC / 4NT
beta version 0.60.4 2013-04-24
Charles Dye
Purpose:
Generating HTML from within a TCC batch file can be tricky, since many of the characters required for HTML — less-than and greater-than signs and ampersands in particular — also have special meaning to TCC. This plugin provides functions which make it easy to write HTML tags and entities from Take Command.
Installation:
To use this plugin, copy HTAGS.DLL to some known location on your
hard drive. Load the plugin with a PLUGIN /L command. For
example:
plugin /l c:\bin\tcmd\htags\htags.dll
If you copy the .DLL to a subdirectory named PlugIns
within your Take Command program directory, the plugin will be loaded
automatically by each new instance of TCC.
Theory:
This plugin takes advantage of Unicode’s “Halfwidth and Fullwidth Forms” block, specifically the characters at U+FF01 through U+FF5E. These characters correspond to ASCII characters 0x21 through 0x7E, and when redirected to a file with //UnicodeOutput=No, they will be automatically translated back to their ASCII equivalents. But TCC doesn’t assign any significance to the characters in this range, so they can be safely used in a batch file. In particular, HTags makes heavy use of U+FF05 (fullwidth percent sign), U+FF06 (fullwidth ampersand), U+FF1C (fullwidth less-than sign), and U+FF1E (fullwidth greater-than sign.) Using these characters gives us HTML tags and entities which can be used in batch files and functions, displayed on screen or redirected to a file, without tripping over TCC’s special syntax characters.
Depending on your font, whether TCC is running in a standalone console window or within a Take Command tab, the phase of the moon, and general Windows witchiness, these characters may or may not appear the same on-screen as their ASCII equivalents. If you see empty boxes instead of normal-looking characters, try a different font. The default “Raster Fonts” works well for me, although it’s not terribly attractive.
One consequence of this approach is that TCC’s Unicode output option must be turned off. If //UnicodeOutput=Yes, then redirected characters will not be translated into ASCII, and you’ll get strange characters in the output file. When any of the new functions are called the plugin will check that Unicode output is disabled, and display an error message if it isn’t.
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 Functions:
@DEENTITIZE — Removes
any HTML entities from the input string, substituting equivalent characters
where available.
Syntax: @DEENTITIZE[string]
| string | the text to process |
The appearance of this function’s output depends on both the character set and the display font. In general, if an entity shows up as a question mark, either the corresponding character does not exist in the current character set, or else this plugin just doesn’t recognize the entity. If an entity appears as a hollow rectangle, it’s usually because the display fonts doesn’t contain a glyph for that character.
C:\> echo %@deentitize[“Here Today — Here Tomorrow!” ®]
"Here Today -- Here Tomorrow!" (R)
C:\>
@DOCTYPE — Returns an HTML
document type tag.
Syntax: @DOCTYPE[n]
| n | which document type to return: |
| 0: HTML 5 (default) | |
| 1: HTML 4.01 strict | |
| 2: HTML 4.01 transitional | |
| 3: HTML 4.01 frameset | |
| 16: XHTML 1.0 strict | |
| 17: XHTML 1.0 transitional | |
| 18: XHTML 1.0 frameset |
C:\> echo %@doctype[]
<!DOCTYPE HTML>
C:\>
@ENTAG — Entitizes a
string, and encloses it in open-and-close HTML tags.
Syntax: @ENTAG[tag,string]
| tag | an HTML tag |
| string | the string to enclose in tags |
tag will be used verbatim for the opening
tag. For the closing tag, a slash will be prefixed, and
tag will be truncated at the first space (if
any). The string will be entitized according
to the current plugin settings. It is possible to nest one
@ENTAG function within the string
argument of another @ENTAG.
C:\> echo %@entag[p,This is a test.]
<p>This is a test.</p>
C:\> echo %@entag[p class="demo","This is a test", he said.]
<p class="demo">“This is a test”, he said.</p>
C:\> echo %@entag[p,"This is %@entag[em,only] a test", he said.]
<p>“This is <em>only</em> a test”, he said.</p>
C:\>
@ENTITIZE — Searches a
string for special characters, and replaces them with HTML entities.
Syntax: @ENTITIZE[string]
| string | the string to be entitized |
See also the HTAGS command, which allows you to change options controlling entitization.
C:\> echo %@entitize["Quick & Silver's"]
“Quick & Silver’s”
C:\>
@HCOMMENT — Returns an
HTML comment.
Syntax: @HCOMMENT[string]
| string | the text of the comment |
C:\> echo %@hcomment[Hello, world.]
<!-- Hello, world. -->
C:\>
@HEXDEC — Replaces
two-digit hex codes with characters in the input string.
Syntax: @HEXDEC[string]
| string | the string to be decoded |
Only sequences of a percent sign followed by two valid hexadecimal digits will be replaced. Anything else (e.g. a percent sign followed by a single hex digit) will be returned unchanged. The null character, %00, is not allowed.
C:\> echo %@hexdec[This%%20is%%20a%%20test.]
This is a test.
C:\>
@HEXENC — Replaces
troublesome characters in a string with hexadecimal codes.
Syntax: @HEXENC[string]
| string | the string to be hex-encoded |
The characters not replaced with hex codes are letters, digits,
and these symbols: #$+-./:;=?@_ To define a
different list of characters not to hex-encode, create an environment variable
named HEXENC_KEEP.
C:\> echo %@hexenc[This is a test.]
This%20is%20a%20test.
C:\>
@MAKEENTITY — Returns
an HTML representation for a character.
Syntax: @MAKEENTITY[char¦string]
| char | a single character, or |
| string | the name of an HTML entity |
If a single character is specified, the plugin will attempt to find a matching named entity, e.g. &. Failing that, it will return a decimal numeric entity, e.g. @. If a multicharacter string is specified, the plugin will assume it’s the name of an HTML entity, and just wrap it fore-and-aft with an ampersand and a semicolon.
C:\> echo %@makeentity[copy] %@makeentity[@]
© @
C:\>
Syntax: @TAG[tag]
| tag | an HTML tag |
The argument is simply wrapped in less-than and greater-than signs.
C:\> echo %@tag[p class="bodytext"]
<p class="bodytext">
C:\>
Plugin Commands:
ARRAYTABLE — Dumps a
two-dimensional array to stdout as an HTML table.
Syntax: ARRAYTABLE /L:n /H:text /K:class /S:style /CKn:class /CSn:style /LK:class /LS:style arrayname
/L | insert line numbers; /L:n starting at n (default 0) |
/H:text | create a header row |
/K:class | CSS class name for the TABLE tag |
/S:style | CSS style info for the TABLE tag |
/CKn:class | CSS class name for column n TD tags |
/CSn:style | CSS style info for column n TD tags |
/LK:class | CSS class name for line-number TD tags; implies /L |
/LS:style | CSS style info for line-number TD tags; implies /L |
/RK0:class | CSS class name for TD tags of even-numbered rows |
/RK1:class | CSS class name for TD tags of odd-numbered rows |
/RS0:class | CSS style info for TD tags of even-numbered rows |
/RS1:class | CSS style info for TD tags of odd-numbered rows |
| arrayname | a two-dimensional array variable |
The arrayname is required. The variable should
be declared and filled with data before running ARRAYTABLE. The
first dimension of the array is the row number; the second is the column number.
Array cells will be entitized; any empty cell will be stored as a non-breakable
space.
• Note: This command is disabled in TCC/LE, and in 4NT/Take Command prior to v10. It is only available in versions which support array variables.
HTAGS — Displays or changes
plugin options.
Syntax: HTAGS QUOTES:n SPACES:n DASH:n APOS:n DEFAULTS
| Option: | 0 | 1 | 2 | 3 | default |
QUOTES | don’t change | always replace with " | “ or ” (best guess) | 2 | |
SPACES | don’t change | always replace with | best guess | 2 | |
DASH | don’t change | replace -- with — | 1 | ||
APOS | don’t change | replace with ' | replace with ' | ‘ or ’ (best guess) | 3 |
DEFAULTS | resets all options to their default states | ||||
At this time, all of the options set or reported by HTAGS
control details of how characters in strings are converted to HTML
entities. QUOTES controls how the ASCII double-quote
character " is handled; SPACES controls the ASCII
space character; DASH determines whether or not a double dash, surrounded
by spaces, is converted to an — and APOS controls the ASCII
apostrophe, '. DEFAULTS resets all of the above options
to their default values.
If no options are specified, HTAGS will display the current
settings and the plugin version.
Size Limits:
All strings in this plugin are limited to 16,383 characters. Attempting to pass or return a string longer than 16,383 characters may result in an error message, silent truncation, or possibly even a crash.
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.
HTags 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://prospero.unm.edu/dl/htags.zip or ftp://prospero.unm.edu/htags.zip.