EmailAdx plugin for Take Command / TCC / TCC/LE
beta version 0.36.0 2023-10-13
Charles Dye
Purpose:
This plugin provides a new function
@EMAILADX which attempts to validate
an email address. There is also one new command,
EMAILADX, which controls parsing options
for @EMAILADX. A pair of convenience functions,
@EMAILDPART and
@EMAILLPART, return the domain part
and the local part of an email address respectively, after performing the same
basic validation.
Installation:
To use this plugin, copy EmailAdx.dll to
some known location on your hard drive. (If you are using the 64-bit
version of Take Command, take EmailAdx-x64.dll
instead of EmailAdx.dll.) Load the plugin
with a PLUGIN /L command, for example:
plugin /l c:\bin\tcmd\test\emailadx.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.
Plugin Features:
New functions: @EMAILADX,
@EMAILDPART, @EMAILLPART
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. |
New Command:
EMAILADX — Display or change
email address parsing options.
Syntax:
EMAILADX /2: /B: /C: /D /H: /I: /L: /M: /N: /P: /R /S /T: /Z
/2:yn | allow any two-letter top-level domain; only significant with /T | Yes |
/B:yn | strip off angle brackets around email address | No |
/C:yn | stricter list of allowed characters | No |
/D | restore the original plugin default settings | |
/H:yn | allow high-order (non-ASCII) characters in the local part | No |
/I:yn | accept a dotted quad as the domain | No |
/L:yn | allow ‘localhost’ as the domain | No |
/M:yn | look up the MX record for the domain | No |
/N:yn | allow ‘noreply’ as the local part | No |
/P:yn | allow ‘postmaster’ as the local part | No |
/R | restore saved settings from the registry | |
/S | save current settings to the registry as the new defaults | |
/T:yn | check the top-level domain against a list | Yes |
/Z | quietly (do not display current or changed settings) |
This command sets options used by the plugin functions to parse email
addresses. It affects the behavior of
@EMAILADX,
@EMAILDPART, and
@EMAILLPART.
/I: Standards allow a dotted-quad
IP address as a domain name in an email address. You can choose whether to
allow or reject such addresses. /I:Y allows dotted quads as
domain names; /I:N rejects them. The default is /I:N.
Even if you choose to allow dotted quads for domain names, some bogus addresses
like 127.0.0.1 or 255.255.255.255 will be rejected anyway.
/T: The plugin can check the
address’s top-level domain against a list of recognized TLDs. You can
supply your own list in a text file, or the plugin can use its own built-in
list. To supply your own list of top-level domains, create a text file named
TLDs.txt in the same directory as the plugin
.DLL file. Put one top-level domain on each line;
leading periods are not required. If you want to create a comment line, start
it with a semicolon. If you do not supply your own list, the built-in list of
TLDs recognized by the plugin is:
| .com |
| .org |
| .net |
| .edu |
| .gov |
| .mil |
| .info |
| .name |
To enable checking top-level domains, specify /T:Y. To disable
this feature use /T:N. The default is Y.
/2: If you check top-level
domains, you may want to allow all two-letter TLDs, rather than including a
complete list of national domains. Use /2:Y to allow all two-letter
top-level domains, or /2:N to disable this feature. The default is
/2:Y. This option is only useful if you are checking top-level
domains with /T:Y; it has no effect with /T:N.
/2:Y will work whether you are reading a list of TLDs from a file
or using the built-in default list.
/M: As a further validation step,
you can check DNS to see whether the given domain advertises a mail server.
/M:Y enables this check, /M:N disables it; the default
is /M:N. If you enable this test, an email address will be rejected
as invalid if the plugin cannot find an MX server for the given domain. This
might happen for a number of reasons, including network errors. If the domain
name is a dotted quad, this test will not be performed (the dotted quad is
assumed to be the MX server). On the other hand, this test will fail if there
is an MX record for the domain, and it resolves to ‘localhost’
or a bogus address like 0.0.0.0 or 127.0.0.1.
/N: and /P: By
default, the plugin will reject any email address beginning with
‘noreply@’ or ‘postmaster@’. The first is often used
for email-sending equipment and software, where there is no real account for a
human being to check. ‘Postmaster’ is a special account that is
assumed to exist on any mail server, but is seldom used for general email
purposes. You can enable such addresses with /N:Y and /P:Y
respectively.
rem Allow noreply@... and postmaster@... addresses:
emailadx /n:y /p:y
New Functions:
@EMAILADX — Attempts to
validate an email address.
Syntax:
%@EMAILADX[text]
| text | string to be validated |
This function attempts to verify that the input string represents a valid
email address. It does not check that the address itself is active;
it only verifies that the string is a legal address that might be assigned to
some user. It does not send email to the address or check for a bounce
message. Unless you specify /M:Y, it does not perform any
network access at all.
You can set various parsing and validation options with the
EMAILADX command.
If the input text appears to be a valid email
address, this function returns 0. On any error, it returns a
nonzero number.
rem Prompt the user for an email address:
do until %@emailadx[%email] == 0
input Enter user email: %%email
enddo
@EMAILDPART — Returns the
domain part of an email address.
Syntax:
%@EMAILDPART[text]
| text | email address |
This function performs the same parsing and validity checks as
@EMAILADX. On any error — if
the text does not appear to be a valid email
address — @EMAILDPART returns an empty string.
set domain=%@emaildpart[bilbo@foo.com]
@EMAILLPART — Returns the
local part of an email address.
Syntax:
%@EMAILLPART[text]
| text | email address |
This function performs the same parsing and validity checks as
@EMAILADX. On any error — if
the text does not appear to be a valid email
address — @EMAILLPART returns an empty string.
set userid=%@emaillpart[bilbo@foo.com]
Error Codes:
Here are some of the codes which can be returned by the
@EMAILADX function. This list may not
be complete and is subject to change. (@EMAILDPART and
@EMAILLPART do not return numeric
error codes; they return an empty string on any error.)
| 0 | all well — address appears to be valid |
| 1024 | empty string |
| 1025 | string too long |
| 1040 | no local part |
| 1041 | no domain part |
| 1042 | missing @ sign |
| 1043 | multiple @ signs |
| 1044 | bad period |
| 1045 | bad character in local part |
| 1046 | bad username (noreply or postmaster) |
| 1047 | missing top-level domain |
| 1048 | unknown top-level domain |
| 1049 | dotted quad not allowed |
| 1050 | bad dotted quad |
| 1051 | localhost not allowed |
| 1052 | no MX record |
| 1053 | bad hostname |
| 1054 | bad quote |
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.
EmailAdx 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/emailadx.zip.