diff options
| author | dkf <donal.k.fellows@manchester.ac.uk> | 2024-01-21 17:48:32 (GMT) |
|---|---|---|
| committer | dkf <donal.k.fellows@manchester.ac.uk> | 2024-01-21 17:48:32 (GMT) |
| commit | c0820abc21f24df06915c420f63efab64af79dac (patch) | |
| tree | 619dd4a0a33861ce42065d751e86a9ba4dbf929b | |
| parent | d8760322be4e1bfb0091bac0a799aef13dc77b87 (diff) | |
| download | tcl-c0820abc21f24df06915c420f63efab64af79dac.zip tcl-c0820abc21f24df06915c420f63efab64af79dac.tar.gz tcl-c0820abc21f24df06915c420f63efab64af79dac.tar.bz2 | |
Clean up of docs
| -rw-r--r-- | doc/after.n | 5 | ||||
| -rw-r--r-- | doc/apply.n | 6 | ||||
| -rw-r--r-- | doc/array.n | 25 | ||||
| -rw-r--r-- | doc/binary.n | 4 | ||||
| -rw-r--r-- | doc/callback.n | 4 | ||||
| -rw-r--r-- | doc/chan.n | 200 | ||||
| -rw-r--r-- | doc/class.n | 3 | ||||
| -rw-r--r-- | doc/classvariable.n | 2 | ||||
| -rw-r--r-- | doc/clock.n | 131 | ||||
| -rw-r--r-- | doc/concat.n | 16 | ||||
| -rw-r--r-- | doc/configurable.n | 13 | ||||
| -rw-r--r-- | doc/cookiejar.n | 26 | ||||
| -rw-r--r-- | doc/coroutine.n | 4 | ||||
| -rw-r--r-- | doc/dde.n | 12 | ||||
| -rw-r--r-- | doc/define.n | 34 | ||||
| -rw-r--r-- | doc/dict.n | 24 | ||||
| -rw-r--r-- | doc/encoding.n | 43 | ||||
| -rw-r--r-- | doc/exec.n | 2 | ||||
| -rw-r--r-- | doc/fconfigure.n | 18 | ||||
| -rw-r--r-- | doc/fcopy.n | 2 | ||||
| -rw-r--r-- | doc/file.n | 48 | ||||
| -rw-r--r-- | doc/glob.n | 6 | ||||
| -rw-r--r-- | doc/history.n | 20 | ||||
| -rw-r--r-- | doc/http.n | 186 | ||||
| -rw-r--r-- | doc/idna.n | 22 | ||||
| -rw-r--r-- | doc/info.n | 70 | ||||
| -rw-r--r-- | doc/interp.n | 90 | ||||
| -rw-r--r-- | doc/library.n | 26 | ||||
| -rw-r--r-- | doc/link.n | 2 | ||||
| -rw-r--r-- | doc/lseq.n | 2 | ||||
| -rw-r--r-- | doc/mathfunc.n | 109 | ||||
| -rw-r--r-- | doc/mathop.n | 71 | ||||
| -rw-r--r-- | doc/memory.n | 20 | ||||
| -rw-r--r-- | doc/msgcat.n | 58 | ||||
| -rw-r--r-- | doc/namespace.n | 40 | ||||
| -rw-r--r-- | doc/object.n | 6 | ||||
| -rw-r--r-- | doc/open.n | 22 | ||||
| -rw-r--r-- | doc/package.n | 17 | ||||
| -rw-r--r-- | doc/platform.n | 3 | ||||
| -rw-r--r-- | doc/platform_shell.n | 6 | ||||
| -rw-r--r-- | doc/prefix.n | 11 | ||||
| -rw-r--r-- | doc/process.n | 4 | ||||
| -rw-r--r-- | doc/refchan.n | 33 | ||||
| -rw-r--r-- | doc/regexp.n | 2 | ||||
| -rw-r--r-- | doc/registry.n | 9 | ||||
| -rw-r--r-- | doc/regsub.n | 2 | ||||
| -rw-r--r-- | doc/return.n | 2 | ||||
| -rw-r--r-- | doc/safe.n | 75 | ||||
| -rw-r--r-- | doc/self.n | 9 | ||||
| -rw-r--r-- | doc/string.n | 31 | ||||
| -rw-r--r-- | doc/switch.n | 4 | ||||
| -rw-r--r-- | doc/tcltest.n | 55 | ||||
| -rw-r--r-- | doc/tclvars.n | 16 | ||||
| -rw-r--r-- | doc/tm.n | 5 | ||||
| -rw-r--r-- | doc/trace.n | 7 | ||||
| -rw-r--r-- | doc/transchan.n | 8 | ||||
| -rw-r--r-- | doc/vwait.n | 10 | ||||
| -rw-r--r-- | doc/zipfs.n | 51 | ||||
| -rw-r--r-- | doc/zlib.n | 23 |
59 files changed, 1266 insertions, 489 deletions
diff --git a/doc/after.n b/doc/after.n index 1a814e0..5d64cb6 100644 --- a/doc/after.n +++ b/doc/after.n @@ -29,6 +29,7 @@ after \- Execute a command after a time delay This command is used to delay execution of the program or to execute a command in background sometime in the future. It has several forms, depending on the first argument to the command: +.\" METHOD: <none> .TP \fBafter \fIms\fR . @@ -37,6 +38,7 @@ A negative number is treated as 0. The command sleeps for \fIms\fR milliseconds and then returns. While the command is sleeping the application does not respond to events. +.\" METHOD: <timedelay> .TP \fBafter \fIms \fR?\fIscript script script ...\fR? . @@ -56,6 +58,7 @@ to cancel the delayed command using \fBafter cancel\fR. A \fIms\fR value of 0 (or negative) queues the event immediately with priority over other event types (if not installed withn an event proc, which will wait for next round of events). +.\" METHOD: cancel .TP \fBafter cancel \fIid\fR . @@ -74,6 +77,7 @@ separators (just as in the \fBconcat\fR command). If there is a pending command that matches the string, it is canceled and will never be executed; if no such command is currently pending then the \fBafter cancel\fR command has no effect. +.\" METHOD: idle .TP \fBafter idle \fIscript \fR?\fIscript script ...\fR? . @@ -87,6 +91,7 @@ to cancel the delayed command using \fBafter cancel\fR. If an error occurs while executing the script then the background error will be reported by the command registered with \fBinterp bgerror\fR. +.\" METHOD: info .TP \fBafter info \fR?\fIid\fR? . diff --git a/doc/apply.n b/doc/apply.n index aeb2227..154ddff 100644 --- a/doc/apply.n +++ b/doc/apply.n @@ -44,18 +44,18 @@ interpreted relative to the global namespace even if its name does not start with .QW :: . .PP -The semantics of \fBapply\fR can also be described by: +The semantics of \fBapply\fR can also be described by approximately this: .PP .CS proc apply {fun args} { set len [llength $fun] if {($len < 2) || ($len > 3)} { - error "can't interpret \e"$fun\e" as anonymous function" + error "can't interpret \e"$fun\e" as anonymous function" } lassign $fun argList body ns set name ::$ns::[getGloballyUniqueName] set body0 { - rename [lindex [info level 0] 0] {} + rename [lindex [info level 0] 0] {} } proc $name $argList ${body0}$body set code [catch {uplevel 1 $name $args} res opt] diff --git a/doc/array.n b/doc/array.n index 268597d..6c63366 100644 --- a/doc/array.n +++ b/doc/array.n @@ -23,8 +23,10 @@ Unless otherwise specified for individual commands below, The \fIoption\fR argument determines what action is carried out by the command. The legal \fIoptions\fR (which may be abbreviated) are: +.\" METHOD: anymore .TP \fBarray anymore \fIarrayName searchId\fR +. Returns 1 if there are any more elements left to be processed in an array search, 0 if all elements have already been returned. @@ -35,6 +37,7 @@ This option is particularly useful if an array has an element with an empty name, since the return value from \fBarray nextelement\fR will not indicate whether the search has been completed. +.\" METHOD: default .TP \fBarray default \fIsubcommand arrayName args...\fR .VS TIP508 @@ -82,19 +85,25 @@ value. Raises an error if \fIarrayName\fR is an existing variable that is not an array. .VE TIP508 .RE +.\" METHOD: donesearch .TP \fBarray donesearch \fIarrayName searchId\fR +. This command terminates an array search and destroys all the state associated with that search. \fISearchId\fR indicates which search on \fIarrayName\fR to destroy, and must have been the return value from a previous invocation of \fBarray startsearch\fR. Returns an empty string. +.\" METHOD: exists .TP \fBarray exists \fIarrayName\fR +. Returns 1 if \fIarrayName\fR is an array variable, 0 if there is no variable by that name or if it is a scalar variable. +.\" METHOD: for .TP \fBarray for {\fIkeyVariable valueVariable\fB} \fIarrayName body\fP +. The first argument is a two element list of variable names for the key and value of each entry in the array. The second argument is the array name to iterate over. The third argument is the body to execute @@ -102,8 +111,10 @@ for each key and value returned. The ordering of the returned keys is undefined. If an array element is deleted or a new array element is inserted during the \fIarray for\fP process, the command will terminate with an error. +.\" METHOD: get .TP \fBarray get \fIarrayName\fR ?\fIpattern\fR? +. Returns a list containing pairs of elements. The first element in each pair is the name of an element in \fIarrayName\fR and the second element of each pair is the value of the @@ -118,8 +129,10 @@ the array contains no elements, then an empty list is returned. If traces on the array modify the list of elements, the elements returned are those that exist both before and after the call to \fBarray get\fR. +.\" METHOD: names .TP \fBarray names \fIarrayName\fR ?\fImode\fR? ?\fIpattern\fR? +. Returns a list containing the names of all of the elements in the array that match \fIpattern\fR. \fIMode\fR may be one of \fB\-exact\fR, \fB\-glob\fR, or \fB\-regexp\fR. If specified, \fImode\fR @@ -132,8 +145,10 @@ If \fIpattern\fR is omitted then the command returns all of the element names in the array. If there are no (matching) elements in the array, or if \fIarrayName\fR is not the name of an array variable, then an empty string is returned. +.\" METHOD: nextelement .TP \fBarray nextelement \fIarrayName searchId\fR +. Returns the name of the next element in \fIarrayName\fR, or an empty string if all elements of \fIarrayName\fR have already been returned in this search. The \fIsearchId\fR @@ -143,8 +158,10 @@ Warning: if elements are added to or deleted from the array, then all searches are automatically terminated just as if \fBarray donesearch\fR had been invoked; this will cause \fBarray nextelement\fR operations to fail for those searches. +.\" METHOD: set .TP \fBarray set \fIarrayName list\fR +. Sets the values of one or more elements in \fIarrayName\fR. \fIlist\fR must have a form like that returned by \fBarray get\fR, consisting of an even number of elements. @@ -154,13 +171,17 @@ is used as a new value for that array element. If the variable \fIarrayName\fR does not already exist and \fIlist\fR is empty, \fIarrayName\fR is created with an empty array value. +.\" METHOD: size .TP \fBarray size \fIarrayName\fR +. Returns a decimal string giving the number of elements in the array. If \fIarrayName\fR is not the name of an array then 0 is returned. +.\" METHOD: startsearch .TP \fBarray startsearch \fIarrayName\fR +. This command initializes an element-by-element search through the array given by \fIarrayName\fR, such that invocations of the \fBarray nextelement\fR command will return the names of the @@ -175,14 +196,18 @@ It is currently more efficient and easier to use either the \fBarray get\fR or \fBarray names\fR, together with \fBforeach\fR, to iterate over all but very large arrays. See the examples below for how to do this. +.\" METHOD: statistics .TP \fBarray statistics \fIarrayName\fR +. Returns statistics about the distribution of data within the hashtable that represents the array. This information includes the number of entries in the table, the number of buckets, and the utilization of the buckets. +.\" METHOD: unset .TP \fBarray unset \fIarrayName\fR ?\fIpattern\fR? +. Unsets all of the elements in the array that match \fIpattern\fR (using the matching rules of \fBstring match\fR). If \fIarrayName\fR is not the name of an array variable or there are no matching elements in the array, no diff --git a/doc/binary.n b/doc/binary.n index 864b0f9..8793b2f 100644 --- a/doc/binary.n +++ b/doc/binary.n @@ -40,6 +40,8 @@ done by other Tcl commands (respectively \fBstring range\fR, binary string in Tcl is merely one where all the characters it contains are in the range \eu0000\-\eu00FF. .SH "BINARY ENCODE AND DECODE" +.\" METHOD: decode +.\" METHOD: encode .PP When encoding binary data as a readable string, the starting binary data is passed to the \fBbinary encode\fR command, together with the name of the @@ -134,6 +136,7 @@ Note that neither the encoder nor the decoder handle the header and footer of the uuencode format. .RE .SH "BINARY FORMAT" +.\" METHOD: format .PP The \fBbinary format\fR command generates a binary string whose layout is specified by the \fIformatString\fR and whose contents come from @@ -607,6 +610,7 @@ will return .CE .RE .SH "BINARY SCAN" +.\" METHOD: scan .PP The \fBbinary scan\fR command parses fields from a binary string, returning the number of conversions performed. \fIString\fR gives the diff --git a/doc/callback.n b/doc/callback.n index 3ab81ac..c96b23b 100644 --- a/doc/callback.n +++ b/doc/callback.n @@ -14,8 +14,8 @@ callback, mymethod \- generate callbacks to methods .nf package require tcl::oo -\fBcallback\fR \fImethodName\fR ?\fIarg ...\fR? -\fBmymethod\fR \fImethodName\fR ?\fIarg ...\fR? +\fBcallback\fI methodName\fR ?\fIarg ...\fR? +\fBmymethod\fI methodName\fR ?\fIarg ...\fR? .fi .BE .SH DESCRIPTION @@ -21,6 +21,7 @@ otherwise manipulating channels, e.g. those created by \fBopen\fR and which correspond respectively to the standard input, output, and error streams of the process. Any unique abbreviation for \fIoperation\fR is acceptable. Available operations are: +.\" METHOD: blocked .TP \fBchan blocked \fIchannelName\fR . @@ -28,6 +29,7 @@ Returns 1 when the channel is in non-blocking mode and the last input operation on the channel failed because it would have otherwise caused the process to block, and 0 otherwise. Each Tcl channel is in blocking mode unless configured otherwise. +.\" METHOD: close .TP \fBchan close \fIchannelName\fR ?\fIdirection\fR? . @@ -84,6 +86,7 @@ switch them back to blocking or (b) use the environment variable .QW \fB0\fR restores the previous behavior. .RE +.\" METHOD: configure .TP \fBchan configure \fIchannelName\fR ?\fIoptionName\fR? ?\fIvalue\fR? ?\fIoptionName value\fR?... . @@ -103,7 +106,7 @@ channel may provide additional options. Those options are described in the relevant documentation. For example, additional options are documented for \fBsocket\fR, and also for serial devices at \fBopen\fR. .TP -\fB\-blocking\fR \fIboolean\fR +\fB\-blocking\fI boolean\fR . If \fB\-blocking\fR is set to \fBtrue\fR, which is the default, reading from or writing to the channel may cause the process to block indefinitely. Otherwise, @@ -113,7 +116,7 @@ generally requires that the event loop is entered, e.g. by calling \fBTcl_DoOneEvent\fR or \fBvwait\fR or by using Tk, to give Tcl a chance to process events on the channel. .TP -\fB\-buffering\fR \fInewValue\fR +\fB\-buffering\fI newValue\fR . If \fInewValue\fR is \fBfull\fR, which is the default, output is buffered until the internal buffer is full or until \fBchan flush\fR is called. If @@ -123,7 +126,7 @@ every output operation. For \fBstdin\fR, \fBstdout\fR, and channels that connect to terminal-like devices, the default value is \fBline\fR. For \fBstderr\fR the default value is \fBnone\fR. .TP -\fB\-buffersize\fR \fInewSize\fR +\fB\-buffersize\fI newSize\fR . \fInewSize\fR, an integer no greater than one million, is the size in bytes of any input or output buffers subsequently allocated for this channel. @@ -145,7 +148,7 @@ which returns the platform- and locale-dependent system encoding used to interface with the operating system, .RE .TP -\fB\-eofchar\fR \fIchar\fR +\fB\-eofchar\fI char\fR . \fIchar\fR signals the end of the data when it is encountered in the input. If \fIchar\fR is the empty string, there is no special character that marks @@ -155,7 +158,7 @@ The default value is the empty string. The acceptable range is \ex01 - \ex7F. A value outside this range results in an error. .VS "TCL8.7 TIP656" .TP -\fB\-profile\fR \fIprofile\fR +\fB\-profile\fI profile\fR . Specifies the encoding profile to be used on the channel. The encoding transforms in use for the channel's input and output will then be subject to the @@ -164,7 +167,7 @@ rules of that profile. Any failures will result in a channel error. See profiles. .VE "TCL8.7 TIP656" .TP -\fB\-translation\fR \fItranslation\fR +\fB\-translation\fI translation\fR .TP \fB\-translation\fR \fB{\fIinTranslation outTranslation\fB}\fR . @@ -232,6 +235,7 @@ translations occur during either input or output. This translation is typically used on UNIX platforms, .RE .RE +.\" METHOD: copy .TP \fBchan copy \fIinputChan outputChan\fR ?\fB\-size \fIsize\fR? ?\fB\-command \fIcallback\fR? . @@ -265,90 +269,15 @@ closed all data already queued is written to \fIoutputChan\fR. There should be no event handler established for \fIinputChan\fR because it may become readable during a background copy. An attempt to read or write from within an event handler results result in the error, "channel busy". Any -wrong-sided I/O attempted (by a \fBfileevent\fR handler or otherwise) results +wrong-sided I/O attempted (by a \fBchan event\fR handler or otherwise) results in a .QW "channel busy" error. .PP .PP .IP \fBEXAMPLES\fR -.PP -The first example transfers the contents of one channel exactly to -another. Note that when copying one file to another, it is better to -use \fBfile copy\fR which also copies file metadata (e.g. the file -access permissions) where possible. -.PP -.CS -fconfigure $in -translation binary -fconfigure $out -translation binary -\fBfcopy\fR $in $out -.CE -.PP -This second example shows how the callback gets -passed the number of bytes transferred. -It also uses vwait to put the application into the event loop. -Of course, this simplified example could be done without the command -callback. -.PP -.CS -proc Cleanup {in out bytes {error {}}} { - global total - set total $bytes - close $in - close $out - if {[string length $error] != 0} { - # error occurred during the copy - } -} -set in [open $file1] -set out [socket $server $port] -\fBfcopy\fR $in $out -command [list Cleanup $in $out] -vwait total -.CE -.PP -The third example copies in chunks and tests for end of file -in the command callback. -.PP -.CS -proc CopyMore {in out chunk bytes {error {}}} { - global total done - incr total $bytes - if {([string length $error] != 0) || [eof $in]} { - set done $total - close $in - close $out - } else { - \fBfcopy\fR $in $out -size $chunk \e - -command [list CopyMore $in $out $chunk] - } -} -set in [open $file1] -set out [socket $server $port] -set chunk 1024 -set total 0 -\fBfcopy\fR $in $out -size $chunk \e - -command [list CopyMore $in $out $chunk] -vwait done -.CE -.PP -The fourth example starts an asynchronous, bidirectional fcopy between -two sockets. Those could also be pipes from two [open "|hal 9000" r+] -(though their conversation would remain secret to the script, since -all four fileevent slots are busy). -.PP -.CS -set flows 2 -proc Done {dir args} { - global flows done - puts "$dir is over." - incr flows -1 - if {$flows<=0} {set done 1} -} -\fBfcopy\fR $sok1 $sok2 -command [list Done UP] -\fBfcopy\fR $sok2 $sok1 -command [list Done DOWN] -vwait done -.CE .RE +.\" METHOD: create .TP \fBchan create \fImode cmdPrefix\fR . @@ -388,11 +317,13 @@ is currently in or shared with. \fBchan create\fR is \fBsafe\fR and is accessible to safe interpreters. The handler is always called in the safe interpreter it was created in. .RE +.\" METHOD: eof .TP \fBchan eof \fIchannelName\fR . Returns 1 if the last read on the channel failed because the end of the data was already reached, and 0 otherwise. +.\" METHOD: event .TP \fBchan event \fIchannelName event\fR ?\fIscript\fR? . @@ -407,7 +338,6 @@ deleted when the channel is closed. If \fIscript\fR is omitted, either the existing script or the empty string is returned. The event loop must be entered, e.g. via \fBvwait\fR or \fBupdate\fR, or by using Tk, for handlers to be evaluated. - .RS .PP \fIscript\fR is evaluated at the global level in the interpreter it was @@ -415,7 +345,6 @@ established in. Any resulting error is handled in the background, i.e. via \fBinterp bgerror\fR. In order to prevent an endless loop due to a buggy handler, the handler is deleted if \fIscript\fR returns an error so that it is not evaluated again. - .PP Without an event handler, \fBchan gets\fR or \fBchan read\fR on a channel in blocking mode may block until data becomes available, become during which the @@ -450,12 +379,14 @@ thread can not do any other processing or service any other events. A channel in non-blocking mode allows a thread to carry on with other work and get back to the channel at the right time. .RE +.\" METHOD: flush .TP \fBchan flush \fIchannelName\fR . For a channel in blocking mode, flushes all buffered output to the destination, and then returns. For a channel in non-blocking mode, returns immediately while all buffered output is flushed in the background as soon as possible. +.\" METHOD: gets .TP \fBchan gets \fIchannelName\fR ?\fIvarName\fR? . @@ -477,11 +408,13 @@ indicate that the empty string means that the end of the data has been reached, and \fBchan blocked\fR may indicate that that the empty string means there isn't currently enough data do return the next line. .RE +.\" METHOD: names .TP \fBchan names\fR ?\fIpattern\fR? . Returns a list of all channel names, or if \fIpattern\fR is given, only those names that match according to the rules of \fBstring match\fR. +.\" METHOD: pending .TP \fBchan pending \fImode channelName\fR . @@ -495,8 +428,10 @@ event callback to impose limits on input line length to avoid a potential denial-of-service attack where an extremely long line exceeds the available memory to buffer it. Returns -1 if the channel was not opened for the mode in question. +.\" METHOD: pipe .TP \fBchan pipe\fR +. Creates a pipe, i.e. a readable channel and a writable channel, and returns the names of the readable channel and the writable channel. Data written to the writable channel can be read from the readable channel. Because the pipe is a @@ -526,12 +461,15 @@ issue, either put the channels into non-blocking mode and use event handlers, or place the read channel and the write channel in separate interpreters in separate threads. .RE +.\" METHOD: pop .TP \fBchan pop \fIchannelName\fR +. Removes the topmost transformation handler from the channel if there is one, and closes the channel otherwise. The result is normally the empty string, but may be an error in some situations, e.g. when closing the underlying resource results in an error. +.\" METHOD: postevent .TP \fBchan postevent \fIchannelName eventSpec\fR . @@ -557,13 +495,16 @@ It is an error to post an event that the channel has no interest in. See reflected channel would have been created, and will be evaluated in that interpreter as well. .RE +.\" METHOD: push .TP \fBchan push \fIchannelName cmdPrefix\fR +. Adds a new transformation handler on top of the channel and returns a handle for the transformation. \fIcmdPrefix\fR is the first words of a command that provides the interface documented for \fBtranschan\fR, and transforms data on the channel, It is an error if handler does not support the mode(s) the channel is in. +.\" METHOD: puts .TP \fBchan puts\fR ?\fB\-nonewline\fR? ?\fIchannelName\fR? \fIstring\fR . @@ -593,6 +534,7 @@ non-blocking mode should normally be handled using \fBchan event\fR, where the application only invokes \fBchan puts\fR after being recently notified through a file event handler that the channel is ready for more output data. .RE +.\" METHOD: read .TP \fBchan read \fIchannelName\fR ?\fInumChars\fR? .TP @@ -623,6 +565,7 @@ possible to get a \fBreadable\fR event for each individual character. In blocking mode, \fBchan read\fR blocks forever when reading to the end of the data if there is no \fBchan configure -eofchar\fR configured for the channel. .RE +.\" METHOD: seek .TP \fBchan seek \fIchannelName offset\fR ?\fIorigin\fR? . @@ -653,12 +596,14 @@ empty string or an error if the channel does not support seeking. read\fR, both \fBchan seek\fR and \fBchan tell\fR operate in terms of bytes, not characters, .RE +.\" METHOD: tell .TP \fBchan tell \fIchannelName\fR . Returns the offset in bytes of the current position in the underlying data, or -1 if the channel does not suport seeking. The value can be passed to \fBchan seek\fR to set current position to that offset. +.\" METHOD: truncate .TP \fBchan truncate \fIchannelName\fR ?\fIlength\fR? . @@ -666,6 +611,7 @@ Flushes the channel and truncates the data in the channel to \fIlength\fR bytes, or to the current position in bytes if \fIlength\fR is omitted. . .SH EXAMPLES +.SS "SIMPLE CHANNEL OPERATION EXAMPLES" .PP In the following example a file is opened using the encoding CP1252, which is common on Windows, searches for a string, rewrites that part, and truncates the @@ -736,6 +682,90 @@ proc echoLine {chan clientName} { socket -server connect 12345 vwait forever .CE +.SS "CHANNEL COPY EXAMPLES" +.PP +The first example transfers the contents of one channel exactly to +another. Note that when copying one file to another, it is better to +use \fBfile copy\fR which also copies file metadata (e.g. the file +access permissions) where possible. +.PP +.CS +\fBchan configure\fR $in -translation binary +\fBchan configure\fR $out -translation binary +\fBchan copy\fR $in $out +.CE +.PP +This second example shows how the callback gets +passed the number of bytes transferred. +It also uses vwait to put the application into the event loop. +Of course, this simplified example could be done without the command +callback. +.PP +.CS +proc Cleanup {in out bytes {error {}}} { + global total + set total $bytes + \fBchan close\fR $in + \fBchan close\fR $out + if {$error ne ""} { + # error occurred during the copy + } +} + +set in [open $file1] +set out [socket $server $port] +\fBchan copy\fR $in $out -command [list Cleanup $in $out] +vwait total +.CE +.PP +The third example copies in chunks and tests for end of file +in the command callback. +.PP +.CS +proc CopyMore {in out chunk bytes {error {}}} { + global total done + incr total $bytes + if {($error ne "") || [\fBchan eof\fR $in]} { + set done $total + \fBchan close\fR $in + \fBchan close\fR $out + } else { + \fBchan copy\fR $in $out -size $chunk \e + -command [list CopyMore $in $out $chunk] + } +} + +set in [open $file1] +set out [socket $server $port] +set chunk 1024 +set total 0 +\fBchan copy\fR $in $out -size $chunk \e + -command [list CopyMore $in $out $chunk] +vwait done +.CE +.PP +The fourth example starts an asynchronous, bidirectional copy between +two sockets. Those could also be pipes from two bidirectional pipelines +(e.g., \fI[open "|hal 9000" r+]\fR); the conversation will remain +essentially secret to the script, since all four \fBchan event\fR slots +are busy, though any transforms that are \fBchan push\fRed on the +channels will be able to observe the passing traffic. +.PP +.CS +proc Done {dir args} { + global flows done + \fBchan puts\fR "$dir is over." + incr flows -1 + if {$flows <= 0} { + set done 1 + } +} + +set flows 2 +\fBchan copy\fR $sok1 $sok2 -command [list Done UP] +\fBchan copy\fR $sok2 $sok1 -command [list Done DOWN] +vwait done +.CE .SH "SEE ALSO" close(n), eof(n), fblocked(n), fconfigure(n), fcopy(n), file(n), fileevent(n), flush(n), gets(n), open(n), puts(n), read(n), seek(n), diff --git a/doc/class.n b/doc/class.n index c48f52d..1f4c774 100644 --- a/doc/class.n +++ b/doc/class.n @@ -48,6 +48,7 @@ The \fBoo::class\fR class does not define an explicit destructor. However, when a class is destroyed, all its subclasses and instances are also destroyed, along with all objects that it has been mixed into. .SS "EXPORTED METHODS" +.\" METHOD: create .TP \fIcls \fBcreate \fIname \fR?\fIarg ...\fR? . @@ -58,6 +59,7 @@ a successful result) returning the fully qualified name of the created object (the result of the constructor is ignored). If the constructor fails (i.e. returns a non-OK result) then the object is destroyed and the error message is the result of this method call. +.\" METHOD: new .TP \fIcls \fBnew \fR?\fIarg ...\fR? . @@ -75,6 +77,7 @@ classes should not be created using this method. .SS "NON-EXPORTED METHODS" .PP The \fBoo::class\fR class supports the following non-exported methods: +.\" METHOD: createWithNamespace .TP \fIcls \fBcreateWithNamespace\fI name nsName\fR ?\fIarg ...\fR? . diff --git a/doc/classvariable.n b/doc/classvariable.n index 70d9f13..15b8783 100644 --- a/doc/classvariable.n +++ b/doc/classvariable.n @@ -15,7 +15,7 @@ classvariable \- create link from local variable to variable in class .nf package require tcl::oo -\fBclassvariable\fR \fIvariableName\fR ?\fI...\fR? +\fBclassvariable\fI variableName\fR ?\fI...\fR? .fi .BE .SH DESCRIPTION diff --git a/doc/clock.n b/doc/clock.n index 5157ed1..5d86ed2 100644 --- a/doc/clock.n +++ b/doc/clock.n @@ -10,17 +10,17 @@ clock \- Obtain and manipulate dates and times .SH "SYNOPSIS" package require \fBTcl 8.5-\fR .sp -\fBclock add\fR \fItimeVal\fR ?\fIcount unit...\fR? ?\fI\-option value\fR? +\fBclock add\fI timeVal\fR ?\fIcount unit...\fR? ?\fI\-option value\fR? .sp \fBclock clicks\fR ?\fI\-option\fR? .sp -\fBclock format\fR \fItimeVal\fR ?\fI\-option value\fR...? +\fBclock format\fI timeVal\fR ?\fI\-option value\fR...? .sp \fBclock microseconds\fR .sp \fBclock milliseconds\fR .sp -\fBclock scan\fR \fIinputString\fR ?\fI\-option value\fR...? +\fBclock scan\fI inputString\fR ?\fI\-option value\fR...? .sp \fBclock seconds\fR .sp @@ -30,16 +30,21 @@ package require \fBTcl 8.5-\fR The \fBclock\fR command performs several operations that obtain and manipulate values that represent times. The command supports several subcommands that determine what action is carried out by the command. +.\" METHOD: add .TP -\fBclock add\fR \fItimeVal\fR ?\fIcount unit...\fR? ?\fI\-option value\fR? +\fBclock add\fI timeVal\fR ?\fIcount unit...\fR? ?\fI\-option value\fR? +. Adds a (possibly negative) offset to a time that is expressed as an integer number of seconds. See \fBCLOCK ARITHMETIC\fR for a full description. +.\" METHOD: clicks .TP \fBclock clicks\fR ?\fI\-option\fR? +. If no \fI\-option\fR argument is supplied, returns a high-resolution time value as a system-dependent integer value. The unit of the value is system-dependent but should be the highest resolution clock available -on the system such as a CPU cycle counter. See \fBHIGH RESOLUTION TIMERS\fR for a full description. +on the system such as a CPU cycle counter. +See \fBHIGH RESOLUTION TIMERS\fR for a full description. .RS .PP If the \fI\-option\fR argument is \fB\-milliseconds\fR, then the command @@ -52,32 +57,45 @@ is synonymous with \fBclock microseconds\fR (see below). This usage is obsolete, and \fBclock microseconds\fR is to be considered the preferred way of obtaining a count of microseconds. .RE +.\" METHOD: format .TP -\fBclock format\fR \fItimeVal\fR ?\fI\-option value\fR...? +\fBclock format\fI timeVal\fR ?\fI\-option value\fR...? +. Formats a time that is expressed as an integer number of seconds into a format intended for consumption by users or external programs. See \fBFORMATTING TIMES\fR for a full description. +.\" METHOD: microseconds .TP \fBclock microseconds\fR -Returns the current time as an integer number of microseconds. See \fBHIGH RESOLUTION TIMERS\fR for a full description. +. +Returns the current time as an integer number of microseconds. +See \fBHIGH RESOLUTION TIMERS\fR for a full description. +.\" METHOD: milliseconds .TP \fBclock milliseconds\fR -Returns the current time as an integer number of milliseconds. See \fBHIGH RESOLUTION TIMERS\fR for a full description. +. +Returns the current time as an integer number of milliseconds. +See \fBHIGH RESOLUTION TIMERS\fR for a full description. +.\" METHOD: scan .TP -\fBclock scan\fR \fIinputString\fR ?\fI\-option value\fR...? +\fBclock scan\fI inputString\fR ?\fI\-option value\fR...? +. Scans a time that is expressed as a character string and produces an integer number of seconds. See \fBSCANNING TIMES\fR for a full description. +.\" METHOD: seconds .TP \fBclock seconds\fR Returns the current time as an integer number of seconds. .SS "PARAMETERS" .TP \fIcount\fR +. An integer representing a count of some unit of time. See \fBCLOCK ARITHMETIC\fR for the details. .TP \fItimeVal\fR +. An integer value passed to the \fBclock\fR command that represents an absolute time as a number of seconds from the \fIepoch time\fR of 1 January 1970, 00:00 UTC. Note that the count of seconds does not @@ -88,6 +106,7 @@ back in sync with UTC; its data model does not represent minutes that have 59 or 61 seconds. .TP \fIunit\fR +. One of the words, \fBseconds\fR, \fBminutes\fR, \fBhours\fR, \fBdays\fR, \fBweekdays\fR, \fBweeks\fR, \fBmonths\fR, or \fByears\fR. Used in conjunction with \fIcount\fR to identify an interval of time, @@ -95,11 +114,13 @@ for example, \fI3 seconds\fR or \fI1 year\fR. .SS "OPTIONS" .TP \fB\-base\fR time +. Specifies that any relative times present in a \fBclock scan\fR command are to be given relative to \fItime\fR. \fItime\fR must be expressed as a count of nominal seconds from the epoch time of 1 January 1970, 00:00 UTC. .TP \fB\-format\fR format +. Specifies the desired output format for \fBclock format\fR or the expected input format for \fBclock scan\fR. The \fIformat\fR string consists of any number of characters other than the per-cent sign @@ -121,15 +142,17 @@ is requested; see \fBFREE FORM SCAN\fR for a description of what happens. .RE .TP \fB\-gmt\fR boolean +. If \fIboolean\fR is true, specifies that a time specified to \fBclock add\fR, \fBclock format\fR or \fBclock scan\fR should be processed in UTC. If \fIboolean\fR is false, the processing defaults to the local time zone. This usage is obsolete; the correct current usage is to specify the UTC time zone with -.QW "\fB\-timezone\fR \fI:UTC\fR" +.QW "\fB\-timezone\fI :UTC\fR" or any of the equivalent ways to specify it. .TP \fB\-locale\fR localeName +. Specifies that locale-dependent scanning and formatting (and date arithmetic for dates preceding the adoption of the Gregorian calendar) is to be done in the locale identified by \fIlocaleName\fR. The locale name may be any of @@ -145,6 +168,7 @@ The effect of locale on clock arithmetic is discussed under .RE .TP \fB\-timezone\fR zoneName +. Specifies that clock arithmetic, formatting, and scanning are to be done according to the rules for the time zone specified by \fIzoneName\fR. The permissible values, and their interpretation, are discussed under @@ -310,9 +334,9 @@ and their interpretation, are described under \fBFORMAT GROUPS\fR. If a \fB\-timezone\fR option is present, the following argument is a string that specifies the time zone in which the date and time are to be formatted. As an alternative to -.QW "\fB\-timezone\fR \fI:UTC\fR" , +.QW "\fB\-timezone\fI :UTC\fR" , the obsolete usage -.QW "\fB\-gmt\fR \fItrue\fR" +.QW "\fB\-gmt\fI true\fR" may be used. See \fBTIME ZONES\fR for the permissible variants for the time zone. .PP @@ -321,14 +345,14 @@ a string that specifies the locale in which the time is to be formatted, in the same format that is used for the \fBmsgcat\fR package. Note that the default, if \fB\-locale\fR is not specified, is the root locale \fB{}\fR rather than the current locale. The current locale may -be obtained by using \fB\-locale\fR \fBcurrent\fR. +be obtained by using \fB\-locale current\fR. In addition, some platforms support a \fBsystem\fR locale that reflects the user's current choices. For instance, on Windows, the format that the user has selected from dates and times in the Control Panel can be obtained by using the \fBsystem\fR locale. On platforms that do not define a user selection of date and time formats -separate from \fBLC_TIME\fR, \fB\-locale\fR \fBsystem\fR is -synonymous with \fB\-locale\fR \fBcurrent\fR. +separate from \fBLC_TIME\fR, \fB\-locale system\fR is +synonymous with \fB\-locale current\fR. .SH "SCANNING TIMES" .PP The \fBclock scan\fR command accepts times that are formatted as @@ -346,8 +370,8 @@ and their interpretation, are described under \fBFORMAT GROUPS\fR. .PP If a \fB\-timezone\fR option is present, the following argument is a string that specifies the time zone in which the date and time -are to be interpreted. As an alternative to \fB\-timezone\fR \fI:UTC\fR, -the obsolete usage \fB\-gmt\fR \fItrue\fR may be used. See +are to be interpreted. As an alternative to \fB\-timezone\fI :UTC\fR, +the obsolete usage \fB\-gmt\fI true\fR may be used. See \fBTIME ZONES\fR for the permissible variants for the time zone. .PP If a \fB\-locale\fR option is present, the following argument is @@ -355,14 +379,14 @@ a string that specifies the locale in which the time is to be interpreted, in the same format that is used for the \fBmsgcat\fR package. Note that the default, if \fB\-locale\fR is not specified, is the root locale \fB{}\fR rather than the current locale. The current locale may -be obtained by using \fB\-locale\fR \fBcurrent\fR. +be obtained by using \fB\-locale current\fR. In addition, some platforms support a \fBsystem\fR locale that reflects the user's current choices. For instance, on Windows, the format that the user has selected from dates and times in the Control Panel can be obtained by using the \fBsystem\fR locale. On platforms that do not define a user selection of date and time formats -separate from \fBLC_TIME\fR, \fB\-locale\fR \fBsystem\fR is -synonymous with \fB\-locale\fR \fBcurrent\fR. +separate from \fBLC_TIME\fR, \fB\-locale system\fR is +synonymous with \fB\-locale current\fR. .PP If a \fB\-base\fR option is present, the following argument is a time (expressed in seconds from the epoch time) that is used as @@ -471,67 +495,79 @@ The following format groups are recognized by the \fBclock scan\fR and \fBclock format\fR commands. .TP \fB%a\fR -On output, produces an abbreviation (\fIe.g.,\fR \fBMon\fR) for the day +. +On output, produces an abbreviation (\fIe.g., \fBMon\fR) for the day of the week in the given locale. On input, matches the name of the day of the week in the given locale (in either abbreviated or full form, or any unique prefix of either form). .TP \fB%A\fR -On output, produces the full name (\fIe.g.,\fR \fBMonday\fR) of the day +. +On output, produces the full name (\fIe.g., \fBMonday\fR) of the day of the week in the given locale. On input, matches the name of the day of the week in the given locale (in either abbreviated or full form, or any unique prefix of either form). .TP \fB%b\fR -On output, produces an abbreviation (\fIe.g.,\fR \fBJan\fR) for the name +. +On output, produces an abbreviation (\fIe.g., \fBJan\fR) for the name of the month in the given locale. On input, matches the name of the month in the given locale (in either abbreviated or full form, or any unique prefix of either form). .TP \fB%B\fR -On output, produces the full name (\fIe.g.,\fR \fBJanuary\fR) +. +On output, produces the full name (\fIe.g., \fBJanuary\fR) of the month in the given locale. On input, matches the name of the month in the given locale (in either abbreviated or full form, or any unique prefix of either form). .TP \fB%c\fR +. On output, produces a localized representation of date and time of day; the localized representation is expected to use the Gregorian calendar. On input, matches whatever \fB%c\fR produces. .TP \fB%C\fR +. On output, produces the number of the century in Indo-Arabic numerals. On input, matches one or two digits, possibly with leading whitespace, that are expected to be the number of the century. .TP \fB%d\fR +. On output, produces the number of the day of the month, as two decimal digits. On input, matches one or two digits, possibly with leading whitespace, that are expected to be the number of the day of the month. .TP \fB%D\fR +. This format group is synonymous with \fB%m/%d/%Y\fR. It should be used only in exchanging data within the \fBen_US\fR locale, since other locales typically do not use this order for the fields of the date. .TP \fB%e\fR +. On output, produces the number of the day of the month, as one or two decimal digits (with a leading blank for one-digit dates). On input, matches one or two digits, possibly with leading whitespace, that are expected to be the number of the day of the month. .TP \fB%Ec\fR +. On output, produces a locale-dependent representation of the date and time of day in the locale's alternative calendar. On input, matches whatever \fB%Ec\fR produces. The locale's alternative calendar need not be the Gregorian calendar. .TP \fB%EC\fR +. On output, produces a locale-dependent name of an era in the locale's alternative calendar. On input, matches the name of the era or any unique prefix. .TP \fB%EE\fR +. On output, produces the string \fBB.C.E.\fR or \fBC.E.\fR, or a string of the same meaning in the locale, to indicate whether \fB%Y\fR refers to years before or after Year 1 of the Common Era. On input, accepts @@ -541,54 +577,65 @@ whether \fB%Y\fR refers to years before or after Year 1 of the Common Era. .TP \fB%Ex\fR +. On output, produces a locale-dependent representation of the date in the locale's alternative calendar. On input, matches whatever \fB%Ex\fR produces. The locale's alternative calendar need not be the Gregorian calendar. .TP \fB%EX\fR +. On output, produces a locale-dependent representation of the time of day in the locale's alternative numerals. On input, matches whatever \fB%EX\fR produces. .TP \fB%Ey\fR +. On output, produces a locale-dependent number of the year of the era in the locale's alternative calendar and numerals. On input, matches such a number. .TP \fB%EY\fR +. On output, produces a representation of the year in the locale's alternative calendar and numerals. On input, matches what \fB%EY\fR produces. Often synonymous with \fB%EC%Ey\fR. .TP \fB%g\fR +. On output, produces a two-digit year number suitable for use with the week-based ISO8601 calendar; that is, the year number corresponds to the week number produced by \fB%V\fR. On input, accepts such a two-digit year number, possibly with leading whitespace. .TP \fB%G\fR +. On output, produces a four-digit year number suitable for use with the week-based ISO8601 calendar; that is, the year number corresponds to the week number produced by \fB%V\fR. On input, accepts such a four-digit year number, possibly with leading whitespace. .TP \fB%h\fR +. This format group is synonymous with \fB%b\fR. .TP \fB%H\fR +. On output, produces a two-digit number giving the hour of the day (00-23) on a 24-hour clock. On input, accepts such a number. .TP \fB%I\fR +. On output, produces a two-digit number giving the hour of the day (12-11) on a 12-hour clock. On input, accepts such a number. .TP \fB%j\fR +. On output, produces a three-digit number giving the day of the year (001-366). On input, accepts such a number. .TP \fB%J\fR +. On output, produces a string of digits giving the Julian Day Number. On input, accepts a string of digits and interprets it as a Julian Day Number. The Julian Day Number is a count of the number of calendar days @@ -597,30 +644,36 @@ Julian calendar. The epoch time of 1 January 1970 corresponds to Julian Day Number 2440588. .TP \fB%k\fR +. On output, produces a one- or two-digit number giving the hour of the day (0-23) on a 24-hour clock. On input, accepts such a number. .TP \fB%l\fR +. On output, produces a one- or two-digit number giving the hour of the day (12-11) on a 12-hour clock. On input, accepts such a number. .TP \fB%m\fR +. On output, produces the number of the month (01-12) with exactly two digits. On input, accepts two digits and interprets them as the number of the month. .TP \fB%M\fR +. On output, produces the number of the minute of the hour (00-59) with exactly two digits. On input, accepts two digits and interprets them as the number of the minute of the hour. .TP \fB%N\fR +. On output, produces the number of the month (1-12) with one or two digits, and a leading blank for one-digit dates. On input, accepts one or two digits, possibly with leading whitespace, and interprets them as the number of the month. .TP \fB%Od\fR, \fB%Oe\fR, \fB%OH\fR, \fB%OI\fR, \fB%Ok\fR, \fB%Ol\fR, \fB%Om\fR, \fB%OM\fR, \fB%OS\fR, \fB%Ou\fR, \fB%Ow\fR, \fB%Oy\fR +. All of these format groups are synonymous with their counterparts without the .QW \fBO\fR , @@ -628,6 +681,7 @@ except that the string is produced and parsed in the locale-dependent alternative numerals. .TP \fB%p\fR +. On output, produces an indicator for the part of the day, \fBAM\fR or \fBPM\fR, appropriate to the given locale. If the script of the given locale supports multiple letterforms, lowercase is preferred. @@ -635,6 +689,7 @@ On input, matches the representation \fBAM\fR or \fBPM\fR in the given locale, in either case. .TP \fB%P\fR +. On output, produces an indicator for the part of the day, \fBam\fR or \fBpm\fR, appropriate to the given locale. If the script of the given locale supports multiple letterforms, uppercase is preferred. @@ -642,18 +697,23 @@ On input, matches the representation \fBAM\fR or \fBPM\fR in the given locale, in either case. .TP \fB%Q\fR +. This format group is reserved for internal use within the Tcl library. +.\" It's the STARDATE! We're so Enterprise-ready... .TP \fB%r\fR +. On output, produces a locale-dependent time of day representation on a 12-hour clock. On input, accepts whatever \fB%r\fR produces. .TP \fB%R\fR +. On output, the time in 24-hour notation (%H:%M). For a version including the seconds, see \fB%T\fR below. On input, accepts whatever \fB%R\fR produces. .TP \fB%s\fR +. On output, simply formats the \fItimeVal\fR argument as a decimal integer and inserts it into the output string. On input, accepts a decimal integer and uses is as the time value without any further @@ -661,23 +721,28 @@ processing. Since \fB%s\fR uniquely determines a point in time, it overrides all other input formats. .TP \fB%S\fR +. On output, produces a two-digit number of the second of the minute (00-59). On input, accepts two digits and uses them as the second of the minute. .TP \fB%t\fR +. On output, produces a TAB character. On input, matches a TAB character. .TP \fB%T\fR +. Synonymous with \fB%H:%M:%S\fR. .TP \fB%u\fR +. On output, produces the number of the day of the week (\fB1\fR\(->Monday, \fB7\fR\(->Sunday). On input, accepts a single digit and interprets it as the day of the week. Sunday may be either \fB0\fR or \fB7\fR. .TP \fB%U\fR +. On output, produces the ordinal number of the week of the year (00-53). The first Sunday of the year is the first day of week 01. On input accepts two digits which are otherwise ignored. This format @@ -686,6 +751,7 @@ of the week of the year was once common in US banking but is now largely obsolete. See \fB%V\fR for the ISO8601 week number. .TP \fB%V\fR +. On output, produces the number of the ISO8601 week as a two digit number (01-53). Week 01 is the week containing January 4; or the first week of the year containing at least 4 days; or the week containing @@ -694,6 +760,7 @@ equivalent). Each week begins on a Monday. On input, accepts the ISO8601 week number. .TP \fB%w\fR +. On output, produces the ordinal number of the day of the week (Sunday==0; Saturday==6). On input, accepts a single digit and interprets it as the day of the week; Sunday may be represented as @@ -701,6 +768,7 @@ either 0 or 7. Note that \fB%w\fR is not the ISO8601 weekday number, which is produced and accepted by \fB%u\fR. .TP \fB%W\fR +. On output, produces a week number (00-53) within the year; week 01 begins on the first Monday of the year. On input, accepts two digits, which are otherwise ignored. This format group is never used in @@ -708,16 +776,19 @@ determining an input date. It is not the ISO8601 week number; that week is produced and accepted by \fB%V\fR. .TP \fB%x\fR +. On output, produces the date in a locale-dependent representation. On input, accepts whatever \fB%x\fR produces and is used to determine calendar date. .TP \fB%X\fR +. On output, produces the time of day in a locale-dependent representation. On input, accepts whatever \fB%X\fR produces and is used to determine time of day. .TP \fB%y\fR +. On output, produces the two-digit year of the century. On input, accepts two digits, and is used to determine calendar date. The date is presumed to lie between 1938 and 2037 inclusive. Note @@ -725,18 +796,21 @@ that \fB%y\fR does not yield a year appropriate for use with the ISO8601 week number \fB%V\fR; programs should use \fB%g\fR for that purpose. .TP \fB%Y\fR +. On output, produces the four-digit calendar year. On input, accepts four digits and may be used to determine calendar date. Note that \fB%Y\fR does not yield a year appropriate for use with the ISO8601 week number \fB%V\fR; programs should use \fB%G\fR for that purpose. .TP \fB%z\fR +. On output, produces the current time zone, expressed in hours and minutes east (+hhmm) or west (\-hhmm) of Greenwich. On input, accepts a time zone specifier (see \fBTIME ZONES\fR below) that will be used to determine the time zone. .TP \fB%Z\fR +. On output, produces the current time zone's name, possibly translated to the given locale. On input, accepts a time zone specifier (see \fBTIME ZONES\fR below) that will be used to determine the @@ -747,6 +821,7 @@ Brazilian Standard Time. It is recommended that date/time strings for use by computers use numeric time zones instead. .TP \fB%%\fR +. On output, produces a literal .QW \fB%\fR character. On input, matches a literal @@ -754,6 +829,7 @@ character. On input, matches a literal character. .TP \fB%+\fR +. Synonymous with .QW "\fB%a %b %e %H:%M:%S %Z %Y\fR" . .SH "TIME ZONES" @@ -766,7 +842,7 @@ A time zone specified inside a string being parsed and matched by a \fB%z\fR or \fB%Z\fR format group. .IP [2] A time zone specified with the \fB\-timezone\fR option to the \fBclock\fR -command (or, equivalently, by \fB\-gmt\fR \fB1\fR). +command (or, equivalently, by \fB\-gmt 1\fR). .IP [3] A time zone specified in an environment variable \fBTCL_TZ\fR. .IP [4] @@ -852,8 +928,9 @@ specification. .SH "FREE FORM SCAN" .PP If the \fBclock scan\fR command is invoked without a \fB\-format\fR -option, then it requests a \fIfree-form scan.\fR \fI -This form of scan is deprecated.\fR The reason for the deprecation +option, then it requests a \fIfree-form scan\fR. +\fIThis form of scan is deprecated.\fR +The reason for the deprecation is that there are too many ambiguities. (Does the string .QW 2000 represent a year, a time of day, or a quantity?) No set of rules diff --git a/doc/concat.n b/doc/concat.n index d10f092..c83d2c4 100644 --- a/doc/concat.n +++ b/doc/concat.n @@ -28,7 +28,7 @@ Although \fBconcat\fR will concatenate lists, flattening them in the process (so giving the following interactive session): .PP .CS -\fI%\fR \fBconcat\fR a b {c d e} {f {g h}} +\fI% \fBconcat\fR a b {c d e} {f {g h}} \fIa b c d e f {g h}\fR .CE .PP @@ -36,7 +36,7 @@ it will also concatenate things that are not lists, as can be seen from this session: .PP .CS -\fI%\fR \fBconcat\fR " a b {c " d " e} f" +\fI% \fBconcat\fR " a b {c " d " e} f" \fIa b {c d e} f\fR .CE .PP @@ -44,14 +44,22 @@ Note also that the concatenation does not remove spaces from the middle of values, as can be seen here: .PP .CS -\fI%\fR \fBconcat\fR "a b c" { d e f } +\fI% \fBconcat\fR "a b c" { d e f } \fIa b c d e f\fR .CE .PP (i.e., there are three spaces between each of the \fBa\fR, the \fBb\fR and the \fBc\fR). +.PP +For \fItrue\fR list concatenation, the \fBlist\fR command should be used with +expansion of each input list: +.PP +.CS +\fI% \fRlist {*}"a b c" {*}{ d e f } +\fIa b c d e f\fR +.CE .SH "SEE ALSO" -append(n), eval(n), join(n) +append(n), eval(n), join(n), list(n) .SH KEYWORDS concatenate, join, list '\" Local Variables: diff --git a/doc/configurable.n b/doc/configurable.n index 0102f8c..07335bd 100644 --- a/doc/configurable.n +++ b/doc/configurable.n @@ -25,8 +25,8 @@ package require TclOO \fB}\fR \fIobjectName \fBconfigure\fR -\fIobjectName \fBconfigure\fR \fI\-prop\fR -\fIobjectName \fBconfigure\fR \fI\-prop value\fR ?\fI\-prop value\fR... +\fIobjectName \fBconfigure\fI \-prop\fR +\fIobjectName \fBconfigure\fI \-prop value\fR ?\fI\-prop value\fR... .fi .SH "CLASS HIERARCHY" .nf @@ -54,6 +54,7 @@ definition command available in definition scripts for the class and instances \fBoo::objdefine\fR) and making a \fBconfigure\fR method available within the instances. .SS "CONFIGURE METHOD" +.\" METHOD: configure .PP The behavior of the \fBconfigure\fR method is modelled after the \fBfconfigure\fR/\fBchan configure\fR command. @@ -74,6 +75,7 @@ method fails, the preceding pairs (if any) will continue to have been applied, and the succeeding pairs (if any) will be not applied. On success, the result of the \fBconfigure\fR method in this mode operation will be an empty string. .SS "PROPERTY DEFINITIONS" +.\" COMMAND: property .PP When a class has been manufactured by the \fBoo::configurable\fR metaclass (or one of its subclasses), it gains an extra definition, \fBproperty\fR. The @@ -143,11 +145,13 @@ The configurable class system is comprised of several pieces. The definition namespaces during object creation that provide the other bits and pieces of machinery. The key pieces of the implementation are enumerated here so that they can be used by other code: +.\" COMMAND: configurable .TP \fBoo::configuresupport::configurable\fR . This is a class that provides the implementation of the \fBconfigure\fR method (described above in \fBCONFIGURE METHOD\fR). +.\" NAMESPACE: configurableclass .TP \fBoo::configuresupport::configurableclass\fR . @@ -156,6 +160,7 @@ This is a namespace that contains the definition dialect that provides the class constructors under normal circumstances), as described above in \fBPROPERTY DEFINITIONS\fR. It \fBnamespace export\fRs its \fBproperty\fR command so that it may be used easily in user definition dialects. +.\" NAMESPACE: configurableobject .TP \fBoo::configuresupport::configurableobject\fR . @@ -173,24 +178,28 @@ slots mean other than that they have unique names, no important order, can be inherited and discovered on classes and instances. .PP These slots, and their intended semantics, are: +.\" METHOD: readableproperties .TP \fBoo::configuresupport::readableproperties\fR . The set of properties of a class (not including those from its superclasses) that may be read from when configuring an instance of the class. This slot can also be read with the \fBinfo class properties\fR command. +.\" METHOD: writableproperties .TP \fBoo::configuresupport::writableproperties\fR . The set of properties of a class (not including those from its superclasses) that may be written to when configuring an instance of the class. This slot can also be read with the \fBinfo class properties\fR command. +.\" METHOD: objreadableproperties .TP \fBoo::configuresupport::objreadableproperties\fR . The set of properties of an object instance (not including those from its classes) that may be read from when configuring the object. This slot can also be read with the \fBinfo object properties\fR command. +.\" METHOD: objwritableproperties .TP \fBoo::configuresupport::objwritableproperties\fR . diff --git a/doc/cookiejar.n b/doc/cookiejar.n index 1391e01..224d488 100644 --- a/doc/cookiejar.n +++ b/doc/cookiejar.n @@ -15,13 +15,13 @@ cookiejar \- Implementation of the Tcl http package cookie jar protocol \fBpackage require\fR \fBcookiejar\fR ?\fB0.1\fR? \fB::http::cookiejar configure\fR ?\fIoptionName\fR? ?\fIoptionValue\fR? -\fB::http::cookiejar create\fR \fIname\fR ?\fIfilename\fR? +\fB::http::cookiejar create\fI name\fR ?\fIfilename\fR? \fB::http::cookiejar new\fR ?\fIfilename\fR? \fIcookiejar\fR \fBdestroy\fR \fIcookiejar\fR \fBforceLoadDomainData\fR -\fIcookiejar\fR \fBgetCookies\fR \fIprotocol host path\fR -\fIcookiejar\fR \fBstoreCookie\fR \fIoptions\fR +\fIcookiejar\fR \fBgetCookies\fI protocol host path\fR +\fIcookiejar\fR \fBstoreCookie\fI options\fR \fIcookiejar\fR \fBlookup\fR ?\fIhost\fR? ?\fIkey\fR? .fi .SH DESCRIPTION @@ -33,6 +33,7 @@ create a cookie jar that manages a particular HTTP session. .PP The database management policy can be controlled at the package level by the \fBconfigure\fR method on the \fB::http::cookiejar\fR class object: +.\" METHOD: configure .TP \fB::http::cookiejar configure\fR ?\fIoptionName\fR? ?\fIoptionValue\fR? . @@ -97,6 +98,7 @@ the database. .PP Cookie jar instances may be made with any of the standard TclOO instance creation methods (\fBcreate\fR or \fBnew\fR). +.\" METHOD: new .TP \fB::http::cookiejar new\fR ?\fIfilename\fR? . @@ -108,27 +110,31 @@ memory, which effectively forces all cookies within it to be session cookies. .SS "INSTANCE METHODS" .PP The following methods are supported on the instances: +.\" METHOD: destroy .TP -\fIcookiejar\fR \fBdestroy\fR +\fIcookiejar \fBdestroy\fR . This is the standard TclOO destruction method. It does \fInot\fR delete the SQLite database if it is written to disk. Callers are responsible for ensuring that the cookie jar is not in use by the http package at the time of destruction. +.\" METHOD: forceLoadDomainData .TP -\fIcookiejar\fR \fBforceLoadDomainData\fR +\fIcookiejar \fBforceLoadDomainData\fR . This method causes the cookie jar to immediately load (and cache) the domain list data. The domain list will be loaded from the \fB\-domainlist\fR configured a the package level if that is enabled, and otherwise will be obtained from the \fB\-domainfile\fR configured at the package level. +.\" METHOD: getCookies .TP -\fIcookiejar\fR \fBgetCookies\fR \fIprotocol host path\fR +\fIcookiejar \fBgetCookies\fI protocol host path\fR . This method obtains the cookies for a particular HTTP request. \fIThis implements the http cookie jar protocol.\fR +.\" METHOD: policyAllow .TP -\fIcookiejar\fR \fBpolicyAllow\fR \fIoperation domain path\fR +\fIcookiejar \fBpolicyAllow\fI operation domain path\fR . This method is called by the \fBstoreCookie\fR method to get a decision on whether to allow \fIoperation\fR to be performed for the \fIdomain\fR and @@ -154,14 +160,16 @@ defined lifetime). The default implementation of this method just returns true, but subclasses of this class may impose their own rules. .RE +.\" METHOD: storeCookie .TP -\fIcookiejar\fR \fBstoreCookie\fR \fIoptions\fR +\fIcookiejar \fBstoreCookie\fI options\fR . This method stores a single cookie from a particular HTTP response. Cookies that fail security checks are ignored. \fIThis implements the http cookie jar protocol.\fR +.\" METHOD: lookup .TP -\fIcookiejar\fR \fBlookup\fR ?\fIhost\fR? ?\fIkey\fR? +\fIcookiejar \fBlookup\fR ?\fIhost\fR? ?\fIkey\fR? . This method looks a cookie by exact host (or domain) matching. If neither \fIhost\fR nor \fIkey\fR are supplied, the list of hosts for which a cookie is diff --git a/doc/coroutine.n b/doc/coroutine.n index 8110628..25ab6ad 100644 --- a/doc/coroutine.n +++ b/doc/coroutine.n @@ -14,7 +14,7 @@ coroutine, yield, yieldto, coroinject, coroprobe \- Create and produce values fr .nf \fBcoroutine \fIname command\fR ?\fIarg...\fR? \fByield\fR ?\fIvalue\fR? -\fByieldto\fR \fIcommand\fR ?\fIarg...\fR? +\fByieldto\fI command\fR ?\fIarg...\fR? \fIname\fR ?\fIvalue...\fR? .sp .VS "8.7, TIP383" @@ -198,7 +198,7 @@ proc juggler {name target {value ""}} { while {$value ne ""} { puts "$name : $value" set value [string range $value 0 end-1] - lassign [\fByieldto\fR \fI$target\fR $value] value + lassign [\fByieldto\fI $target\fR $value] value } } \fBcoroutine\fR j1 juggler Larry [ @@ -44,6 +44,7 @@ has the service name \fBExcel\fR. .PP The following commands are a subset of the full Dynamic Data Exchange set of commands. +.\" METHOD: servername .TP \fBdde servername \fR?\fB\-force\fR? ?\fB\-handler \fIproc\fR? ?\fB\-\|\-\fR? ?\fItopic\fR? . @@ -68,6 +69,7 @@ safe interpreter then a \fB\-handler\fR procedure must be defined. The procedure is called with all the arguments provided by the remote call. .RE +.\" METHOD: execute .TP \fBdde execute\fR ?\fB\-async\fR? ?\fB\-binary\fR? \fIservice topic data\fR . @@ -80,11 +82,15 @@ script is run in the application. The \fB\-async\fR option requests asynchronous invocation. The command returns an error message if the script did not run, unless the \fB\-async\fR flag was used, in which case the command returns immediately with no error. +.RS +.PP Without the \fB\-binary\fR option all data will be sent in unicode. For dde clients which don't implement the CF_UNICODE clipboard format, this will automatically be translated to the system encoding. You can use the \fB\-binary\fR option in combination with the result of \fBencoding convertto\fR to send data in any other encoding. +.RE +.\" METHOD: poke .TP \fBdde poke\fR ?\fB\-binary\fR? \fIservice topic item data\fR . @@ -95,11 +101,15 @@ specific but can be a command to the server or the name of a file to work on. The \fIitem\fR is also application specific and is often not used, but it must always be non-null. The \fIdata\fR field is given to the remote application. +.RS +.PP Without the \fB\-binary\fR option all data will be sent in unicode. For dde clients which don't implement the CF_UNICODE clipboard format, this will automatically be translated to the system encoding. You can use the \fB\-binary\fR option in combination with the result of \fBencoding convertto\fR to send data in any other encoding. +.RE +.\" METHOD: request .TP \fBdde request\fR ?\fB\-binary\fR? \fIservice topic item\fR . @@ -111,6 +121,7 @@ application-specific. The command returns the value of \fIitem\fR as defined in the application. Normally this is interpreted to be a string with terminating null. If \fB\-binary\fR is specified, the result is returned as a byte array. +.\" METHOD: services .TP \fBdde services \fIservice topic\fR . @@ -123,6 +134,7 @@ returned. If \fIservice\fR is non-empty and \fItopic\fR is, all topics for a given service are returned. If both are non-empty, if that service-topic pair currently exists, it is returned; otherwise, an empty string is returned. +.\" METHOD: eval .TP \fBdde eval\fR ?\fB\-async\fR? \fItopic cmd \fR?\fIarg arg ...\fR? . diff --git a/doc/define.n b/doc/define.n index c5e93ac..cb1864c43 100644 --- a/doc/define.n +++ b/doc/define.n @@ -42,6 +42,7 @@ and define a class in one step. .PP The following commands are supported in the \fIdefScript\fR for \fBoo::define\fR, each of which may also be used in the \fIsubcommand\fR form: +.\" METHOD: classmethod .TP \fBclassmethod\fI name\fR ?\fIargList bodyScrip\fR? .VS TIP478 @@ -63,6 +64,7 @@ In a private definition context, the methods as invoked on classes are private. .RE .VE TIP478 +.\" METHOD: constructor .TP \fBconstructor\fI argList bodyScript\fR . @@ -79,6 +81,7 @@ string, the constructor will be deleted. Classes do not need to have a constructor defined. If none is specified, the superclass's constructor will be used instead. .RE +.\" METHOD: destructor .TP \fBdestructor\fI bodyScript\fR . @@ -95,6 +98,7 @@ Note that errors during the evaluation of a destructor \fIare not returned\fR to the code that causes the destruction of an object. Instead, they are passed to the currently-defined \fBbgerror\fR handler. .RE +.\" METHOD: export .TP \fBexport\fI name \fR?\fIname ...\fR? . @@ -103,6 +107,7 @@ This arranges for each of the named methods, \fIname\fR, to be exported class being defined. Note that the methods themselves may be actually defined by a superclass; subclass exports override superclass visibility, and may in turn be overridden by instances. +.\" METHOD: forward .TP \fBforward\fI name cmdName \fR?\fIarg ...\fR? . @@ -122,6 +127,8 @@ If in a private definition context (see the \fBprivate\fR definition command, below), this command creates private forwarded methods. .VE TIP500 .RE +.\" METHOD: initialise +.\" METHOD: initialize .TP \fBinitialise\fI script\fR .TP @@ -131,6 +138,7 @@ This evaluates \fIscript\fR in a context which supports local variables and where the current namespace is the instance namespace of the class object itself. This is useful for setting up, e.g., class-scoped variables. .VE TIP478 +.\" METHOD: method .TP \fBmethod\fI name \fR?\fIoption\fR? \fIargList bodyScript\fR . @@ -155,6 +163,7 @@ below) or if the \fB\-private\fR flag is given for \fIoption\fR, this command creates private procedure-like methods. .VE TIP500 .RE +.\" METHOD: private .TP \fBprivate \fIcmd arg...\fR .TP @@ -174,6 +183,7 @@ commands have no difference in behavior when used in a private definition context. .RE .VE TIP500 +.\" METHOD: self .TP \fBself\fI subcommand arg ...\fR .TP @@ -201,6 +211,7 @@ below), the definitions on the class object will also be made in a private definition context. .VE TIP500 .RE +.\" METHOD: superclass .TP \fBsuperclass\fR ?\fI\-slotOperation\fR? ?\fIclassName ...\fR? . @@ -212,6 +223,7 @@ being non-classes or vice-versa, that an empty parent class is equivalent to \fBoo::object\fR, and that the parent classes of \fBoo::object\fR and \fBoo::class\fR may not be modified. By default, this slot works by replacement. +.\" METHOD: unexport .TP \fBunexport\fI name \fR?\fIname ...\fR? . @@ -221,6 +233,7 @@ but instead just through the \fBmy\fR command visible in each object's context) by the class being defined. Note that the methods themselves may be actually defined by a superclass; subclass unexports override superclass visibility, and may be overridden by instance unexports. +.\" METHOD: variable .TP \fBvariable\fR ?\fI\-slotOperation\fR? ?\fIname ...\fR? . @@ -252,6 +265,7 @@ extremely unlikely. .PP The following definitions are also supported, but are not required in simple programs: +.\" METHOD: definitionnamespace .TP \fBdefinitionnamespace\fR ?\fIkind\fR? \fInamespaceName\fR .VS TIP524 @@ -278,6 +292,7 @@ locked to \fB::oo::define\fR. A consequence of this is that effective use of this feature for classes requires the definition of a metaclass. .RE .VE TIP524 +.\" METHOD: deletemethod .TP \fBdeletemethod\fI name\fR ?\fIname ...\fR? . @@ -286,6 +301,7 @@ must have previously existed in that class. Does not affect the superclasses of the class, nor does it affect the subclasses or instances of the class (except when they have a call chain through the class being modified) or the class object itself. +.\" METHOD: filter .TP \fBfilter\fR ?\fI\-slotOperation\fR? ?\fImethodName ...\fR? . @@ -296,6 +312,7 @@ results are. Each \fImethodName\fR names a single filtering method (which may be exposed or not exposed); it is not an error for a non-existent method to be named since they may be defined by subclasses. By default, this slot works by appending. +.\" METHOD: mixin .TP \fBmixin\fR ?\fI\-slotOperation\fR? ?\fIclassName ...\fR? . @@ -304,6 +321,7 @@ sets or updates the list of additional classes that are to be mixed into all the instances of the class being defined. Each \fIclassName\fR argument names a single class that is to be mixed in. By default, this slot works by replacement. +.\" METHOD: renamemethod .TP \fBrenamemethod\fI fromName toName\fR . @@ -320,6 +338,7 @@ be afterwards. The following commands are supported in the \fIdefScript\fR for \fBoo::objdefine\fR, each of which may also be used in the \fIsubcommand\fR form: +.\" METHOD: export .TP \fBexport\fI name \fR?\fIname ...\fR? . @@ -327,6 +346,7 @@ This arranges for each of the named methods, \fIname\fR, to be exported (i.e. usable outside the object through the object's command) by the object being defined. Note that the methods themselves may be actually defined by a class or superclass; object exports override class visibility. +.\" METHOD: forward .TP \fBforward\fI name cmdName \fR?\fIarg ...\fR? . @@ -343,6 +363,7 @@ If in a private definition context (see the \fBprivate\fR definition command, below), this command creates private forwarded methods. .VE TIP500 .RE +.\" METHOD: method .TP \fBmethod\fI name \fR?\fIoption\fR? \fIargList bodyScript\fR . @@ -366,6 +387,7 @@ below) or if the \fB\-private\fR flag is given for \fIoption\fR, this command creates private procedure-like methods. .VE TIP500 .RE +.\" METHOD: mixin .TP \fBmixin\fR ?\fI\-slotOperation\fR? ?\fIclassName ...\fR? . @@ -374,6 +396,7 @@ sets or updates a per-object list of additional classes that are to be mixed into the object. Each argument, \fIclassName\fR, names a single class that is to be mixed in. By default, this slot works by replacement. +.\" METHOD: private .TP \fBprivate \fIcmd arg...\fR .TP @@ -391,6 +414,7 @@ just a private definition context. All other definition commands have no difference in behavior when used in a private definition context. .RE .VE TIP500 +.\" METHOD: unexport .TP \fBunexport\fI name \fR?\fIname ...\fR? . @@ -399,6 +423,7 @@ This arranges for each of the named methods, \fIname\fR, to be not exported just through the \fBmy\fR command visible in the object's context) by the object being defined. Note that the methods themselves may be actually defined by a class; instance unexports override class visibility. +.\" METHOD: variable .TP \fBvariable\fR ?\fI\-slotOperation\fR? ?\fIname ...\fR? . @@ -428,12 +453,14 @@ superclass methods extremely unlikely. .PP The following definitions are also supported, but are not required in simple programs: +.\" METHOD: class .TP \fBclass\fI className\fR . This allows the class of an object to be changed after creation. Note that the class's constructors are not called when this is done, and so the object may well be in an inconsistent state unless additional configuration work is done. +.\" METHOD: deletemethod .TP \fBdeletemethod\fI name\fR ?\fIname ...\fR . @@ -442,6 +469,7 @@ must have previously existed in that object (e.g., because it was created through \fBoo::objdefine method\fR). Does not affect the classes that the object is an instance of, or remove the exposure of those class-provided methods in the instance of that class. +.\" METHOD: filter .TP \fBfilter\fR ?\fI\-slotOperation\fR? ?\fImethodName ...\fR? . @@ -453,6 +481,7 @@ not exposed); it is not an error for a non-existent method to be named. Note that the actual list of filters also depends on the filters set upon any classes that the object is an instance of. By default, this slot works by appending. +.\" METHOD: renamemethod .TP \fBrenamemethod\fI fromName toName\fR . @@ -527,6 +556,7 @@ which is forwarded to the default operation of the slot (thus, for the class slot, this is forwarded to .QW "\fBmy \-append\fR" ), and these methods which provide the implementation interface: +.\" METHOD: Get .TP \fIslot\fR \fBGet\fR . @@ -542,8 +572,9 @@ The elements of the list should be fully resolved, if that is a meaningful concept to the slot. .VE TIP516 .RE +.\" METHOD: Resolve .TP -\fIslot\fR \fBResolve\fR \fIslotElement\fR +\fIslot\fR \fBResolve\fI slotElement\fR .VS TIP516 Returns \fIslotElement\fR with a resolution operation applied to it, but does not modify the slot. For slots of simple strings, this is an operation that @@ -560,6 +591,7 @@ Implementations \fIshould not\fR enforce uniqueness and ordering constraints in this method; that is the responsibility of the \fBSet\fR method. .RE .VE TIP516 +.\" METHOD: Set .TP \fIslot\fR \fBSet \fIelementList\fR . @@ -19,6 +19,7 @@ Performs one of several operations on dictionary values or variables containing dictionary values (see the \fBDICTIONARY VALUES\fR section below for a description), depending on \fIoption\fR. The legal \fIoption\fRs (which may be abbreviated) are: +.\" METHOD: append .TP \fBdict append \fIdictionaryVariable key \fR?\fIstring ...\fR? . @@ -32,12 +33,14 @@ If \fIdictionaryVariable\fR indicates an element that does not exist of an array that has a default value set, the default value and will be used as the value of the dictionary prior to the appending operation. .VE TIP508 +.\" METHOD: create .TP \fBdict create \fR?\fIkey value ...\fR? . Return a new dictionary that contains each of the key/value mappings listed as arguments (keys and values alternating, with each key being followed by its associated value.) +.\" METHOD: exists .TP \fBdict exists \fIdictionaryValue key \fR?\fIkey ...\fR? . @@ -45,6 +48,7 @@ This returns a boolean value indicating whether the given key (or path of keys through a set of nested dictionaries) exists in the given dictionary value. This returns a true value exactly when \fBdict get\fR on that path will succeed. +.\" METHOD: filter .TP \fBdict filter \fIdictionaryValue filterType arg \fR?\fIarg ...\fR? . @@ -54,6 +58,7 @@ type (which may be abbreviated.) Supported filter types are: .RS .TP \fBdict filter \fIdictionaryValue \fBkey\fR ?\fIglobPattern ...\fR? +. The key rule only matches those key/value pairs whose keys match any of the given patterns (in the style of \fBstring match\fR.) .TP @@ -72,9 +77,11 @@ result. The key/value pairs are tested in the order in which the keys were inserted into the dictionary. .TP \fBdict filter \fIdictionaryValue \fBvalue \fR?\fIglobPattern ...\fR? +. The value rule only matches those key/value pairs whose values match any of the given patterns (in the style of \fBstring match\fR.) .RE +.\" METHOD: for .TP \fBdict for {\fIkeyVariable valueVariable\fB} \fIdictionaryValue body\fR . @@ -90,6 +97,7 @@ terminate successfully immediately. If any evaluation of the body generates a \fBTCL_CONTINUE\fR result, this shall be treated exactly like a normal \fBTCL_OK\fR result. The order of iteration is the order in which the keys were inserted into the dictionary. +.\" METHOD: get .TP \fBdict get \fIdictionaryValue \fR?\fIkey ...\fR? . @@ -115,6 +123,8 @@ the value for that key. It is an error to attempt to retrieve a value for a key that is not present in the dictionary. .RE +.\" METHOD: getdef +.\" METHOD: getwithdefault .TP \fBdict getdef \fIdictionaryValue \fR?\fIkey ...\fR? \fIkey default\fR .TP @@ -131,6 +141,7 @@ Note that there must always be at least one \fIkey\fR provided, and that \fBdict getdef\fR and \fBdict getwithdefault\fR are aliases for each other. .RE .VE "8.7, TIP342" +.\" METHOD: incr .TP \fBdict incr \fIdictionaryVariable key \fR?\fIincrement\fR? . @@ -146,6 +157,7 @@ If \fIdictionaryVariable\fR indicates an element that does not exist of an array that has a default value set, the default value and will be used as the value of the dictionary prior to the incrementing operation. .VE TIP508 +.\" METHOD: info .TP \fBdict info \fIdictionaryValue\fR . @@ -154,6 +166,7 @@ given dictionary though the format of this data is dependent on the implementation of the dictionary. For dictionaries that are implemented by hash tables, it is expected that this will return the string produced by \fBTcl_HashStats\fR, similar to \fBarray statistics\fR. +.\" METHOD: keys .TP \fBdict keys \fIdictionaryValue \fR?\fIglobPattern\fR? . @@ -161,6 +174,7 @@ Return a list of all keys in the given dictionary value. If a pattern is supplied, only those keys that match it (according to the rules of \fBstring match\fR) will be returned. The returned keys will be in the order that they were inserted into the dictionary. +.\" METHOD: lappend .TP \fBdict lappend \fIdictionaryVariable key \fR?\fIvalue ...\fR? . @@ -176,6 +190,7 @@ If \fIdictionaryVariable\fR indicates an element that does not exist of an array that has a default value set, the default value and will be used as the value of the dictionary prior to the list-appending operation. .VE TIP508 +.\" METHOD: map .TP \fBdict map \fR{\fIkeyVariable valueVariable\fR} \fIdictionaryValue body\fR . @@ -201,6 +216,7 @@ of iteration is the natural order of the dictionary (typically the order in which the keys were added to the dictionary; the order is the same as that used in \fBdict for\fR). .RE +.\" METHOD: merge .TP \fBdict merge \fR?\fIdictionaryValue ...\fR? . @@ -209,6 +225,7 @@ Return a dictionary that contains the contents of each of the contain a mapping for the same key, the resulting dictionary maps that key to the value according to the last dictionary on the command line containing a mapping for that key. +.\" METHOD: remove .TP \fBdict remove \fIdictionaryValue \fR?\fIkey ...\fR? . @@ -217,6 +234,7 @@ first argument except without mappings for each of the keys listed. It is legal for there to be no keys to remove, and it also legal for any of the keys to be removed to not be present in the input dictionary in the first place. +.\" METHOD: replace .TP \fBdict replace \fIdictionaryValue \fR?\fIkey value ...\fR? . @@ -225,6 +243,7 @@ first argument except with some values different or some extra key/value pairs added. It is legal for this command to be called with no key/value pairs, but illegal for this command to be called with a key but no value. +.\" METHOD: set .TP \fBdict set \fIdictionaryVariable key \fR?\fIkey ...\fR? \fIvalue\fR . @@ -238,10 +257,12 @@ If \fIdictionaryVariable\fR indicates an element that does not exist of an array that has a default value set, the default value and will be used as the value of the dictionary prior to the value insert/update operation. .VE TIP508 +.\" METHOD: size .TP \fBdict size \fIdictionaryValue\fR . Return the number of key/value mappings in the given dictionary value. +.\" METHOD: unset .TP \fBdict unset \fIdictionaryVariable key \fR?\fIkey ...\fR? . @@ -258,6 +279,7 @@ If \fIdictionaryVariable\fR indicates an element that does not exist of an array that has a default value set, the default value and will be used as the value of the dictionary prior to the value remove operation. .VE TIP508 +.\" METHOD: update .TP \fBdict update \fIdictionaryVariable key varName \fR?\fIkey varName ...\fR? \fIbody\fR . @@ -289,6 +311,7 @@ Note that the mapping of values to variables does not use traces; changes to the \fIdictionaryVariable\fR's contents only happen when \fIbody\fR terminates. .RE +.\" METHOD: values .TP \fBdict values \fIdictionaryValue \fR?\fIglobPattern\fR? . @@ -297,6 +320,7 @@ pattern is supplied, only those values that match it (according to the rules of \fBstring match\fR) will be returned. The returned values will be in the order of that the keys associated with those values were inserted into the dictionary. +.\" METHOD: with .TP \fBdict with \fIdictionaryVariable \fR?\fIkey ...\fR? \fIbody\fR . diff --git a/doc/encoding.n b/doc/encoding.n index 255e070..b88dbc4 100644 --- a/doc/encoding.n +++ b/doc/encoding.n @@ -44,14 +44,14 @@ expr {$text eq $decoded}; #-> 1 .SH DESCRIPTION .PP Performs one of the following encoding \fIoperations\fR: +.\" METHOD: convertfrom .TP \fBencoding convertfrom\fR ?\fIencoding\fR? \fIdata\fR .TP -\fBencoding convertfrom\fR ?\fB-profile \fIprofile\fR? ?\fB-failindex var\fR? \fIencoding\fR \fIdata\fR +\fBencoding convertfrom\fR ?\fB-profile \fIprofile\fR? ?\fB-failindex var\fR? \fIencoding data\fR . Decodes \fIdata\fR encoded in \fIencoding\fR. If \fIencoding\fR is not specified the current system encoding is used. - .VS "TCL8.7 TIP607, TIP656" \fB-profile\fR determines how invalid data for the encoding are handled. See the \fBPROFILES\fR section below for details. Returns an error if decoding @@ -61,17 +61,18 @@ the character that could not be converted. If no errors are encountered the entire result of the conversion is returned and the value \fB-1\fR is stored in \fBvar\fR. .VE "TCL8.7 TIP607, TIP656" +.\" METHOD: convertto .TP \fBencoding convertto\fR ?\fIencoding\fR? \fIdata\fR .TP -\fBencoding convertto\fR ?\fB-profile \fIprofile\fR? ?\fB-failindex var\fR? \fIencoding\fR \fIdata\fR +\fBencoding convertto\fR ?\fB-profile \fIprofile\fR? ?\fB-failindex var\fR? \fIencoding data\fR . Converts \fIstring\fR to \fIencoding\fR. If \fIencoding\fR is not given, the current system encoding is used. - .VS "TCL8.7 TIP607, TIP656" See \fBencoding convertfrom\fR for the meaning of \fB-profile\fR and \fB-failindex\fR. .VE "TCL8.7 TIP607, TIP656" +.\" METHOD: dirs .TP \fBencoding dirs\fR ?\fIdirectoryList\fR? . @@ -80,6 +81,7 @@ directories given by \fIdirectoryList\fR. If \fIdirectoryList\fR is not given, returns the current list of directories that make up the search path. It is not an error for an item in \fIdirectoryList\fR to not refer to a readable, searchable directory. +.\" METHOD: names .TP \fBencoding names\fR . @@ -95,6 +97,7 @@ are guaranteed to be present in the list. Returns a list of names of available encoding profiles. See \fBPROFILES\fR below. .VE "TCL8.7 TIP656" +.\" METHOD: system .TP \fBencoding system\fR ?\fIencoding\fR? . @@ -109,15 +112,16 @@ Each \fIprofile\fR is a distinct strategy for dealing with invalid data for an encoding. .PP The following profiles are currently implemented. -.VS "TCL8.7 TIP656" +.VE "TCL8.7 TIP656" .TP \fBstrict\fR -. +.VS "TCL8.7 TIP656" The default profile. The operation fails when invalid data for the encoding are encountered. +.VE "TCL8.7 TIP656" .TP \fBtcl8\fR -. +.VS "TCL8.7 TIP656" Provides for behaviour identical to that of Tcl 8.6: When decoding, for encodings \fBother than utf-8\fR, each invalid byte is interpreted as the Unicode value given by that one byte. For example, the byte 0x80, which @@ -128,18 +132,23 @@ not is treated as the Unicode value given by that one byte. For example, byte 0x80 is defined by CP1252 and is therefore mapped to its Unicode equivalent U+20AC while byte 0x81 which is not defined by CP1252 is mapped to U+0081. As an additional special case, the sequence 0xC0 0x80 is mapped to U+0000. - +.RS +.PP When encoding, each character that cannot be represented in the encoding is replaced by an encoding-dependent character, usually the question mark \fB?\fR. +.RE +.VE "TCL8.7 TIP656" .TP \fBreplace\fR -. +.VS "TCL8.7 TIP 656" When decoding, invalid bytes are replaced by U+FFFD, the Unicode REPLACEMENT CHARACTER. - +.RS +.PP When encoding, Unicode values that cannot be represented in the target encoding are transformed to an encoding-specific fallback character, U+FFFD REPLACEMENT CHARACTER for UTF targets, and generally `?` for other encodings. +.RE .VE "TCL8.7 TIP656" .SH EXAMPLES .PP @@ -170,18 +179,18 @@ The letter \fBA\fR is Unicode character U+0041 and the byte "\ex80" is invalid in ASCII encoding. .PP .CS -% codepoints [encoding convertfrom -profile tcl8 ascii A\ex80] +% codepoints [\fBencoding convertfrom\fR -profile tcl8 ascii A\ex80] U+000041 U+000080 -% codepoints [encoding convertfrom -profile replace ascii A\ex80] +% codepoints [\fBencoding convertfrom\fR -profile replace ascii A\ex80] U+000041 U+00FFFD -% codepoints [encoding convertfrom -profile strict ascii A\ex80] +% codepoints [\fBencoding convertfrom\fR -profile strict ascii A\ex80] unexpected byte sequence starting at index 1: '\ex80' .CE .PP Example 3: Get partial data and the error location: .PP .CS -% codepoints [encoding convertfrom -failindex idx ascii AB\ex80] +% codepoints [\fBencoding convertfrom\fR -failindex idx ascii AB\ex80] U+000041 U+000042 % set idx 2 @@ -190,11 +199,11 @@ U+000041 U+000042 Example 4: Encode a character that is not representable in ISO8859-1: .PP .CS -% encoding convertto iso8859-1 A\eu0141 +% \fBencoding convertto\fR iso8859-1 A\eu0141 A? -% encoding convertto -profile strict iso8859-1 A\eu0141 +% \fBencoding convertto\fR -profile strict iso8859-1 A\eu0141 unexpected character at index 1: 'U+000141' -% encoding convertto -failindex idx iso8859-1 A\eu0141 +% \fBencoding convertto\fR -failindex idx iso8859-1 A\eu0141 A % set idx 1 @@ -52,7 +52,7 @@ described below then it is used by \fBexec\fR to control the flow of input and output among the subprocess(es). Such arguments will not be passed to the subprocess(es). In forms such as -.QW "\fB<\fR \fIfileName\fR" , +.QW "\fB<\fI fileName\fR" , \fIfileName\fR may either be in a separate argument from .QW \fB<\fR or in the same argument with no intervening space (i.e. diff --git a/doc/fconfigure.n b/doc/fconfigure.n index c2847cd..e265fc4 100644 --- a/doc/fconfigure.n +++ b/doc/fconfigure.n @@ -13,8 +13,8 @@ fconfigure \- Set and get options on a channel .SH SYNOPSIS .nf \fBfconfigure \fIchannelId\fR -\fBfconfigure \fIchannelId\fR \fIname\fR -\fBfconfigure \fIchannelId\fR \fIname value \fR?\fIname value ...\fR? +\fBfconfigure \fIchannelId name\fR +\fBfconfigure \fIchannelId name value \fR?\fIname value ...\fR? .fi .BE .SH DESCRIPTION @@ -42,7 +42,7 @@ that that specific type of channel supports. For example, see the manual entry for the \fBsocket\fR command for additional options for sockets, and the \fBopen\fR command for additional options for serial devices. .TP -\fB\-blocking\fR \fIboolean\fR +\fB\-blocking\fI boolean\fR The \fB\-blocking\fR option determines whether I/O operations on the channel can cause the process to block indefinitely. The value of the option must be a proper boolean value. @@ -55,7 +55,7 @@ For nonblocking mode to work correctly, the application must be using the Tcl event loop (e.g. by calling \fBTcl_DoOneEvent\fR or invoking the \fBvwait\fR command). .TP -\fB\-buffering\fR \fInewValue\fR +\fB\-buffering\fI newValue\fR . If \fInewValue\fR is \fBfull\fR then the I/O system will buffer output until its internal buffer is full or until the \fBflush\fR command is @@ -68,14 +68,14 @@ connect to terminal-like devices; for these channels the initial setting is \fBline\fR. Additionally, \fBstdin\fR and \fBstdout\fR are initially set to \fBline\fR, and \fBstderr\fR is set to \fBnone\fR. .TP -\fB\-buffersize\fR \fInewSize\fR +\fB\-buffersize\fI newSize\fR . \fINewvalue\fR must be an integer; its value is used to set the size of buffers, in bytes, subsequently allocated for this channel to store input or output. \fINewvalue\fR must be between one and one million, allowing buffers of one to one million bytes in size. .TP -\fB\-encoding\fR \fIname\fR +\fB\-encoding\fI name\fR . This option is used to specify the encoding of the channel, so that the data can be converted to and from Unicode for use in Tcl. For instance, in @@ -101,7 +101,7 @@ locale-dependent system encoding used for interfacing with the operating system, as returned by \fBencoding system\fR. .RE .TP -\fB\-eofchar\fR \fIchar\fR +\fB\-eofchar\fI char\fR . This option supports DOS file systems that use Control-z (\ex1A) as an end of file marker. If \fIchar\fR is not an empty string, then this @@ -114,7 +114,7 @@ attempting to set \fB\-eofchar\fR to a value outside of this range will generate an error. .VS "TCL8.7 TIP656" .TP -\fB\-profile\fR \fIprofile\fR +\fB\-profile\fI profile\fR . Specifies the encoding profile to be used on the channel. The encoding transforms in use for the channel's input and output will then be subject to the @@ -123,7 +123,7 @@ rules of that profile. Any failures will result in a channel error. See profiles. .VE "TCL8.7 TIP656" .TP -\fB\-translation\fR \fImode\fR +\fB\-translation\fI mode\fR .TP \fB\-translation\fR \fB{\fIinMode outMode\fB}\fR . diff --git a/doc/fcopy.n b/doc/fcopy.n index 9f7c218..800a392 100644 --- a/doc/fcopy.n +++ b/doc/fcopy.n @@ -12,7 +12,7 @@ .SH NAME fcopy \- Copy data from one channel to another .SH SYNOPSIS -\fBfcopy \fIinputChan\fR \fIoutputChan\fR ?\fB\-size \fIsize\fR? ?\fB\-command \fIcallback\fR? +\fBfcopy \fIinputChan outputChan\fR ?\fB\-size \fIsize\fR? ?\fB\-command \fIcallback\fR? .BE .SH DESCRIPTION @@ -12,7 +12,7 @@ .SH NAME file \- Manipulate file names and attributes .SH SYNOPSIS -\fBfile \fIoption\fR \fIname\fR ?\fIarg arg ...\fR? +\fBfile \fIoption name\fR ?\fIarg arg ...\fR? .BE .SH DESCRIPTION .PP @@ -20,6 +20,7 @@ This command provides several operations on a file's name or attributes. The \fIname\fR argument is the name of a file in most cases. The \fIoption\fR argument indicates what to do with the file name. Any unique abbreviation for \fIoption\fR is acceptable. The valid options are: +.\" METHOD: atime .TP \fBfile atime \fIname\fR ?\fItime\fR? . @@ -31,6 +32,7 @@ does not exist or its access time cannot be queried or set then an error is generated. On Windows, FAT file systems do not support access time. On \fBzipfs\fR file systems, access time is mapped to the modification time. +.\" METHOD: attributes .TP \fBfile attributes \fIname\fR .TP @@ -95,6 +97,7 @@ This is \fB0\fR for directories. Other attributes may be present in the returned list. These should be ignored. .RE +.\" METHOD: channels .TP \fBfile channels\fR ?\fIpattern\fR? . @@ -102,8 +105,9 @@ If \fIpattern\fR is not specified, returns a list of names of all registered open channels in this interpreter. If \fIpattern\fR is specified, only those names matching \fIpattern\fR are returned. Matching is determined using the same rules as for \fBstring match\fR. +.\" METHOD: copy .TP -\fBfile copy \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR \fItarget\fR +\fBfile copy \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource target\fR .TP \fBfile copy \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR ?\fIsource\fR ...? \fItargetDir\fR . @@ -124,6 +128,7 @@ or overwrite a file with a directory will all result in errors even if specified, halting at the first error, if any. A \fB\-\|\-\fR marks the end of switches; the argument following the \fB\-\|\-\fR will be treated as a \fIsource\fR even if it starts with a \fB\-\fR. +.\" METHOD: delete .TP \fBfile delete \fR?\fB\-force\fR? ?\fB\-\|\-\fR? ?\fIpathname\fR ... ? . @@ -143,8 +148,10 @@ the first error, if any. A \fB\-\|\-\fR marks the end of switches; the argument following the \fB\-\|\-\fR will be treated as a \fIpathname\fR even if it starts with a \fB\-\fR. +.\" METHOD: dirname .TP \fBfile dirname \fIname\fR +. Returns a name comprised of all of the path components in \fIname\fR excluding the last element. If \fIname\fR is a relative file name and only contains one path element, then returns @@ -159,6 +166,7 @@ returned. For example, .PP returns \fBc:/\fR. .RE +.\" METHOD: executable .TP \fBfile executable \fIname\fR . @@ -166,17 +174,20 @@ Returns \fB1\fR if file \fIname\fR is executable by the current user, \fB0\fR otherwise. On Windows, which does not have an executable attribute, the command treats all directories and any files with extensions \fBexe\fR, \fBcom\fR, \fBcmd\fR or \fBbat\fR as executable. +.\" METHOD: exists .TP \fBfile exists \fIname\fR . Returns \fB1\fR if file \fIname\fR exists and the current user has search privileges for the directories leading to it, \fB0\fR otherwise. +.\" METHOD: extension .TP \fBfile extension \fIname\fR . Returns all of the characters in \fIname\fR after and including the last dot in the last element of \fIname\fR. If there is no dot in the last element of \fIname\fR then returns the empty string. +.\" METHOD: home .TP \fBfile home ?\fIusername\fR? .VS "8.7, TIP 602" @@ -195,14 +206,17 @@ raised if the \fIusername\fR does not correspond to a user account on the system. .RE .VE "8.7, TIP 602" +.\" METHOD: isdirectory .TP \fBfile isdirectory \fIname\fR . Returns \fB1\fR if file \fIname\fR is a directory, \fB0\fR otherwise. +.\" METHOD: isfile .TP \fBfile isfile \fIname\fR . Returns \fB1\fR if file \fIname\fR is a regular file, \fB0\fR otherwise. +.\" METHOD: join .TP \fBfile join \fIname\fR ?\fIname ...\fR? . @@ -223,6 +237,7 @@ Note that any of the names can contain separators, and that the result is always canonical for the current platform: \fB/\fR for Unix and Windows. .RE +.\" METHOD: link .TP \fBfile link\fR ?\fI\-linktype\fR? \fIlinkName\fR ?\fItarget\fR? . @@ -263,8 +278,9 @@ error message will be returned. Most Unix platforms support both symbolic and hard links (the latter for files only). Windows supports symbolic directory links and hard file links on NTFS drives. .RE +.\" METHOD: lstat .TP -\fBfile lstat \fIname ?varName?\fR +\fBfile lstat \fIname\fR ?\fIvarName\fR? . Same as \fBstat\fR option (see below) except uses the \fIlstat\fR kernel call instead of \fIstat\fR. This means that if \fIname\fR @@ -272,6 +288,7 @@ refers to a symbolic link the information returned is for the link rather than the file it refers to. On systems that do not support symbolic links this option behaves exactly the same as the \fBstat\fR option. +.\" METHOD: mkdir .TP \fBfile mkdir\fR ?\fIdir\fR ...? . @@ -281,6 +298,7 @@ well as \fIdir\fR itself. If an existing directory is specified, then no action is taken and no error is returned. Trying to overwrite an existing file with a directory will result in an error. Arguments are processed in the order specified, halting at the first error, if any. +.\" METHOD: mtime .TP \fBfile mtime \fIname\fR ?\fItime\fR? . @@ -291,12 +309,14 @@ standard POSIX fashion as seconds from a fixed starting time (often January 1, 1970). If the file does not exist or its modified time cannot be queried or set then an error is generated. On \fBzipfs\fR file systems, modification time cannot be explicitly set. +.\" METHOD: nativename .TP \fBfile nativename \fIname\fR . Returns the platform-specific name of the file. This is useful if the filename is needed to pass to a platform-specific call, such as to a subprocess via \fBexec\fR under Windows (see \fBEXAMPLES\fR below). +.\" METHOD: normalize .TP \fBfile normalize \fIname\fR . @@ -318,11 +338,13 @@ last link in the path is necessary, because Tcl or the user may wish to operate on the actual symbolic link itself (for example \fBfile delete\fR, \fBfile rename\fR, \fBfile copy\fR are defined to operate on symbolic links, not on the things that they point to). +.\" METHOD: owned .TP \fBfile owned \fIname\fR . Returns \fB1\fR if file \fIname\fR is owned by the current user, \fB0\fR otherwise. +.\" METHOD: pathtype .TP \fBfile pathtype \fIname\fR . @@ -333,11 +355,13 @@ working directory, then the path type will be \fBrelative\fR. If \fIname\fR refers to a file relative to the current working directory on a specified volume, or to a specific file on the current working volume, then the path type is \fBvolumerelative\fR. +.\" METHOD: readable .TP \fBfile readable \fIname\fR . Returns \fB1\fR if file \fIname\fR is readable by the current user, \fB0\fR otherwise. +.\" METHOD: readlink .TP \fBfile readlink \fIname\fR . @@ -345,8 +369,9 @@ Returns the value of the symbolic link given by \fIname\fR (i.e. the name of the file it points to). If \fIname\fR is not a symbolic link or its value cannot be read, then an error is returned. On systems that do not support symbolic links this option is undefined. +.\" METHOD: rename .TP -\fBfile rename \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR \fItarget\fR +\fBfile rename \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource target\fR .TP \fBfile rename \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR ?\fIsource\fR ...? \fItargetDir\fR . @@ -364,6 +389,7 @@ result in errors. Arguments are processed in the order specified, halting at the first error, if any. A \fB\-\|\-\fR marks the end of switches; the argument following the \fB\-\|\-\fR will be treated as a \fIsource\fR even if it starts with a \fB\-\fR. +.\" METHOD: rootname .TP \fBfile rootname \fIname\fR . @@ -372,6 +398,7 @@ last .QW . character in the last component of name. If the last component of \fIname\fR does not contain a dot, then returns \fIname\fR. +.\" METHOD: separator .TP \fBfile separator\fR ?\fIname\fR? . @@ -380,12 +407,14 @@ path segments for native files on this platform. If a path is given, the filesystem responsible for that path is asked to return its separator character. If no file system accepts \fIname\fR, an error is generated. +.\" METHOD: size .TP \fBfile size \fIname\fR . Returns a decimal string giving the size of file \fIname\fR in bytes. If the file does not exist or its size cannot be queried then an error is generated. +.\" METHOD: split .TP \fBfile split \fIname\fR . @@ -393,8 +422,9 @@ Returns a list whose elements are the path components in \fIname\fR. The first element of the list will have the same path type as \fIname\fR. All other elements will be relative. Path separators will be discarded unless they are needed to ensure that an element is unambiguously relative. +.\" METHOD: stat .TP -\fBfile stat \fIname ?varName?\fR +\fBfile stat \fIname\fR ?\fIvarName\fR? . Invokes the \fBstat\fR kernel call on \fIname\fR, and returns a dictionary with the information returned from the kernel call. If @@ -408,6 +438,7 @@ field from the \fBstat\fR return structure; see the manual entry for \fBstat\fR for details on the meanings of the values. The \fBtype\fR element gives the type of the file in the same form returned by the command \fBfile type\fR. +.\" METHOD: system .TP \fBfile system \fIname\fR . @@ -429,6 +460,7 @@ to represent a file on a remote ftp site mounted as a virtual filesystem through an extension called .QW vfs . If the file does not belong to any filesystem, an error is generated. +.\" METHOD: tail .TP \fBfile tail \fIname\fR . @@ -437,6 +469,7 @@ Returns all of the characters in the last filesystem component of If \fIname\fR contains no separators then returns \fIname\fR. So, \fBfile tail a/b\fR, \fBfile tail a/b/\fR and \fBfile tail b\fR all return \fBb\fR. +.\" METHOD: tempdir .TP \fBfile tempdir\fR ?\fItemplate\fR? .VS "8.7, TIP 431" @@ -467,6 +500,7 @@ between platforms: .CE .RE .VE "8.7, TIP 431" +.\" METHOD: tempfile .TP \fBfile tempfile\fR ?\fInameVar\fR? ?\fItemplate\fR? '\" TIP #210 @@ -484,6 +518,7 @@ Note that temporary files are \fIonly\fR ever created on the native filesystem. As such, they can be relied upon to be used with operating-system native APIs and external programs that require a filename. .RE +.\" METHOD: tildeexpand .TP \fBfile tildeexpand \fIname\fR .VS "8.7, TIP 602" @@ -500,12 +535,14 @@ retrieve the user's home directory for substitution. An error is raised if the If the file name does not begin with a tilde, it is returned unmodified. .RE .VE "8.7, TIP 602" +.\" METHOD: type .TP \fBfile type \fIname\fR . Returns a string giving the type of file \fIname\fR, which will be one of \fBfile\fR, \fBdirectory\fR, \fBcharacterSpecial\fR, \fBblockSpecial\fR, \fBfifo\fR, \fBlink\fR, or \fBsocket\fR. +.\" METHOD: volumes .TP \fBfile volumes\fR . @@ -519,6 +556,7 @@ On Windows, it will return a list of the available local drives .QW "a:/ c:/" ). If any virtual filesystem has mounted additional volumes, they will be in the returned list. +.\" METHOD: writable .TP \fBfile writable \fIname\fR . @@ -29,7 +29,7 @@ If the initial arguments to \fBglob\fR start with \fB\-\fR then they are treated as switches. The following switches are currently supported: .TP -\fB\-directory\fR \fIdirectory\fR +\fB\-directory\fI directory\fR . Search for files which match the given patterns starting in the given \fIdirectory\fR. This allows searching of directories whose name @@ -49,7 +49,7 @@ separators. Allows an empty list to be returned without error; This is the default behavior in Tcl 9.0, so this switch has no effect any more. .TP -\fB\-path\fR \fIpathPrefix\fR +\fB\-path\fI pathPrefix\fR . Search for files with the given \fIpathPrefix\fR where the rest of the name matches the given patterns. This allows searching for files with names @@ -75,7 +75,7 @@ path segment, so .QW "\fBglob \-tails \-path [file rootname /home/fred/foo.tex] .*\fR" will return paths like \fBfoo.aux foo.bib foo.tex\fR etc. .TP -\fB\-types\fR \fItypeList\fR +\fB\-types\fI typeList\fR . Only list files or directories which match \fItypeList\fR, where the items in the list have two forms. The first form is like the \-type option of diff --git a/doc/history.n b/doc/history.n index 05d936e..30a5eeb 100644 --- a/doc/history.n +++ b/doc/history.n @@ -39,14 +39,18 @@ The \fBhistory\fR command can take any of the following forms: \fBhistory\fR Same as \fBhistory info\fR, described below. +.\" METHOD: add .TP \fBhistory add\fI command \fR?\fBexec\fR? +. Adds the \fIcommand\fR argument to the history list as a new event. If \fBexec\fR is specified (or abbreviated) then the command is also executed and its result is returned. If \fBexec\fR is not specified then an empty string is returned as result. +.\" METHOD: change .TP \fBhistory change\fI newValue\fR ?\fIevent\fR? +. Replaces the value recorded for an event with \fInewValue\fR. \fIEvent\fR specifies the event to replace, and defaults to the \fIcurrent\fR event (not event \fB\-1\fR). This command @@ -54,32 +58,44 @@ is intended for use in commands that implement new forms of history substitution and wish to replace the current event (which invokes the substitution) with the command created through substitution. The return value is an empty string. +.\" METHOD: clear .TP \fBhistory clear\fR +. Erase the history list. The current keep limit is retained. The history event numbers are reset. +.\" METHOD: event .TP \fBhistory event\fR ?\fIevent\fR? +. Returns the value of the event given by \fIevent\fR. \fIEvent\fR defaults to \fB\-1\fR. +.\" METHOD: info .TP \fBhistory info \fR?\fIcount\fR? +. Returns a formatted string (intended for humans to read) giving the event number and contents for each of the events in the history list except the current event. If \fIcount\fR is specified then only the most recent \fIcount\fR events are returned. +.\" METHOD: keep .TP \fBhistory keep \fR?\fIcount\fR? +. This command may be used to change the size of the history list to \fIcount\fR events. Initially, 20 events are retained in the history list. If \fIcount\fR is not specified, the current keep limit is returned. +.\" METHOD: nextid .TP \fBhistory nextid\fR +. Returns the number of the next event to be recorded in the history list. It is useful for things like printing the event number in command-line prompts. +.\" METHOD: redo .TP \fBhistory redo \fR?\fIevent\fR? +. Re-executes the command indicated by \fIevent\fR and returns its result. \fIEvent\fR defaults to \fB\-1\fR. This command results in history revision: see below for details. @@ -93,8 +109,8 @@ history operations \fBsubstitute\fR and \fBwords\fR have been removed. The history option \fBredo\fR results in much simpler .QW "history revision" . When this option is invoked then the most recent event -is modified to eliminate the history command and replace it with -the result of the history command. +is modified to eliminate the \fBhistory\fR command and replace it with +the result of the \fBhistory\fR command. If you want to redo an event without modifying history, then use the \fBevent\fR operation to retrieve some event, and the \fBadd\fR operation to add it to history and execute it. @@ -20,11 +20,11 @@ http \- Client-side implementation of the HTTP/1.1 protocol .sp \fB::http::geturl \fIurl\fR ?\fI\-option value\fR ...? .sp -\fB::http::formatQuery\fR \fIkey value\fR ?\fIkey value\fR ...? +\fB::http::formatQuery\fI key value\fR ?\fIkey value\fR ...? .sp -\fB::http::quoteString\fR \fIvalue\fR +\fB::http::quoteString\fI value\fR .sp -\fB::http::reset\fR \fItoken\fR ?\fIwhy\fR? +\fB::http::reset\fI token\fR ?\fIwhy\fR? .sp \fB::http::wait \fItoken\fR .sp @@ -38,25 +38,25 @@ http \- Client-side implementation of the HTTP/1.1 protocol .sp \fB::http::cleanup \fItoken\fR .sp -\fB::http::requestLine\fR \fItoken\fR +\fB::http::requestLine\fI token\fR .sp -\fB::http::requestHeaders\fR \fItoken\fR ?\fIheaderName\fR? +\fB::http::requestHeaders\fI token\fR ?\fIheaderName\fR? .sp -\fB::http::requestHeaderValue\fR \fItoken\fR \fIheaderName\fR +\fB::http::requestHeaderValue\fI token headerName\fR .sp -\fB::http::responseLine\fR \fItoken\fR +\fB::http::responseLine\fI token\fR .sp -\fB::http::responseCode\fR \fItoken\fR +\fB::http::responseCode\fI token\fR .sp -\fB::http::reasonPhrase\fR \fIcode\fR +\fB::http::reasonPhrase\fI code\fR .sp -\fB::http::responseHeaders\fR \fItoken\fR ?\fIheaderName\fR? +\fB::http::responseHeaders\fI token\fR ?\fIheaderName\fR? .sp -\fB::http::responseHeaderValue\fR \fItoken\fR \fIheaderName\fR +\fB::http::responseHeaderValue\fI token headerName\fR .sp -\fB::http::responseInfo\fR \fItoken\fR +\fB::http::responseInfo\fI token\fR .sp -\fB::http::responseBody\fR \fItoken\fR +\fB::http::responseBody\fI token\fR .sp \fB::http::register \fIproto port command\fR ?\fIsocketCmdVarName\fR? ?\fIuseSockThread\fR? ?\fIendToEndProxy\fR? .sp @@ -70,7 +70,7 @@ http \- Client-side implementation of the HTTP/1.1 protocol .sp \fB::http::meta \fItoken\fR ?\fIheaderName\fR? .sp -\fB::http::metaValue\fR \fItoken\fR \fIheaderName\fR +\fB::http::metaValue\fI token headerName\fR .sp \fB::http::ncode \fItoken\fR .SH "EXPORTED COMMANDS" @@ -130,6 +130,7 @@ The response itself is returned by command \fB::http::responseBody\fR, unless it has been redirected to a file by the \fI\-channel\fR option of \fB::http::geturl\fR. .SH COMMANDS +.\" METHOD: config .TP \fB::http::config\fR ?\fIoptions\fR? . @@ -142,7 +143,7 @@ that setting is returned. Otherwise, the options should be a set of flags and values that define the configuration: .RS .TP -\fB\-accept\fR \fImimetypes\fR +\fB\-accept\fI mimetypes\fR . The Accept header of the request. The default is */*, which means that all types of documents are accepted. Otherwise you can supply a @@ -150,7 +151,7 @@ comma-separated list of mime type patterns that you are willing to receive. For example, .QW "image/gif, image/jpeg, text/*" . .TP -\fB\-cookiejar\fR \fIcommand\fR +\fB\-cookiejar\fI command\fR .VS TIP406 The cookie store for the package to use to manage HTTP cookies. \fIcommand\fR is a command prefix list; if the empty list (the @@ -159,20 +160,20 @@ from responses. The command indicated by \fIcommand\fR, if supplied, must obey the \fBCOOKIE JAR PROTOCOL\fR described below. .VE TIP406 .TP -\fB\-pipeline\fR \fIboolean\fR +\fB\-pipeline\fI boolean\fR . Specifies whether HTTP/1.1 transactions on a persistent socket will be pipelined. See the \fBPERSISTENT SOCKETS\fR section for details. The default is 1. .TP -\fB\-postfresh\fR \fIboolean\fR +\fB\-postfresh\fI boolean\fR . Specifies whether requests that use the \fBPOST\fR method will always use a fresh socket, overriding the \fB\-keepalive\fR option of command \fBhttp::geturl\fR. See the \fBPERSISTENT SOCKETS\fR section for details. The default is 0. .TP -\fB\-proxyauth\fR \fIstring\fR +\fB\-proxyauth\fI string\fR . If non-empty, the string is supplied to the proxy server as the value of the request header Proxy-Authorization. This option can be used for HTTP Basic @@ -182,7 +183,7 @@ useful. In that case the caller must expect a 407 response from the proxy, compute the authentication value to be supplied, and use the \fB\-headers\fR option to supply it as the value of the Proxy-Authorization header. .TP -\fB\-proxyfilter\fR \fIcommand\fR +\fB\-proxyfilter\fI command\fR . The command is a callback that is made during \fB::http::geturl\fR @@ -209,13 +210,13 @@ not call the \fBbgerror\fR handler. See the \fBERRORS\fR section for details. .RE .TP -\fB\-proxyhost\fR \fIhostname\fR +\fB\-proxyhost\fI hostname\fR . The host name or IP address of the proxy server, if any. If this value is the empty string, the URL host is contacted directly. See \fB\-proxyfilter\fR for how the value is used. .TP -\fB\-proxynot\fR \fIlist\fR +\fB\-proxynot\fI list\fR . A Tcl list of domain names and IP addresses that should be accessed directly, not through the proxy server. The target hostname is compared with each list @@ -224,12 +225,12 @@ to use the wildcard "*" at the start of a domain name (e.g. *.example.com) or at the end of an IP address (e.g. 192.168.0.*). See \fB\-proxyfilter\fR for how the value is used. .TP -\fB\-proxyport\fR \fInumber\fR +\fB\-proxyport\fI number\fR . The port number of the proxy server. See \fB\-proxyfilter\fR for how the value is used. .TP -\fB\-repost\fR \fIboolean\fR +\fB\-repost\fI boolean\fR . Specifies what to do if a POST request over a persistent connection fails because the server has half-closed the connection. If boolean \fBtrue\fR, the @@ -241,7 +242,7 @@ retrying the POST. The value \fBtrue\fR should be used only under certain conditions. See the \fBPERSISTENT SOCKETS\fR section for details. The default is 0. .TP -\fB\-threadlevel\fR \fIlevel\fR +\fB\-threadlevel\fI level\fR . Specifies whether and how to use the \fBThread\fR package. Possible values of \fIlevel\fR are 0, 1 or 2. @@ -259,13 +260,13 @@ available only to the main interpreter in each thread. See section \fBTHREADS\fR for more information. .RE .TP -\fB\-urlencoding\fR \fIencoding\fR +\fB\-urlencoding\fI encoding\fR . The \fIencoding\fR used for creating the x-url-encoded URLs with \fB::http::formatQuery\fR and \fB::http::quoteString\fR. The default is \fButf-8\fR, as specified by RFC 2718. .TP -\fB\-useragent\fR \fIstring\fR +\fB\-useragent\fI string\fR . The value of the User-Agent header in the HTTP request. In an unsafe interpreter, the default value depends upon the operating system, and @@ -275,7 +276,7 @@ A safe interpreter cannot determine its operating system, and so the default in a safe interpreter is to use a Windows 10 value with the current version numbers of \fBhttp\fR and \fBTcl\fR. .TP -\fB\-zip\fR \fIboolean\fR +\fB\-zip\fI boolean\fR . If the value is boolean \fBtrue\fR, then by default requests will send a header .QW "\fBAccept-Encoding: gzip,deflate\fR" . @@ -285,8 +286,9 @@ In either case the default can be overridden for an individual request by supplying a custom \fBAccept-Encoding\fR header in the \fB\-headers\fR option of \fBhttp::geturl\fR. The default value is 1. .RE +.\" METHOD: geturl .TP -\fB::http::geturl\fR \fIurl\fR ?\fIoptions\fR? +\fB::http::geturl\fI url\fR ?\fIoptions\fR? . The \fB::http::geturl\fR command is the main procedure in the package. The \fB\-query\fR or \fB\-querychannel\fR option causes a POST operation and @@ -301,25 +303,25 @@ that is invoked when the HTTP transaction completes. \fB::http::geturl\fR takes several options: .RS .TP -\fB\-binary\fR \fIboolean\fR +\fB\-binary\fI boolean\fR . Specifies whether to force interpreting the URL data as binary. Normally this is auto-detected (anything not beginning with a \fBtext\fR content type or whose content encoding is \fBgzip\fR or \fBdeflate\fR is considered binary data). .TP -\fB\-blocksize\fR \fIsize\fR +\fB\-blocksize\fI size\fR . The block size used when reading the URL. At most \fIsize\fR bytes are read at once. After each block, a call to the \fB\-progress\fR callback is made (if that option is specified). .TP -\fB\-channel\fR \fIname\fR +\fB\-channel\fI name\fR . Copy the URL contents to channel \fIname\fR instead of saving it in a Tcl variable for retrieval by \fB::http::responseBody\fR. .TP -\fB\-command\fR \fIcallback\fR +\fB\-command\fI callback\fR . The presence of this option causes \fB::http::geturl\fR to return immediately. After the HTTP transaction completes, the value of \fIcallback\fR is expanded, @@ -345,7 +347,7 @@ not call the \fBbgerror\fR handler. See the \fBERRORS\fR section for details. .RE .TP -\fB\-guesstype\fR \fIboolean\fR +\fB\-guesstype\fI boolean\fR . Attempt to guess the \fBContent-Type\fR and character set when a misconfigured server provides no information. The default value is \fIfalse\fR (do @@ -359,7 +361,7 @@ state(binary) is changed to 0, and the character set is changed to the one specified by the "encoding" tag of the XML line, or to utf-8 if no encoding is specified. Not used if a \fI\-channel\fR is specified. .TP -\fB\-handler\fR \fIcallback\fR +\fB\-handler\fI callback\fR . If this option is absent, \fBhttp::geturl\fR processes incoming data itself, either appending it to the state(body) variable or writing it to the -channel. @@ -406,7 +408,7 @@ not call the \fBbgerror\fR handler. See the \fBERRORS\fR section for details. .RE .TP -\fB\-headers\fR \fIkeyvaluelist\fR +\fB\-headers\fI keyvaluelist\fR . This option is used to add headers not already specified by \fB::http::config\fR to the HTTP request. The @@ -423,12 +425,12 @@ Pragma: no-cache .CE .RE .TP -\fB\-keepalive\fR \fIboolean\fR +\fB\-keepalive\fI boolean\fR . If boolean \fBtrue\fR, attempt to keep the connection open for servicing multiple requests. Default is 0. .TP -\fB\-method\fR \fItype\fR +\fB\-method\fI type\fR . Force the HTTP request method to \fItype\fR. \fB::http::geturl\fR will auto-select GET, POST or HEAD based on other options, but this option overrides @@ -437,7 +439,7 @@ that selection and enables choices like PUT and DELETE for WebDAV support. .PP It is the caller's responsibility to ensure that the headers and request body (if any) conform to the requirements of the request method. For example, if -using \fB\-method\fR \fIPOST\fR to send a POST with an empty request body, the +using \fB\-method\fI POST\fR to send a POST with an empty request body, the caller must also supply the option .PP .CS @@ -445,12 +447,12 @@ caller must also supply the option .CE .RE .TP -\fB\-myaddr\fR \fIaddress\fR +\fB\-myaddr\fI address\fR . Pass an specific local address to the underlying \fBsocket\fR call in case multiple interfaces are available. .TP -\fB\-progress\fR \fIcallback\fR +\fB\-progress\fI callback\fR . If the \fB\-progress\fR option is present, then the \fIcallback\fR is made after each transfer of data from the URL. @@ -476,13 +478,13 @@ proc httpProgress {token total current} { .CE .RE .TP -\fB\-protocol\fR \fIversion\fR +\fB\-protocol\fI version\fR . Select the HTTP protocol version to use. This should be 1.0 or 1.1 (the default). Should only be necessary for servers that do not understand or otherwise complain about HTTP/1.1. .TP -\fB\-query\fR \fIquery\fR +\fB\-query\fI query\fR . This flag (if the value is non-empty) causes \fB::http::geturl\fR to do a POST request that passes the string @@ -500,7 +502,7 @@ used in a POST submitted from an html form). The \fB::http::formatQuery\fR procedure can be used to do the formatting. .RE .TP -\fB\-queryblocksize\fR \fIsize\fR +\fB\-queryblocksize\fI size\fR . The block size used when posting query data to the URL. At most @@ -509,7 +511,7 @@ bytes are written at once. After each block, a call to the \fB\-queryprogress\fR callback is made (if that option is specified). .TP -\fB\-querychannel\fR \fIchannelID\fR +\fB\-querychannel\fI channelID\fR . This flag causes \fB::http::geturl\fR to do a POST request that passes the data contained in \fIchannelID\fR to the server. The data contained in @@ -520,7 +522,7 @@ options, \fB::http::geturl\fR attempts to determine the size of the post data in order to create that header. If it is unable to determine the size, it returns an error. .TP -\fB\-queryprogress\fR \fIcallback\fR +\fB\-queryprogress\fI callback\fR . If the \fB\-queryprogress\fR option is present, then the \fIcallback\fR is made after each transfer of data to the URL @@ -528,13 +530,13 @@ in a POST request (i.e. a call to \fB::http::geturl\fR with option \fB\-query\fR or \fB\-querychannel\fR) and acts exactly like the \fB\-progress\fR option (the callback format is the same). .TP -\fB\-strict\fR \fIboolean\fR +\fB\-strict\fI boolean\fR . If true then the command will test that the URL complies with RFC 3986, i.e. that it has no characters that should be "x-url-encoded" (e.g. a space should be encoded to "%20"). Default value is 1. .TP -\fB\-timeout\fR \fImilliseconds\fR +\fB\-timeout\fI milliseconds\fR . If \fImilliseconds\fR is non-zero, then \fB::http::geturl\fR sets up a timeout to occur after the specified number of milliseconds. @@ -544,13 +546,13 @@ The return value of \fB::http::status\fR (and the value of the \fIstatus\fR key in the dictionary returned by \fB::http::responseInfo\fR) is \fBtimeout\fR after a timeout has occurred. .TP -\fB\-type\fR \fImime-type\fR +\fB\-type\fI mime-type\fR . Use \fImime-type\fR as the \fBContent-Type\fR value, instead of the default value (\fBapplication/x-www-form-urlencoded\fR) during a POST operation. .TP -\fB\-validate\fR \fIboolean\fR +\fB\-validate\fI boolean\fR . If \fIboolean\fR is non-zero, then \fB::http::geturl\fR does an HTTP HEAD request. This server returns the same status line and response headers as it @@ -559,27 +561,31 @@ would for a HTTP GET request, but omits the response entity transaction using command \fB::http::responseHeaders\fR or, for selected information, \fB::http::responseInfo\fR. .RE +.\" METHOD: formatQuery .TP -\fB::http::formatQuery\fR \fIkey value\fR ?\fIkey value\fR ...? +\fB::http::formatQuery\fI key value\fR ?\fIkey value\fR ...? . This procedure does x-url-encoding of query data. It takes an even number of arguments that are the keys and values of the query. It encodes the keys and values, and generates one string that has the proper & and = separators. The result is suitable for the \fB\-query\fR value passed to \fB::http::geturl\fR. +.\" METHOD: quoteString .TP -\fB::http::quoteString\fR \fIvalue\fR +\fB::http::quoteString\fI value\fR . This procedure does x-url-encoding of string. It takes a single argument and encodes it. +.\" METHOD: reset .TP -\fB::http::reset\fR \fItoken\fR ?\fIwhy\fR? +\fB::http::reset\fI token\fR ?\fIwhy\fR? . This command resets the HTTP transaction identified by \fItoken\fR, if any. This sets the \fBstate(status)\fR value to \fIwhy\fR, which defaults to \fBreset\fR, and then calls the registered \fB\-command\fR callback. +.\" METHOD: wait .TP -\fB::http::wait\fR \fItoken\fR +\fB::http::wait\fI token\fR . This command blocks and waits for the transaction to complete. This only works in trusted code because it @@ -588,8 +594,9 @@ uses \fBvwait\fR. Also, it is not useful for the case where because in this case the \fB::http::geturl\fR call does not return until the HTTP transaction is complete, and thus there is nothing to wait for. +.\" METHOD: status .TP -\fB::http::status\fR \fItoken\fR +\fB::http::status\fI token\fR . This command returns a description of the status of the HTTP transaction. The return value is the empty string until the HTTP transaction is @@ -601,19 +608,22 @@ section \fBERRORS\fR (below). The name "status" is not related to the terms "status line" and "status code" that are defined for a HTTP response. .RE +.\" METHOD: size .TP -\fB::http::size\fR \fItoken\fR +\fB::http::size\fI token\fR . This command returns the number of bytes received so far from the URL in the \fB::http::geturl\fR call. +.\" METHOD: error .TP -\fB::http::error\fR \fItoken\fR +\fB::http::error\fI token\fR . This command returns the error information if the HTTP transaction failed, or the empty string if there was no error. The information is a Tcl list of the error message, stack trace, and error code. +.\" METHOD: postError .TP -\fB::http::postError\fR \fItoken\fR +\fB::http::postError\fI token\fR . A POST request is a call to \fB::http::geturl\fR with either the \fB\-query\fR or \fB\-querychannel\fR option. @@ -623,8 +633,9 @@ string if there was no error. The information is a Tcl list of the error message, stack trace, and error code. When this type of error occurs, the \fB::http::geturl\fR command continues the transaction and attempts to receive a response from the server. +.\" METHOD: cleanup .TP -\fB::http::cleanup\fR \fItoken\fR +\fB::http::cleanup\fI token\fR . This procedure cleans up the state associated with the connection identified by \fItoken\fR. After this call, the procedures @@ -634,8 +645,9 @@ this function after you are done with a given HTTP request. Not doing so will result in memory not being freed, and if your app calls \fB::http::geturl\fR enough times, the memory leak could cause a performance hit...or worse. +.\" METHOD: requestLine .TP -\fB::http::requestLine\fR \fItoken\fR +\fB::http::requestLine\fI token\fR . This command returns the "request line" sent to the server. The "request line" is the first line of a HTTP client request, and has three @@ -647,8 +659,9 @@ GET / HTTP/1.1 GET /introduction.html?subject=plumbing HTTP/1.1 POST /forms/order.html HTTP/1.1 .RE +.\" METHOD: requestHeaders .TP -\fB::http::requestHeaders\fR \fItoken\fR ?\fIheaderName\fR? +\fB::http::requestHeaders\fI token\fR ?\fIheaderName\fR? . This command returns the HTTP request header names and values, in the order that they were sent to the server, as a Tcl list of the form @@ -659,8 +672,9 @@ are returned. If two arguments are supplied, the second provides the value of a header name. Only headers with the requested name (converted to lower case) are returned. If no such headers are found, an empty list is returned. +.\" METHOD: requestHeaderValue .TP -\fB::http::requestHeaderValue\fR \fItoken\fR \fIheaderName\fR +\fB::http::requestHeaderValue\fI token headerName\fR . This command returns the value of the HTTP request header named \fIheaderName\fR. Header names are case-insensitive and are converted to @@ -668,8 +682,9 @@ lower case. If no such header exists, the return value is the empty string. If there are multiple headers named \fIheaderName\fR, the result is obtained by joining the individual values with the string ", " (comma and space), preserving their order. +.\" METHOD: responseLine .TP -\fB::http::responseLine\fR \fItoken\fR +\fB::http::responseLine\fI token\fR . This command returns the first line of the server response: the HTTP "status line". The "status line" has three @@ -695,15 +710,17 @@ and can be changed without affecting the HTTP protocol. The recommended values (RFC 7231 and IANA assignments) for each code are provided by the command \fB::http::reasonPhrase\fR. .RE +.\" METHOD: responseCode .TP -\fB::http::responseCode\fR \fItoken\fR +\fB::http::responseCode\fI token\fR . This command returns the "status code" (200, 404, etc.) of the server "status line". If a three-digit code cannot be found, the full status line is returned. See command \fB::http::responseLine\fR for more information on the "status line". +.\" METHOD: reasonPhrase .TP -\fB::http::reasonPhrase\fR \fIcode\fR +\fB::http::reasonPhrase\fI code\fR . This command returns the IANA recommended "reason phrase" for a particular "status code" returned by a HTTP server. The argument \fIcode\fR is a valid @@ -724,8 +741,9 @@ the "reason phrase" stored in key \fIreasonPhrase\fR). A registry of valid status codes is maintained at https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml .RE +.\" METHOD: responseHeaders .TP -\fB::http::responseHeaders\fR \fItoken\fR ?\fIheaderName\fR? +\fB::http::responseHeaders\fI token\fR ?\fIheaderName\fR? . The response from a HTTP server includes metadata headers that describe the response body and the transaction itself. @@ -739,8 +757,9 @@ supplied, it provides the value of a header name. Only headers with the requested name (converted to lower case) are returned. If no such headers are found, an empty list is returned. See section \fBMETADATA\fR for more information. +.\" METHOD: responseHeaderValue .TP -\fB::http::responseHeaderValue\fR \fItoken\fR \fIheaderName\fR +\fB::http::responseHeaderValue\fI token headerName\fR . This command returns the value of the HTTP response header named \fIheaderName\fR. Header names are case-insensitive and are converted to @@ -751,9 +770,10 @@ preserving their order. Multiple headers with the same name may be processed in this manner, except \fBSet-Cookie\fR which does not conform to the comma-separated-list syntax and cannot be combined into a single value. Each \fBSet-Cookie\fR header must be treated individually, e.g. by processing -the return value of \fB::http::responseHeaders\fR \fItoken\fR \fBSet-Cookie\fR. +the return value of \fB::http::responseHeaders\fI token\fR \fBSet-Cookie\fR. +.\" METHOD: responseInfo .TP -\fB::http::responseInfo\fR \fItoken\fR +\fB::http::responseInfo\fI token\fR . This command returns a \fBdict\fR of selected response metadata that are essential for identifying a successful transaction and making use of the @@ -775,8 +795,9 @@ text resource as a binary, or vice versa. After a POST transaction, check the value of \fIpostError\fR to verify that the request body was uploaded without error. .RE +.\" METHOD: responseBody .TP -\fB::http::responseBody\fR \fItoken\fR +\fB::http::responseBody\fI token\fR . This command returns the entity sent by the HTTP server (unless \fI-channel\fR was used, in which case the entity was delivered to the @@ -788,8 +809,9 @@ Other terms for "resource", "response body after decoding", "payload", "message body after decoding", "content(s)", and "file". .RE +.\" METHOD: register .TP -\fB::http::register\fR \fIproto port command\fR ?\fIsocketCmdVarName\fR? ?\fIuseSockThread\fR? ?\fIendToEndProxy\fR? +\fB::http::register\fI proto port command\fR ?\fIsocketCmdVarName\fR? ?\fIuseSockThread\fR? ?\fIendToEndProxy\fR? . This procedure allows one to provide custom HTTP transport types such as HTTPS, by registering a prefix, the default port, and the @@ -809,7 +831,7 @@ arguments \fIuseSockThread\fR, \fIendToEndProxy\fR, which take boolean values with default value \fIfalse\fR. .PP Iff argument \fIuseSockThread\fR is supplied and is boolean \fItrue\fR, -then iff permitted by the value [\fBhttp::config\fR \fI-threadlevel\fR] +then iff permitted by the value [\fBhttp::config\fI \-threadlevel\fR] and by the availability of package \fBThread\fR, sockets created for the transport will be opened in a different thread so that a slow DNS lookup will not cause the script to block. @@ -834,8 +856,9 @@ set token [::http::geturl https://my.secure.site/] .CE .RE .RE +.\" METHOD: registerError .TP -\fB::http::registerError\fR \fIsock\fR ?\fImessage\fR? +\fB::http::registerError\fI sock\fR ?\fImessage\fR? . This procedure allows a registered protocol handler to deliver an error message for use by \fBhttp\fR. Calling this command does not raise an @@ -845,27 +868,32 @@ propagate to \fBhttp\fR. The command allows \fBhttp\fR to provide a precise error message rather than a general one. The command returns the value provided by the last call with argument \fImessage\fR, or the empty string if no such call has been made. +.\" METHOD: unregister .TP -\fB::http::unregister\fR \fIproto\fR +\fB::http::unregister\fI proto\fR . This procedure unregisters a protocol handler that was previously registered via \fB::http::register\fR, returning a six-item list of the values that were previously supplied to \fB::http::register\fR if there was such a handler, and an error if there was no such handler. +.\" METHOD: code .TP -\fB::http::code\fR \fItoken\fR +\fB::http::code\fI token\fR . An alternative name for the command \fB::http::responseLine\fR +.\" METHOD: data .TP -\fB::http::data\fR \fItoken\fR +\fB::http::data\fI token\fR . An alternative name for the command \fB::http::responseBody\fR. +.\" METHOD: meta .TP -\fB::http::meta\fR \fItoken\fR ?\fIheaderName\fR? +\fB::http::meta\fI token\fR ?\fIheaderName\fR? . An alternative name for the command \fB::http::responseHeaders\fR +.\" METHOD: ncode .TP -\fB::http::ncode\fR \fItoken\fR +\fB::http::ncode\fI token\fR . An alternative name for the command \fB::http::responseCode\fR .SH ERRORS @@ -1493,6 +1521,7 @@ values of \fIcookieJar\fR will correspond to sessions; it is up to the caller of \fB::http::config\fR to decide what session applies and to manage the deletion of said sessions when they are no longer desired (which should be when they not configured as the current cookie jar). +.\" METHOD: getCookies .TP \fIcookieJar \fBgetCookies \fIprotocol host requestPath\fR . @@ -1509,6 +1538,7 @@ request (typically the one with the most specific \fIhost\fR/domain match and most specific \fIrequestPath\fR/path match), but there may be many cookies with different names in any request. .RE +.\" METHOD: storeCookie .TP \fIcookieJar \fBstoreCookie \fIcookieDictionary\fR . @@ -14,38 +14,41 @@ tcl::idna \- Support for normalization of Internationalized Domain Names .nf package require tcl::idna 1.0 -\fBtcl::idna decode\fR \fIhostname\fR -\fBtcl::idna encode\fR \fIhostname\fR -\fBtcl::idna puny decode\fR \fIstring\fR ?\fIcase\fR? -\fBtcl::idna puny encode\fR \fIstring\fR ?\fIcase\fR? +\fBtcl::idna decode\fI hostname\fR +\fBtcl::idna encode\fI hostname\fR +\fBtcl::idna puny decode\fI string\fR ?\fIcase\fR? +\fBtcl::idna puny encode\fI string\fR ?\fIcase\fR? \fBtcl::idna version\fR .fi .SH DESCRIPTION This package provides an implementation of the punycode scheme used in Internationalised Domain Names, and some access commands. (See RFC 3492 for a description of punycode.) +.\" METHOD: decode .TP -\fBtcl::idna decode\fR \fIhostname\fR +\fBtcl::idna decode\fI hostname\fR . This command takes the name of a host that potentially contains punycode-encoded character sequences, \fIhostname\fR, and returns the hostname as might be displayed to the user. Note that there are often UNICODE characters that have extremely similar glyphs, so care should be taken with displaying hostnames to users. +.\" METHOD: encode .TP -\fBtcl::idna encode\fR \fIhostname\fR +\fBtcl::idna encode\fI hostname\fR . This command takes the name of a host as might be displayed to the user, \fIhostname\fR, and returns the version of the hostname with characters not permitted in basic hostnames encoded with punycode. +.\" METHOD: puny .TP -\fBtcl::idna puny\fR \fIsubcommand ...\fR +\fBtcl::idna puny\fI subcommand ...\fR . This command provides direct access to the basic punycode encoder and decoder. It supports two \fIsubcommand\fRs: .RS .TP -\fBtcl::idna puny decode\fR \fIstring\fR ?\fIcase\fR? +\fBtcl::idna puny decode\fI string\fR ?\fIcase\fR? . This command decodes the punycode-encoded string, \fIstring\fR, and returns the result. If \fIcase\fR is provided, it is a boolean to make the case be @@ -53,7 +56,7 @@ folded to upper case (if \fIcase\fR is true) or lower case (if \fIcase\fR is false) during the decoding process; if omitted, no case transformation is applied. .TP -\fBtcl::idna puny encode\fR \fIstring\fR ?\fIcase\fR? +\fBtcl::idna puny encode\fI string\fR ?\fIcase\fR? . This command encodes the string, \fIstring\fR, and returns the punycode-encoded version of the string. If \fIcase\fR is provided, it is a @@ -61,6 +64,7 @@ boolean to make the case be folded to upper case (if \fIcase\fR is true) or lower case (if \fIcase\fR is false) during the encoding process; if omitted, no case transformation is applied. .RE +.\" METHOD: version .TP \fBtcl::idna version\fR . @@ -20,23 +20,28 @@ info \- Information about the state of the Tcl interpreter .SH DESCRIPTION .PP Available commands: +.\" METHOD: args .TP \fBinfo args \fIprocname\fR . Returns the names of the parameters to the procedure named \fIprocname\fR. +.\" METHOD: body .TP \fBinfo body \fIprocname\fR . Returns the body of the procedure named \fIprocname\fR. +.\" METHOD: class .TP \fBinfo class\fI subcommand class\fR ?\fIarg ...\fR . Returns information about the class named \fIclass\fR. See \fBCLASS INTROSPECTION\fR below. +.\" METHOD: cmdcount .TP \fBinfo cmdcount\fR . Returns the total number of commands evaluated in this interpreter. +.\" METHOD: cmdtype .TP \fBinfo cmdtype \fIcommandName\fR .VS TIP426 @@ -70,6 +75,7 @@ that represents an instance of \fBoo::object\fR or one of its subclasses. \fIcommandName\fR was created by \fBzlib stream\fR. .RE .VE TIP426 +.\" METHOD: commands .TP \fBinfo commands \fR?\fIpattern\fR? . @@ -78,18 +84,21 @@ Returns the names of all commands visible in the current namespace. If \fBstring match\fR. Only the last component of \fIpattern\fR is a pattern. Other components identify a namespace. See \fBNAMESPACE RESOLUTION\fR in the \fBnamespace\fR(n) documentation. +.\" METHOD: complete .TP \fBinfo complete \fIcommand\fR . Returns 1 if \fIcommand\fR is a complete command, and \fB0\fR otherwise. Typically used in line-oriented input environments to allow users to type in commands that span multiple lines. +.\" METHOD: constant .TP \fBinfo constant \fIvarName\fR .VS "TIP 677" Returns 1 if \fIvarName\fR is a constant variable (see \fBconst\fR) and 0 otherwise. .VE "TIP 677" +.\" METHOD: consts .TP \fBinfo consts\fR ?\fIpattern\fR? .VS "TIP 677" @@ -97,18 +106,21 @@ Returns the list of constant variables (see \fBconst\fR) in the current scope, or the list of constant variables matching \fIpattern\fR (if that is provided) in a manner similar to \fBinfo vars\fR. .VE "TIP 677" +.\" METHOD: coroutine .TP \fBinfo coroutine\fR . Returns the name of the current \fBcoroutine\fR, or the empty string if there is no current coroutine or the current coroutine has been deleted. +.\" METHOD: default .TP \fBinfo default \fIprocname parameter varname\fR . If the parameter \fIparameter\fR for the procedure named \fIprocname\fR has a default value, stores that value in \fIvarname\fR and returns \fB1\fR. Otherwise, returns \fB0\fR. +.\" METHOD: errorstack .TP \fBinfo errorstack \fR?\fIinterp\fR? . @@ -136,11 +148,13 @@ options dictionary returned by 3-argument \fBcatch\fR; \fBinfo errorstack\fR is a convenient way of retrieving it for uncaught errors at top-level in an interactive \fBinterpreter\fR. .RE +.\" METHOD: exists .TP \fBinfo exists \fIvarName\fR . Returns \fB1\fR if a variable named \fIvarName\fR is visible and has been defined, and \fB0\fR otherwise. +.\" METHOD: frame .TP \fBinfo frame\fR ?\fIdepth\fR? . @@ -242,6 +256,7 @@ is given a literal list argument the system tracks the line number within the list words as well, and otherwise all line numbers are counted relative to the start of each word (smallest scope) .RE +.\" METHOD: functions .TP \fBinfo functions \fR?\fIpattern\fR? . @@ -249,6 +264,7 @@ If \fIpattern\fR is not given, returns a list of all the math functions currently defined. If \fIpattern\fR is given, returns only those names that match \fIpattern\fR according to \fBstring match\fR. +.\" METHOD: globals .TP \fBinfo globals \fR?\fIpattern\fR? . @@ -258,16 +274,20 @@ Global variables are variables in the global namespace. If \fIpattern\fR is given, only those names matching \fIpattern\fR are returned. Matching is determined using the same rules as for \fBstring match\fR. +.\" METHOD: hostname .TP \fBinfo hostname\fR . Returns the name of the current host. - +.RS +.PP This name is not guaranteed to be the fully-qualified domain name of the host. Where machines have several different names, as is common on systems with both TCP/IP (DNS) and NetBIOS-based networking installed, it is the name that is suitable for TCP/IP networking that is returned. +.RE +.\" METHOD: level .TP \fBinfo level\fR ?\fIlevel\fR? . @@ -277,11 +297,13 @@ Otherwise returns the complete command active at the given level. If is \fInumber\fR levels up from the current level. A complete command is the words in the command, with all subsitutions performed, meaning that it is a list. See \fBuplevel\fR for more information on levels. +.\" METHOD: library .TP \fBinfo library\fR . Returns the value of \fBtcl_library\fR, which is the name of the library directory in which the scripts distributed with Tcl scripts are stored. +.\" METHOD: loaded .TP \fBinfo loaded \fR?\fIinterp\fR? ?\fIpackage\fR? . @@ -290,6 +312,7 @@ Returns the name of each file loaded in \fIinterp\fR va \fBload\fR as part of is the name of the loaded file and the name of the package for which the file was loaded. For a statically-loaded package the name of the file is the empty string. For \fIinterp\fR, the empty string is the current interpreter. +.\" METHOD: locals .TP \fBinfo locals \fR?\fIpattern\fR? . @@ -297,22 +320,25 @@ If \fIpattern\fR is given, returns the name of each local variable matching \fIpattern\fR according to \fBstring match\fR. Otherwise, returns the name of each local variable. A variables defined with the \fBglobal\fR, \fBupvar\fR or \fBvariable\fR is not local. - +.\" METHOD: nameofexecutable .TP \fBinfo nameofexecutable\fR . Returns the absolute pathname of the program for the current interpreter. If such a file can not be identified an empty string is returned. +.\" METHOD: object .TP \fBinfo object\fI subcommand object\fR ?\fIarg ...\fR . Returns information about the object named \fIobject\fR. \fIsubcommand\fR is described \fBOBJECT INTROSPECTION\fR below. +.\" METHOD: patchlevel .TP \fBinfo patchlevel\fR . Returns the value of the global variable \fBtcl_patchLevel\fR, in which the exact version of the Tcl library initially stored. +.\" METHOD: procs .TP \fBinfo procs \fR?\fIpattern\fR? . @@ -321,6 +347,7 @@ only those names that match according to \fBstring match\fR. Only the final component in \fIpattern\fR is actually considered a pattern. Any qualifying components simply select a namespace. See \fBNAMESPACE RESOLUTION\fR in the \fBnamespace\fR(n) documentation. +.\" METHOD: script .TP \fBinfo script\fR ?\fIfilename\fR? . @@ -329,17 +356,20 @@ empty string if no pathname can be determined. If \fIfilename\fR is given, sets the return value of any future calls to \fBinfo script\fR for the duration of the innermost active script. This is useful in virtual file system applications. +.\" METHOD: sharedlibextension .TP \fBinfo sharedlibextension\fR . Returns the extension used on this platform for names of shared libraries, e.g. \fB.so\fR under Solaris. Returns the empty string if shared libraries are not supported on this platform. +.\" METHOD: tclversion .TP \fBinfo tclversion\fR . Returns the value of the global variable \fBtcl_version\fR, in which the major and minor version of the Tcl library are stored. +.\" METHOD: vars .TP \fBinfo vars\fR ?\fIpattern\fR? . @@ -349,11 +379,15 @@ If \fIpattern\fR is not given, returns the names of all visible variables. If Other components identify a namespace. See \fBNAMESPACE RESOLUTION\fR in the \fBnamespace\fR(n) documentation. When \fIpattern\fR is a qualified name, results are fully qualified. - -A variable that has declared but not yet defined is included in the results. +.RS +.PP +A variable that has been declared but not yet given a value will be included in +the results. +.RE .SS "CLASS INTROSPECTION" .PP The following \fIsubcommand\fR values are supported by \fBinfo class\fR: +.\" METHOD: call .TP \fBinfo class call\fI class method\fR . @@ -384,6 +418,7 @@ and the call chains that this command files do not actually contain private methods. .VE TIP500 .RE +.\" METHOD: constructor .TP \fBinfo class constructor\fI class\fR . @@ -393,6 +428,7 @@ element is the list of arguments to the constructor in a form suitable for passing to another call to \fBproc\fR or a method definition, and the second element is the body of the constructor. If no constructor is present, this returns the empty list. +.\" METHOD: definition .TP \fBinfo class definition\fI class method\fR . @@ -401,6 +437,7 @@ This subcommand returns a description of the definition of the method named list; the first element is the list of arguments to the method in a form suitable for passing to another call to \fBproc\fR or a method definition, and the second element is the body of the method. +.\" METHOD: definitionnamespace .TP \fBinfo class definitionnamespace\fI class\fR ?\fIkind\fR? .VS TIP524 @@ -419,26 +456,31 @@ this command returns the empty string. In those circumstances, the namespace to use using the class inheritance hierarchy. .RE .VE TIP524 +.\" METHOD: destructor .TP \fBinfo class destructor\fI class\fR . This subcommand returns the body of the destructor of class \fIclass\fR. If no destructor is present, this returns the empty string. +.\" METHOD: filters .TP \fBinfo class filters\fI class\fR . This subcommand returns the list of filter methods set on the class. +.\" METHOD: forward .TP \fBinfo class forward\fI class method\fR . This subcommand returns the argument list for the method forwarding called \fImethod\fR that is set on the class called \fIclass\fR. +.\" METHOD: instances .TP \fBinfo class instances\fI class\fR ?\fIpattern\fR? . This subcommand returns a list of instances of class \fIclass\fR. If the optional \fIpattern\fR argument is present, it constrains the list of returned instances to those that match it according to the rules of \fBstring match\fR. +.\" METHOD: methods .TP \fBinfo class methods\fI class\fR ?\fIoptions...\fR? . @@ -489,6 +531,7 @@ methods) are to be returned. .RE .VE TIP500 .RE +.\" METHOD: methodtype .TP \fBinfo class methodtype\fI class method\fR . @@ -497,11 +540,13 @@ the method named \fImethod\fR of class \fIclass\fR. When the result is \fBmethod\fR, further information can be discovered with \fBinfo class definition\fR, and when the result is \fBforward\fR, further information can be discovered with \fBinfo class forward\fR. +.\" METHOD: mixins .TP \fBinfo class mixins\fI class\fR . This subcommand returns a list of all classes that have been mixed into the class named \fIclass\fR. +.\" METHOD: properties .TP \fBinfo class properties\fI class\fR ?\fIoptions...\fR .VS "TIP 558" @@ -525,6 +570,7 @@ This option asks for the writable properties to be returned. Only readable or writable properties are returned, not both. .RE .VE "TIP 558" +.\" METHOD: subclasses .TP \fBinfo class subclasses\fI class\fR ?\fIpattern\fR? . @@ -532,11 +578,13 @@ This subcommand returns a list of direct subclasses of class \fIclass\fR. If the optional \fIpattern\fR argument is present, it constrains the list of returned classes to those that match it according to the rules of \fBstring match\fR. +.\" METHOD: superclasses .TP \fBinfo class superclasses\fI class\fR . This subcommand returns a list of direct superclasses of class \fIclass\fR in inheritance precedence order. +.\" METHOD: variables .TP \fBinfo class variables\fI class\fR ?\fB\-private\fR? . @@ -550,6 +598,7 @@ declared instead. .SS "OBJECT INTROSPECTION" .PP The following \fIsubcommand\fR values are supported by \fBinfo object\fR: +.\" METHOD: call .TP \fBinfo object call\fI object method\fR . @@ -579,12 +628,14 @@ and the call chains that this command files do not actually contain private methods. .VE TIP500 .RE +.\" METHOD: class .TP \fBinfo object class\fI object\fR ?\fIclassName\fR? . If \fIclassName\fR is not given, this subcommand returns class of the \fIobject\fR object. If \fIclassName\fR is present, this subcommand returns a boolean value indicating whether the \fIobject\fR is of that class. +.\" METHOD: creationid .TP \fBinfo object creationid\fI object\fR .VS TIP500 @@ -597,6 +648,7 @@ cannot be controlled at object creation time or altered afterwards. identifiers associated with the object, especially for private variables. .RE .VE TIP500 +.\" METHOD: definition .TP \fBinfo object definition\fI object method\fR . @@ -605,15 +657,18 @@ This subcommand returns a description of the definition of the method named element list; the first element is the list of arguments to the method in a form suitable for passing to another call to \fBproc\fR or a method definition, and the second element is the body of the method. +.\" METHOD: filters .TP \fBinfo object filters\fI object\fR . This subcommand returns the list of filter methods set on the object. +.\" METHOD: forward .TP \fBinfo object forward\fI object method\fR . This subcommand returns the argument list for the method forwarding called \fImethod\fR that is set on the object called \fIobject\fR. +.\" METHOD: isa .TP \fBinfo object isa\fI category object\fR ?\fIarg\fR? . @@ -646,6 +701,7 @@ This returns whether \fIclass\fR is the type of \fIobject\fR (i.e. whether \fIobject\fR is an instance of \fIclass\fR or one of its subclasses, whether direct or indirect). .RE +.\" METHOD: methods .TP \fBinfo object methods\fI object\fR ?\fIoption...\fR? . @@ -696,6 +752,7 @@ instance methods) are to be returned. .RE .VE TIP500 .RE +.\" METHOD: methodtype .TP \fBinfo object methodtype\fI object method\fR . @@ -704,16 +761,19 @@ the method named \fImethod\fR of object \fIobject\fR. When the result is \fBmethod\fR, further information can be discovered with \fBinfo object definition\fR, and when the result is \fBforward\fR, further information can be discovered with \fBinfo object forward\fR. +.\" METHOD: mixins .TP \fBinfo object mixins\fI object\fR . This subcommand returns a list of all classes that have been mixed into the object named \fIobject\fR. +.\" METHOD: namespace .TP \fBinfo object namespace\fI object\fR . This subcommand returns the name of the internal namespace of the object named \fIobject\fR. +.\" METHOD: properties .TP \fBinfo object properties\fI object\fR ?\fIoptions...\fR .VS "TIP 558" @@ -738,6 +798,7 @@ This option asks for the writable properties to be returned. Only readable or writable properties are returned, not both. .RE .VE "TIP 558" +.\" METHOD: variables .TP \fBinfo object variables\fI object\fRR ?\fB\-private\fR? . @@ -748,6 +809,7 @@ object's methods). If the \fB\-private\fR option is given, this lists the private variables declared instead. .VE TIP500 +.\" METHOD: vars .TP \fBinfo object vars\fI object\fR ?\fIpattern\fR? . diff --git a/doc/interp.n b/doc/interp.n index 7037c65..7cff9c2 100644 --- a/doc/interp.n +++ b/doc/interp.n @@ -87,8 +87,9 @@ The \fBinterp\fR command is used to create, delete, and manipulate child interpreters, and to share or transfer channels between interpreters. It can have any of several forms, depending on the \fIsubcommand\fR argument: +.\" METHOD: alias .TP -\fBinterp\fR \fBalias\fR \fIsrcPath\fR \fIsrcToken\fR +\fBinterp alias\fI srcPath srcToken\fR . Returns a Tcl list whose elements are the \fItargetCmd\fR and \fIarg\fRs associated with the alias represented by \fIsrcToken\fR @@ -96,7 +97,7 @@ Returns a Tcl list whose elements are the \fItargetCmd\fR and created; it is possible that the name of the source command in the child is different from \fIsrcToken\fR). .TP -\fBinterp\fR \fBalias\fR \fIsrcPath\fR \fIsrcToken\fR \fB{}\fR +\fBinterp alias\fI srcPath srcToken\fR \fB{}\fR . Deletes the alias for \fIsrcToken\fR in the child interpreter identified by \fIsrcPath\fR. @@ -104,7 +105,7 @@ Deletes the alias for \fIsrcToken\fR in the child interpreter identified by was created; if the source command has been renamed, the renamed command will be deleted. .TP -\fBinterp\fR \fBalias\fR \fIsrcPath\fR \fIsrcCmd\fR \fItargetPath\fR \fItargetCmd \fR?\fIarg arg ...\fR? +\fBinterp alias\fI srcPath srcCmd targetPath targetCmd \fR?\fIarg arg ...\fR? . This command creates an alias between one child and another (see the \fBalias\fR child command below for creating aliases between a child @@ -135,14 +136,16 @@ more details. The command returns a token that uniquely identifies the command created \fIsrcCmd\fR, even if the command is renamed afterwards. The token may but does not have to be equal to \fIsrcCmd\fR. +.\" METHOD: aliases .TP -\fBinterp\fR \fBaliases \fR?\fIpath\fR? +\fBinterp aliases \fR?\fIpath\fR? . This command returns a Tcl list of the tokens of all the source commands for aliases defined in the interpreter identified by \fIpath\fR. The tokens correspond to the values returned when the aliases were created (which may not be the same as the current names of the commands). +.\" METHOD: bgerror .TP \fBinterp bgerror \fIpath\fR ?\fIcmdPrefix\fR? . @@ -152,8 +155,10 @@ absent, the current background exception handler is returned, and if it is present, it is a list of words (of minimum length one) that describes what to set the interpreter's background exception handler to. See the \fBBACKGROUND EXCEPTION HANDLING\fR section for more details. +.\" METHOD: cancel .TP -\fBinterp\fR \fBcancel \fR?\fB\-unwind\fR? ?\fB\-\|\-\fR? ?\fIpath\fR? ?\fIresult\fR? +\fBinterp cancel \fR?\fB\-unwind\fR? ?\fB\-\|\-\fR? ?\fIpath\fR? ?\fIresult\fR? +. Cancels the script being evaluated in the interpreter identified by \fIpath\fR. Without the \fB\-unwind\fR switch the evaluation stack for the interpreter is unwound until an enclosing catch command is found or @@ -166,8 +171,16 @@ switches; it may be needed if \fIpath\fR is an unusual value such as \fB\-safe\fR. If \fIresult\fR is present, it will be used as the error message string; otherwise, a default error message string will be used. +.\" METHOD: children +.TP +\fBinterp children\fR ?\fIpath\fR? +. +Returns a Tcl list of the names of all the child interpreters associated +with the interpreter identified by \fIpath\fR. If \fIpath\fR is omitted, +the invoking interpreter is used. +.\" METHOD: create .TP -\fBinterp\fR \fBcreate \fR?\fB\-safe\fR? ?\fB\-\|\-\fR? ?\fIpath\fR? +\fBinterp create \fR?\fB\-safe\fR? ?\fB\-\|\-\fR? ?\fIpath\fR? . Creates a child interpreter identified by \fIpath\fR and a new command, called a \fIchild command\fR. The name of the child command is the last @@ -191,8 +204,9 @@ the children for its parent; an error occurs if a child interpreter by the given name already exists in this parent. The initial recursion limit of the child interpreter is set to the current recursion limit of its parent interpreter. +.\" METHOD: debug .TP -\fBinterp\fR \fBdebug \fIpath\fR ?\fB\-frame\fR ?\fIbool\fR?? +\fBinterp debug \fIpath\fR ?\fB\-frame\fR ?\fIbool\fR?? . Controls whether frame-level stack information is captured in the child interpreter identified by \fIpath\fR. If no arguments are @@ -233,16 +247,18 @@ Note that once it is on, this flag cannot be switched back off: such attempts are silently ignored. This is needed to maintain the consistency of the underlying interpreter's state. .RE +.\" METHOD: delete .TP -\fBinterp\fR \fBdelete \fR?\fIpath ...\fR? +\fBinterp delete \fR?\fIpath ...\fR? . Deletes zero or more interpreters given by the optional \fIpath\fR arguments, and for each interpreter, it also deletes its children. The command also deletes the child command for each interpreter deleted. For each \fIpath\fR argument, if no interpreter by that name exists, the command raises an error. +.\" METHOD: eval .TP -\fBinterp\fR \fBeval\fR \fIpath arg \fR?\fIarg ...\fR? +\fBinterp eval\fI path arg \fR?\fIarg ...\fR? . This command concatenates all of the \fIarg\fR arguments in the same fashion as the \fBconcat\fR command, then evaluates the resulting string as @@ -255,14 +271,16 @@ Note that the script will be executed in the current context stack frame of the interpreter) of aliases in a child interpreter can execute scripts in the child that find out information about the child's current state and stack frame. +.\" METHOD: exists .TP \fBinterp exists \fIpath\fR . Returns \fB1\fR if a child interpreter by the specified \fIpath\fR exists in this parent, \fB0\fR otherwise. If \fIpath\fR is omitted, the invoking interpreter is used. +.\" METHOD: expose .TP -\fBinterp expose \fIpath\fR \fIhiddenName\fR ?\fIexposedCmdName\fR? +\fBinterp expose \fIpath hiddenName\fR ?\fIexposedCmdName\fR? . Makes the hidden command \fIhiddenName\fR exposed, eventually bringing it back under a new \fIexposedCmdName\fR name (this name is currently @@ -272,8 +290,9 @@ denoted by \fIpath\fR. If an exposed command with the targeted name already exists, this command fails. Hidden commands are explained in more detail in \fBHIDDEN COMMANDS\fR, below. +.\" METHOD: hide .TP -\fBinterp\fR \fBhide\fR \fIpath\fR \fIexposedCmdName\fR ?\fIhiddenCmdName\fR? +\fBinterp hide\fI path exposedCmdName\fR ?\fIhiddenCmdName\fR? . Makes the exposed command \fIexposedCmdName\fR hidden, renaming it to the hidden command \fIhiddenCmdName\fR, or keeping the same name if @@ -288,13 +307,15 @@ namespace even if the current namespace is not the global one. This prevents children from fooling a parent interpreter into hiding the wrong command, by making the current namespace be different from the global one. Hidden commands are explained in more detail in \fBHIDDEN COMMANDS\fR, below. +.\" METHOD: hidden .TP -\fBinterp\fR \fBhidden\fR \fIpath\fR +\fBinterp hidden\fI path\fR . Returns a list of the names of all hidden commands in the interpreter identified by \fIpath\fR. +.\" METHOD: invokehidden .TP -\fBinterp\fR \fBinvokehidden\fR \fIpath\fR ?\fI\-option ...\fR? \fIhiddenCmdName\fR ?\fIarg ...\fR? +\fBinterp invokehidden\fI path\fR ?\fI\-option ...\fR? \fIhiddenCmdName\fR ?\fIarg ...\fR? . Invokes the hidden command \fIhiddenCmdName\fR with the arguments supplied in the interpreter denoted by \fIpath\fR. No substitutions or evaluation @@ -315,13 +336,15 @@ If both the \fB\-namespace\fR and \fB\-global\fR flags are present, the Note that the hidden command will be executed (by default) in the current context stack frame of the \fIpath\fR interpreter. Hidden commands are explained in more detail in \fBHIDDEN COMMANDS\fR, below. +.\" METHOD: issafe .TP \fBinterp issafe\fR ?\fIpath\fR? . Returns \fB1\fR if the interpreter identified by the specified \fIpath\fR is safe, \fB0\fR otherwise. +.\" METHOD: limit .TP -\fBinterp\fR \fBlimit\fR \fIpath\fR \fIlimitType\fR ?\fI\-option\fR? ?\fIvalue\fR \fI...\fR? +\fBinterp limit\fI path limitType\fR ?\fI\-option\fR? ?\fIvalue ...\fR? . Sets up, manipulates and queries the configuration of the resource limit \fIlimitType\fR for the interpreter denoted by \fIpath\fR. If @@ -330,16 +353,18 @@ limit. If \fI\-option\fR is the sole argument, return the value of that option. Otherwise, a list of \fI\-option\fR/\fIvalue\fR argument pairs must supplied. See \fBRESOURCE LIMITS\fR below for a more detailed explanation of what limits and options are supported. +.\" METHOD: marktrusted .TP -\fBinterp marktrusted\fR \fIpath\fR +\fBinterp marktrusted\fI path\fR . Marks the interpreter identified by \fIpath\fR as trusted. Does not expose the hidden commands. This command can only be invoked from a trusted interpreter. The command has no effect if the interpreter identified by \fIpath\fR is already trusted. +.\" METHOD: recursionlimit .TP -\fBinterp\fR \fBrecursionlimit\fR \fIpath\fR ?\fInewlimit\fR? +\fBinterp recursionlimit\fI path\fR ?\fInewlimit\fR? . Returns the maximum allowable nesting depth for the interpreter specified by \fIpath\fR. If \fInewlimit\fR is specified, @@ -358,8 +383,9 @@ may get stack overflows before reaching the limit set by the command. If this happens, see if there is a mechanism in your system for increasing the maximum size of the C stack. .RE +.\" METHOD: share .TP -\fBinterp\fR \fBshare\fR \fIsrcPath channelId destPath\fR +\fBinterp share\fI srcPath channelId destPath\fR . Causes the IO channel identified by \fIchannelId\fR to become shared between the interpreter identified by \fIsrcPath\fR and the interpreter @@ -368,14 +394,9 @@ on the IO channel. Both interpreters must close it to close the underlying IO channel; IO channels accessible in an interpreter are automatically closed when an interpreter is destroyed. +.\" METHOD: target .TP -\fBinterp\fR \fBchildren\fR ?\fIpath\fR? -. -Returns a Tcl list of the names of all the child interpreters associated -with the interpreter identified by \fIpath\fR. If \fIpath\fR is omitted, -the invoking interpreter is used. -.TP -\fBinterp\fR \fBtarget\fR \fIpath alias\fR +\fBinterp target\fI path alias\fR . Returns a Tcl list describing the target interpreter for an alias. The alias is specified with an interpreter path and source command name, just @@ -385,8 +406,9 @@ If the target interpreter for the alias is the invoking interpreter then an empty list is returned. If the target interpreter for the alias is not the invoking interpreter or one of its descendants then an error is generated. The target command does not have to be defined at the time of this invocation. +.\" METHOD: transfer .TP -\fBinterp\fR \fBtransfer\fR \fIsrcPath channelId destPath\fR +\fBinterp transfer\fI srcPath channelId destPath\fR . Causes the IO channel identified by \fIchannelId\fR to become available in the interpreter identified by \fIdestPath\fR and unavailable in the @@ -406,6 +428,7 @@ general form: \fIChild\fR is the name of the interpreter, and \fIcommand\fR and the \fIarg\fRs determine the exact behavior of the command. The valid forms of this command are: +.\" METHOD: aliases .TP \fIchild \fBaliases\fR . @@ -413,6 +436,7 @@ Returns a Tcl list whose elements are the tokens of all the aliases in \fIchild\fR. The tokens correspond to the values returned when the aliases were created (which may not be the same as the current names of the commands). +.\" METHOD: alias .TP \fIchild \fBalias \fIsrcToken\fR . @@ -440,6 +464,7 @@ See \fBALIAS INVOCATION\fR below for details. The command returns a token that uniquely identifies the command created \fIsrcCmd\fR, even if the command is renamed afterwards. The token may but does not have to be equal to \fIsrcCmd\fR. +.\" METHOD: bgerror .TP \fIchild \fBbgerror\fR ?\fIcmdPrefix\fR? . @@ -449,6 +474,7 @@ absent, the current background exception handler is returned, and if it is present, it is a list of words (of minimum length one) that describes what to set the interpreter's background exception handler to. See the \fBBACKGROUND EXCEPTION HANDLING\fR section for more details. +.\" METHOD: eval .TP \fIchild \fBeval \fIarg \fR?\fIarg ..\fR? . @@ -463,6 +489,7 @@ of \fIchild\fR; this is so that the implementations (in a parent interpreter) of aliases in a child interpreter can execute scripts in the child that find out information about the child's current state and stack frame. +.\" METHOD: expose .TP \fIchild \fBexpose \fIhiddenName \fR?\fIexposedCmdName\fR? . @@ -473,6 +500,7 @@ in \fIchild\fR. If an exposed command with the targeted name already exists, this command fails. For more details on hidden commands, see \fBHIDDEN COMMANDS\fR, below. +.\" METHOD: hide .TP \fIchild \fBhide \fIexposedCmdName\fR ?\fIhiddenCmdName\fR? . @@ -488,10 +516,12 @@ namespace even if the current namespace is not the global one. This prevents children from fooling a parent interpreter into hiding the wrong command, by making the current namespace be different from the global one. For more details on hidden commands, see \fBHIDDEN COMMANDS\fR, below. +.\" METHOD: hidden .TP \fIchild \fBhidden\fR . Returns a list of the names of all hidden commands in \fIchild\fR. +.\" METHOD: invokehidden .TP \fIchild \fBinvokehidden\fR ?\fI\-option ...\fR? \fIhiddenName \fR?\fIarg ..\fR? . @@ -514,12 +544,14 @@ Note that the hidden command will be executed (by default) in the current context stack frame of \fIchild\fR. For more details on hidden commands, see \fBHIDDEN COMMANDS\fR, below. +.\" METHOD: issafe .TP \fIchild \fBissafe\fR . -Returns \fB1\fR if the child interpreter is safe, \fB0\fR otherwise. +Returns \fB1\fR if the child interpreter is safe, \fB0\fR otherwise. +.\" METHOD: limit .TP -\fIchild \fBlimit\fR \fIlimitType\fR ?\fI\-option\fR? ?\fIvalue\fR \fI...\fR? +\fIchild \fBlimit\fI limitType\fR ?\fI\-option\fR? ?\fIvalue ...\fR? . Sets up, manipulates and queries the configuration of the resource limit \fIlimitType\fR for the child interpreter. If no \fI\-option\fR @@ -528,6 +560,7 @@ is specified, return the current configuration of the limit. If Otherwise, a list of \fI\-option\fR/\fIvalue\fR argument pairs must supplied. See \fBRESOURCE LIMITS\fR below for a more detailed explanation of what limits and options are supported. +.\" METHOD: marktrusted .TP \fIchild \fBmarktrusted\fR . @@ -535,8 +568,9 @@ Marks the child interpreter as trusted. Can only be invoked by a trusted interpreter. This command does not expose any hidden commands in the child interpreter. The command has no effect if the child is already trusted. +.\" METHOD: recursionlimit .TP -\fIchild\fR \fBrecursionlimit\fR ?\fInewlimit\fR? +\fIchild \fBrecursionlimit\fR ?\fInewlimit\fR? . Returns the maximum allowable nesting depth for the \fIchild\fR interpreter. If \fInewlimit\fR is specified, the recursion limit in \fIchild\fR will be diff --git a/doc/library.n b/doc/library.n index 0342cbe..d55218d 100644 --- a/doc/library.n +++ b/doc/library.n @@ -61,6 +61,7 @@ the auto-load mechanism defined below. .SH "COMMAND PROCEDURES" .PP The following procedures are provided in the Tcl library: +.\" COMMAND: auto_execok .TP \fBauto_execok \fIcmd\fR . @@ -97,6 +98,7 @@ you would do: set mayFrob [expr {[llength [\fBauto_execok\fR frobnicate]] > 0}] .CE .RE +.\" COMMAND: auto_import .TP \fBauto_import \fIpattern\fR . @@ -111,6 +113,7 @@ matching rules of \fBnamespace import\fR. .PP It is not normally necessary to call this command directly. .RE +.\" COMMAND: auto_load .TP \fBauto_load \fIcmd\fR . @@ -142,6 +145,7 @@ reload the index database from disk. It is not normally necessary to call this command directly; the default \fBunknown\fR handler will do so. .RE +.\" COMMAND: auto_mkindex .TP \fBauto_mkindex \fIdir pattern pattern ...\fR . @@ -184,6 +188,7 @@ code, such as global initialization code or procedure names with special characters like \fB$\fR, \fB*\fR, \fB[\fR or \fB]\fR, you are safer using \fBauto_mkindex_old\fR. .RE +.\" COMMAND: auto_reset .TP \fBauto_reset\fR . @@ -192,6 +197,7 @@ Destroys all the information cached by \fBauto_execok\fR and time it is needed. \fBAuto_reset\fR also deletes any procedures listed in the auto-load index, so that fresh copies of them will be loaded the next time that they are used. +.\" COMMAND: auto_qualify .TP \fBauto_qualify \fIcommand namespace\fR . @@ -212,6 +218,7 @@ if it were a command in the global namespace. for producing auto-loading indexes such as \fIpkgIndex.tcl\fR, and for performing the actual auto-loading of functions at runtime. .RE +.\" COMMAND: auto_findLibrary .TP \fBtcl_findLibrary \fIbasename version patch initScript enVarName varName\fR . @@ -235,6 +242,7 @@ relative to the executable file in the standard installation bin or bin/\fIarch\fR directory; relative to the executable file in the current build tree; relative to the executable file in a parallel build tree. +.\" COMMAND: parray .TP \fBparray \fIarrayName\fR ?\fIpattern\fR? . @@ -256,6 +264,7 @@ For example, to print the contents of the \fBtcl_platform\fR array, do: .SS "WORD BOUNDARY HELPERS" .PP These procedures are mainly used internally by Tk. +.\" COMMAND: tcl_endOfWord .TP \fBtcl_endOfWord \fIstr start\fR . @@ -267,6 +276,7 @@ are no more end-of-word locations after the starting point. See the description of \fBtcl_wordchars\fR and \fBtcl_nonwordchars\fR below for more details on how Tcl determines which characters are word characters. +.\" COMMAND: tcl_startOfNextWord .TP \fBtcl_startOfNextWord \fIstr start\fR . @@ -288,6 +298,7 @@ for {set idx 0} {$idx >= 0} { } .CE .RE +.\" COMMAND: tcl_startOfPreviousWord .TP \fBtcl_startOfPreviousWord \fIstr start\fR . @@ -295,6 +306,7 @@ Returns the index of the first start-of-word location that occurs before a starting index \fIstart\fR in the string \fIstr\fR. Returns \-1 if there are no more start-of-word locations before the starting point. +.\" COMMAND: tcl_wordBreakAfter .TP \fBtcl_wordBreakAfter \fIstr start\fR . @@ -303,6 +315,7 @@ Returns the index of the first word boundary after the starting index boundaries after the starting point in the given string. The index returned refers to the second character of the pair that comprises a boundary. +.\" COMMAND: tcl_wordBreakBefore .TP \fBtcl_wordBreakBefore \fIstr start\fR . @@ -311,6 +324,8 @@ Returns the index of the first word boundary before the starting index boundaries before the starting point in the given string. The index returned refers to the second character of the pair that comprises a boundary. +.SS "FILE ACCESS HELPERS" +.\" COMMAND: foreachLine .TP \fBforeachLine \fIvarName filename body\fR .VS "Tcl 8.7, TIP 670" @@ -325,6 +340,7 @@ The overall result of \fBforeachLine\fR is the empty string (assuming no errors from I/O or from evaluating the body of the loop); the file will be closed prior to the procedure returning. .VE "Tcl 8.7, TIP 670" +.\" COMMAND: readFile .TP \fBreadFile \fIfilename\fR ?\fBtext\fR|\fBbinary\fR? .VS "Tcl 8.7, TIP 670" @@ -335,6 +351,7 @@ The second argument says how to read in the file, either as \fBtext\fR will include any trailing newline. The file will be closed prior to the procedure returning. .VE "Tcl 8.7, TIP 670" +.\" COMMAND: writeFile .TP \fBwriteFile \fIfilename\fR ?\fBtext\fR|\fBbinary\fR? \fIcontents\fR .VS "Tcl 8.7, TIP 670" @@ -352,6 +369,7 @@ The following global variables are defined or used by the procedures in the Tcl library. They fall into two broad classes, handling unknown commands and packages, and determining what are words. .SS "AUTOLOADING AND PACKAGE MANAGEMENT VARIABLES" +.\" VARIABLE: auto_execs .TP \fBauto_execs\fR . @@ -361,6 +379,7 @@ particular commands exist as executable files. .PP Not normally usefully accessed directly by user code. .RE +.\" VARIABLE: auto_index .TP \fBauto_index\fR . @@ -370,16 +389,19 @@ disk. .PP Not normally usefully accessed directly by user code. .RE +.\" VARIABLE: auto_noexec .TP \fBauto_noexec\fR . If set to any value, then \fBunknown\fR will not attempt to auto-exec any commands. +.\" VARIABLE: auto_noload .TP \fBauto_noload\fR . If set to any value, then \fBunknown\fR will not attempt to auto-load any commands. +.\" VARIABLE: auto_path .TP \fBauto_path\fR . @@ -405,6 +427,7 @@ lappend \fBauto_path\fR [file dirname [info script]]/lib Note that if the script uses \fBcd\fR, it is advisable to ensure that entries on the \fBauto_path\fR are \fBfile normalize\fRd. .RE +.\" VARIABLE: env(TCL_LIBRARY) .TP \fBenv(TCL_LIBRARY)\fR . @@ -419,6 +442,7 @@ Use of this environment variable is not recommended outside of testing. Tcl installations should already know where to find their own script files, as the value is baked in during the build or installation. .RE +.\" VARIABLE: env(TCLLIBPATH) .TP \fBenv(TCLLIBPATH)\fR . @@ -441,6 +465,7 @@ as their own threads or subprocesses). These variables are only used in the \fBtcl_endOfWord\fR, \fBtcl_startOfNextWord\fR, \fBtcl_startOfPreviousWord\fR, \fBtcl_wordBreakAfter\fR, and \fBtcl_wordBreakBefore\fR commands. +.\" VARIABLE: tcl_nonwordchars .TP \fBtcl_nonwordchars\fR . @@ -449,6 +474,7 @@ like \fBtcl_endOfWord\fR to identify whether a character is part of a word or not. If the pattern matches a character, the character is considered to be a non-word character. The default value is .QW "\\W" . +.\" VARIABLE: tcl_wordchars .TP \fBtcl_wordchars\fR . @@ -15,7 +15,7 @@ link \- create link from command to method of object .nf package require tcl::oo -\fBlink\fR \fImethodName\fR ?\fI...\fR? +\fBlink\fI methodName\fR ?\fI...\fR? \fBlink\fR \fB{\fIcommandName methodName\fB}\fR ?\fI...\fR? .fi .BE @@ -13,7 +13,7 @@ lseq \- Build a numeric sequence returned as a list .SH SYNOPSIS \fBlseq \fIstart \fR?(\fB..\fR|\fBto\fR)? \fIend\fR ??\fBby\fR? \fIstep\fR? -\fBlseq \fIstart \fBcount\fR \fIcount\fR ??\fBby\fR? \fIstep\fR? +\fBlseq \fIstart \fBcount\fI count\fR ??\fBby\fR? \fIstep\fR? \fBlseq \fIcount\fR ?\fBby \fIstep\fR? .BE diff --git a/doc/mathfunc.n b/doc/mathfunc.n index 805cf82..00fef17 100644 --- a/doc/mathfunc.n +++ b/doc/mathfunc.n @@ -15,83 +15,83 @@ mathfunc \- Mathematical functions for Tcl expressions .SH SYNOPSIS package require \fBTcl 8.5-\fR .sp -\fB::tcl::mathfunc::abs\fR \fIarg\fR +\fB::tcl::mathfunc::abs\fI arg\fR .br -\fB::tcl::mathfunc::acos\fR \fIarg\fR +\fB::tcl::mathfunc::acos\fI arg\fR .br -\fB::tcl::mathfunc::asin\fR \fIarg\fR +\fB::tcl::mathfunc::asin\fI arg\fR .br -\fB::tcl::mathfunc::atan\fR \fIarg\fR +\fB::tcl::mathfunc::atan\fI arg\fR .br -\fB::tcl::mathfunc::atan2\fR \fIy\fR \fIx\fR +\fB::tcl::mathfunc::atan2\fI y x\fR .br -\fB::tcl::mathfunc::bool\fR \fIarg\fR +\fB::tcl::mathfunc::bool\fI arg\fR .br -\fB::tcl::mathfunc::ceil\fR \fIarg\fR +\fB::tcl::mathfunc::ceil\fI arg\fR .br -\fB::tcl::mathfunc::cos\fR \fIarg\fR +\fB::tcl::mathfunc::cos\fI arg\fR .br -\fB::tcl::mathfunc::cosh\fR \fIarg\fR +\fB::tcl::mathfunc::cosh\fI arg\fR .br -\fB::tcl::mathfunc::double\fR \fIarg\fR +\fB::tcl::mathfunc::double\fI arg\fR .br -\fB::tcl::mathfunc::entier\fR \fIarg\fR +\fB::tcl::mathfunc::entier\fI arg\fR .br -\fB::tcl::mathfunc::exp\fR \fIarg\fR +\fB::tcl::mathfunc::exp\fI arg\fR .br -\fB::tcl::mathfunc::floor\fR \fIarg\fR +\fB::tcl::mathfunc::floor\fI arg\fR .br -\fB::tcl::mathfunc::fmod\fR \fIx\fR \fIy\fR +\fB::tcl::mathfunc::fmod\fI x y\fR .br -\fB::tcl::mathfunc::hypot\fR \fIx\fR \fIy\fR +\fB::tcl::mathfunc::hypot\fI x y\fR .br -\fB::tcl::mathfunc::int\fR \fIarg\fR +\fB::tcl::mathfunc::int\fI arg\fR .br .VS "8.7, TIP 521" -\fB::tcl::mathfunc::isfinite\fR \fIarg\fR +\fB::tcl::mathfunc::isfinite\fI arg\fR .br -\fB::tcl::mathfunc::isinf\fR \fIarg\fR +\fB::tcl::mathfunc::isinf\fI arg\fR .br -\fB::tcl::mathfunc::isnan\fR \fIarg\fR +\fB::tcl::mathfunc::isnan\fI arg\fR .br -\fB::tcl::mathfunc::isnormal\fR \fIarg\fR +\fB::tcl::mathfunc::isnormal\fI arg\fR .VE "8.7, TIP 521" .br -\fB::tcl::mathfunc::isqrt\fR \fIarg\fR +\fB::tcl::mathfunc::isqrt\fI arg\fR .br .VS "8.7, TIP 521" -\fB::tcl::mathfunc::issubnormal\fR \fIarg\fR +\fB::tcl::mathfunc::issubnormal\fI arg\fR .br -\fB::tcl::mathfunc::isunordered\fR \fIx y\fR +\fB::tcl::mathfunc::isunordered\fI x y\fR .VE "8.7, TIP 521" .br -\fB::tcl::mathfunc::log\fR \fIarg\fR +\fB::tcl::mathfunc::log\fI arg\fR .br -\fB::tcl::mathfunc::log10\fR \fIarg\fR +\fB::tcl::mathfunc::log10\fI arg\fR .br -\fB::tcl::mathfunc::max\fR \fIarg\fR ?\fIarg\fR ...? +\fB::tcl::mathfunc::max\fI arg\fR ?\fIarg\fR ...? .br -\fB::tcl::mathfunc::min\fR \fIarg\fR ?\fIarg\fR ...? +\fB::tcl::mathfunc::min\fI arg\fR ?\fIarg\fR ...? .br -\fB::tcl::mathfunc::pow\fR \fIx\fR \fIy\fR +\fB::tcl::mathfunc::pow\fI x y\fR .br \fB::tcl::mathfunc::rand\fR .br -\fB::tcl::mathfunc::round\fR \fIarg\fR +\fB::tcl::mathfunc::round\fI arg\fR .br -\fB::tcl::mathfunc::sin\fR \fIarg\fR +\fB::tcl::mathfunc::sin\fI arg\fR .br -\fB::tcl::mathfunc::sinh\fR \fIarg\fR +\fB::tcl::mathfunc::sinh\fI arg\fR .br -\fB::tcl::mathfunc::sqrt\fR \fIarg\fR +\fB::tcl::mathfunc::sqrt\fI arg\fR .br -\fB::tcl::mathfunc::srand\fR \fIarg\fR +\fB::tcl::mathfunc::srand\fI arg\fR .br -\fB::tcl::mathfunc::tan\fR \fIarg\fR +\fB::tcl::mathfunc::tan\fI arg\fR .br -\fB::tcl::mathfunc::tanh\fR \fIarg\fR +\fB::tcl::mathfunc::tanh\fI arg\fR .br -\fB::tcl::mathfunc::wide\fR \fIarg\fR +\fB::tcl::mathfunc::wide\fI arg\fR .sp .BE .SH "DESCRIPTION" @@ -126,26 +126,31 @@ define additional functions by using \fBproc\fR (or any other method, such as \fBinterp alias\fR or \fBTcl_CreateObjCommand\fR) to define new commands in the \fBtcl::mathfunc\fR namespace. .SS "DETAILED DEFINITIONS" +.\" COMMAND: abs .TP \fBabs \fIarg\fR . Returns the absolute value of \fIarg\fR. \fIArg\fR may be either integer or floating-point, and the result is returned in the same form. +.\" COMMAND: acos .TP \fBacos \fIarg\fR . Returns the arc cosine of \fIarg\fR, in the range [\fI0\fR,\fIpi\fR] radians. \fIArg\fR should be in the range [\fI\-1\fR,\fI1\fR]. +.\" COMMAND: asin .TP \fBasin \fIarg\fR . Returns the arc sine of \fIarg\fR, in the range [\fI\-pi/2\fR,\fIpi/2\fR] radians. \fIArg\fR should be in the range [\fI\-1\fR,\fI1\fR]. +.\" COMMAND: atan .TP \fBatan \fIarg\fR . Returns the arc tangent of \fIarg\fR, in the range [\fI\-pi/2\fR,\fIpi/2\fR] radians. +.\" COMMAND: atan2 .TP \fBatan2 \fIy x\fR . @@ -153,6 +158,7 @@ Returns the arc tangent of \fIy\fR/\fIx\fR, in the range [\fI\-pi\fR,\fIpi\fR] radians. \fIx\fR and \fIy\fR cannot both be 0. If \fIx\fR is greater than \fI0\fR, this is equivalent to .QW "\fBatan \fR[\fBexpr\fR {\fIy\fB/\fIx\fR}]" . +.\" COMMAND: bool .TP \fBbool \fIarg\fR . @@ -161,21 +167,25 @@ Accepts any numeric value, or any string acceptable to boolean value \fB0\fR or \fB1\fR. Non-zero numbers are true. Other numbers are false. Non-numeric strings produce boolean value in agreement with \fBstring is true\fR and \fBstring is false\fR. +.\" COMMAND: ceil .TP \fBceil \fIarg\fR . Returns the smallest integral floating-point value (i.e. with a zero fractional part) not less than \fIarg\fR. The argument may be any numeric value. +.\" COMMAND: cos .TP \fBcos \fIarg\fR . Returns the cosine of \fIarg\fR, measured in radians. +.\" COMMAND: cosh .TP \fBcosh \fIarg\fR . Returns the hyperbolic cosine of \fIarg\fR. If the result would cause an overflow, an error is returned. +.\" COMMAND: double .TP \fBdouble \fIarg\fR . @@ -184,6 +194,7 @@ If \fIarg\fR is a floating-point value, returns \fIarg\fR, otherwise converts \fIarg\fR to floating-point and returns the converted value. May return \fBInf\fR or \fB\-Inf\fR when the argument is a numeric value that exceeds the floating-point range. +.\" COMMAND: entier .TP \fBentier \fIarg\fR . @@ -191,22 +202,26 @@ The argument may be any numeric value. The integer part of \fIarg\fR is determined and returned. The integer range returned by this function is unlimited, unlike \fBint\fR and \fBwide\fR which truncate their range to fit in particular storage widths. +.\" COMMAND: exp .TP \fBexp \fIarg\fR . Returns the exponential of \fIarg\fR, defined as \fIe\fR**\fIarg\fR. If the result would cause an overflow, an error is returned. +.\" COMMAND: floor .TP \fBfloor \fIarg\fR . Returns the largest integral floating-point value (i.e. with a zero fractional part) not greater than \fIarg\fR. The argument may be any numeric value. +.\" COMMAND: fmod .TP \fBfmod \fIx y\fR . Returns the floating-point remainder of the division of \fIx\fR by \fIy\fR. If \fIy\fR is 0, an error is returned. +.\" COMMAND: hypot .TP \fBhypot \fIx y\fR . @@ -215,6 +230,7 @@ approximately .QW "\fBsqrt\fR [\fBexpr\fR {\fIx\fB*\fIx\fB+\fIy\fB*\fIy\fR}]" except for being more numerically stable when the two arguments have substantially different magnitudes. +.\" COMMAND: int .TP \fBint \fIarg\fR . @@ -223,6 +239,7 @@ is determined, and then the low order bits of that integer value up to the machine word size are returned as an integer value. For reference, the number of bytes in the machine word are stored in the \fBwordSize\fR element of the \fBtcl_platform\fR array. +.\" COMMAND: isfinite .TP \fBisfinite \fIarg\fR .VS "8.7, TIP 521" @@ -230,6 +247,7 @@ Returns 1 if the floating-point number \fIarg\fR is finite. That is, if it is zero, subnormal, or normal. Returns 0 if the number is infinite or NaN. Throws an error if \fIarg\fR cannot be promoted to a floating-point value. .VE "8.7, TIP 521" +.\" COMMAND: isinf .TP \fBisinf \fIarg\fR .VS "8.7, TIP 521" @@ -237,6 +255,7 @@ Returns 1 if the floating-point number \fIarg\fR is infinite. Returns 0 if the number is finite or NaN. Throws an error if \fIarg\fR cannot be promoted to a floating-point value. .VE "8.7, TIP 521" +.\" COMMAND: isnan .TP \fBisnan \fIarg\fR .VS "8.7, TIP 521" @@ -244,6 +263,7 @@ Returns 1 if the floating-point number \fIarg\fR is Not-a-Number. Returns 0 if the number is finite or infinite. Throws an error if \fIarg\fR cannot be promoted to a floating-point value. .VE "8.7, TIP 521" +.\" COMMAND: isnormal .TP \fBisnormal \fIarg\fR .VS "8.7, TIP 521" @@ -251,6 +271,7 @@ Returns 1 if the floating-point number \fIarg\fR is normal. Returns 0 if the number is zero, subnormal, infinite or NaN. Throws an error if \fIarg\fR cannot be promoted to a floating-point value. .VE "8.7, TIP 521" +.\" COMMAND: isqrt .TP \fBisqrt \fIarg\fR . @@ -258,6 +279,7 @@ Computes the integer part of the square root of \fIarg\fR. \fIArg\fR must be a positive value, either an integer or a floating point number. Unlike \fBsqrt\fR, which is limited to the precision of a floating point number, \fIisqrt\fR will return a result of arbitrary precision. +.\" COMMAND: issubnormal .TP \fBissubnormal \fIarg\fR .VS "8.7, TIP 521" @@ -266,6 +288,7 @@ result of gradual underflow. Returns 0 if the number is zero, normal, infinite or NaN. Throws an error if \fIarg\fR cannot be promoted to a floating-point value. .VE "8.7, TIP 521" +.\" COMMAND: isunordered .TP \fBisunordered \fIx y\fR .VS "8.7, TIP 521" @@ -275,31 +298,37 @@ are both chosen from among the set of zero, subnormal, normal and infinite values. Throws an error if either \fIx\fR or \fIy\fR cannot be promoted to a floating-point value. .VE "8.7, TIP 521" +.\" COMMAND: log .TP \fBlog \fIarg\fR . Returns the natural logarithm of \fIarg\fR. \fIArg\fR must be a positive value. +.\" COMMAND: log10 .TP \fBlog10 \fIarg\fR . Returns the base 10 logarithm of \fIarg\fR. \fIArg\fR must be a positive value. +.\" COMMAND: max .TP \fBmax \fIarg\fB \fI...\fR . Accepts one or more numeric arguments. Returns the one argument with the greatest value. +.\" COMMAND: min .TP \fBmin \fIarg\fB \fI...\fR . Accepts one or more numeric arguments. Returns the one argument with the least value. +.\" COMMAND: pow .TP \fBpow \fIx y\fR . Computes the value of \fIx\fR raised to the power \fIy\fR. If \fIx\fR is negative, \fIy\fR must be an integer value. +.\" COMMAND: rand .TP \fBrand\fR . @@ -310,20 +339,24 @@ determines all future results from subsequent calls to \fBrand\fR, so \fBrand\fR should not be used to generate a sequence of secrets, such as one-time passwords. The seed of the generator is initialized from the internal clock of the machine or may be set with the \fBsrand\fR function. +.\" COMMAND: round .TP \fBround \fIarg\fR . If \fIarg\fR is an integer value, returns \fIarg\fR, otherwise converts \fIarg\fR to integer by rounding and returns the converted value. +.\" COMMAND: sin .TP \fBsin \fIarg\fR . Returns the sine of \fIarg\fR, measured in radians. +.\" COMMAND: sinh .TP \fBsinh \fIarg\fR . Returns the hyperbolic sine of \fIarg\fR. If the result would cause an overflow, an error is returned. +.\" COMMAND: sqrt .TP \fBsqrt \fIarg\fR . @@ -331,20 +364,24 @@ The argument may be any non-negative numeric value. Returns a floating-point value that is the square root of \fIarg\fR. May return \fBInf\fR when the argument is a numeric value that exceeds the square of the maximum value of the floating-point range. +.\" COMMAND: srand .TP \fBsrand \fIarg\fR . The \fIarg\fR, which must be an integer, is used to reset the seed for the random number generator of \fBrand\fR. Returns the first random number (see \fBrand\fR) from that seed. Each interpreter has its own seed. +.\" COMMAND: tan .TP \fBtan \fIarg\fR . Returns the tangent of \fIarg\fR, measured in radians. +.\" COMMAND: tanh .TP \fBtanh \fIarg\fR . Returns the hyperbolic tangent of \fIarg\fR. +.\" COMMAND: wide .TP \fBwide \fIarg\fR . diff --git a/doc/mathop.n b/doc/mathop.n index 3a13456..f8a0dc4 100644 --- a/doc/mathop.n +++ b/doc/mathop.n @@ -13,19 +13,19 @@ mathop \- Mathematical operators as Tcl commands .SH SYNOPSIS package require \fBTcl 8.5-\fR .sp -\fB::tcl::mathop::!\fR \fInumber\fR +\fB::tcl::mathop::!\fI number\fR .br -\fB::tcl::mathop::~\fR \fInumber\fR +\fB::tcl::mathop::~\fI number\fR .br \fB::tcl::mathop::+\fR ?\fInumber\fR ...? .br -\fB::tcl::mathop::\-\fR \fInumber\fR ?\fInumber\fR ...? +\fB::tcl::mathop::\-\fI number\fR ?\fInumber\fR ...? .br \fB::tcl::mathop::*\fR ?\fInumber\fR ...? .br -\fB::tcl::mathop::/\fR \fInumber\fR ?\fInumber\fR ...? +\fB::tcl::mathop::/\fI number\fR ?\fInumber\fR ...? .br -\fB::tcl::mathop::%\fR \fInumber number\fR +\fB::tcl::mathop::%\fI number number\fR .br \fB::tcl::mathop::**\fR ?\fInumber\fR ...? .br @@ -35,13 +35,13 @@ package require \fBTcl 8.5-\fR .br \fB::tcl::mathop::^\fR ?\fInumber\fR ...? .br -\fB::tcl::mathop::<<\fR \fInumber number\fR +\fB::tcl::mathop::<<\fI number number\fR .br -\fB::tcl::mathop::>>\fR \fInumber number\fR +\fB::tcl::mathop::>>\fI number number\fR .br \fB::tcl::mathop::==\fR ?\fIarg\fR ...? .br -\fB::tcl::mathop::!=\fR \fIarg arg\fR +\fB::tcl::mathop::!=\fI arg arg\fR .br \fB::tcl::mathop::<\fR ?\fIarg\fR ...? .br @@ -53,7 +53,7 @@ package require \fBTcl 8.5-\fR .br \fB::tcl::mathop::eq\fR ?\fIarg\fR ...? .br -\fB::tcl::mathop::ne\fR \fIarg arg\fR +\fB::tcl::mathop::ne\fI arg arg\fR .br .VS "8.7, TIP461" \fB::tcl::mathop::lt\fR ?\fIarg\fR ...? @@ -65,9 +65,9 @@ package require \fBTcl 8.5-\fR \fB::tcl::mathop::ge\fR ?\fIarg\fR ...? .VE "8.7, TIP461" .br -\fB::tcl::mathop::in\fR \fIarg list\fR +\fB::tcl::mathop::in\fI arg list\fR .br -\fB::tcl::mathop::ni\fR \fIarg list\fR +\fB::tcl::mathop::ni\fI arg list\fR .sp .BE .SH DESCRIPTION @@ -92,34 +92,39 @@ The following operator commands are supported: .SS "MATHEMATICAL OPERATORS" .PP The behaviors of the mathematical operator commands are as follows: +.\" COMMAND: ! .TP -\fB!\fR \fIboolean\fR +\fB!\fI boolean\fR . Returns the boolean negation of \fIboolean\fR, where \fIboolean\fR may be any numeric value or any other form of boolean value (i.e. it returns truth if the argument is falsity or zero, and falsity if the argument is truth or non-zero). +.\" COMMAND: + .TP \fB+\fR ?\fInumber\fR ...? . Returns the sum of arbitrarily many arguments. Each \fInumber\fR argument may be any numeric value. If no arguments are given, the result will be zero (the summation identity). +.\" COMMAND: - .TP -\fB\-\fR \fInumber\fR ?\fInumber\fR ...? +\fB\-\fI number\fR ?\fInumber\fR ...? . If only a single \fInumber\fR argument is given, returns the negation of that numeric value. Otherwise returns the number that results when all subsequent numeric values are subtracted from the first one. All \fInumber\fR arguments must be numeric values. At least one argument must be given. +.\" COMMAND: * .TP \fB*\fR ?\fInumber\fR ...? . Returns the product of arbitrarily many arguments. Each \fInumber\fR may be any numeric value. If no arguments are given, the result will be one (the multiplicative identity). +.\" COMMAND: / .TP -\fB/\fR \fInumber\fR ?\fInumber\fR ...? +\fB/\fI number\fR ?\fInumber\fR ...? . If only a single \fInumber\fR argument is given, returns the reciprocal of that numeric value (i.e. the value obtained by dividing 1.0 by that value). @@ -134,8 +139,9 @@ results will be as if the functions \fIfloor\fR and \fIint\fR are applied to them, in that order). If all values in the operation are integers, the result will be an integer. .RE +.\" COMMAND: % .TP -\fB%\fR \fInumber number\fR +\fB%\fI number number\fR . Returns the integral modulus (i.e., remainder) of the first argument with respect to the second. @@ -152,6 +158,7 @@ clarity): \fB==\fR [\fB*\fR [\fB/\fI x y\fR] \fIy\fR] [\fB\-\fI x\fR [\fB%\fI x y\fR]] .CE .RE +.\" COMMAND: ** .TP \fB**\fR ?\fInumber\fR ...? . @@ -171,6 +178,7 @@ arguments are integral values. .PP The behaviors of the comparison operator commands (most of which operate preferentially on numeric arguments) are as follows: +.\" COMMAND: == .TP \fB==\fR ?\fIarg\fR ...? . @@ -178,23 +186,27 @@ Returns whether each argument is equal to the arguments on each side of it in the sense of the \fBexpr\fR == operator (\fIi.e.\fR, numeric comparison if possible, exact string comparison otherwise). If fewer than two arguments are given, this operation always returns a true value. +.\" COMMAND: eq .TP \fBeq\fR ?\fIarg\fR ...? . Returns whether each argument is equal to the arguments on each side of it using exact string comparison. If fewer than two arguments are given, this operation always returns a true value. +.\" COMMAND: != .TP -\fB!=\fR \fIarg arg\fR +\fB!=\fI arg arg\fR . Returns whether the two arguments are not equal to each other, in the sense of the \fBexpr\fR != operator (\fIi.e.\fR, numeric comparison if possible, exact string comparison otherwise). +.\" COMMAND: ne .TP -\fBne\fR \fIarg arg\fR +\fBne\fI arg arg\fR . Returns whether the two arguments are not equal to each other using exact string comparison. +.\" COMMAND: < .TP \fB<\fR ?\fIarg\fR ...? . @@ -205,6 +217,7 @@ otherwise performed using UNICODE string comparison. If fewer than two arguments are present, this operation always returns a true value. When the arguments are numeric but should be compared as strings, the \fBlt\fR operator or the \fBstring compare\fR command should be used instead. +.\" COMMAND: <= .TP \fB<=\fR ?\fIarg\fR ...? . @@ -215,6 +228,7 @@ otherwise performed using UNICODE string comparison. If fewer than two arguments are present, this operation always returns a true value. When the arguments are numeric but should be compared as strings, the \fBle\fR operator or the \fBstring compare\fR command should be used instead. +.\" COMMAND: > .TP \fB>\fR ?\fIarg\fR ...? . @@ -225,6 +239,7 @@ otherwise performed using UNICODE string comparison. If fewer than two arguments are present, this operation always returns a true value. When the arguments are numeric but should be compared as strings, the \fBgt\fR operator or the \fBstring compare\fR command should be used instead. +.\" COMMAND: >= .TP \fB>=\fR ?\fIarg\fR ...? . @@ -235,6 +250,7 @@ otherwise performed using UNICODE string comparison. If fewer than two arguments are present, this operation always returns a true value. When the arguments are numeric but should be compared as strings, the \fBge\fR operator or the \fBstring compare\fR command should be used instead. +.\" COMMAND: lt .TP \fBlt\fR ?\fIarg\fR ...? .VS "8.7, TIP461" @@ -243,6 +259,7 @@ after the first having to be strictly more than the one preceding it. Comparisons are performed using UNICODE string comparison. If fewer than two arguments are present, this operation always returns a true value. .VE "8.7, TIP461" +.\" COMMAND: le .TP \fBle\fR ?\fIarg\fR ...? .VS "8.7, TIP461" @@ -251,6 +268,7 @@ after the first having to be equal to or strictly more than the one preceding it Comparisons are performed using UNICODE string comparison. If fewer than two arguments are present, this operation always returns a true value. .VE "8.7, TIP461" +.\" COMMAND: gt .TP \fBgt\fR ?\fIarg\fR ...? .VS "8.7, TIP461" @@ -259,6 +277,7 @@ after the first having to be strictly less than the one preceding it. Comparisons are performed using UNICODE string comparison. If fewer than two arguments are present, this operation always returns a true value. .VE "8.7, TIP461" +.\" COMMAND: ge .TP \fBge\fR ?\fIarg\fR ...? .VS "8.7, TIP461" @@ -271,38 +290,44 @@ arguments are present, this operation always returns a true value. .PP The behaviors of the bit-wise operator commands (all of which only operate on integral arguments) are as follows: +.\" COMMAND: ~ .TP -\fB~\fR \fInumber\fR +\fB~\fI number\fR . Returns the bit-wise negation of \fInumber\fR. \fINumber\fR may be an integer of any size. Note that the result of this operation will always have the opposite sign to the input \fInumber\fR. +.\" COMMAND: & .TP \fB&\fR ?\fInumber\fR ...? . Returns the bit-wise AND of each of the arbitrarily many arguments. Each \fInumber\fR must have an integral value. If no arguments are given, the result will be minus one. +.\" COMMAND: | .TP \fB|\fR ?\fInumber\fR ...? . Returns the bit-wise OR of each of the arbitrarily many arguments. Each \fInumber\fR must have an integral value. If no arguments are given, the result will be zero. +.\" COMMAND: ^ .TP \fB^\fR ?\fInumber\fR ...? . Returns the bit-wise XOR of each of the arbitrarily many arguments. Each \fInumber\fR must have an integral value. If no arguments are given, the result will be zero. +.\" COMMAND: << .TP -\fB<<\fR \fInumber number\fR +\fB<<\fI number number\fR . Returns the result of bit-wise shifting the first argument left by the number of bits specified in the second argument. Each \fInumber\fR must have an integral value. +.\" COMMAND: >> .TP -\fB>>\fR \fInumber number\fR +\fB>>\fI number number\fR . Returns the result of bit-wise shifting the first argument right by the number of bits specified in the second argument. Each \fInumber\fR @@ -310,13 +335,15 @@ must have an integral value. .SS "LIST OPERATORS" .PP The behaviors of the list-oriented operator commands are as follows: +.\" COMMAND: in .TP -\fBin\fR \fIarg list\fR +\fBin\fI arg list\fR . Returns whether the value \fIarg\fR is present in the list \fIlist\fR (according to exact string comparison of elements). +.\" COMMAND: ni .TP -\fBni\fR \fIarg list\fR +\fBni\fI arg list\fR . Returns whether the value \fIarg\fR is not present in the list \fIlist\fR (according to exact string comparison of elements). diff --git a/doc/memory.n b/doc/memory.n index 7a69221..8fe6a9b 100644 --- a/doc/memory.n +++ b/doc/memory.n @@ -18,18 +18,21 @@ debugging capabilities. The memory command has several suboptions, which are described below. It is only available when Tcl has been compiled with memory debugging enabled (when \fBTCL_MEM_DEBUG\fR is defined at compile time), and after \fBTcl_InitMemory\fR has been called. +.\" METHOD: active .TP -\fBmemory active\fR \fIfile\fR +\fBmemory active\fI file\fR . Write a list of all currently allocated memory to the specified \fIfile\fR. +.\" METHOD: break_on_malloc .TP -\fBmemory break_on_malloc\fR \fIcount\fR +\fBmemory break_on_malloc\fI count\fR . After the \fIcount\fR allocations have been performed, \fBTcl_Alloc\fR outputs a message to this effect and that it is now attempting to enter the C debugger. Tcl will then issue a \fISIGINT\fR signal against itself. If you are running Tcl under a C debugger, it should then enter the debugger command mode. +.\" METHOD: info .TP \fBmemory info\fR . @@ -38,26 +41,30 @@ Tcl began, the current packets allocated (the current number of calls to \fBTcl_Alloc\fR not met by a corresponding call to \fBTcl_Free\fR), the current bytes allocated, and the maximum number of packets and bytes allocated. +.\" METHOD: init .TP \fBmemory init \fR[\fBon\fR|\fBoff\fR] . Turn on or off the preinitialization of all allocated memory with bogus bytes. Useful for detecting the use of uninitialized values. +.\" METHOD: objs .TP \fBmemory objs \fIfile\fR . Causes a list of all allocated Tcl_Obj values to be written to the specified \fIfile\fR immediately, together with where they were allocated. Useful for checking for leaks of values. +.\" METHOD: onexit .TP -\fBmemory onexit\fR \fIfile\fR +\fBmemory onexit\fI file\fR . Causes a list of all allocated memory to be written to the specified \fIfile\fR during the finalization of Tcl's memory subsystem. Useful for checking that memory is properly cleaned up during process exit. +.\" METHOD: tag .TP -\fBmemory tag\fR \fIstring\fR +\fBmemory tag\fI string\fR . Each packet of memory allocated by \fBTcl_Alloc\fR can have associated with it a string-valued tag. In the lists of allocated memory generated @@ -65,6 +72,7 @@ by \fBmemory active\fR and \fBmemory onexit\fR, the tag for each packet is printed along with other information about the packet. The \fBmemory tag\fR command sets the tag value for subsequent calls to \fBTcl_Alloc\fR to be \fIstring\fR. +.\" METHOD: trace .TP \fBmemory trace \fR[\fBon\fR|\fBoff\fR] . @@ -81,8 +89,9 @@ Tcl_Alloc 40e478 98 tclProc.c 1406 .PP Calls to \fBTcl_Free\fR are traced in the same manner. .RE +.\" METHOD: trace_on_at_malloc .TP -\fBmemory trace_on_at_malloc\fR \fIcount\fR +\fBmemory trace_on_at_malloc\fI count\fR . Enable memory tracing after \fIcount\fR \fBTcl_Alloc\fRs have been performed. For example, if you enter \fBmemory trace_on_at_malloc 100\fR, @@ -93,6 +102,7 @@ can reduce the slowdown caused by tracing (and the amount of trace information produced), if you can identify a number of allocations that occur before the problem sets in. The current number of memory allocations that have occurred since Tcl started is printed on a guard zone failure. +.\" METHOD: validate .TP \fBmemory validate \fR[\fBon\fR|\fBoff\fR] . diff --git a/doc/msgcat.n b/doc/msgcat.n index c39dc87..58b5b0d 100644 --- a/doc/msgcat.n +++ b/doc/msgcat.n @@ -52,7 +52,7 @@ msgcat \- Tcl message catalog .VS "TIP 412" \fB::msgcat::mcpackagelocale subcommand\fR ?\fIlocale\fR? .sp -\fB::msgcat::mcpackageconfig subcommand\fR \fIoption\fR ?\fIvalue\fR? +\fB::msgcat::mcpackageconfig subcommand\fI option\fR ?\fIvalue\fR? .sp \fB::msgcat::mcforgetpackage\fR .VE "TIP 412" @@ -87,6 +87,7 @@ Object oriented programming is supported by the use of a package namespace. .VE tip490 .PP .SH COMMANDS +.\" COMMAND: mc .TP \fB::msgcat::mc \fIsrc-string\fR ?\fIarg arg ...\fR? . @@ -110,17 +111,18 @@ use the result. If an application is written for a single language in this fashion, then it is easy to add support for additional languages later simply by defining new message catalog entries. .RE -.VS "TIP 490" +.\" COMMAND: mcc .TP -\fB::msgcat::mcn \fInamespace\fR \fIsrc-string\fR ?\fIarg arg ...\fR? -. +\fB::msgcat::mcn \fInamespace src-string\fR ?\fIarg arg ...\fR? +.VS "TIP 490" Like \fB::msgcat::mc\fR, but with the message namespace specified as first argument. .PP .RS \fBmcn\fR may be used for cases where the package namespace is not the namespace of the caller. An example is shown within the description of the command \fB::msgcat::mcpackagenamespaceget\fR below. .RE -.PP +.VE +.\" COMMAND: mcmax .TP \fB::msgcat::mcmax ?\fIsrc-string src-string ...\fR? . @@ -128,10 +130,10 @@ Given several source strings, \fB::msgcat::mcmax\fR returns the length of the longest translated string. This is useful when designing localized GUIs, which may require that all buttons, for example, be a fixed width (which will be the width of the widest button). -.VS "TIP 412" +.\" COMMAND: mcexists .TP -\fB::msgcat::mcexists\fR ?\fB-exactnamespace\fR? ?\fB-exactlocale\fR? ?\fB-namespace\fR \fInamespace\fR? \fIsrc-string\fR -. +\fB::msgcat::mcexists\fR ?\fB-exactnamespace\fR? ?\fB-exactlocale\fR? ?\fB-namespace\fI namespace\fR? \fIsrc-string\fR +.VS "TIP 412" Return true, if there is a translation for the given \fIsrc-string\fR. .PP .RS @@ -146,10 +148,10 @@ The namespace of the caller is used if not explicitly specified. .RE .PP .VE "TIP 490" -.VS "TIP 490" +.\" COMMAND: mcpackagenamespaceget .TP \fB::msgcat::mcpackagenamespaceget\fR -. +.VS "TIP 490" Return the package namespace of the caller. This command handles all cases described in section \fBOBJECT ORIENTED PROGRAMMING\fR. .PP @@ -172,6 +174,7 @@ proc ::tooltip::show {widget messagenamespace message} { .RE .PP .VE "TIP 490" +.\" COMMAND: mclocale .TP \fB::msgcat::mclocale \fR?\fInewLocale\fR? . @@ -182,7 +185,7 @@ is set to \fInewLocale\fR. If the new locale is set to \fInewLocale\fR, the corresponding preferences are calculated and set. For example, if the current locale is en_US_funky, then \fB::msgcat::mcpreferences\fR returns \fB{en_us_funky en_us en {}}\fR. .PP -The same result may be acheved by \fB::msgcat::mcpreferences\fR {*}[\fB::msgcat::mcutil getpreferences\fR \fInewLocale\fR]. +The same result may be acheved by \fB::msgcat::mcpreferences\fR {*}[\fB::msgcat::mcutil getpreferences\fI newLocale\fR]. .PP The current locale is always the first element of the list returned by \fBmcpreferences\fR. .PP @@ -197,6 +200,7 @@ If the locale is set, the preference list of locales is evaluated. Locales in this list are loaded now, if not jet loaded. .VE "TIP 412" .RE +.\" COMMAND: mcpreferences .TP \fB::msgcat::mcpreferences\fR ?\fIlocale preference\fR? ... . @@ -217,10 +221,10 @@ As an example, the user may prefer French or English text. This may be configure .CE .RE .PP -.VS "TIP 499" +.\" COMMAND: mcloadedlocales .TP \fB::msgcat::mcloadedlocales subcommand\fR ?\fIlocale\fR? -. +.VS "TIP 499" This group of commands manage the list of loaded locales for packages not setting a package locale. .PP .RS @@ -228,9 +232,10 @@ The subcommand \fBloaded\fR returns the list of currently loaded locales. .PP The subcommand \fBclear\fR removes all locales and their data, which are not in the current preference list. .RE +.VE +.\" COMMAND: mcload .TP \fB::msgcat::mcload \fIdirname\fR -. .VS "TIP 412" Searches the specified directory for files that match the language specifications returned by \fB::msgcat::mcloadedlocales loaded\fR @@ -245,9 +250,12 @@ evaluation. The number of message files which matched the specification and were loaded is returned. .RS .PP -In addition, the given folder is stored in the \fBmsgcat\fR package configuration option \fImcfolder\fR to eventually load message catalog files required by a locale change. +In addition, the given folder is stored in the \fBmsgcat\fR package +configuration option \fImcfolder\fR to eventually load message catalog +files required by a locale change. .VE "TIP 412" .RE +.\" COMMAND: mcset .TP \fB::msgcat::mcset \fIlocale src-string \fR?\fItranslate-string\fR? . @@ -255,6 +263,7 @@ Sets the translation for \fIsrc-string\fR to \fItranslate-string\fR in the specified \fIlocale\fR and the current namespace. If \fItranslate-string\fR is not specified, \fIsrc-string\fR is used for both. The function returns \fItranslate-string\fR. +.\" COMMAND: mcmset .TP \fB::msgcat::mcmset \fIlocale src-trans-list\fR . @@ -266,15 +275,19 @@ the form {\fIsrc-string translate-string\fR ?\fIsrc-string translate-string ...\fR?} \fB::msgcat::mcmset\fR can be significantly faster than multiple invocations of \fB::msgcat::mcset\fR. The function returns the number of translations set. +.\" COMMAND: mcflset .TP \fB::msgcat::mcflset \fIsrc-string \fR?\fItranslate-string\fR? +. Sets the translation for \fIsrc-string\fR to \fItranslate-string\fR in the current namespace for the locale implied by the name of the message catalog being loaded via \fB::msgcat::mcload\fR. If \fItranslate-string\fR is not specified, \fIsrc-string\fR is used for both. The function returns \fItranslate-string\fR. +.\" COMMAND: mcflmset .TP \fB::msgcat::mcflmset \fIsrc-trans-list\fR +. Sets the translation for multiple source strings in \fIsrc-trans-list\fR in the current namespace for the locale implied by the name of the message catalog being loaded via \fB::msgcat::mcload\fR. \fIsrc-trans-list\fR must @@ -282,6 +295,7 @@ have an even number of elements and is in the form {\fIsrc-string translate-string\fR ?\fIsrc-string translate-string ...\fR?} \fB::msgcat::mcflmset\fR can be significantly faster than multiple invocations of \fB::msgcat::mcflset\fR. The function returns the number of translations set. +.\" COMMAND: mcunknown .TP \fB::msgcat::mcunknown \fIlocale src-string\fR ?\fIarg arg ...\fR? . @@ -300,15 +314,17 @@ to \fB::msgcat::mc\fR. .PP Note that this routine is only called if the concerned package did not set a package locale unknown command name. .RE +.\" COMMAND: mcforgetpackage .TP \fB::msgcat::mcforgetpackage\fR . The calling package clears all its state within the \fBmsgcat\fR package including all settings and translations. .VE "TIP 412" .PP +.\" COMMAND: mcutil .VS "TIP 499" .TP -\fB::msgcat::mcutil getpreferences\fR \fIlocale\fR +\fB::msgcat::mcutil getpreferences\fI locale\fR . Return the preferences list of the given locale as described in section \fBLOCALE SPECIFICATION\fR. An example is the composition of a preference list for the bilingual region "Biel/Bienne" as a concatenation of swiss german and swiss french: @@ -582,7 +598,7 @@ Unset the package private locale and use the globale locale. Load and remove locales to adjust the list of loaded locales for the package to the global loaded locales list. .TP -\fB::msgcat::mcpackagelocale present\fR \fIlocale\fR +\fB::msgcat::mcpackagelocale present\fI locale\fR . Returns true, if the given locale is loaded for the package. .TP @@ -596,22 +612,22 @@ Each package using msgcat has a set of options within \fBmsgcat\fR. The package options are described in the next sectionPackage options. Each package option may be set or unset individually using the following ensemble: .TP -\fB::msgcat::mcpackageconfig get\fR \fIoption\fR +\fB::msgcat::mcpackageconfig get\fI option\fR . Return the current value of the given \fIoption\fR. This call returns an error if the option is not set for the package. .TP -\fB::msgcat::mcpackageconfig isset\fR \fIoption\fR +\fB::msgcat::mcpackageconfig isset\fI option\fR . Returns 1, if the given \fIoption\fR is set for the package, 0 otherwise. .TP -\fB::msgcat::mcpackageconfig set\fR \fIoption\fR \fIvalue\fR +\fB::msgcat::mcpackageconfig set\fI option value\fR . Set the given \fIoption\fR to the given \fIvalue\fR. This may invoke additional actions in dependency of the \fIoption\fR. The return value is 0 or the number of loaded packages for the option \fBmcfolder\fR. .TP -\fB::msgcat::mcpackageconfig unset\fR \fIoption\fR +\fB::msgcat::mcpackageconfig unset\fI option\fR . Unsets the given \fIoption\fR for the package. No action is taken if the \fIoption\fR is not set for the package. diff --git a/doc/namespace.n b/doc/namespace.n index 4be0a3a..5e90d13 100644 --- a/doc/namespace.n +++ b/doc/namespace.n @@ -24,6 +24,7 @@ See the section \fBWHAT IS A NAMESPACE?\fR below for a brief overview of namespaces. The legal values of \fIsubcommand\fR are listed below. Note that you can abbreviate the \fIsubcommand\fRs. +.\" METHOD: children .TP \fBnamespace children \fR?\fInamespace\fR? ?\fIpattern\fR? . @@ -40,6 +41,7 @@ a pattern that starts with double colon (\fB::\fR) is used directly, otherwise the namespace \fInamespace\fR (or the fully-qualified name of the current namespace) is prepended onto the pattern. +.\" METHOD: code .TP \fBnamespace code \fIscript\fR . @@ -68,6 +70,7 @@ A scoped command captures a command together with its namespace context in a way that allows it to be executed properly later. See the section \fBSCOPED SCRIPTS\fR for some examples of how this is used to create callback scripts. +.\" METHOD: current .TP \fBnamespace current\fR . @@ -77,6 +80,7 @@ The actual name of the global namespace is (i.e., an empty string), but this command returns \fB::\fR for the global namespace as a convenience to programmers. +.\" METHOD: delete .TP \fBnamespace delete \fR?\fInamespace namespace ...\fR? . @@ -89,14 +93,16 @@ however, the namespace is marked to prevent other code from looking it up by name. If a namespace does not exist, this command returns an error. If no namespace names are given, this command does nothing. +.\" METHOD: ensemble .TP -\fBnamespace ensemble\fR \fIsubcommand\fR ?\fIarg ...\fR? +\fBnamespace ensemble \fIsubcommand\fR ?\fIarg ...\fR? . Creates and manipulates a command that is formed out of an ensemble of subcommands. See the section \fBENSEMBLES\fR below for further details. +.\" METHOD: eval .TP -\fBnamespace eval\fR \fInamespace arg\fR ?\fIarg ...\fR? +\fBnamespace eval \fInamespace arg\fR ?\fIarg ...\fR? . Activates a namespace called \fInamespace\fR and evaluates some code in that context. @@ -111,11 +117,13 @@ If \fInamespace\fR has leading namespace qualifiers and any leading namespaces do not exist, they are automatically created. .RE +.\" METHOD: exists .TP -\fBnamespace exists\fR \fInamespace\fR +\fBnamespace exists \fInamespace\fR . Returns \fB1\fR if \fInamespace\fR is a valid namespace in the current context, returns \fB0\fR otherwise. +.\" METHOD: export .TP \fBnamespace export \fR?\fB\-clear\fR? ?\fIpattern pattern ...\fR? . @@ -137,6 +145,7 @@ the namespace's export pattern list is reset to empty before any \fIpattern\fR arguments are appended. If no \fIpattern\fRs are given and the \fB\-clear\fR flag is not given, this command returns the namespace's current export list. +.\" METHOD: forget .TP \fBnamespace forget \fR?\fIpattern pattern ...\fR? . @@ -162,8 +171,9 @@ It then checks whether any of those commands were previously imported by the current namespace. If so, this command deletes the corresponding imported commands. In effect, this undoes the action of a \fBnamespace import\fR command. +.\" METHOD: import .TP -\fBnamespace import \fR?\fB\-force\fR? ?\fIpattern\fR \fIpattern ...\fR? +\fBnamespace import \fR?\fB\-force\fR? ?\fIpattern pattern ...\fR? . Imports commands into a namespace, or queries the set of imported commands in a namespace. When no arguments are present, @@ -205,8 +215,9 @@ at the time when the \fBnamespace import\fR command is executed. If another command is defined and exported in this namespace later on, it will not be imported. .RE +.\" METHOD: inscope .TP -\fBnamespace inscope\fR \fInamespace\fR \fIscript\fR ?\fIarg ...\fR? +\fBnamespace inscope \fInamespace script\fR ?\fIarg ...\fR? . Executes a script in the context of the specified \fInamespace\fR. This command is not expected to be used directly by programmers; @@ -232,6 +243,7 @@ is equivalent to thus additional arguments will not undergo a second round of substitution, as is the case with \fBnamespace eval\fR. .RE +.\" METHOD: origin .TP \fBnamespace origin \fIcommand\fR . @@ -247,6 +259,7 @@ this command returns the fully-qualified name of the original command in the first namespace, \fIa\fR. If \fIcommand\fR does not refer to an imported command, the command's own fully-qualified name is returned. +.\" METHOD: parent .TP \fBnamespace parent\fR ?\fInamespace\fR? . @@ -254,6 +267,7 @@ Returns the fully-qualified name of the parent namespace for namespace \fInamespace\fR. If \fInamespace\fR is not specified, the fully-qualified name of the current namespace's parent is returned. +.\" METHOD: path .TP \fBnamespace path\fR ?\fInamespaceList\fR? . @@ -263,8 +277,9 @@ current namespace's command resolution path is set to those namespaces and returns the empty list. The default command resolution path is always empty. See the section \fBNAME RESOLUTION\fR below for an explanation of the rules regarding name resolution. +.\" METHOD: qualifiers .TP -\fBnamespace qualifiers\fR \fIstring\fR +\fBnamespace qualifiers\fI string\fR . Returns any leading namespace qualifiers for \fIstring\fR. Qualifiers are namespace names separated by double colons (\fB::\fR). @@ -275,8 +290,9 @@ This command is the complement of the \fBnamespace tail\fR command. Note that it does not check whether the namespace names are, in fact, the names of currently defined namespaces. +.\" METHOD: tail .TP -\fBnamespace tail\fR \fIstring\fR +\fBnamespace tail\fI string\fR . Returns the simple name at the end of a qualified string. Qualifiers are namespace names separated by double colons (\fB::\fR). @@ -286,8 +302,9 @@ and for \fB::\fR it returns an empty string. This command is the complement of the \fBnamespace qualifiers\fR command. It does not check whether the namespace names are, in fact, the names of currently defined namespaces. +.\" METHOD: upvar .TP -\fBnamespace upvar\fR \fInamespace\fR ?\fIotherVar myVar \fR...? +\fBnamespace upvar\fI namespace\fR ?\fIotherVar myVar \fR...? . This command arranges for zero or more local variables in the current procedure to refer to variables in \fInamespace\fR. The namespace name is @@ -297,6 +314,7 @@ The command \fBupvar 0 ${ns}::a b\fR, with the sole exception of the resolution rules used for qualified namespace or variable names. \fBnamespace upvar\fR returns an empty string. +.\" METHOD: unknown .TP \fBnamespace unknown\fR ?\fIscript\fR? . @@ -310,6 +328,7 @@ the handler is invoked, the full invocation line will be appended to the script and the result evaluated in the context of the namespace. The default handler for all namespaces is \fB::unknown\fR. If no argument is given, it returns the handler for the current namespace. +.\" METHOD: which .TP \fBnamespace which\fR ?\fB\-command\fR? ?\fB\-variable\fR? \fIname\fR . @@ -730,6 +749,7 @@ namespace is deleted. The link between an ensemble command and its namespace is maintained however the ensemble is renamed. .PP Three subcommands of the \fBnamespace ensemble\fR command are defined: +.\" METHOD: create .TP \fBnamespace ensemble create\fR ?\fIoption value ...\fR? . @@ -741,6 +761,7 @@ command. If not overridden with the \fB\-command\fR option, this command creates an ensemble with exactly the same name as the linked namespace. See the section \fBENSEMBLE OPTIONS\fR below for a full list of options supported and their effects. +.\" METHOD: configure .TP \fBnamespace ensemble configure \fIcommand\fR ?\fIoption\fR? ?\fIvalue ...\fR? . @@ -748,8 +769,9 @@ Retrieves the value of an option associated with the ensemble command named \fIcommand\fR, or updates some options associated with that ensemble command. See the section \fBENSEMBLE OPTIONS\fR below for a full list of options supported and their effects. +.\" METHOD: exists .TP -\fBnamespace ensemble exists\fR \fIcommand\fR +\fBnamespace ensemble exists\fI command\fR . Returns a boolean value that describes whether the command \fIcommand\fR exists and is an ensemble command. This command only diff --git a/doc/object.n b/doc/object.n index 98679d1..2bed231 100644 --- a/doc/object.n +++ b/doc/object.n @@ -48,6 +48,7 @@ The \fBoo::object\fR class does not define an explicit constructor. The \fBoo::object\fR class does not define an explicit destructor. .SS "EXPORTED METHODS" The \fBoo::object\fR class supports the following exported methods: +.\" METHOD: destroy .TP \fIobj \fBdestroy\fR . @@ -58,12 +59,14 @@ always the empty string. .SS "NON-EXPORTED METHODS" .PP The \fBoo::object\fR class supports the following non-exported methods: +.\" METHOD: eval .TP \fIobj \fBeval\fR ?\fIarg ...\fR? . This method concatenates the arguments, \fIarg\fR, as if with \fBconcat\fR, and then evaluates the resulting script in the namespace that is uniquely associated with \fIobj\fR, returning the result of the evaluation. +.\" METHOD: unknown .TP \fIobj \fBunknown ?\fImethodName\fR? ?\fIarg ...\fR? . @@ -78,6 +81,7 @@ The default implementation (i.e., the one defined by the \fBoo::object\fR class) generates a suitable error, detailing what methods the object supports given whether the object was invoked by its public name or through the \fBmy\fR command. +.\" METHOD: variable .TP \fIobj \fBvariable \fR?\fIvarName ...\fR? . @@ -86,11 +90,13 @@ the object \fIobj\fR's unique namespace into the caller's context. Thus, if it is invoked from inside a procedure then the namespace variable in the object is linked to the local variable in the procedure. Each \fIvarName\fR argument must not have any namespace separators in it. The result is the empty string. +.\" METHOD: varname .TP \fIobj \fBvarname \fIvarName\fR . This method returns the globally qualified name of the variable \fIvarName\fR in the unique namespace for the object \fIobj\fR. +.\" METHOD: <cloned> .TP \fIobj \fB<cloned> \fIsourceObjectName\fR .VS @@ -192,7 +192,7 @@ The \fBchan configure\fR and \fBfconfigure\fR commands can be used to query and set additional configuration options specific to serial ports (where supported): .TP -\fB\-mode\fR \fIbaud\fB,\fIparity\fB,\fIdata\fB,\fIstop\fR +\fB\-mode\fI baud\fB,\fIparity\fB,\fIdata\fB,\fIstop\fR . This option is a set of 4 comma-separated values: the baud rate, parity, number of data bits, and number of stop bits for this serial port. The @@ -209,7 +209,7 @@ or data bits and should be an integer from 5 to 8, while \fIstop\fR is the number of stop bits and should be the integer 1 or 2. .TP -\fB\-handshake\fR \fItype\fR +\fB\-handshake\fI type\fR . (Windows and Unix). This option is used to setup automatic handshake control. Note that not all handshake types maybe supported by your operating @@ -233,7 +233,7 @@ The \fB\-handshake\fR option cannot be queried. It returns a list of two integers representing the current number of bytes in the input and output queue respectively. .TP -\fB\-timeout\fR \fImsec\fR +\fB\-timeout\fI msec\fR . (Windows and Unix). This option is used to set the timeout for blocking read operations. It specifies the maximum interval between the @@ -243,7 +243,7 @@ The \fB\-timeout\fR option does not affect write operations or nonblocking reads. This option cannot be queried. .TP -\fB\-ttycontrol\fR \fI{signal boolean signal boolean ...}\fR +\fB\-ttycontrol\fI {signal boolean signal boolean ...}\fR . (Windows and Unix). This option is used to setup the handshake output lines (see below) permanently or to send a BREAK over the serial line. @@ -265,14 +265,14 @@ The result is a list of signal,value pairs with a fixed order, e.g. \fB{CTS 1 DSR 0 RING 1 DCD 0}\fR. The \fIsignal\fR names are returned upper case. .TP -\fB\-xchar\fR \fI{xonChar xoffChar}\fR +\fB\-xchar\fI {xonChar xoffChar}\fR . (Windows and Unix). This option is used to query or change the software handshake characters. Normally the operating system default should be DC1 (0x11) and DC3 (0x13) representing the ASCII standard XON and XOFF characters. .TP -\fB\-closemode\fR \fIcloseMode\fR +\fB\-closemode\fI closeMode\fR .VS "8.7, TIP 160" (Windows and Unix). This option is used to query or change the close mode of the serial channel, which defines how pending output in operating system @@ -298,7 +298,7 @@ been consumed. This may slow down \fBclose\fR noticeably. .RE .VE "8.7, TIP 160" .TP -\fB\-inputmode\fR \fIinputMode\fR +\fB\-inputmode\fI inputMode\fR .VS "8.7, TIP 160" (Unix only; Windows has the equivalent option on console channels). This option is used to query or change the input mode of the serial channel under @@ -341,7 +341,7 @@ option is query only. It retrieves a two-element list with the the current width and height of the terminal. .VE "8.7, TIP 160" .TP -\fB\-pollinterval\fR \fImsec\fR +\fB\-pollinterval\fI msec\fR . (Windows only). This option is used to set the maximum time between polling for fileevents. @@ -350,9 +350,9 @@ interpreter (the smallest value always wins). Use this option only if you want to poll the serial port more or less often than 10 msec (the default). .TP -\fB\-sysbuffer\fR \fIinSize\fR +\fB\-sysbuffer\fI inSize\fR .TP -\fB\-sysbuffer\fR \fI{inSize outSize}\fR +\fB\-sysbuffer\fI {inSize outSize}\fR . (Windows only). This option is used to change the size of Windows system buffers for a serial channel. Especially at higher communication @@ -511,7 +511,7 @@ applications on the various platforms On Windows only, console channels (usually \fBstdin\fR or \fBstdout\fR) support the following options: .TP -\fB\-inputmode\fR \fIinputMode\fR +\fB\-inputmode\fI inputMode\fR . This option is used to query or change the input mode of the console channel, which controls how interactive input from users is handled. The following diff --git a/doc/package.n b/doc/package.n index 5687480..dc21093 100644 --- a/doc/package.n +++ b/doc/package.n @@ -12,7 +12,7 @@ package \- Facilities for package loading and version control .SH SYNOPSIS .nf -\fBpackage files\fR \fIpackage\fR +\fBpackage files\fI package\fR \fBpackage forget\fR ?\fIpackage package ...\fR? \fBpackage ifneeded \fIpackage version\fR ?\fIscript\fR? \fBpackage names\fR @@ -43,19 +43,22 @@ primarily by system scripts that maintain the package database. .PP The behavior of the \fBpackage\fR command is determined by its first argument. The following forms are permitted: +.\" METHOD: files .TP -\fBpackage files\fR \fIpackage\fR +\fBpackage files \fIpackage\fR . Lists all files forming part of \fIpackage\fR. Auto-loaded files are not included in this list, only files which were directly sourced during package initialization. The list order corresponds with the order in which the files were sourced. +.\" METHOD: forget .TP \fBpackage forget\fR ?\fIpackage package ...\fR? . Removes all information about each specified package from this interpreter, including information provided by both \fBpackage ifneeded\fR and \fBpackage provide\fR. +.\" METHOD: ifneeded .TP \fBpackage ifneeded \fIpackage version\fR ?\fIscript\fR? . @@ -78,6 +81,7 @@ If the \fIscript\fR argument is omitted, the current script for version \fIversion\fR of package \fIpackage\fR is returned, or an empty string if no \fBpackage ifneeded\fR command has been invoked for this \fIpackage\fR and \fIversion\fR. +.\" METHOD: names .TP \fBpackage names\fR . @@ -86,11 +90,13 @@ interpreter for which a version has been provided (via \fBpackage provide\fR) or for which a \fBpackage ifneeded\fR script is available. The order of elements in the list is arbitrary. +.\" METHOD: present .TP \fBpackage present\fR ?\fB\-exact\fR? \fIpackage\fR ?\fIrequirement...\fR? . This command is equivalent to \fBpackage require\fR except that it does not try and load the package if it is not already loaded. +.\" METHOD: provide .TP \fBpackage provide \fIpackage \fR?\fIversion\fR? . @@ -104,6 +110,7 @@ If the \fIversion\fR argument is omitted, then the command returns the version number that is currently provided, or an empty string if no \fBpackage provide\fR command has been invoked for \fIpackage\fR in this interpreter. +.\" METHOD: require .TP \fBpackage require \fR\fIpackage \fR?\fIrequirement...\fR? . @@ -156,6 +163,7 @@ package, then the command returns an error. This form of the command is used when only the given \fIversion\fR of \fIpackage\fR is acceptable to the caller. This command is equivalent to \fBpackage require \fIpackage version\fR-\fIversion\fR. +.\" METHOD: unknown .TP \fBpackage unknown \fR?\fIcommand\fR? . @@ -178,18 +186,21 @@ argument, then the current \fBpackage unknown\fR script is returned, or an empty string if there is none. If \fIcommand\fR is specified as an empty string, then the current \fBpackage unknown\fR script is removed, if there is one. +.\" METHOD: vcompare .TP \fBpackage vcompare \fIversion1 version2\fR . Compares the two version numbers given by \fIversion1\fR and \fIversion2\fR. Returns -1 if \fIversion1\fR is an earlier version than \fIversion2\fR, 0 if they are equal, and 1 if \fIversion1\fR is later than \fIversion2\fR. +.\" METHOD: versions .TP \fBpackage versions \fIpackage\fR . Returns a list of all the version numbers of \fIpackage\fR for which information has been provided by \fBpackage ifneeded\fR commands. +.\" METHOD: vsatisfies .TP \fBpackage vsatisfies \fIversion requirement...\fR . @@ -260,8 +271,10 @@ requirement if, and only if it is greater than or equal to the .QW a0 . There is no constraint to a maximum. .RE +.\" METHOD: prefer .TP \fBpackage prefer \fR?\fBlatest\fR|\fBstable\fR? +. With no arguments, the commands returns either .QW latest or diff --git a/doc/platform.n b/doc/platform.n index 7cb685d..8ac07d2 100644 --- a/doc/platform.n +++ b/doc/platform.n @@ -43,6 +43,7 @@ establishes a standard naming convention for architectures running Tcl and makes it more convenient for developers to identify the current architecture a Tcl program is running on. .SH COMMANDS +.\" METHOD: identify .TP \fBplatform::identify\fR . @@ -52,6 +53,7 @@ core is running on. The returned identifier has the general format details like kernel version, libc version, etc., and this information may contain dashes as well. The \fICPU\fR part will not contain dashes, making the preceding dash the last dash in the result. +.\" METHOD: generic .TP \fBplatform::generic\fR . @@ -59,6 +61,7 @@ This command returns a simplified identifier describing the platform the Tcl core is running on. In contrast to \fBplatform::identify\fR it leaves out details like kernel version, libc version, etc. The returned identifier has the general format \fIOS\fR-\fICPU\fR. +.\" METHOD: patterns .TP \fBplatform::patterns \fIidentifier\fR . diff --git a/doc/platform_shell.n b/doc/platform_shell.n index a9e14d0..54a1edb 100644 --- a/doc/platform_shell.n +++ b/doc/platform_shell.n @@ -41,16 +41,22 @@ the architecture of the shell which will actually run the installed packages, versus the architecture of the shell running the repository software. .SH COMMANDS +.\" METHOD: identify .TP \fBplatform::shell::identify \fIshell\fR +. This command does the same identification as \fBplatform::identify\fR, for the specified Tcl shell, in contrast to the running shell. +.\" METHOD: generic .TP \fBplatform::shell::generic \fIshell\fR +. This command does the same identification as \fBplatform::generic\fR, for the specified Tcl shell, in contrast to the running shell. +.\" METHOD: platform .TP \fBplatform::shell::platform \fIshell\fR +. This command returns the contents of \fBtcl_platform(platform)\fR for the specified Tcl shell. .SH KEYWORDS diff --git a/doc/prefix.n b/doc/prefix.n index d327a78..abd337a 100644 --- a/doc/prefix.n +++ b/doc/prefix.n @@ -12,8 +12,8 @@ tcl::prefix \- facilities for prefix matching .SH SYNOPSIS .nf -\fB::tcl::prefix all\fR \fItable string\fR -\fB::tcl::prefix longest\fR \fItable string\fR +\fB::tcl::prefix all\fI table string\fR +\fB::tcl::prefix longest\fI table string\fR \fB::tcl::prefix match\fR ?\fIoption ...\fR? \fItable string\fR .fi .BE @@ -21,16 +21,19 @@ tcl::prefix \- facilities for prefix matching .PP This document describes commands looking up a prefix in a list of strings. The following commands are supported: +.\" METHOD: all .TP -\fB::tcl::prefix all\fR \fItable string\fR +\fB::tcl::prefix all\fI table string\fR . Returns a list of all elements in \fItable\fR that begin with the prefix \fIstring\fR. +.\" METHOD: longest .TP -\fB::tcl::prefix longest\fR \fItable string\fR +\fB::tcl::prefix longest\fI table string\fR . Returns the longest common prefix of all elements in \fItable\fR that begin with the prefix \fIstring\fR. +.\" METHOD: match .TP \fB::tcl::prefix match\fR ?\fIoptions\fR? \fItable string\fR . diff --git a/doc/process.n b/doc/process.n index 165e413..f69811e 100644 --- a/doc/process.n +++ b/doc/process.n @@ -18,6 +18,7 @@ tcl::process \- Subprocess management This command provides a way to manage subprocesses created by the \fBopen\fR and \fBexec\fR commands, as identified by the process identifiers (PIDs) of those subprocesses. The legal \fIoptions\fR (which may be abbreviated) are: +.\" METHOD: autopurge .TP \fB::tcl::process autopurge\fR ?\fIflag\fR? . @@ -28,12 +29,14 @@ status as a boolean value. When autopurge is active, executed or a pipe channel created by \fBopen\fR is closed. When autopurge is inactive, \fB::tcl::process\fR purge must be called explicitly. By default autopurge is active. +.\" METHOD: list .TP \fB::tcl::process list\fR . Returns the list of subprocess PIDs. This includes all currently executing subprocesses and all terminated subprocesses that have not yet had their corresponding process table entries purged. +.\" METHOD: purge .TP \fB::tcl::process purge\fR ?\fIpids\fR? . @@ -41,6 +44,7 @@ Cleans up all data associated with terminated subprocesses. If \fIpids\fR is specified as a list of PIDs then the command only cleanup data for the matching subprocesses if they exist, and raises an error otherwise. If a process listed is still active, this command does nothing to that process. +.\" METHOD: status .TP \fB::tcl::process status\fR ?\fIswitches\fR? ?\fIpids\fR? . diff --git a/doc/refchan.n b/doc/refchan.n index 94823c5..2b79da2 100644 --- a/doc/refchan.n +++ b/doc/refchan.n @@ -14,16 +14,16 @@ refchan \- command handler API of reflected channels .nf \fBchan create \fImode cmdPrefix\fR -\fIcmdPrefix \fBblocking\fR \fIchannelId mode\fR -\fIcmdPrefix \fBcget\fR \fIchannelId option\fR -\fIcmdPrefix \fBcgetall\fR \fIchannelId\fR -\fIcmdPrefix \fBconfigure\fR \fIchannelId option value\fR -\fIcmdPrefix \fBfinalize\fR \fIchannelId\fR -\fIcmdPrefix \fBinitialize\fR \fIchannelId mode\fR -\fIcmdPrefix \fBread\fR \fIchannelId count\fR -\fIcmdPrefix \fBseek\fR \fIchannelId offset base\fR -\fIcmdPrefix \fBwatch\fR \fIchannelId eventspec\fR -\fIcmdPrefix \fBwrite\fR \fIchannelId data\fR +\fIcmdPrefix \fBblocking\fI channelId mode\fR +\fIcmdPrefix \fBcget\fI channelId option\fR +\fIcmdPrefix \fBcgetall\fI channelId\fR +\fIcmdPrefix \fBconfigure\fI channelId option value\fR +\fIcmdPrefix \fBfinalize\fI channelId\fR +\fIcmdPrefix \fBinitialize\fI channelId mode\fR +\fIcmdPrefix \fBread\fI channelId count\fR +\fIcmdPrefix \fBseek\fI channelId offset base\fR +\fIcmdPrefix \fBwatch\fI channelId eventspec\fR +\fIcmdPrefix \fBwrite\fI channelId data\fR .fi .BE .SH DESCRIPTION @@ -42,6 +42,7 @@ Of all the possible subcommands, the handler \fImust\fR support \fBinitialize\fR, \fBfinalize\fR, and \fBwatch\fR. Support for the other subcommands is optional. .SS "MANDATORY SUBCOMMANDS" +.\" METHOD: initialize .TP \fIcmdPrefix \fBinitialize \fIchannelId mode\fR . @@ -72,6 +73,7 @@ will usually contain at least one element. The subcommand must throw an error if the chosen mode is not supported by the \fIcmdPrefix\fR. .RE +.\" METHOD: finalize .TP \fIcmdPrefix \fBfinalize \fIchannelId\fR . @@ -94,6 +96,7 @@ treated as (and converted to) an error. This subcommand is not invoked if the creation of the channel was aborted during \fBinitialize\fR (See above). .RE +.\" METHOD: watch .TP \fIcmdPrefix \fBwatch \fIchannelId eventspec\fR . @@ -114,6 +117,7 @@ event which was not listed in the last call to \fBwatch\fR will cause \fBchan postevent\fR to throw an error. .RE .SS "OPTIONAL SUBCOMMANDS" +.\" METHOD: read .TP \fIcmdPrefix \fBread \fIchannelId count\fR . @@ -170,6 +174,7 @@ invocation (usually \fBgets\fR, or \fBread\fR) will appear to have thrown this error. Any exception beyond \fBerror\fR, (e.g.,\ \fBbreak\fR, etc.) is treated as and converted to an error. .RE +.\" METHOD: write .TP \fIcmdPrefix \fBwrite \fIchannelId data\fR . @@ -227,6 +232,7 @@ invocation (usually \fBputs\fR) will appear to have thrown this error. Any exception beyond \fBerror\fR (e.g.,\ \fBbreak\fR, etc.) is treated as and converted to an error. .RE +.\" METHOD: seek .TP \fIcmdPrefix \fBseek \fIchannelId offset base\fR . @@ -269,6 +275,7 @@ The offset/base combination of 0/\fBcurrent\fR signals a \fBchan tell\fR request, i.e.,\ seek nothing relative to the current location, making the new location identical to the current one, which is then returned. .RE +.\" METHOD: configure .TP \fIcmdPrefix \fBconfigure \fIchannelId option value\fR . @@ -288,6 +295,7 @@ If the subcommand throws an error the command which performed the beyond \fBerror\fR (e.g.,\ \fBbreak\fR, etc.) is treated as and converted to an error. .RE +.\" METHOD: cget .TP \fIcmdPrefix \fBcget \fIchannelId option\fR . @@ -303,6 +311,7 @@ If the subcommand throws an error, the command which performed the will appear to have thrown this error. Any exception beyond \fIerror\fR (e.g.,\ \fBbreak\fR, etc.) is treated as and converted to an error. .RE +.\" METHOD: cgetall .TP \fIcmdPrefix \fBcgetall \fIchannelId\fR . @@ -319,6 +328,7 @@ If the subcommand throws an error the command which performed the will appear to have thrown this error. Any exception beyond \fBerror\fR (e.g.,\ \fBbreak\fR, etc.) is treated as and converted to an error. .RE +.\" METHOD: blocking .TP \fIcmdPrefix \fBblocking \fIchannelId mode\fR . @@ -335,8 +345,9 @@ invocation (usually \fBfconfigure\fR or \fBchan configure\fR) will appear to have thrown this error. Any exception beyond \fBerror\fR (e.g.,\ \fBbreak\fR, etc.) is treated as and converted to an error. .RE +.\" METHOD: truncate .TP -\fIcmdPrefix \fBtruncate\fR \fIchannelId length\fR +\fIcmdPrefix \fBtruncate\fI channelId length\fR . This \fIoptional\fR subcommand handles changing the length of the underlying data stream for the channel \fIchannelId\fR. Its length diff --git a/doc/regexp.n b/doc/regexp.n index 6f303a4..f39f389 100644 --- a/doc/regexp.n +++ b/doc/regexp.n @@ -130,7 +130,7 @@ regular expression. Examples are: .CE .RE .TP 15 -\fB\-start\fR \fIindex\fR +\fB\-start\fI index\fR . Specifies a character index offset into the string to start matching the regular expression at. diff --git a/doc/registry.n b/doc/registry.n index 66b2dd9..a58dd87 100644 --- a/doc/registry.n +++ b/doc/registry.n @@ -15,7 +15,7 @@ registry \- Manipulate the Windows registry .sp \fBpackage require registry 1.3\fR .sp -\fBregistry \fR?\fI\-mode\fR? \fIoption\fR \fIkeyName\fR ?\fIarg arg ...\fR? +\fBregistry \fR?\fI\-mode\fR? \fIoption keyName\fR ?\fIarg arg ...\fR? .BE .SH DESCRIPTION .PP @@ -53,6 +53,7 @@ of the requested operation. \fIOption\fR indicates what to do with the registry key name. Any unique abbreviation for \fIoption\fR is acceptable. The valid options are: +.\" METHOD: broadcast .TP \fBregistry broadcast \fIkeyName\fR ?\fB\-timeout \fImilliseconds\fR? . @@ -79,6 +80,7 @@ set curPath [\fBregistry get\fR $regPath "Path"] \fBregistry broadcast\fR "Environment" .CE .RE +.\" METHOD: delete .TP \fBregistry delete \fIkeyName\fR ?\fIvalueName\fR? . @@ -88,6 +90,7 @@ optional \fIvalueName\fR is omitted, the specified key and any subkeys or values beneath it in the registry hierarchy will be deleted. If the key could not be deleted then an error is generated. If the key did not exist, the command has no effect. +.\" METHOD: get .TP \fBregistry get \fIkeyName valueName\fR . @@ -95,6 +98,7 @@ Returns the data associated with the value \fIvalueName\fR under the key \fIkeyName\fR. If either the key or the value does not exist, then an error is generated. For more details on the format of the returned data, see \fBSUPPORTED TYPES\fR, below. +.\" METHOD: keys .TP \fBregistry keys \fIkeyName\fR ?\fIpattern\fR? . @@ -103,6 +107,7 @@ subkeys of \fIkeyName\fR. If \fIpattern\fR is specified, only those names matching \fIpattern\fR are returned. Matching is determined using the same rules as for \fBstring match\fR. If the specified \fIkeyName\fR does not exist, then an error is generated. +.\" METHOD: set .TP \fBregistry set \fIkeyName\fR ?\fIvalueName data \fR?\fItype\fR?? . @@ -113,12 +118,14 @@ contents of \fIvalueName\fR are set to \fIdata\fR with the type indicated by \fItype\fR. If \fItype\fR is not specified, the type \fBsz\fR is assumed. For more details on the data and type arguments, see \fBSUPPORTED TYPES\fR below. +.\" METHOD: type .TP \fBregistry type \fIkeyName valueName\fR . Returns the type of the value \fIvalueName\fR in the key \fIkeyName\fR. For more information on the possible types, see \fBSUPPORTED TYPES\fR, below. +.\" METHOD: values .TP \fBregistry values \fIkeyName\fR ?\fIpattern\fR? . diff --git a/doc/regsub.n b/doc/regsub.n index 29c118a..439ad49 100644 --- a/doc/regsub.n +++ b/doc/regsub.n @@ -147,7 +147,7 @@ Upper-case characters in \fIstring\fR will be converted to lower-case before matching against \fIexp\fR; however, substitutions specified by \fIsubSpec\fR use the original unconverted form of \fIstring\fR. .TP -\fB\-start\fR \fIindex\fR +\fB\-start\fI index\fR . Specifies a character index offset into the string to start matching the regular expression at. diff --git a/doc/return.n b/doc/return.n index e3d7c06..58b1b75 100644 --- a/doc/return.n +++ b/doc/return.n @@ -54,7 +54,7 @@ of the procedure is 0 (\fBTCL_OK\fR). . Error return: the return code of the procedure is 1 (\fBTCL_ERROR\fR). The procedure command behaves in its calling context as if it -were the command \fBerror\fR \fIresult\fR. See below for additional +were the command \fBerror\fI result\fR. See below for additional options. .TP 13 \fBreturn\fR (or \fB2\fR) @@ -13,26 +13,26 @@ safe \- Creating and manipulating safe interpreters .SH SYNOPSIS \fB::safe::interpCreate\fR ?\fIchild\fR? ?\fIoptions...\fR? .sp -\fB::safe::interpInit\fR \fIchild\fR ?\fIoptions...\fR? +\fB::safe::interpInit\fI child\fR ?\fIoptions...\fR? .sp -\fB::safe::interpConfigure\fR \fIchild\fR ?\fIoptions...\fR? +\fB::safe::interpConfigure\fI child\fR ?\fIoptions...\fR? .sp -\fB::safe::interpDelete\fR \fIchild\fR +\fB::safe::interpDelete\fI child\fR .sp -\fB::safe::interpAddToAccessPath\fR \fIchild\fR \fIdirectory\fR +\fB::safe::interpAddToAccessPath\fI child directory\fR .sp -\fB::safe::interpFindInAccessPath\fR \fIchild\fR \fIdirectory\fR +\fB::safe::interpFindInAccessPath\fI child directory\fR .sp \fB::safe::setSyncMode\fR ?\fInewValue\fR? .sp \fB::safe::setLogCmd\fR ?\fIcmd arg...\fR? .SS OPTIONS .PP -?\fB\-accessPath\fR \fIpathList\fR? -?\fB\-autoPath\fR \fIpathList\fR? -?\fB\-statics\fR \fIboolean\fR? ?\fB\-noStatics\fR? -?\fB\-nested\fR \fIboolean\fR? ?\fB\-nestedLoadOk\fR? -?\fB\-deleteHook\fR \fIscript\fR? +?\fB\-accessPath\fI pathList\fR? +?\fB\-autoPath\fI pathList\fR? +?\fB\-statics\fI boolean\fR? ?\fB\-noStatics\fR? +?\fB\-nested\fI boolean\fR? ?\fB\-nestedLoadOk\fR? +?\fB\-deleteHook\fI script\fR? .BE .SH DESCRIPTION Safe Tcl is a mechanism for executing untrusted Tcl scripts @@ -66,8 +66,10 @@ All commands provided in the parent interpreter by Safe Tcl reside in the \fBsafe\fR namespace. .SH COMMANDS The following commands are provided in the parent interpreter: +.\" COMMAND: interpCreate .TP \fB::safe::interpCreate\fR ?\fIchild\fR? ?\fIoptions...\fR? +. Creates a safe interpreter, installs the aliases described in the section \fBALIASES\fR and initializes the auto-loading and package mechanism as specified by the supplied \fIoptions\fR. @@ -75,21 +77,27 @@ See the \fBOPTIONS\fR section below for a description of the optional arguments. If the \fIchild\fR argument is omitted, a name will be generated. \fB::safe::interpCreate\fR always returns the interpreter name. -.sp +.RS +.PP The interpreter name \fIchild\fR may include namespace separators, but may not have leading or trailing namespace separators, or excess colon characters in namespace separators. The interpreter name is qualified relative to the global namespace ::, not the namespace in which the \fB::safe::interpCreate\fR command is evaluated. +.RE +.\" COMMAND: interpInit .TP -\fB::safe::interpInit\fR \fIchild\fR ?\fIoptions...\fR? +\fB::safe::interpInit\fI child\fR ?\fIoptions...\fR? +. This command is similar to \fBinterpCreate\fR except it that does not create the safe interpreter. \fIchild\fR must have been created by some other means, like \fBinterp create\fR \fB\-safe\fR. The interpreter name \fIchild\fR may include namespace separators, subject to the same restrictions as for \fBinterpCreate\fR. +.\" COMMAND: interpConfigure .TP -\fB::safe::interpConfigure\fR \fIchild\fR ?\fIoptions...\fR? +\fB::safe::interpConfigure\fI child\fR ?\fIoptions...\fR? +. If no \fIoptions\fR are given, returns the settings for all options for the named safe interpreter as a list of options and their current values for that \fIchild\fR. @@ -115,15 +123,18 @@ set dh [safe::interpConfigure $i0 \-del] safe::interpConfigure $i0 \-delete {foo bar} \-statics 0 .CE .RE +.\" COMMAND: interpDelete .TP -\fB::safe::interpDelete\fR \fIchild\fR +\fB::safe::interpDelete\fI child\fR Deletes the safe interpreter and cleans up the corresponding parent interpreter data structures. If a \fIdeleteHook\fR script was specified for this interpreter it is evaluated before the interpreter is deleted, with the name of the interpreter as an additional argument. +.\" COMMAND: interpFindInAccessPath .TP -\fB::safe::interpFindInAccessPath\fR \fIchild\fR \fIdirectory\fR +\fB::safe::interpFindInAccessPath\fI child directory\fR +. This command finds and returns the token for the real directory \fIdirectory\fR in the safe interpreter's current virtual access path. It generates an error if the directory is not found. @@ -135,8 +146,10 @@ $child eval [list set tk_library \e [::safe::interpFindInAccessPath $name $tk_library]] .CE .RE +.\" COMMAND: interpAddToAccessPath .TP -\fB::safe::interpAddToAccessPath\fR \fIchild\fR \fIdirectory\fR +\fB::safe::interpAddToAccessPath\fI child directory\fR +. This command adds \fIdirectory\fR to the virtual path maintained for the safe interpreter in the parent, and returns the token that can be used in the safe interpreter to obtain access to files in that directory. @@ -150,8 +163,10 @@ $child eval [list set tk_library \e [::safe::interpAddToAccessPath $name $tk_library]] .CE .RE +.\" COMMAND: setSyncMode .TP \fB::safe::setSyncMode\fR ?\fInewValue\fR? +. This command is used to get or set the "Sync Mode" of the Safe Base. When an argument is supplied, the command returns an error if the argument is not a boolean value, or if any Safe Base interpreters exist. Typically @@ -159,8 +174,10 @@ the value will be set as part of initialization - boolean true for "Sync Mode" on (the default), false for "Sync Mode" off. With "Sync Mode" on, the Safe Base keeps each child interpreter's ::auto_path synchronized with its access path. See the section \fBSYNC MODE\fR below for details. +.\" COMMAND: setLogCmd .TP \fB::safe::setLogCmd\fR ?\fIcmd arg...\fR? +. This command installs a script that will be called when interesting life cycle events occur for a safe interpreter. When called with no arguments, it returns the currently installed script. @@ -202,7 +219,8 @@ Any option name can be abbreviated to its minimal non-ambiguous name. Option names are not case sensitive. .TP -\fB\-accessPath\fR \fIdirectoryList\fR +\fB\-accessPath\fI directoryList\fR +. This option sets the list of directories from which the safe interpreter can \fBsource\fR and \fBload\fR files. If this option is not specified, or if it is given as the @@ -211,25 +229,29 @@ parent for auto-loading. See the section \fBSECURITY\fR below for more detail about virtual paths, tokens and access control. .TP -\fB\-autoPath\fR \fIdirectoryList\fR +\fB\-autoPath\fI directoryList\fR +. This option sets the list of directories in the safe interpreter's ::auto_path. The option is undefined if the Safe Base has "Sync Mode" on - in that case the safe interpreter's ::auto_path is managed by the Safe Base and is a tokenized form of its access path. See the section \fBSYNC MODE\fR below for details. .TP -\fB\-statics\fR \fIboolean\fR +\fB\-statics\fI boolean\fR +. This option specifies if the safe interpreter will be allowed to load statically linked packages (like \fBload {} Tk\fR). The default value is \fBtrue\fR : safe interpreters are allowed to load statically linked packages. .TP \fB\-noStatics\fR +. This option is a convenience shortcut for \fB\-statics false\fR and thus specifies that the safe interpreter will not be allowed to load statically linked packages. .TP -\fB\-nested\fR \fIboolean\fR +\fB\-nested\fI boolean\fR +. This option specifies if the safe interpreter will be allowed to load packages into its own sub-interpreters. The default value is \fBfalse\fR : @@ -237,11 +259,13 @@ safe interpreters are not allowed to load packages into their own sub-interpreters. .TP \fB\-nestedLoadOk\fR +. This option is a convenience shortcut for \fB\-nested true\fR and thus specifies the safe interpreter will be allowed to load packages into its own sub-interpreters. .TP -\fB\-deleteHook\fR \fIscript\fR +\fB\-deleteHook\fI script\fR +. When this option is given a non-empty \fIscript\fR, it will be evaluated in the parent with the name of the safe interpreter as an additional argument @@ -252,7 +276,8 @@ The default value (\fB{}\fR) is not to have any deletion call back. .SH ALIASES The following aliases are provided in a safe interpreter: .TP -\fBsource\fR \fIfileName\fR +\fBsource\fI fileName\fR +. The requested file, a Tcl source file, is sourced into the safe interpreter if it is found. The \fBsource\fR alias can only source files from directories in @@ -263,7 +288,8 @@ which the file to be sourced can be found. See the section on \fBSECURITY\fR for more discussion of restrictions on valid filenames. .TP -\fBload\fR \fIfileName\fR +\fBload\fI fileName\fR +. The requested file, a shared object file, is dynamically loaded into the safe interpreter if it is found. The filename must contain a token name mentioned in the virtual path for @@ -272,6 +298,7 @@ Additionally, the shared object file must contain a safe entry point; see the manual page for the \fBload\fR command for more details. .TP \fBfile\fR ?\fIsubCmd args...\fR? +. The \fBfile\fR alias provides access to a safe subset of the subcommands of the \fBfile\fR command; it allows only \fBdirname\fR, \fBjoin\fR, \fBextension\fR, \fBroot\fR, \fBtail\fR, \fBpathname\fR and \fBsplit\fR @@ -279,12 +306,14 @@ subcommands. For more details on what these subcommands do see the manual page for the \fBfile\fR command. .TP \fBencoding\fR ?\fIsubCmd args...\fR? +. The \fBencoding\fR alias provides access to a safe subset of the subcommands of the \fBencoding\fR command; it disallows setting of the system encoding, but allows all other subcommands including \fBsystem\fR to check the current encoding. .TP \fBexit\fR +. The calling interpreter is deleted and its computation is stopped, but the Tcl process in which this interpreter exists is not terminated. .SH SECURITY @@ -24,6 +24,7 @@ used to allow the method to discover information about how it was called. It takes an argument, \fIsubcommand\fR, that tells it what sort of information is actually desired; if omitted the result will be the same as if \fBself object\fR was invoked. The supported subcommands are: +.\" METHOD: call .TP \fBself call\fR . @@ -40,6 +41,7 @@ being a \fBmethod\fR), and the second element is an index into the first element's list that indicates which actual implementation is currently executing (the first implementation to execute is always at index 0). +.\" METHOD: caller .TP \fBself caller\fR . @@ -50,6 +52,7 @@ second element is the name of the object on which the containing method was invoked, and the third element is the name of the method (with the strings \fB<constructor>\fR and \fB<destructor>\fR indicating constructors and destructors respectively). +.\" METHOD: class .TP \fBself class\fR . @@ -66,6 +69,7 @@ construct: info object class [\fBself object\fR] .CE .RE +.\" METHOD: filter .TP \fBself filter\fR . @@ -75,17 +79,20 @@ that declared the filter (note that this may be different from the object or class that provided the implementation of the filter), the second element is either \fBobject\fR or \fBclass\fR depending on whether the declaring entity was an object or class, and the third element is the name of the filter. +.\" METHOD: method .TP \fBself method\fR . This returns the name of the current method (with the strings \fB<constructor>\fR and \fB<destructor>\fR indicating constructors and destructors respectively). +.\" METHOD: namespace .TP \fBself namespace\fR . This returns the name of the unique namespace of the object that the method was invoked upon. +.\" METHOD: next .TP \fBself next\fR . @@ -98,10 +105,12 @@ of the method (with the strings \fB<constructor>\fR and \fB<destructor>\fR indicating constructors and destructors respectively). If invoked from a method that is at the end of a call chain, this subcommand returns the empty string. +.\" METHOD: object .TP \fBself object\fR . This returns the name of the object that the method was invoked upon. +.\" METHOD: target .TP \fBself target\fR . diff --git a/doc/string.n b/doc/string.n index c610aeb..6e87deb 100644 --- a/doc/string.n +++ b/doc/string.n @@ -18,6 +18,7 @@ string \- Manipulate strings .PP Performs one of several string operations, depending on \fIoption\fR. The legal \fIoption\fRs (which may be abbreviated) are: +.\" METHOD: cat .TP \fBstring cat\fR ?\fIstring1\fR? ?\fIstring2...\fR? . @@ -32,6 +33,7 @@ of a concatenation without resorting to \fBreturn\fR \fB\-level 0\fR, and is more efficient than building a list of arguments and using \fBjoin\fR with an empty join string. .RE +.\" METHOD: compare .TP \fBstring compare\fR ?\fB\-nocase\fR? ?\fB\-length\fI length\fR? \fIstring1 string2\fR . @@ -42,6 +44,7 @@ than \fIstring2\fR. If \fB\-length\fR is specified, then only the first \fIlength\fR characters are used in the comparison. If \fB\-length\fR is negative, it is ignored. If \fB\-nocase\fR is specified, then the strings are compared in a case-insensitive manner. +.\" METHOD: equal .TP \fBstring equal\fR ?\fB\-nocase\fR? ?\fB\-length\fI length\fR? \fIstring1 string2\fR . @@ -51,6 +54,7 @@ identical, or 0 when not. If \fB\-length\fR is specified, then only the first \fIlength\fR characters are used in the comparison. If \fB\-length\fR is negative, it is ignored. If \fB\-nocase\fR is specified, then the strings are compared in a case-insensitive manner. +.\" METHOD: first .TP \fBstring first \fIneedleString haystackString\fR ?\fIstartIndex\fR? . @@ -75,6 +79,7 @@ will return \fB10\fR, but .PP will return \fB\-1\fR. .RE +.\" METHOD: index .TP \fBstring index \fIstring charIndex\fR . @@ -87,6 +92,7 @@ string. \fIcharIndex\fR may be specified as described in the If \fIcharIndex\fR is less than 0 or greater than or equal to the length of the string then this command returns an empty string. .RE +.\" METHOD: insert .TP \fBstring insert \fIstring index insertString\fR .VS "TIP 504" @@ -105,6 +111,7 @@ or after the end of \fIstring\fR (e.g., \fIindex\fR is \fBend\fR), \fIinsertString\fR is appended to \fIstring\fR. .RE .VE "TIP 504" +.\" METHOD: is .TP \fBstring is \fIclass\fR ?\fB\-strict\fR? ?\fB\-failindex \fIvarname\fR? \fIstring\fR . @@ -196,6 +203,7 @@ In the case of \fBboolean\fR, \fBtrue\fR and \fBfalse\fR, if the function will return 0, then the \fIvarname\fR will always be set to 0, due to the varied nature of a valid boolean value. .RE +.\" METHOD: last .TP \fBstring last \fIneedleString haystackString\fR ?\fIlastIndex\fR? . @@ -220,6 +228,7 @@ will return \fB10\fR, but .PP will return \fB1\fR. .RE +.\" METHOD: length .TP \fBstring length \fIstring\fR . @@ -228,6 +237,7 @@ Returns a decimal string giving the number of characters in number of bytes used to store the string. If the value is a byte array value (such as those returned from reading a binary encoded channel), then this will return the actual byte length of the value. +.\" METHOD: map .TP \fBstring map\fR ?\fB\-nocase\fR? \fImapping string\fR . @@ -259,8 +269,9 @@ reordered like this, .PP it will return the string \fB02c322c222c\fR. .RE +.\" METHOD: match .TP -\fBstring match\fR ?\fB\-nocase\fR? \fIpattern\fR \fIstring\fR +\fBstring match\fR ?\fB\-nocase\fR? \fIpattern string\fR . See if \fIpattern\fR matches \fIstring\fR; return 1 if it does, 0 if it does not. If \fB\-nocase\fR is specified, then the pattern attempts @@ -293,6 +304,7 @@ Matches the single character \fIx\fR. This provides a way of avoiding the special interpretation of the characters \fB*?[]\e\fR in \fIpattern\fR. .RE +.\" METHOD: range .TP \fBstring range \fIstring first last\fR . @@ -307,12 +319,14 @@ it is treated as if it were zero, and if \fIlast\fR is greater than or equal to the length of the string then it is treated as if it were \fBend\fR. If \fIfirst\fR is greater than \fIlast\fR then an empty string is returned. +.\" METHOD: repeat .TP \fBstring repeat \fIstring count\fR . Returns a string consisting of \fIstring\fR concatenated with itself \fIcount\fR times. If \fIcount\fR is 0, the empty string will be returned. +.\" METHOD: replace .TP \fBstring replace \fIstring first last\fR ?\fInewstring\fR? . @@ -329,11 +343,13 @@ then it is treated as if it were \fBend\fR. The initial string is returned untouched, if \fIfirst\fR is greater than \fIlast\fR, or if \fIfirst\fR is equal to or greater than the length of the initial string, or \fIlast\fR is less than 0. +.\" METHOD: reverse .TP \fBstring reverse \fIstring\fR . Returns a string that is the same length as \fIstring\fR but with its characters in the reverse order. +.\" METHOD: tolower .TP \fBstring tolower \fIstring\fR ?\fIfirst\fR? ?\fIlast\fR? . @@ -343,6 +359,7 @@ specified, it refers to the first char index in the string to start modifying. If \fIlast\fR is specified, it refers to the char index in the string to stop at (inclusive). \fIfirst\fR and \fIlast\fR may be specified using the forms described in \fBSTRING INDICES\fR. +.\" METHOD: totitle .TP \fBstring totitle \fIstring\fR ?\fIfirst\fR? ?\fIlast\fR? . @@ -354,6 +371,7 @@ refers to the first char index in the string to start modifying. If \fIlast\fR is specified, it refers to the char index in the string to stop at (inclusive). \fIfirst\fR and \fIlast\fR may be specified using the forms described in \fBSTRING INDICES\fR. +.\" METHOD: toupper .TP \fBstring toupper \fIstring\fR ?\fIfirst\fR? ?\fIlast\fR? . @@ -363,6 +381,7 @@ specified, it refers to the first char index in the string to start modifying. If \fIlast\fR is specified, it refers to the char index in the string to stop at (inclusive). \fIfirst\fR and \fIlast\fR may be specified using the forms described in \fBSTRING INDICES\fR. +.\" METHOD: trim .TP \fBstring trim \fIstring\fR ?\fIchars\fR? . @@ -370,6 +389,7 @@ Returns a value equal to \fIstring\fR except that any leading or trailing characters present in the string given by \fIchars\fR are removed. If \fIchars\fR is not specified then white space is removed (any character for which \fBstring is space\fR returns 1, and "\e0"). +.\" METHOD: trimleft .TP \fBstring trimleft \fIstring\fR ?\fIchars\fR? . @@ -377,6 +397,7 @@ Returns a value equal to \fIstring\fR except that any leading characters present in the string given by \fIchars\fR are removed. If \fIchars\fR is not specified then white space is removed (any character for which \fBstring is space\fR returns 1, and "\e0"). +.\" METHOD: trimright .TP \fBstring trimright \fIstring\fR ?\fIchars\fR? . @@ -389,12 +410,7 @@ for which \fBstring is space\fR returns 1, and "\e0"). These subcommands are currently supported, but are likely to go away in a future release as their functionality is either virtually never used or highly misleading. -.RS -.PP -.CS -\fBstring length\fR [encoding convertto utf-8 $theString] -.CE -.RE +.\" METHOD: wordend .TP \fBstring wordend \fIstring charIndex\fR . @@ -404,6 +420,7 @@ may be specified using the forms in \fBSTRING INDICES\fR. A word is considered to be any contiguous range of alphanumeric (Unicode letters or decimal digits) or underscore (Unicode connector punctuation) characters, or any single character other than these. +.\" METHOD: wordstart .TP \fBstring wordstart \fIstring charIndex\fR . diff --git a/doc/switch.n b/doc/switch.n index 70eeb09..d35c650 100644 --- a/doc/switch.n +++ b/doc/switch.n @@ -56,7 +56,7 @@ expression matching . Causes comparisons to be handled in a case-insensitive manner. .TP 10 -\fB\-matchvar\fR \fIvarName\fR +\fB\-matchvar\fI varName\fR . This option (only legal when \fB\-regexp\fR is also specified) specifies the name of a variable into which the list of matches @@ -69,7 +69,7 @@ on. When a \fBdefault\fR branch is taken, the variable will have the empty list written to it. This option may be specified at the same time as the \fB\-indexvar\fR option. .TP 10 -\fB\-indexvar\fR \fIvarName\fR +\fB\-indexvar\fI varName\fR . This option (only legal when \fB\-regexp\fR is also specified) specifies the name of a variable into which the list of indices diff --git a/doc/tcltest.n b/doc/tcltest.n index 965ed64..c29b05e 100644 --- a/doc/tcltest.n +++ b/doc/tcltest.n @@ -89,8 +89,9 @@ See \fBCREATING TEST SUITES WITH TCLTEST\fR below for an extended example of how to use the commands of \fBtcltest\fR to produce test suites for your Tcl-enabled code. .SH COMMANDS +.\" COMMAND: test .TP -\fBtest\fR \fIname description\fR ?\fI\-option value ...\fR? +\fBtest\fI name description\fR ?\fI\-option value ...\fR? . Defines and possibly runs a test with the name \fIname\fR and description \fIdescription\fR. The name and description of a test @@ -104,17 +105,18 @@ See \fBTESTS\fR below for a complete description of the valid options and how they define a test. The \fBtest\fR command returns an empty string. .TP -\fBtest\fR \fIname description\fR ?\fIconstraints\fR? \fIbody result\fR +\fBtest\fI name description\fR ?\fIconstraints\fR? \fIbody result\fR . This form of \fBtest\fR is provided to support test suites written for version 1 of the \fBtcltest\fR package, and also a simpler interface for a common usage. It is the same as -.QW "\fBtest\fR \fIname description\fB \-constraints \fIconstraints\fB \-body \fIbody\fB \-result \fIresult\fR" . +.QW "\fBtest\fI name description\fB \-constraints \fIconstraints\fB \-body \fIbody\fB \-result \fIresult\fR" . All other options to \fBtest\fR take their default values. When \fIconstraints\fR is omitted, this form of \fBtest\fR can be distinguished from the first because all \fIoption\fRs begin with .QW \- . +.\" COMMAND: loadTestedCommands .TP \fBloadTestedCommands\fR . @@ -124,8 +126,9 @@ Returns the result of that script evaluation, including any error raised by the script. Use this command and the related configuration options to provide the commands to be tested to the interpreter running the test suite. +.\" COMMAND: makeFile .TP -\fBmakeFile\fR \fIcontents name\fR ?\fIdirectory\fR? +\fBmakeFile\fI contents name\fR ?\fIdirectory\fR? . Creates a file named \fIname\fR relative to directory \fIdirectory\fR and write \fIcontents\fR @@ -140,16 +143,18 @@ of \fBcleanupTests\fR, unless it is removed by \fIdirectory\fR is the directory \fBconfigure \-tmpdir\fR. Returns the full path of the file created. Use this command to create any text file required by a test with contents as needed. +.\" COMMAND: removeFile .TP -\fBremoveFile\fR \fIname\fR ?\fIdirectory\fR? +\fBremoveFile\fI name\fR ?\fIdirectory\fR? . Forces the file referenced by \fIname\fR to be removed. This file name should be relative to \fIdirectory\fR. The default value of \fIdirectory\fR is the directory \fBconfigure \-tmpdir\fR. Returns an empty string. Use this command to delete files created by \fBmakeFile\fR. +.\" COMMAND: makeDirectory .TP -\fBmakeDirectory\fR \fIname\fR ?\fIdirectory\fR? +\fBmakeDirectory\fI name\fR ?\fIdirectory\fR? . Creates a directory named \fIname\fR relative to directory \fIdirectory\fR. The directory will be removed by the next evaluation of \fBcleanupTests\fR, @@ -158,8 +163,9 @@ The default value of \fIdirectory\fR is the directory \fBconfigure \-tmpdir\fR. Returns the full path of the directory created. Use this command to create any directories that are required to exist by a test. +.\" COMMAND: removeDirectory .TP -\fBremoveDirectory\fR \fIname\fR ?\fIdirectory\fR? +\fBremoveDirectory\fI name\fR ?\fIdirectory\fR? . Forces the directory referenced by \fIname\fR to be removed. This directory should be relative to \fIdirectory\fR. @@ -167,8 +173,9 @@ The default value of \fIdirectory\fR is the directory \fBconfigure \-tmpdir\fR. Returns an empty string. Use this command to delete any directories created by \fBmakeDirectory\fR. +.\" COMMAND: viewFile .TP -\fBviewFile\fR \fIfile\fR ?\fIdirectory\fR? +\fBviewFile\fI file\fR ?\fIdirectory\fR? . Returns the contents of \fIfile\fR, except for any final newline, just as \fBread \-nonewline\fR would return. @@ -180,6 +187,7 @@ by a test into the result of that test for matching against an expected result. The contents of the file are read using the system encoding, so its usefulness is limited to text files. +.\" COMMAND: cleanupTests .TP \fBcleanupTests\fR . @@ -200,6 +208,7 @@ to \fBoutputChannel\fR. This command also restores the original shell environment, as described by the global \fBenv\fR array. Returns an empty string. .RE +.\" COMMAND: runAllTests .TP \fBrunAllTests\fR . @@ -209,6 +218,7 @@ the configurable options of \fBtcltest\fR. See \fBRUNNING ALL TESTS\fR below for a complete description of the many variations possible with \fBrunAllTests\fR. .SS "CONFIGURATION COMMANDS" +.\" COMMAND: configure .TP \fBconfigure\fR . @@ -238,6 +248,7 @@ then its value is taken as a list of arguments to pass to \fBconfigure\fR. This allows the default values of the configuration options to be set by the environment. .RE +.\" COMMAND: customMatch .TP \fBcustomMatch \fImode script\fR . @@ -252,11 +263,13 @@ is evaluated in the global namespace. The completed script is expected to return a boolean value indicating whether or not the results match. The built-in matching modes of \fBtest\fR are \fBexact\fR, \fBglob\fR, and \fBregexp\fR. +.\" COMMAND: testConstraint .TP \fBtestConstraint \fIconstraint\fR ?\fIboolean\fR? . Sets or returns the boolean value associated with the named \fIconstraint\fR. See \fBTEST CONSTRAINTS\fR below for more information. +.\" COMMAND: interpreter .TP \fBinterpreter\fR ?\fIexecutableName\fR? . @@ -265,6 +278,7 @@ Sets or returns the name of the executable to be \fBexec\fRed by \fBconfigure \-singleproc\fR is false. The default value for \fBinterpreter\fR is the name of the currently running program as returned by \fBinfo nameofexecutable\fR. +.\" COMMAND: outputChannel .TP \fBoutputChannel\fR ?\fIchannelID\fR? . @@ -272,6 +286,7 @@ Sets or returns the output channel ID. This defaults to \fBstdout\fR. Any test that prints test related output should send that output to \fBoutputChannel\fR rather than letting that output default to \fBstdout\fR. +.\" COMMAND: errorChannel .TP \fBerrorChannel\fR ?\fIchannelID\fR? . @@ -280,6 +295,7 @@ Any test that prints error messages should send that output to \fBerrorChannel\fR rather than printing directly to \fBstderr\fR. .SS "SHORTCUT CONFIGURATION COMMANDS" +.\" COMMAND: debug .TP \fBdebug\fR ?\fIlevel\fR? . @@ -290,76 +306,91 @@ Same as . Same as .QW "\fBconfigure \-errfile\fR ?\fIfilename\fR?" . +.\" COMMAND: limitConstraints .TP \fBlimitConstraints\fR ?\fIboolean\fR? . Same as .QW "\fBconfigure \-limitconstraints\fR ?\fIboolean\fR?" . +.\" COMMAND: loadFile .TP \fBloadFile\fR ?\fIfilename\fR? . Same as .QW "\fBconfigure \-loadfile\fR ?\fIfilename\fR?" . +.\" COMMAND: loadScript .TP \fBloadScript\fR ?\fIscript\fR? . Same as .QW "\fBconfigure \-load\fR ?\fIscript\fR?" . +.\" COMMAND: match .TP \fBmatch\fR ?\fIpatternList\fR? . Same as .QW "\fBconfigure \-match\fR ?\fIpatternList\fR?" . +.\" COMMAND: matchDirectories .TP \fBmatchDirectories\fR ?\fIpatternList\fR? . Same as .QW "\fBconfigure \-relateddir\fR ?\fIpatternList\fR?" . +.\" COMMAND: matchFiles .TP \fBmatchFiles\fR ?\fIpatternList\fR? . Same as .QW "\fBconfigure \-file\fR ?\fIpatternList\fR?" . +.\" COMMAND: outputFile .TP \fBoutputFile\fR ?\fIfilename\fR? . Same as .QW "\fBconfigure \-outfile\fR ?\fIfilename\fR?" . +.\" COMMAND: preserveCore .TP \fBpreserveCore\fR ?\fIlevel\fR? . Same as .QW "\fBconfigure \-preservecore\fR ?\fIlevel\fR?" . +.\" COMMAND: singleProcess .TP \fBsingleProcess\fR ?\fIboolean\fR? . Same as .QW "\fBconfigure \-singleproc\fR ?\fIboolean\fR?" . +.\" COMMAND: skip .TP \fBskip\fR ?\fIpatternList\fR? . Same as .QW "\fBconfigure \-skip\fR ?\fIpatternList\fR?" . +.\" COMMAND: skipDirectories .TP \fBskipDirectories\fR ?\fIpatternList\fR? . Same as .QW "\fBconfigure \-asidefromdir\fR ?\fIpatternList\fR?" . +.\" COMMAND: skipFiles .TP \fBskipFiles\fR ?\fIpatternList\fR? . Same as .QW "\fBconfigure \-notfile\fR ?\fIpatternList\fR?" . +.\" COMMAND: temporaryDirectory .TP \fBtemporaryDirectory\fR ?\fIdirectory\fR? . Same as .QW "\fBconfigure \-tmpdir\fR ?\fIdirectory\fR?" . +.\" COMMAND: testsDirectory .TP \fBtestsDirectory\fR ?\fIdirectory\fR? . Same as .QW "\fBconfigure \-testdir\fR ?\fIdirectory\fR?" . +.\" COMMAND: verbose .TP \fBverbose\fR ?\fIlevel\fR? . @@ -372,7 +403,7 @@ alternatives provided by \fBtcltest\fR or \fBTcl\fR itself. They are retained to support existing test suites, but should be avoided in new code. .TP -\fBtest\fR \fIname description optionList\fR +\fBtest\fI name description optionList\fR . This form of \fBtest\fR was provided to enable passing many options spanning several lines to \fBtest\fR as a single @@ -396,6 +427,7 @@ If you insist on using this form, examine the source code of \fBtcltest\fR if you want to know the substitution details, or just enclose the third through last argument to \fBtest\fR in braces and hope for the best. +.\" COMMAND: workingDirectory .TP \fBworkingDirectory\fR ?\fIdirectoryName\fR? . @@ -403,6 +435,7 @@ Sets or returns the current working directory when the test suite is running. The default value for workingDirectory is the directory in which the test suite was launched. The Tcl commands \fBcd\fR and \fBpwd\fR are sufficient replacements. +.\" COMMAND: normalizeMsg .TP \fBnormalizeMsg \fImsg\fR . @@ -414,6 +447,7 @@ is rather imprecise. Tcl offers plenty of string processing commands to modify strings as you wish, and \fBcustomMatch\fR allows flexible matching of actual and expected results. +.\" COMMAND: normalizePath .TP \fBnormalizePath \fIpathVar\fR . @@ -421,6 +455,7 @@ Resolves symlinks in a path, thus creating a path without internal redirection. It is assumed that \fIpathVar\fR is absolute. \fIpathVar\fR is modified in place. The Tcl command \fBfile normalize\fR is a sufficient replacement. +.\" COMMAND: bytestring .TP \fBbytestring \fIstring\fR . @@ -445,7 +480,7 @@ also influence how \fBtest\fR operates. The valid options for \fBtest\fR are summarized: .PP .CS -\fBtest\fR \fIname\fR \fIdescription\fR +\fBtest\fI name description\fR ?\fB\-constraints \fIkeywordList|expression\fR? ?\fB\-setup \fIsetupScript\fR? ?\fB\-body \fItestScript\fR? diff --git a/doc/tclvars.n b/doc/tclvars.n index 49e86a5..a08f525 100644 --- a/doc/tclvars.n +++ b/doc/tclvars.n @@ -17,6 +17,7 @@ argc, argv, argv0, auto_path, env, errorCode, errorInfo, tcl_interactive, tcl_li The following global variables are created and managed automatically by the Tcl library. Except where noted below, these variables should normally be treated as read-only by application-specific code and by users. +.\" VARIABLE: auto_path .TP \fBauto_path\fR . @@ -40,6 +41,7 @@ Additional variables relating to package management exist. More details are listed in the \fBVARIABLES\fR section of the \fBlibrary\fR manual page. .RE +.\" VARIABLE: env .TP \fBenv\fR . @@ -121,6 +123,7 @@ If existing, it has the same effect as running \fBinterp debug\fR \fB{} -frame 1\fR as the very first command of each new Tcl interpreter. .RE +.\" VARIABLE: errorCode .TP \fBerrorCode\fR . @@ -217,6 +220,7 @@ If none of these methods for setting the error code has been used, the Tcl interpreter will reset the variable to \fBNONE\fR after the next error. .RE +.\" VARIABLE: errorInfo .TP \fBerrorInfo\fR . @@ -227,6 +231,7 @@ identifying the Tcl commands and procedures that were being executed when the most recent error occurred. Its contents take the form of a stack trace showing the various nested Tcl commands that had been invoked at the time of the error. +.\" VARIABLE: tcl_library .TP \fBtcl_library\fR . @@ -249,6 +254,7 @@ If \fBTCL_LIBRARY\fR is not set or doesn't refer to an appropriate directory, then Tcl checks several other directories based on a compiled-in default location, the location of the binary containing the application, and the current working directory. +.\" VARIABLE: tcl_patchLevel .TP \fBtcl_patchLevel\fR . @@ -258,6 +264,7 @@ hold a string giving the current patch level for Tcl, such as \fB8.5b3\fR for the third beta release of Tcl 8.5. The value of this variable is returned by the \fBinfo patchlevel\fR command. +.\" VARIABLE: tcl_pkgPath .TP \fBtcl_pkgPath\fR . @@ -277,6 +284,7 @@ value is added to \fBauto_path\fR at startup; changes to \fBtcl_pkgPath\fR are not reflected in \fBauto_path\fR. If you want Tcl to search additional directories for packages you should add the names of those directories to \fBauto_path\fR, not \fBtcl_pkgPath\fR. +.\" VARIABLE: tcl_platform .TP \fBtcl_platform\fR . @@ -357,6 +365,7 @@ and the value from the GetUserName() system call on Windows. This gives the size of the native-machine word in bytes (strictly, it is same as the result of evaluating \fIsizeof(long)\fR in C.) .RE +.\" VARIABLE: tcl_traceCompile .TP \fBtcl_traceCompile\fR . @@ -375,6 +384,7 @@ tracking down suspected problems with the Tcl compiler. This variable and functionality only exist if \fBTCL_COMPILE_DEBUG\fR was defined during Tcl's compilation. .RE +.\" VARIABLE: tcl_traceExec .TP \fBtcl_traceExec\fR . @@ -401,6 +411,7 @@ and interpreter. This variable and functionality only exist if \fBTCL_COMPILE_DEBUG\fR was defined during Tcl's compilation. .RE +.\" VARIABLE: tcl_wordchars .TP \fBtcl_wordchars\fR . @@ -423,6 +434,7 @@ selecting a word by double-clicking in text in Tk. It is platform dependent. On Windows, it defaults to \fB\es\fR, meaning any Unicode space character. Otherwise it defaults to \fB\eW\fR, which is anything but a Unicode word character (number, letter, or underscore). +.\" VARIABLE: tcl_version .TP \fBtcl_version\fR . @@ -438,20 +450,24 @@ command. The following variables are only guaranteed to exist in \fBtclsh\fR and \fBwish\fR executables; the Tcl library does not define them itself but many Tcl environments do. +.\" VARIABLE: argc .TP 6 \fBargc\fR . The number of arguments to \fBtclsh\fR or \fBwish\fR. +.\" VARIABLE: argv .TP 6 \fBargv\fR . Tcl list of arguments to \fBtclsh\fR or \fBwish\fR. +.\" VARIABLE: argv0 .TP 6 \fBargv0\fR . The script that \fBtclsh\fR or \fBwish\fR started executing (if it was specified) or otherwise the name by which \fBtclsh\fR or \fBwish\fR was invoked. +.\" VARIABLE: tcl_interactive .TP 6 \fBtcl_interactive\fR . @@ -23,6 +23,8 @@ tm \- Facilities for locating and loading of Tcl Modules This document describes the facilities for locating and loading Tcl Modules (see \fBMODULE DEFINITION\fR for the definition of a Tcl Module). The following commands are supported: +.\" COMMAND: path +.\" METHOD: add .TP \fB::tcl::tm::path add \fR?\fIpath\fR...? . @@ -45,16 +47,19 @@ list. As they are added to the front of the list they are searched in reverse order of addition. In other words, the paths added last are looked at first. .RE +.\" METHOD: remove .TP \fB::tcl::tm::path remove \fR?\fIpath\fR...? . Removes the paths from the list of module paths. The command silently ignores all paths which are not on the list. +.\" METHOD: list .TP \fB::tcl::tm::path list\fR . Returns a list containing all registered module paths, in the order that they are searched for modules. +.\" COMMAND: roots .TP \fB::tcl::tm::roots \fR?\fIpath\fR...? . diff --git a/doc/trace.n b/doc/trace.n index 72b415b..a60b36c 100644 --- a/doc/trace.n +++ b/doc/trace.n @@ -19,13 +19,14 @@ trace \- Monitor variable accesses, command usages and command executions .PP This command causes Tcl commands to be executed whenever certain operations are invoked. The legal \fIoption\fRs (which may be abbreviated) are: +.\" METHOD: add .TP \fBtrace add \fItype name ops\fR ?\fIargs\fR? . Where \fItype\fR is \fBcommand\fR, \fBexecution\fR, or \fBvariable\fR. .RS .TP -\fBtrace add command\fR \fIname ops commandPrefix\fR +\fBtrace add command\fI name ops commandPrefix\fR . Arrange for \fIcommandPrefix\fR to be executed (with additional arguments) whenever command \fIname\fR is modified in one of the ways given by the list @@ -76,7 +77,7 @@ Both \fIoldName\fR and \fInewName\fR are fully qualified with any namespace(s) in which they appear. .RE .TP -\fBtrace add execution\fR \fIname ops commandPrefix\fR +\fBtrace add execution\fI name ops commandPrefix\fR . Arrange for \fIcommandPrefix\fR to be executed (with additional arguments) whenever command \fIname\fR is executed, with traces occurring at the points @@ -302,6 +303,7 @@ but will not remove traces on the overall array. This command returns an empty string. .RE .RE +.\" METHOD: remove .TP \fBtrace remove \fItype name opList commandPrefix\fR Where \fItype\fR is either \fBcommand\fR, \fBexecution\fR or \fBvariable\fR. @@ -327,6 +329,7 @@ command given by \fIopList\fR and \fIcommandPrefix\fR, then the trace is removed, so that \fIcommandPrefix\fR will never again be invoked. Returns an empty string. .RE +.\" METHOD: info .TP \fBtrace info \fItype name\fR Where \fItype\fR is either \fBcommand\fR, \fBexecution\fR or \fBvariable\fR. diff --git a/doc/transchan.n b/doc/transchan.n index b9a0f21..a424981 100644 --- a/doc/transchan.n +++ b/doc/transchan.n @@ -44,6 +44,7 @@ create the transformation. .SS "GENERIC SUBCOMMANDS" .PP The following subcommands are relevant to all types of channel. +.\" METHOD: clear .TP \fIcmdPrefix \fBclear \fIhandle\fR . @@ -51,6 +52,7 @@ This optional subcommand is called to signify to the transformation that any data stored in internal buffers (either incoming or outgoing) must be cleared. It is called when a \fBchan seek\fR is performed on the channel being transformed. +.\" METHOD: finalize .TP \fIcmdPrefix \fBfinalize \fIhandle\fR . @@ -59,6 +61,7 @@ never again, and it exists to allow for cleaning up any Tcl-level data structures associated with the transformation. \fIWarning!\fR Any errors thrown by this subcommand will be ignored. It is not guaranteed to be called if the interpreter is deleted. +.\" METHOD: initialize .TP \fIcmdPrefix \fBinitialize \fIhandle mode\fR . @@ -86,6 +89,7 @@ as error thrown by \fBchan push\fR. These subcommands are used for handling transformations applied to readable channels; though strictly \fBread \fRis optional, it must be supported if any of the others is or the channel will be made non-readable. +.\" METHOD: drain .TP \fIcmdPrefix \fBdrain \fIhandle\fR . @@ -100,6 +104,7 @@ In other words, when this method is called the transformation cannot defer the actual transformation operation anymore and has to transform all data waiting in its internal read buffers and return the result of that action. .RE +.\" METHOD: limit? .TP \fIcmdPrefix \fBlimit? \fIhandle\fR . @@ -108,6 +113,7 @@ how far ahead it should read. If present, it should return an integer number greater than zero which indicates how many bytes ahead should be read, or an integer less than zero to indicate that the I/O engine may read as far ahead as it likes. +.\" METHOD: read .TP \fIcmdPrefix \fBread \fIhandle buffer\fR . @@ -131,6 +137,7 @@ defer the actual transformation until it has more data. These subcommands are used for handling transformations applied to writable channels; though strictly \fBwrite\fR is optional, it must be supported if any of the others is or the channel will be made non-writable. +.\" METHOD: flush .TP \fIcmdPrefix \fBflush \fIhandle\fR . @@ -145,6 +152,7 @@ In other words, when this subcommand is called the transformation cannot defer the actual transformation operation anymore and has to transform all data waiting in its internal write buffers and return the result of that action. .RE +.\" METHOD: write .TP \fIcmdPrefix \fBwrite \fIhandle buffer\fR . diff --git a/doc/vwait.n b/doc/vwait.n index e595a74..951dbaa 100644 --- a/doc/vwait.n +++ b/doc/vwait.n @@ -11,7 +11,7 @@ .SH NAME vwait \- Process events until a variable is written .SH SYNOPSIS -\fBvwait\fR \fIvarName\fR +\fBvwait\fI varName\fR .sp \fBvwait\fR ?\fIoptions\fR? ?\fIvarName ...\fR? .BE @@ -61,21 +61,21 @@ Timer handlers are not serviced during the wait operation. . Events of the windowing system are not handled during the wait operation. .TP -\fB\-readable\fR \fIchannel\fR +\fB\-readable\fI channel\fR . \fIChannel\fR must name a Tcl channel open for reading. If \fIchannel\fR is or becomes readable the wait operation completes. .TP -\fB\-timeout\fR \fImilliseconds\fR +\fB\-timeout\fI milliseconds\fR . The wait operation is constrained to \fImilliseconds\fR. .TP -\fB\-variable\fR \fIvarName\fR +\fB\-variable\fI varName\fR . \fIVarName\fR must be the name of a global variable. Writing or unsetting this variable completes the wait operation. .TP -\fB\-writable\fR \fIchannel\fR +\fB\-writable\fI channel\fR . \fIChannel\fR must name a Tcl channel open for writing. If \fIchannel\fR is or becomes writable the wait operation completes. diff --git a/doc/zipfs.n b/doc/zipfs.n index 0a05078..b7bcab1 100644 --- a/doc/zipfs.n +++ b/doc/zipfs.n @@ -17,18 +17,18 @@ zipfs \- Mount and work with ZIP files within Tcl \fBpackage require tcl::zipfs \fR?\fB1.0\fR? .sp \fBzipfs canonical\fR ?\fImntpnt\fR? \fIfilename\fR ?\fIZIPFS\fR? -\fBzipfs exists\fR \fIfilename\fR -\fBzipfs find\fR \fIdirectoryName\fR -\fBzipfs info\fR \fIfilename\fR +\fBzipfs exists\fI filename\fR +\fBzipfs find\fI directoryName\fR +\fBzipfs info\fI filename\fR \fBzipfs list\fR ?(\fB\-glob\fR|\fB\-regexp\fR)? ?\fIpattern\fR? -\fBzipfs lmkimg\fR \fIoutfile inlist\fR ?\fIpassword infile\fR? -\fBzipfs lmkzip\fR \fIoutfile inlist\fR ?\fIpassword\fR? -\fBzipfs mkimg\fR \fIoutfile indir\fR ?\fIstrip\fR? ?\fIpassword\fR? ?\fIinfile\fR? -\fBzipfs mkkey\fR \fIpassword\fR -\fBzipfs mkzip\fR \fIoutfile indir\fR ?\fIstrip\fR? ?\fIpassword\fR? +\fBzipfs lmkimg\fI outfile inlist\fR ?\fIpassword infile\fR? +\fBzipfs lmkzip\fI outfile inlist\fR ?\fIpassword\fR? +\fBzipfs mkimg\fI outfile indir\fR ?\fIstrip\fR? ?\fIpassword\fR? ?\fIinfile\fR? +\fBzipfs mkkey\fI password\fR +\fBzipfs mkzip\fI outfile indir\fR ?\fIstrip\fR? ?\fIpassword\fR? \fBzipfs mount\fR ?\fIzipfile\fR? ?\fImountpoint\fR? ?\fIpassword\fR? \fBzipfs root\fR -\fBzipfs unmount\fR \fImountpoint\fR +\fBzipfs unmount\fI mountpoint\fR .fi '\" The following subcommand is *UNDOCUMENTED* '\" \fBzipfs mount_data\fR ?\fIdata\fR ?\fImountpoint\fR?? @@ -49,6 +49,7 @@ cannot be created. Further, modifications to files are limited to the mounted archive in memory and are not persisted to disk. .PP Paths in mounted archives are case-sensitive on all platforms. +.\" METHOD: canonical .TP \fBzipfs canonical\fR ?\fImountpoint\fR? \fIfilename\fR ?\fIinZipfs\fR? . @@ -57,19 +58,22 @@ mapped into a zipfs mount as its result. If specified, \fImountpoint\fR says within which mount the mapping will be done; if omitted, the main root of the zipfs system is used. The \fIinZipfs\fR argument is a an optional boolean which controls whether to fully canonicalise the name; it defaults to true. +.\" METHOD: exists .TP -\fBzipfs exists\fR \fIfilename\fR +\fBzipfs exists\fI filename\fR . Return 1 if the given filename exists in the mounted zipfs and 0 if it does not. +.\" METHOD: find .TP -\fBzipfs find\fR \fIdirectoryName\fR +\fBzipfs find\fI directoryName\fR . Returns the list of paths under directory \fIdirectoryName\fR which need not be within a zipfs mounted archive. The paths are prefixed with \fIdirectoryName\fR. This command is also used by the \fBzipfs mkzip\fR and \fBzipfs mkimg\fR commands. +.\" METHOD: info .TP -\fBzipfs info\fR \fIfile\fR +\fBzipfs info\fI file\fR . Return information about the given \fIfile\fR in the mounted zipfs. The information consists of: @@ -87,6 +91,7 @@ As a special case, querying the mount point gives the start of the zip data as t in (4), which can be used to truncate the zip information from an executable. Querying an ancestor of a mount point will raise an error. .RE +.\" METHOD: list .TP \fBzipfs list\fR ?(\fB\-glob\fR|\fB\-regexp\fR)? ?\fIpattern\fR? . @@ -101,12 +106,13 @@ ordinary characters in the matching. Thus forward slashes should be used as path separators in the pattern. The returned paths only include those actually in the archive and does not include intermediate directories in mount paths. +.\" METHOD: mount .TP \fBzipfs mount\fR .TP -\fBzipfs mount\fR \fImountpoint\fR +\fBzipfs mount\fI mountpoint\fR .TP -\fBzipfs mount\fR \fIzipfile\fR \fImountpoint\fR ?\fIpassword\fR? +\fBzipfs mount\fI zipfile mountpoint\fR ?\fIpassword\fR? .RS .PP The \fBzipfs mount\fR command mounts ZIP archives as Tcl virtual file systems @@ -137,6 +143,7 @@ uses direct access to the OS rather than through Tcl's filesystem API, it will not see the current directory as being inside the mount and will not be able to access the files inside the mount). .RE +.\" METHOD: root .TP \fBzipfs root\fR . @@ -145,6 +152,7 @@ for the current platform. This value is .QW \fB//zipfs:/\fR on most platforms. +.\" METHOD: unmount .TP \fBzipfs unmount \fImountpoint\fR . @@ -154,8 +162,9 @@ there are any files within the mounted archive are open. .SS "ZIP CREATION COMMANDS" This package also provides several commands to aid the creation of ZIP archives as Tcl applications. +.\" METHOD: mkzip .TP -\fBzipfs mkzip\fR \fIoutfile indir\fR ?\fIstrip\fR? ?\fIpassword\fR? +\fBzipfs mkzip\fI outfile indir\fR ?\fIstrip\fR? ?\fIpassword\fR? . Creates a ZIP archive file named \fIoutfile\fR from the contents of the input directory \fIindir\fR (contained regular files only) with optional ZIP @@ -168,8 +177,9 @@ the whole source directory name or the name of its parent directory. \fBCaution:\fR the choice of the \fIindir\fR parameter (less the optional stripped prefix) determines the later root name of the archive's content. .RE +.\" METHOD: mkimg .TP -\fBzipfs mkimg\fR \fIoutfile indir\fR ?\fIstrip\fR? ?\fIpassword\fR? ?\fIinfile\fR? +\fBzipfs mkimg\fI outfile indir\fR ?\fIstrip\fR? ?\fIpassword\fR? ?\fIinfile\fR? . Creates an image (potentially a new executable file) similar to \fBzipfs mkzip\fR; see that command for a description of most parameters to this @@ -196,20 +206,23 @@ that script has been executed. \fBCaution:\fR highly experimental, not usable on Android, only partially tested on Linux and Windows. .RE +.\" METHOD: mkkey .TP -\fBzipfs mkkey\fR \fIpassword\fR +\fBzipfs mkkey\fI password\fR . Given the clear text \fIpassword\fR argument, an obfuscated string version is returned with the same format used in the \fBzipfs mkimg\fR command. +.\" METHOD: lmkimg .TP -\fBzipfs lmkimg\fR \fIoutfile inlist\fR ?\fIpassword infile\fR? +\fBzipfs lmkimg\fI outfile inlist\fR ?\fIpassword infile\fR? . This command is like \fBzipfs mkimg\fR, but instead of an input directory, \fIinlist\fR must be a Tcl list where the odd elements are the names of files to be copied into the archive in the image, and the even elements are their respective names within that archive. +.\" METHOD: lmkzip .TP -\fBzipfs lmkzip\fR \fIoutfile inlist\fR ?\fIpassword\fR? +\fBzipfs lmkzip\fI outfile inlist\fR ?\fIpassword\fR? . This command is like \fBzipfs mkzip\fR, but instead of an input directory, \fIinlist\fR must be a Tcl list where the odd elements are the names of files @@ -21,24 +21,28 @@ The \fBzlib\fR command provides access to the compression and check-summing facilities of the Zlib library by Jean-loup Gailly and Mark Adler. It has the following subcommands. .SS "COMPRESSION SUBCOMMANDS" +.\" METHOD: compress .TP \fBzlib compress\fI string\fR ?\fIlevel\fR? . Returns the zlib-format compressed binary data of the binary string in \fIstring\fR. If present, \fIlevel\fR gives the compression level to use (from 0, which is uncompressed, to 9, maximally compressed). +.\" METHOD: decompress .TP \fBzlib decompress\fI string\fR ?\fIbufferSize\fR? . Returns the uncompressed version of the raw compressed binary data in \fIstring\fR. If present, \fIbufferSize\fR is a hint as to what size of buffer is to be used to receive the data. +.\" METHOD: deflate .TP \fBzlib deflate\fI string\fR ?\fIlevel\fR? . Returns the raw compressed binary data of the binary string in \fIstring\fR. If present, \fIlevel\fR gives the compression level to use (from 0, which is uncompressed, to 9, maximally compressed). +.\" METHOD: gunzip .TP \fBzlib gunzip\fI string\fR ?\fB\-headerVar \fIvarName\fR? . @@ -80,6 +84,7 @@ named by the \fBfilename\fR field was modified. Suitable for use with . The type of the uncompressed data (\fBbinary\fR or \fBtext\fR) if known. .RE +.\" METHOD: gzip .TP \fBzlib gzip\fI string\fR ?\fB\-level \fIlevel\fR? ?\fB\-header \fIdict\fR? . @@ -118,6 +123,7 @@ will be in the same as is returned by \fBclock seconds\fR or \fBfile mtime\fR. . The type of the data being compressed, being \fBbinary\fR or \fBtext\fR. .RE +.\" METHOD: inflate .TP \fBzlib inflate\fI string\fR ?\fIbufferSize\fR? . @@ -125,6 +131,7 @@ Returns the uncompressed version of the raw compressed binary data in \fIstring\fR. If present, \fIbufferSize\fR is a hint as to what size of buffer is to be used to receive the data. .SS "CHANNEL SUBCOMMAND" +.\" METHOD: push .TP \fBzlib push\fI mode channel\fR ?\fIoptions ...\fR? . @@ -250,6 +257,7 @@ maximum number of bytes ahead to read from the underlying data source. See above for more information. .RE .SS "STREAMING SUBCOMMAND" +.\" METHOD: stream .TP \fBzlib stream\fI mode\fR ?\fIoptions\fR? . @@ -311,11 +319,13 @@ is correct. .VE .RE .SS "CHECKSUMMING SUBCOMMANDS" +.\" METHOD: adler32 .TP \fBzlib adler32\fI string\fR ?\fIinitValue\fR? . Compute a checksum of binary string \fIstring\fR using the Adler-32 algorithm. If given, \fIinitValue\fR is used to initialize the checksum engine. +.\" METHOD: crc32 .TP \fBzlib crc32\fI string\fR ?\fIinitValue\fR? . @@ -330,6 +340,7 @@ the transformed data. .PP The full set of subcommands supported by a streaming instance command, \fIstream\fR, is as follows: +.\" METHOD: add .TP \fIstream \fBadd\fR ?\fIoption...\fR? \fIdata\fR . @@ -337,47 +348,56 @@ A short-cut for .QW "\fIstream \fBput \fR?\fIoption...\fR? \fIdata\fR" followed by .QW "\fIstream \fBget\fR" . +.\" METHOD: checksum .TP \fIstream \fBchecksum\fR . Returns the checksum of the uncompressed data seen so far by this stream. +.\" METHOD: close .TP \fIstream \fBclose\fR . Deletes this stream and frees up all resources associated with it. +.\" METHOD: eof .TP \fIstream \fBeof\fR . Returns a boolean indicating whether the end of the stream (as determined by the compressed data itself) has been reached. Not all formats support detection of the end of the stream. +.\" METHOD: finalize .TP \fIstream \fBfinalize\fR . A short-cut for .QW "\fIstream \fBput \-finalize {}\fR" . +.\" METHOD: flush .TP \fIstream \fBflush\fR . A short-cut for .QW "\fIstream \fBput \-flush {}\fR" . +.\" METHOD: fullflush .TP \fIstream \fBfullflush\fR . A short-cut for .QW "\fIstream \fBput \-fullflush {}\fR" . +.\" METHOD: get .TP \fIstream \fBget \fR?\fIcount\fR? . Return up to \fIcount\fR bytes from \fIstream\fR's internal buffers with the transformation applied. If \fIcount\fR is omitted, the entire contents of the buffers are returned. -. +.\" METHOD: header +.TP \fIstream \fBheader\fR . Return the gzip header description dictionary extracted from the stream. Only supported for streams created with their \fImode\fR parameter set to \fBgunzip\fR. +.\" METHOD: put .TP \fIstream \fBput\fR ?\fIoption...\fR? \fIdata\fR . @@ -429,6 +449,7 @@ This option is mutually exclusive with the \fB\-finalize\fR and \fB\-flush\fR options. .RE .RE +.\" METHOD: reset .TP \fIstream \fBreset\fR . |