neulab/tldr huggingface dataset:
bsearch fileId key ?retvar? ?compare_proc? Search an opened file fileId containing lines of text sorted into ascending order for a match.  Key contains the string to match. If retvar is specified, then the line from the file is returned in retvar, and the command returns 1 if key was found, and 0 if it wasn't.  If retvar is not specified or is a null name, then the command returns the line that was found, or an empty string if key wasn't found.
By default, the key is matched against the first white-space separated field in each line.  The field is treated as an ASCII string.  If compare_proc is specified, then it defines the name of a Tcl procedure to evaluate against each line read from the sorted file during the execution of the bsearch command.  Compare_proc takes two arguments, the key and a line extracted from the file. The compare routine should return a number less than zero if the key is less than the line, zero if the key matches the line, or greater than zero if the key is greater than the line.  The file must be sorted in ascending order according to the same criteria compare_proc uses to compare the key with the line, or errouenous results will occur.
copyfile ?-bytes num|-maxbytes num? fromFileId toFileId Copies the rest of the file specified by fromFileId, starting from its current position, to the file specified by toFileId, starting from its current position.
If -bytes is specified, then num bytes are copied.  If less than num bytes are available, an error is returned.  If -maxbytes is specified, then num bytes are copied but no error is returned if less are available.
The command returns the number of bytes that were copied.
The -bytes option is particularly useful for mixing binary data in with ASCII commands or data in a data stream.
chmod [-fileid] mode filelist Set permissions of each of the files in the list filelist to mode, where mode is an absolute numeric mode or symbolic permissions as in the UNIX chmod(1) command.  To specify a mode as octal, it should be prefixed with a "0" (e.g. 0622).
If the option -fileid is specified, filelist is a list of open file identifiers rather than a list of file names.  This option is not available on all Unix systems.  Use the infox have_fchmod command to determine if this functionallity is available.
chown [-fileid] owner|{owner group} filelist Set owner of each file in the list filelist to owner, which can be a user name or numeric user id.  If the first parameter is a list, then the owner is set to the first element of the list and the group is set to the second element.  Group can be a group name or numeric group id.  If group is {}, then the file group will be set to the login group of the specified user.
If the option -fileid is specified, filelist is a list of open file identifiers rather than a list of file names.  This option is not available on all Unix systems.  Use the infox have_fchown command to determine if this functionallity is available.
chgrp [-fileid] group filelist Set the group id of each file in the list filelist to group, which can be either a group name or a numeric group id.
dup fileId ?targetFileId? Duplicate an open file.  A new file id is opened that addresses the same file as fileId.
If targetFileId is specified, the the file is dup to this specified file id.  Normally this is stdin, stdout, or stderr. The dup command will handle flushing output and closing this file. The new file will be buffered, if its needs to be unbuffered, use the fcntl command to set it unbuffered.
If fileId is a number rather than a Tcl file id, then the dup command will bind that file to a Tcl file id.  This is usedful for accessing files that are passed from the parent process.  The argument ?targetFileId? is not valid with this operation.
fcntl fileId attribute ?value? This command either sets or clears a file option or returns its current value.  If value are not specified, then the current value of attribute is returned. The following attributes may be specified:
RDONLY - The file is opened for reading only. (Get only)
WRONLY - The file is opened for writing only.  (Get only)
RDWR - The file is opened for reading and writing.  (Get only)
READ - If the file is readable. (Get only).
WRITE - If the file is writable. (Get only).
APPEND - The file is opened for append-only writes.  All writes will be forced to the end of the file.
NONBLOCK - The file is to be accessed with non-blocking I/O.  See the read system call for a description of how it affects the behavior of file reads.
CLOEXEC - Close the file on an process exec.  If the execl command or some other mechanism causes the process to do an exec, the file will be closed if this option is set.
NOBUF - The file is not buffered. If set, then there no stdio buffering for the file.
LINEBUF - Output the file will be line buffered. The buffer will be flushed when a newline is written, when the buffer is full, or when input is requested.
The APPEND, NONBLOCK, and CLOEXEC attributes may be set or cleared by specifying the attribute name and a value 1 to set the attribute and 0 to clear it.
The NOBUF and LINEBUF attributes may only be set (a value of 1) and only one of the options may be selected.  Once set, it may not be changed.  These options should be set before any I/O operations have been done on the file or data may be lost.
flock options fileId ?start? ?length? ?origin? This command places a lock on all or part of the file specified by fileId.  The lock is either advisory or mandatory, depending on the mode bits of the file.  The lock is placed beginning at relative byte offset start for length bytes.  If start or length is omitted or empty, zero is assumed.  If length is zero, then the lock always extents to end of file, even if the file grows.  If origin is "start", then the offset is relative to the beginning of the file. If it is "current", it is relative to the current access position in the file.  If it is "end", then it is relative to the end-of-file (a negative is before the EOF, positive is after).  If origin is omitted, start is assumed.
-read - Place a read lock on the file.  Multiple processes may be accessing the file with read-locks.
-write - Place a write lock on the file.  Only one process may be accessing a file if there is a write lock.
-nowait - If specified, then the process will not block if the lock can not be obtained.  With this option, the command returns 1 if the lock is obtained and 0 if it is not.
See your system's fcntl system call documentation for full details of the behavior of file locking.  If locking is being done on ranges of a file, it is best to use unbuffered file access (see the fcntl command).
for_file var filename { code } This procedure implements a loop over the contents of a file.  For each line in filename, it sets var to the line and executes code.
The break and continue commands work as with foreach.
For example, the command
for_file line /etc/passwd {echo $line}
would echo all the lines in the password file.
funlock fileId ?start? ?length? ?origin? Remove a locked from a file that was previously placed with the flock command.  The arguments are the same as for the flock command, see that command for more details.
fstat fileId ?item?|?stat arrayvar? Obtain status information about an open file.
The following keys are used to identify data items:
o atime - The time of last access.
o ctime - The time of last file status change
o dev - The device containing a directory for the file.  This value uniquely identifies the file system that contains the file.
o gid - The group ID of the file's group.
o ino - The inode number.  This field uniquely identifies the file in a given file system.
o mode - The mode of the file (see the mknod system call).
o mtime - Time when the data in the file was last modified.
o nlink - The number of links to the file.
o size - The file size in bytes.
o tty - If the file is associated with a terminal, then 1 otherwise 0.
o type - The type of the file in symbolic form, which is one of the following values: file, directory, characterSpecial, blockSpecial, fifo, link, or socket.
o uid - The user ID of the file's owner.
If one of these keys is specified as item, then that data item is returned.
If stat arrayvar is specified, then the information is returned in the array arrrayvar.  Each of the above keys indexes an element of the array containing the data.
If only fileId is specified, the command returns the data as a keyed list.
The following values may be returned only if explicitly asked for, it will not be returned with the array or keyed list forms:
o remotehost - If fileId is a TCP/IP socket connection, then a list is returned with the first element being the remote host IP address.  If the remote host name can be found, it is returned as the second element of the list.  The remote host IP port number is returned as the this element.
o localhost - If fileId is a TCP/IP socket connection, then a list is returned with the first element being the local host IP address.  If the local host name can be found, it is returned as the second element of the list.  The local host IP port number is returned as the this element.
ftruncate [-fileid] file newsize Truncate a file to have a length of at most newsize bytes.
If the option -fileid is specified, file is an open file identifier, otherwise it is a file path.
This command is not available or not fully functional if the underlying operating system support is not available.  The command infox have_truncate will indicate if this command may truncate by file path.  The command infox have_ftruncate will indicate if this command may truncate by file id.
lgets fileId ?varName? Reads the next Tcl list from the file given by fileId and discards the terminating newline character.  This command differs from the gets command, in that it reads Tcl lists rather than lines.  If the list contains a newline, then that newline will be returned as part of the result.  Only a newline not quoted as part of the list indicates the end of the list.  There is no corresponding command for outputing lists, as puts will do this correctly.  If varName is specified, then the line is placed in the variable by that name and the return value is a count of the number of characters read (not including the newline).  If the end of the file is reached before reading any characters then -1 is returned and varName is set to an empty string.  If varName is not specified then the return value will be the line (minus the newline character) or an empty string if the end of the file is reached before reading any characters.  An empty string will also be returned if a line contains no characters except the newline, so eof may have to be used to determine what really happened.
frename oldPath newPath Renames oldPath to newPath.  This command does not support renaming across file systems.
pipe ?fileId_var_r fileId_var_w? Create a pipe.  If fileId_var_r and fileId_var_r are specified, then pipe will set the a variable named fileId_var_r to contain the fileId of the side of the pipe that was opened for reading, and fileId_var_w will contain the fileId of the side of the pipe that was opened for writing.
If the fileId variables are not specified, then a list containing the read and write fileIdw is returned as the result of the command.
read_file ?-nonewline? fileName read_file fileName numBytes This proecure reads the file fileName and returns the contents as a string.  If -nonewline is specified, then the last character of the file is discarded if it is a newline.  The second form specifies exactly how many bytes will be read and returned, unless there are fewer than numBytes bytes left in the file; in this case, all the remaining bytes are returned.
select readfileIds ?writefileIds? ?exceptfileIds? ?timeout? This command allows an Extended Tcl program to wait on zero or more files being ready for for reading, writing, have an exceptional condition pending, or for a timeout period to expire. readFileIds, writeFileIds, exceptFileIds are each lists of fileIds, as returned from open, to query.  An empty list ({}) may be specified if a category is not used.
The files specified by the readFileIds list are checked to see if data is available for reading. The writeFileIds are checked if the specified files are clear for writing.  The exceptFileIds are checked to see if an exceptional condition has occured (typically, an error).  The write and exception checking is most useful on devices, however, the read checking is very useful when communicating with multiple processes through pipes.  Select considers data pending in the stdio input buffer for read files as being ready for reading, the files do.  not have to be unbuffered.
Timeout is a floating point timeout value, in seconds.  If an empty list is supplied (or the parameter is omitted), then no timeout is set.  If the value is zero, then the select command functions as a poll of the files, returning immediately even if none are ready.
If the timeout period expires with none of the files becomming ready, then the command returns an empty list.  Otherwise the command returns a list of three elements, each of those elements is a list of the fileIds that are ready in the read, write and exception classes.  If none are ready in a class, then that element will be the null list.  For example:
select {file3 file4 file5} {file6 file7} {} 10.5
could return
{file3 file4} {file6} {}
or perhaps
file3 {} {}
write_file fileName string ?string...? This procedure writes the specified strings to the named file.
TCP/IP SERVER ACCESS Commands are provided to access TCP/IP-based servers, and to create them. It is easy to build servers using Extended Tcl that run under inetd, or even servers that run standalone and accept and manage multiple simultaneous connections.  The socket file handles maybe be read using the either the gets or read command and written using either the puts or server_send command.
The fstat remotehost and fstat localhost requests are useful both for clients and servers.  To obtain the host name of the system the script is running on, use id host.
If a TclX script is setup to run under inetd, it is launched with its stdin, stdout and stderr associated with the client socket.  The standard Tcl file ids stdin, stdout and stderr maybe then be used to communicate with the client.
server_connect ?options? host service Open a TCP/IP connection to a server of host on the port specified by service.  The server is then accessed using the standard Tcl file I/O commands.  Host may be a host name or an IP address. Port may be a port number of a service name.
If a destination host name is supplied and more that one address is valid for the host, the host's addresses will be tried in the order returned until one can be connected to, or the list is exhausted.  You may also use the server_info command to obtain the list of valid address.
o -buf - Specifies that the file is buffered.  When writing to the file, the flush command must be used to force data in the buffer to be sent to the server.  Buffered access will result in significantly better performance when reading data, and will also improve the performance of a series of writes done without intervening reads.  The buffering is only used when accessing the file via the gets, read, and puts commands. The server_send command does not use the buffer.
o -nobuf - The file is unbuffered. A single file id, open for both reading and writing, is returned.
o -twoids - Return a pair of file ids in a list.  The first id is open for read access, the second for write access.  The close command must be called against both file ids when you are done using the socket and they maybe closed independently.  This option is primarily intended to implement compatibility procedures for deprecated commands, however it maybe useful for code that needs to independently manage the read and write ends of the socket.
o -myip ipNumber - Define the IP number for your side of the connection.  This is useful for multi-homed hosts (hosts with more than one IP address).  Note that only IP addresses corresponding to network interfaces on your machine may be used.  If -myip is not specified, the operating system will assign the IP number for you.
o -myport portNumber - Define the port number for your side of the connection.  If the port number is already in use, an error will be returned.  If the port number is in the privileged range, the Tcl program will have to be running as superuser, or an error will be returned.
server_create ?options? Creates a TCP/IP server socket on the local machine.  A file handle is returned upon successful creation.  When a connection request is made to the server, the file handle becomes read-ready. Connections can be accepted using server_accept.
The file handle can be detected as read-ready using select, by using fcntl to make the handle nonblocking and then calling server_accept, or by using the Tk fileevent command.
o -backlog count - Maximum length the queue of pending connections may grow to.  If a connection request arrives with the queue full, the client may receive an error with an indication of ECONNREFUSED, or, if the underlying protocol supports retransmission, the request may be ignored so that retries may succeed.  Note that on at least some BSD-based systems the backlog is silently limited to 5, regardless of the value specified.  The default is 5.
o -reuseaddr - Allow reuse of local addresses.
server_accept ?options? fileid Accept a TCP/IP connection to the server socket associated with fileid.  Options are -buf, -nobuf and -twoids.  See the server_connect command for a description of these options.  A file handle (or a pair of file handles when -twoids) is return.
server_info addresses host server_info official_name host server_info aliases host Optain information about a TCP/IP server. The argument host can be either a host name or an IP address.
The following subcommands are recognized:
o addresses - Return the list of IP addresses for host.
o official_name - Return official name for host.
o aliases - Return the list of aliases for host.  (Note that these are IP number aliases, not DNS CNAME aliases. See ifconfig(2).)
server_send ?options? fileid string Send the specified string to the TCP/IP connection corresponding to fileid.  Theserver_send command is provide as an option to puts for writing to a socket as it is better at detecting lost connections and other IP-related error conditions.  File buffering is ignored for server_send. There is no need to flush after a server_send.  The results of mixing server_send with puts without flushing the puts output is indeterminate.
o -nonewline - Don't append a newline character to the end of the message.  The default is to append a newline character.
o -dontroute - Requests that routing be bypassed and the direct interface used (usually used only by diagnostic or routing programs)
o -outofband - Send out-of-band data on the socket.
server_cntl fileid attribute [value] Set or get the value of a socket attribute.
Attributes are:
o KEEPALIVE - Keep connection alive.  If SIGPIPE is enabled, then it is sent if connection is broken and data is written to the socket.  Note that SIGPIPE is set to be ignored by the Tcl library to support pipes to processes in the exec and open commands.  If SIGPIPE is ignored, an error is returned on the write.  Use server_send to detect dropped connections reliably, Boolean value.
If value is specifice, the options is set to that value. Otherwise, the value is returned.
These commands provide a facility to scan files, matching lines of the file against regular expressions and executing Tcl code on a match.  With this facility you can use Tcl to do the sort of file processing that is traditionally done with awk.  And since Tcl's approach is more declarative, some of the scripts that can be rather difficult to write in awk are simple to code in Tcl.
File scanning in Tcl centers around the concept of a scan context.  A scan context contains one or more match statements, which associate regular expressions to scan for with Tcl code to be executed when the expressions are matched.
scancontext ?option? This command manages file scan contexts.  A scan context is a collection of regular expressions and commands to execute when that regular expression matches a line of the file.  A context may also have a single default match, to be applied against lines that do not match any of the regular expressions.  Multiple scan contexts may be defined and they may be reused on multiple files. A scan context is identified by a context handle.  The scancontext command takes the following forms:
scancontext create Create a new scan context.  The scanmatch command is used to define patterns in the context.  A contexthandle is returned, which the Tcl programmer uses to refer to the newly created scan context in calls to the Tcl file scanning commands.
scancontext delete contexthandle Delete the scan context identified by contexthandle, and free all of the match statements and compiled regular expressions associated with the specified context.
scancontext copyfile contexthandle ?filehandle? Set or return the file handle that unmatched lines are copied to. (See scanfile).  If filehandle is omitted, the copy file handle is returned.  If no copy file is associated with the context, {} is returned.  If a file handle is specified, it becomes the copy file for this context.  If filehandle is {}, then it removes any copy file specification for the context.
scanfile ?-copyfile copyFileId? contexthandle fileId Scan the file specified by fileId, starting from the current file position.  Check all patterns in the scan context specified by contexthandle against it, executing the match commands corresponding to patterns matched.
If the optional -copyfile argument is specified, the next argument is a file ID to which all lines not matched by any pattern (excluding the default pattern) are to be written.  If the copy file is specified with this flag, instead of using the scancontext copyfile command, the file is disassociated from the scan context at the end of the scan.
scanmatch ?-nocase? contexthandle ?regexp? commands Specify Tcl commands, to be evaluated when regexp is matched by a scanfile command.  The match is added to the scan context specified by contexthandle.  Any number of match statements may be specified for a give context.  Regexp is a regular expression (see the regexp command).  If -nocase is specified as the first argument, the pattern is matched regardless of alphabetic case.
If regexp is not specified, then a default match is specified for the scan context.  The default match will be executed when a line of the file does not match any of the regular expressions in the current scancontext.
The array matchInfo is available to the Tcl code that is executed when an expression matches (or defaults).  It contans information about the file being scanned and where within it the expression was matched.
matchInfo is local to the top level of the match command unless declared global at that level by the Tcl global command.  If it is to be used as a global, it must be declared global before scanfile is called (since scanfile sets the matchInfo before the match code is executed, a subsequent global will override the local variable).  The following array entries are available:
matchInfo(line) Contains the text of the line of the file that was matched.
matchInfo(offset) The byte offset into the file of the first character of the line that was matched.
matchInfo(linenum) The line number of the line that was matched. This is relative to the first line scanned, which is usually, but not necessarily, the first line of the file.  The first line is line number one.
matchInfo(context) The context handle of the context that this scan is associated with.
matchInfo(handle) The file id (handle) of the file currently being scanned.
matchInfo(copyHandle) The file id (handle) of the file specified by the -copyfile option.  The element does not exist if -copyfile was not specified.
matchInfo(submatch0) Will contain the characters matching the first parenthesized subexpression.  The second will be contained in submatch1, etc.
matchInfo(subindex0) Will contain the a list of the starting and ending indices of the string matching the first parenthesized subexpression. The second will be contained in subindex1, etc.
All scanmatch patterns that match a line will be processed in the order in which their specifications were added to the scan context.  The remainder of the scanmatch pattern-command pairs may be skipped for a file line if a continue is executed by the Tcl code of a preceding, matched pattern.
If a return is executed in the body of the match command, the scanfile command currently in progress returns, with the value passed to return as its return value.
Several extended math commands commands make many additional math functions available in TclX.  In addition, a set of procedures provide command access to the math functions supported by the expr command.
The following procedures provide command interfaces to the expr math functions. They take the same arguments as the expr functions and may take expressions as arguments.
abs         acos        asin       atan2 atan        ceil        cos        cosh double      exp         floor      fmod hypot       int         log10      log pow         round       sin        sinh sqrt        tan         tanh
max num1 num2 ?..numN?
expr max(num1, num2) Returns the argument that has the highest numeric value. Each argument may be any integer or floating point value.
This functionality is also available as a math function max in the Tcl expr command.
min num1 num2 ?..numN?
expr min(num1, num2) Returns the argument that has the lowest numeric value.  Each argument may be any integer or floating point value.
This functionality is also available as a math function min in the Tcl expr command.
random limit | seed ?seedval? Generate a pseudorandom integer number greater than or equal to zero and less than limit.  If seed is specified, then the command resets the random number generator to a starting point derived from the seedval. This allows one to reproduce pseudorandom number sequences for testing purposes.  If seedval is omitted, then the seed is set to a value based on current system state and the current time, providing a reasonably interesting and ever-changing seed.
Extended Tcl provides additional list manipulation commands and procedures.
intersect lista listb Procedure to return the logical intersection of two lists.  The returned list will be sorted.
intersect3 lista listb Procedure to intersects two lists, returning a list containing three lists:  The first list returned is everything in lista that wasn't in listb.  The second list contains the intersection of the two lists, and the third list contains all the elements that were in listb but weren't in lista.  The returned lists will be sorted.
lassign list var ?var...? Assign successive elements of a list to specified variables.  If there are more variable names than fields, the remaining variables are set to the empty string.  If there are more elements than variables, a list of the unassigned elements is returned.
lassign {dave 100 200 {Dave Foo}} name uid gid longName
Assigns name to ``dave'', uid to ``100'', gid to ``200'', and longName to ``Dave Foo''.
lempty list Determine if the specified list is empty.  If empty, 1 is returned, otherwise, 0 is returned.  This command is an alternative to comparing a list to an empty string.
lmatch ?mode? list pattern Search the elements of list, returning a list of all elements matching pattern.  If none match, an empty list is returned.
The mode argument indicates how the elements of the list are to be matched against pattern and it must have one of the following values:
-exact The list element must contain exactly the same string as pattern.
-glob Pattern is a glob-style pattern which is matched against each list element using the same rules as the string match command.
-regexp Pattern is treated as a regular expression and matched against each list element using the same rules as the regexp command.
If mode is omitted then it defaults to -glob.
lrmdups list Procedure to remove duplicate elements from a list.  The returned list will be sorted.
lvarcat var string ?string...? This command treats each string argument as a list and concatenates them to the end of the contents of var, forming a a single list.  The list is stored back into var and also returned as the result.  if var does not exist, it is created.
lvarpop var ?indexExpr? ?string? The lvarpop command pops (deletes) the element indexed by the expression indexExpr from the list contained in the variable var. If index is omitted, then 0 is assumed.  If string, is specified, then the deleted element is replaced by string. The replaced or deleted element is returned.  Thus ``lvarpop argv 0'' returns the first element of argv, setting argv to contain the remainder of the string.
If the expression indexExpr starts with the string end, then end is replaced with the index of the last element in the list.  If the expression starts with len, then len is replaced with the length of the list.
lvarpush var string ?indexExpr? The lvarpush command pushes (inserts) string as an element in the list contained in the variable var.  The element is inserted before position indexExpr in the list. If index is omitted, then 0 is assumed.  If var does not exists, it is created.
If the expression indexExpr starts with the string end, then end is replaced with the index of the last element in the list.  If the expression starts with len, then len is replaced with the length of the list.  Note the a value of end means insert the string before the last element.
union lista listb Procedure to return the logical union of the two specified lists. Any duplicate elements are removed.
Extended Tcl defines a special type of list referred to as keyed lists. These lists provided a structured data type built upon standard Tcl lists.  This provides a functionality similar to structs in the C programming language.
A keyed list is a list in which each element contains a key and value pair.  These element pairs are stored as lists themselves, where the key is the first element of the list, and the value is the second.  The key- value pairs are refered to as fields.  This is an example of a keyed list:
{{NAME {Frank Zappa}} {JOB {musician and composer}}}
If the variable person contained the above list, then keylget person NAME would return {Frank Zappa}.  Executing the command:
keylset person ID 106
would make person contain
{{ID 106} {NAME {Frank Zappa}} {JOB {musician and composer}}
Fields may contain subfields; `.' is the seperator character.  Subfields are actually fields where the value is another keyed list.  Thus the following list has the top level fields ID and NAME, and subfields NAME.FIRST and  NAME.LAST:
{ID 106} {NAME {{FIRST Frank} {LAST Zappa}}}
There is no limit to the recursive depth of subfields, allowing one to build complex data structures.
Keyed lists are constructed and accessed via a number of commands.  All keyed list management commands take the name of the variable containing the keyed list as an argument (i.e. passed by reference), rather than passing the list directly.
keyldel listvar key Delete the field specified by key from the keyed list in the variable listvar.  This removes both the key and the value from the keyed list.
keylget listvar ?key? ?retvar | {}? Return the value associated with key from the keyed list in the variable listvar.  If retvar is not specified, then the value will be returned as the result of the command.  In this case, if key is not found in the list, an error will result.
If retvar is specified and key is in the list, then the value is returned in the variable retvar and the command returns 1 if the key was present within the list.  If key isn't in the list, the command will return 0, and retvar will be left unchanged.  If {} is specified for retvar, the value is not returned, allowing the Tcl programmer to determine if a key is present in a keyed list without setting a variable as a side-effect.
If key is omitted, then a list of all the keys in the keyed list is returned.
keylkeys listvar ?key? Return the a list of the keyes in the keyed list in the variable listvar.  If keys is specified, then it is the name of a key field who's subfield keys are to be retrieve.
keylset listvar key value ?key2 value2 ...? Set the value associated with key, in the keyed list contained in the variable listvar, to value.  If listvar does not exists, it is created.  If key is not currently in the list, it will be added. If it already exists, value replaces the existing value.  Multiple keywords and values may be specified, if desired.
The commands provide additional functionality to classify characters, convert characters between character and numeric values, index into a string, determine the length of a string, extract a range of character from a string, replicate a string a number of times, and transliterate a string (similar to the Unix tr program).
ccollate ?-local? string1 string2 This command compares two strings.  If returns -1 if string1 is less than string2, 0 if they are equal amd 1 if string1 is greater than string2.
If -local is specified, the strings are compared according to the collation environment of the current locale.
cequal string1 string2 This command compares two strings for equality.  It returns 1 if string1 and string2 are the identical and 0 if they are not.  This command is a short-cut for string compare and avoids the problems with string expressions being treated unintentionally as numbers.
cindex string indexExpr Returns the character indexed by the expression indexExpr (zero based) from string.
If the expression indexExpr starts with the string end, then end is replaced with the index of the last character in the string. If the expression starts with len, then len is replaced with the length of the string.
clength string Returns the length of string in characters.  This command is a shortcut for:
string length string
crange string firstExpr lastExpr Returns a range of characters from string starting at the character indexed by the expression firstExpr (zero-based) until the character indexed by the expression lastExpr.
If the expression firstExpr or lastExpr starts with the string end, then end is replaced with the index of the last character in the string.  If the expression starts with len, then len is replaced with the length of the string.
csubstr string firstExpr lengthExpr Returns a range of characters from string starting at the character indexed by the expression firstExpr (zero-based) for lengthExpr characters.
If the expression firstExpr or lengthExpr starts with the string end, then end is replaced with the index of the last character in the string.  If the expression starts with len, then len is replaced with the length of the string.
ctoken strvar separators Parse a token out of a character string.  The string to parse is contained in the variable named strvar.  The string separators contains all of the valid separator characters for tokens in the string.  All leading separators are skipped and the first token is returned.  The variable strvar will be modified to contain the remainder of the string following the token.
ctype ?-failindex var? class string ctype determines whether all characters in string are of the specified class.  It returns 1 if they are all of class, and 0 if they are not, or if the string is empty.  This command also provides another method (besides format and scan) of converting between an ASCII character and its numeric value.  The following ctype commands are available:
ctype ?-failindex var? alnum string Tests that all characters are alphabetic or numeric characters as defined by the character set.
ctype ?-failindex var? alpha string Tests that all characters are alphabetic characters as defined by the character set.
ctype ?-failindex var? ascii string Tests that all characters are an ASCII character (a non- negative number less than 0200).
ctype char number Converts the numeric value, string, to an ASCII character. Number must be in the range 0 through 255.
ctype ?-failindex var? cntrl string Tests that all characters are ``control characters'' as defined by the character set.
ctype ?-failindex var? digit string Tests that all characters are valid decimal digits, i.e. 0 through 9.
ctype ?-failindex var? graph string Tests that all characters within are any character for which ctype print is true, except for space characters.
ctype ?-failindex var? lower string Tests that all characters are lowercase letters as defined by the character set.
ctype ord character Convert a character into its decimal numeric value.  The first character of the string is converted.
ctype ?-failindex var? space string Tests that all characters are either a space, horizontal-tab, carriage return, newline, vertical-tab, or form-feed.
ctype ?-failindex var? print string Tests that all characters are a space or any character for which ctype alnum or ctype punct is true or other ``printing character'' as defined by the character set.
ctype ?-failindex var? punct string Tests that all characters are made up of any of the characters other than the ones for which alnum, cntrl, or space is true.
ctype ?-failindex var? upper string Tests that all characters are uppercase letters as defined by the character set.
ctype ?-failindex var? xdigit string Tests that all characters are valid hexadecimal digits, that is 0 through 9, a through f or A through F.
If -failindex is specified, then the index into string of the first character that did not match the class is returned in var.
replicate string countExpr Returns string, replicated the number of times indicated by the expression countExpr.
translit inrange outrange string Translate characters in string, changing characters occuring in inrange to the corresponding character in outrange. Inrange and outrange may be list of characters or a range in the form `A-M'. For example: translit a-z A-Z foobar
XPG/3 MESSAGE CATALOG COMMANDS These commands provide a Tcl interface to message catalogs that are compliant with the X/Open Portability Guide, Version 3 (XPG/3).
Tcl programmers can use message catalogs to create applications that are language-independent.  Through the use of message catalogs, prompts, messages, menus and so forth can exist for any number of languages, and they can altered, and new languages added,  without affecting any Tcl or C source code, greatly easing the maintenance difficulties incurred by supporting multiple languages.
A default text message is passed to the command that fetches entries from message catalogs.  This allows the Tcl programmer to create message catalogs containing messages in various languages, but still have a set of default messages available regardless of the presence of any message catalogs, and allow the programs to press on without difficulty when no catalogs are present.
Thus, the normal approach to using message catalogs is to ignore errors on catopen, in which case catgets will return the default message that was specified in the call.
The Tcl message catalog commands normally ignore most errors.  If it is desirable to detect errors, a special option is provided.  This is normally used only during debugging, to insure that message catalogs are being used.  If your Unix implementation does not have XPG/3 message catalog support, stubs will be compiled in that will create a version of catgets that always returns the default string.  This allows for easy porting of software to environments that don't have support for message catalogs.
Message catalogs are global to the process, an application with multiple Tcl interpreters within the same process may pass and share message catalog handles.
catopen ?-fail|-nofail? catname Open the message catalog catname.  This may be a relative path name, in which case the NLSPATH environment variable is searched to find an absolute path to the message catalog.  A handle in the form msgcatN is returned.  Normally, errors are ignored, and in the case of a failed call to catopen, a handle is returned to an unopened message catalog.  (This handle may still be passed to catgets and catclose, causing catgets to simply return the default string, as described above.  If the -fail option is specified, an error is returned if the open fails.  The option -nofail specifies the default behavior of not returning an error when catopen fails to open a specified message catalog.  If the handle from a failed catopen is passed to catgets, the default string is returned.
catgets catHandle setnum msgnum defaultstr Retrieve a message form a message catalog. CatHandle should be a Tcl message catalog handle that was returned by catopen.  Setnum is the message set number, and msgnum is the message number. If the message catalog was not opened, or the message set or message number cannot be found, then the default string, defaultstr, is returned.
catclose ?-fail|-nofail? cathandle Close the message catalog specified by cathandle.  Normally, errors are ignored.  If -fail is specified, any errors closing the message catalog file are returned.  The option -nofail specifies the default behavior of not returning an error.  The use of -fail only makes sense if it was also specified in the call to catopen.
tcl ?-qn? ?-f? script?|?-c command? ?args?
Tcl starts the interactive Tcl command interpreter.  The Tcl shell provides an environment for writing, debugging and executing Tcl scripts. The functionality of the Tcl shell can be easily obtained by any application that includes Tcl.
The tcl command, issued without any arguments, invokes an interactive Tcl shell, allowing the user to interact directly with Tcl, executing any Tcl commands at will and viewing their results.
If script is specified, then the script is executed non-interactively with any additional arguments, args, being supplied in the global Tcl variable `argv'.  If command is supplied, then this command (or semicolon-separated series of commands) is executed, with `argv' containing any args.
The Tcl shell is intended as an environment for Tcl program development and execution.  While it is not a full-featured interactive shell, it provides a comfortable environment for the interactive development of Tcl code.  Note that the package library code described here overrides the unknown command provided as part of the standard Berkeley Tcl library facility, although Tcl source libraries coded to that standard can be loaded and used by Extended Tcl.
The following command line flags are recognized by the Tcl shell command line parser:
-q     Quick initialization flag.  The Tcl initiaization file is not evaluated and the auto_path variable is not set.  Tcl auto-load libraries will not be available.
-n     No procedure call stack dump.  The procedure call stack will not be displayed when an error occurs, only the error message.  Useful in the #! line of already debugged scripts.
-f     Takes the next argument as a script for Tcl to source, rather than entering interactive mode.  The -f flag is optional.  Normally the first argument that does not start with a `-' is taken as the script to execute unless the `-c' option is specified.  Any following arguments are passed to the script via argv, thus any other Tcl shell command-line flags must precede this option.
-c     Take the next argument as a Tcl command to execute.  It may contain series of commands to execute, separated by `;'.  Any following arguments are passed in argv, thus, as with -f, any other Tcl shell flags must precede this option.
--     Mark the end of the arguments to the Tcl shell. All arguments following this are passed in the Tcl variable argv.  This is useful to pass arguments without attempting to execute a Tcl script.
The result string returned by a command executed from the Tcl shell command line is normally echoed back to the user.  If an error occurs, then the string result is displayed, along with the error message.  The error message will be preceded by the string ``Error:''.
The set command is a special case.  If the command is called to set a variable (i.e. with two arguments), then the result will not be echoed. If only one argument, the name of a variable, is supplied to set, then the result will be echoed.
If an unknown Tcl command is entered from the command line, then the Unix command path, specified in the environment variable PATH, will be searched for a command of the same name.  If the command is found, it will be executed with any arguments remaining on the Tcl command line being passed as arguments to the command.  This feature is provided to enhance the interactive environment for developing Tcl scripts.
Automatic execution of programs in this manner is only supported from the command line, not in script files or in procedures, to reduce confusion and mistakes while programming in Tcl.  Scripts should use the Tcl exec or system commands to run Unix commands.
The following variables are set and/or used by the Tcl shell.
argv0  Contains the name of the Tcl program specified on the command line or the name that the Tcl shell was invoked under if no program was specified.  argc Contains a count of the number of argv arguments (0 if none).  argv A list containing the arguments passed in from the command line, excluding arguments used by the Tcl shell.  The first element is the first passed argument, not the program name.
tcl_interactive Set to 1 if Tcl shell is invoked interactively, or 0 if the Tcl shell is directly executing a script.  Normally checked by scripts so that they can function as a standalone application if specified on the command line, but merely load in and not execute if loaded during an interactive invocation of Tcl.
auto_path Path to search to locate Tcl scripts.  Used by the auto_load command and the TclX unknown command handler.  The path is a Tcl list of directory names.
tclx_library Path to the TclX runtime library.  If your running the TclX shell or an appilcation based on it (like wishx), this is the same value returned by "info library".
tcl_prompt1 Contains code to run to output the prompt used when interactively prompting for commands.
tcl_prompt2 Contains code to run to output the prompt used when interactively prompting for continuation of an incomplete command.
tclx_errorHandler If this variable is set to the name of a procedure, that procedure will be call if an uncaught error occurs.  The procedure will be passed a single argument of the error message, however to allow future expansion, the procedure should have a final argument of args.  The procedure is only called in non-interactive shells.  If the procedure returns normally, the program will just exit without any error being issued by the shell.  Generally the procedure should exit with a non-zero exit code once the error has been processed.  It is not possible to continue executing the code in which the error occurred.  This is useful for logging errorInfo or e-mailing it to the maintainer.
TCLXENV Array that contains information used internally by various Tcl procedures that are part of the TclX shell.  Don't change this array unless you know what your doing.
When Extended Tcl is installed, the standard runtime files are places in the Tcl master directory, which is configured when Tcl is built.  This master directory normally contains the Tcl initialization file (TclInit.tcl), the standard Tcl library file (tcl.tlib) and the help files.  The Tcl master directory is named after the version of Tcl it is associated with, e.g. /usr/local/tclX/7.4a.  The path to the Tcl master directory is available from the info library command.  The location of the Tcl master directory can be overridden with the TCL_LIBRARY environment variable.
The first step in initializing the Tcl shell is to locate the Tcl initialization file, normally TclInit.tcl.  If an environment variable TCLINIT exists, it contains the path to the Tcl initialization file.  If the TCLINIT environment variable is not set, the file TclInit.tcl is used from the default Tcl master directory.
Tcl then evaulates the Tcl initialization file.  The auto_path variable is initialized to the Tcl master directory and may be augmented by the intialization file or the application.  Other procedures and variables used by the Extended Tcl shell are also defined by this file.
If the Tcl is invoked interactively, it will source a file named .tclrc in the user's home directory, if it exists.  Tcl is viewed primarily as a programming language, not an interactive shell, so the .tclrc is intended for use for loading development utilities, not to support applications, which should not have to rely on the user's environment in such a manner.