UChars plugin for Take Command / TCC / TCC/LE

beta version 0.99.0     2020-07-30

Charles Dye

Purpose:

This plugin adds a few new functions to support Unicode characters. They behave similarly to TCC’s familiar native functions, but support high-order Unicode characters — characters outside the Basic Multilingual Plane, with values greater than 0xFFFF.

These functions also expect and return hexadecimal character values, as God and the Unicode Consortium intended.

Installation:

To use this plugin, copy UChars.dll to some known location on your hard drive. (If you are using the 32-bit version of Take Command, take UChars-x86.dll instead of UChars.dll.) Load the .DLL file with a PLUGIN /L command, for example:

plugin /l c:\bin\tcmd\test\uchars.dll

If you copy the .DLL file to a subdirectory named PlugIns within your Take Command program directory, the plugin will be loaded automatically when TCC starts.

Plugin Features:

New functions:

Function:Like:Returns:
@UCHAR@CHARcharacters with the specified hex values
@UCODE@UNICODEhex values of characters in a string (no prefix)
@UCODEX@UNICODEhex values of characters in a string (leading 0x)
@ULEN@LENthe number of characters in a string

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.

New Functions:

@UCHAR — Returns Unicode characters with the specified values.

Syntax:
%@UCHAR[value value…]

valuea hexadecimal number

This function behaves like @CHAR, except that the input values are assumed to be hexadecimal, and characters outside the Basic Multilingual Plane are supported. You may prefix values with 0x or U+ but neither is required. With or without either prefix, each value will be parsed as hexadecimal. Separate values with spaces.

Values must be in the range of 1 to 10FFFF.

echo %@uchar[16a6 16d6 16eb 16bb 16a9 16d2 16d2 16c1 16cf]



@UCODE — Returns the hexadecimal values of characters in a string.

Syntax:
%@UCODE[string]

stringthe string to examine

This function behaves like @UNICODE, except that it returns values as hexadecimal (without any prefix), and characters outside the Basic Multilingual Plane are supported. A few characters, including the backquote and the closing square bracket, will need to be escaped.

echo %@ucode[This is a test.]

echo %@ucode[😎]



@UCODEX — Returns the hexadecimal values of characters in a string.

Syntax:
%@UCODEX[string]

stringthe string to examine

This function behaves like @UNICODE, except that it returns values as hexadecimal with a leading 0x, and characters outside the Basic Multilingual Plane are supported. A few characters, including the backquote and the closing square bracket, will need to be escaped.

echo %@ucodex[This is a test.]

echo %@ucodex[💀]



@ULEN — Returns the number of Unicode characters in a string.

Syntax:
%@ULEN[string]

stringthe string to be counted

This function is almost the same as @LEN, except that it counts surrogate pairs as single characters. (Surrogates which are not properly paired will be counted as separate ‘characters’.)

echo %@ulen[😺]

echo %@ulen[%@char[0xd83d 0xde00]]



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.

UChars 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/uchars.zip or ftp://prospero.unm.edu/uchars.zip.