Miscellaneous

Various TWAPI ancillary commands

SYNOPSIS

package require twapi

expand_environment_strings STRING

export_public_commands

format_message ?options?

get_command_line

get_command_line_args COMMANDLINE

get_version ?-patchlevel?

import_commands

large_system_time_to_secs_since_1970 SYSTEMTIMEVALUE ?BOOLEAN?

large_system_time_to_timelist SYSTEMTIMEVALUE

parseargs ARGLISTVAR OPTLIST ?-ignoreunknown? ?-nulldefault? ?-maxleftover MAXLEFTOVER?

secs_since_1970_to_large_system_time SECONDS

timelist_to_large_system_time TIMELIST

DESCRIPTION

This module provides miscellaneous utility commands.

get_version returns TWAPI version information. export_public_commands and import_commands enable export and import of commands defined in the TWAPI namespace. parseargs parses an argument list based on specified options. get_command_line retrieves the command line passed to the process. get_command_line_args parses a command line using Windows conventions. The command expand_environment_strings replaces environment variables in a string with their values. format_message formats a operating system or application message.

Commands

expand_environment_strings STRING

Returns the string formed by replacing all environment variable references in STRING with their values. Environment variable references are in the form %ENVIRONMENTVAR%. References to undefined environment variables are not replaced.

export_public_commands

Export public commands in the twapi:: namespace. The commands in the twapi:: namespace are not exported by default.

format_message ?options?

Formats and returns a message string based on a format string. The format string may be directly supplied, obtained from a loaded library or module, or the system message tables. The format string may contain format insert specifiers of the form %N where N is a number between 1 and 99. The format specifier is replaced by the corresponding positional parameter. The format specifier %0 is treated specially as indicating that a newline character is not to be appended to the result. See FormatMessage in the Windows SDK for more details regarding this command including format specifiers. The command takes the following options:

-module MODULE	Specifies that the format string is to be loaded from the module identified by MODULE. MODULE may either be a handle returned from a command such as load_library or the path to a DLL. If this option is specified, options -messageid and -langid must also be specified. This option cannot be used with the -fmtstring option.
-fmtstring FORMATSTRING	Specifies that FORMATSTRING should be used as the format string for the message. Cannot be used with the -module option.
-messageid MESSAGEID	Specifies the message identifier of the format string. This option cannot be used with the -fmtstring option.
-langid LANGID	Specifies the language identifier to be used in constructing the message. This option cannot be used with the -fmtstring option.
-includesystem	Specifies that the system message tables should also be searched in addition to the message tables in the module specified by -module. This option cannot be used with the -fmtstring option.
-params PARAMLIST	Specifies a list of positional parameters that are to be used to replace the %N format insert sequences in the format string. If the number of parameters does not match the number of escape sequences, a Tcl exception may be generated.
-ignoreinserts	If specified, the %N format insert sequences are not replaced in the returned string.
-width MAXLINEWIDTH	By default, the returned string contains the same line breaks as in the original format string. The -width option may be used to control the maximum line width in the created message. If MAXLINEWIDTH is between 1 and 254, the command will insert line end characters at appropriate points in the message. In this case, line end characters in the original message are ignored. However, hard coded line end characters, specified as %n in the format string are kept. A MAXLINEWIDTH value of -1 also ignores line end characters while keeping the hard coded %n line end specifiers, but does not insert and line end characters to limit the line length and to terminate the message. A value of 0 for MAXLINEWIDTH is identical to the default behaviour.

Warning: This command requires all insert placeholders to be strings. Decimal format specifiers such as %|u! will not result in the correct decimal value being inserted.

get_command_line

Returns the command line of the current process. This may be passed to the get_command_line_args function to split the line into arguments.

get_command_line_args COMMANDLINE

Parses COMMANDLINE as per Windows command line conventions and returns a list of the parsed arguments. The main advantage of this over using the argv and argv0 variables in tclsh and wish is that this call will correctly handle Unicode arguments.

get_version ?-patchlevel?

Without any arguments, the command returns the major/minor TWAPI version number in the form MAJOR.MINOR. If the option -patchlevel is specified, the returned string includes patchlevel and release information similar to the Tcl info patchlevel command, for example, 1.0.2 for final release of version 1.0 patch 2, 1.0b3 for the third beta release of version 1.0 and 1.0a3 for the third alpha release of version 1.0.

import_commands

Imports all public commands in the twapi:: namespace into the caller's namespace.

large_system_time_to_secs_since_1970 SYSTEMTIMEVALUE ?BOOLEAN?

Some Windows functions return time as the number of 100 nanosecond units since Jan 1, 1601. The command converts such time values to seconds since the epoch Jan 1, 1970. If BOOLEAN is false (default), an integral number of seconds is returned. Otherwise, the fractional part is also returned.

large_system_time_to_timelist SYSTEMTIMEVALUE

Some Windows functions return time as the number of 100 nanosecond units since Jan 1, 1601. The command converts such time values to a list of 7 elements representing the year, month, day, hour, minutes, seconds and milliseconds.

parseargs ARGLISTVAR OPTLIST ?-ignoreunknown? ?-nulldefault? ?-maxleftover MAXLEFTOVER?

Parses the options specified in a list of arguments. ARGLISTVAR is the name of a variable in the caller's scope that contains a list of arguments. Option names are case-sensitive.

OPTLIST specifies the valid options allowed and is list of option specifiers. Each option specifier is a list of up to 3 elements and takes the following form:

OPTNAME?.OPTTYPE? ?DEFAULTVALUE ?VALIDVALUELIST??

OPTNAME is the name of the option (without a leading -) and is required. OPTTYPE should be separated from the name with a . and specifies the type of the option. It must have one of the following values: arg, bool, int, or switch. In the first three cases, the argument following the option is taken as the value of the option and must be of an appropriate type: an arbitrary string, a boolean value (0, 1, off, on, false, true) or an integer respectively. If the option type is switch, or is not specified at all, then the option is not associated with any value and is treated as a binary switch.

DEFAULTVALUE, specifies a default value to be assumed for the option if it is not present in ARGLISTVAR. This is ignored for options of type switch.

If VALIDVALUELIST is specified, it is treated as a list of allowed values for the option. If an option's value is not in the list, the command will return an error. VALIDVALUELIST is ignored if the option type is bool or switch.

The command returns a list of the form OPTION VALUE OPTION VALUE.... If the -nulldefault option is not present, only options that are present in ARGLISTVAR, or have a default value specified, or are of type switch are included in the returned result. If the -nulldefault option is present, then the returned list also includes values for options that are not present - 0 for options of type int and bool, and an empty string for arguments of type arg.

As a side effect, the variable ARGLISTVAR is modified to remove the parsed options and associated values. If the -maxleftover option is specified, the command will raise a Tcl error if the number of arguments left over after parsing the options is more than MAXLEFTOVER.

The command will normally generate a Tcl error if the arguments include an unknown option (an argument that begins with a - character and is not in OPTLIST). If the -ignoreunknown option is specified to the command, unknown options in ARGLISTVAR are ignored instead of an error being generated and are not removed from ARGLISTVAR.

secs_since_1970_to_large_system_time SECONDS

This command converts SECONDS which is the number of seconds since the epoch Jan 1, 1970 to the number of 100 nanoseconds since Jan 1, 1601.

timelist_to_large_system_time TIMELIST

Converts TIMELIST to the number of 100 nanoseconds since Jan 1, 1601. TIMELIST must be a list of 7 elements representing the year, month, day, hour, minutes, seconds and milliseconds.

COPYRIGHT

Copyright © 2004-2009 Ashok P. Nadkarni