diff options
| author | griffin <briang42@easystreet.net> | 2023-05-24 23:17:17 (GMT) |
|---|---|---|
| committer | griffin <briang42@easystreet.net> | 2023-05-24 23:17:17 (GMT) |
| commit | ba261e8e87cd9fb904172ca5a43fadb8f163666a (patch) | |
| tree | 07f644f0eb19d93b953c156179e27db3c292384f /doc | |
| parent | c3f8318a3f328bd39244bc8f88ed606848ec5b85 (diff) | |
| parent | 231fd112f959c258117188b044681643f30129f1 (diff) | |
| download | tcl-ba261e8e87cd9fb904172ca5a43fadb8f163666a.zip tcl-ba261e8e87cd9fb904172ca5a43fadb8f163666a.tar.gz tcl-ba261e8e87cd9fb904172ca5a43fadb8f163666a.tar.bz2 | |
merge trunk
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Thread.3 | 2 | ||||
| -rw-r--r-- | doc/chan.n | 19 | ||||
| -rw-r--r-- | doc/close.n | 21 | ||||
| -rw-r--r-- | doc/configurable.n | 2 | ||||
| -rw-r--r-- | doc/link.n | 14 | ||||
| -rw-r--r-- | doc/lremove.n | 2 | ||||
| -rw-r--r-- | doc/lseq.n | 130 |
7 files changed, 118 insertions, 72 deletions
diff --git a/doc/Thread.3 b/doc/Thread.3 index 51df5bb..c59a8dd 100644 --- a/doc/Thread.3 +++ b/doc/Thread.3 @@ -69,7 +69,7 @@ This procedure will act as the \fBmain()\fR of the newly created thread. The specified \fIclientData\fR will be its sole argument. .AP void *clientData in Arbitrary information. Passed as sole argument to the \fIproc\fR. -.AP int stackSize in +.AP size_t stackSize in The size of the stack given to the new thread. .AP int flags in Bitmask containing flags allowing the caller to modify behavior of @@ -55,7 +55,9 @@ channel is flushed in the background before finally being closed. .PP \fBchan close\fR may return an error if an error occurs while flushing output. If a process in a command pipeline created by \fBopen\fR returns an -error, \fBchan close\fR generates an error in the same manner as \fBexec\fR. +error (either by returning a non-zero exit code or writing to its standard +error file descriptor), \fBchan close\fR generates an error in the same +manner as \fBexec\fR. .PP Closing one side of a socket or command pipeline may lead to the shutdown() or close() of the underlying system resource, leading to a reaction from whatever @@ -70,6 +72,17 @@ description of channel sharing. .PP When the last interpreter sharing a channel is destroyed, the channel is switched to blocking mode and fully flushed and then closed. +.PP +Channels are automatically closed when an interpreter is destroyed and +when the process exits. +From 8.6 on (TIP#398), nonblocking channels are no longer switched to +blocking mode when exiting; this guarantees a timely exit even when the +peer or a communication channel is stalled. To ensure proper flushing of +stalled nonblocking channels on exit, one must now either (a) actively +switch them back to blocking or (b) use the environment variable +\fBTCL_FLUSH_NONBLOCKING_ON_EXIT\fR, which when set and not equal to +.QW \fB0\fR +restores the previous behavior. .RE .TP \fBchan configure \fIchannelName\fR ?\fIoptionName\fR? ?\fIvalue\fR? ?\fIoptionName value\fR?... @@ -348,8 +361,8 @@ first words of a command that provides the interface for a \fBrefchan\fR. \fBImode\fR is a list of one or more of the strings .QW \fBread\fR or -.QW \fBwrite\fR -, indicating whether the channel is a read channel, a write channel, or both. +.QW \fBwrite\fR , +indicating whether the channel is a read channel, a write channel, or both. It is an error if the handler does not support the chosen mode. .PP The handler is called as needed from the global namespace at the top level, and diff --git a/doc/close.n b/doc/close.n index 3d18aea..2066583 100644 --- a/doc/close.n +++ b/doc/close.n @@ -12,11 +12,12 @@ .SH NAME close \- Close an open channel .SH SYNOPSIS -\fBclose \fIchannelId\fR ?r(ead)|w(rite)? +\fBclose \fIchannelId\fR ?\fBr\fR(\fBead\fR)|\fBw\fR(\fBrite\fR)? .BE .SH DESCRIPTION .PP -Closes or half-closes the channel given by \fIchannelId\fR. +Closes or half-closes the channel given by \fIchannelId\fR. \fBchan close\fR +is another name for this command. .PP \fIChannelId\fR must be an identifier for an open channel such as a Tcl standard channel (\fBstdin\fR, \fBstdout\fR, or \fBstderr\fR), @@ -49,12 +50,20 @@ When the last interpreter in which the channel is registered invokes .PP Channels are automatically closed when an interpreter is destroyed and when the process exits. -From 8.6 on (TIP#398), nonblocking channels are no longer switched to blocking mode when exiting; this guarantees a timely exit even when the peer or a communication channel is stalled. To ensure proper flushing of stalled nonblocking channels on exit, one must now either (a) actively switch them back to blocking or (b) use the environment variable TCL_FLUSH_NONBLOCKING_ON_EXIT, which when set and not equal to "0" restores the previous behavior. +From 8.6 on (TIP#398), nonblocking channels are no longer switched to +blocking mode when exiting; this guarantees a timely exit even when the +peer or a communication channel is stalled. To ensure proper flushing of +stalled nonblocking channels on exit, one must now either (a) actively +switch them back to blocking or (b) use the environment variable +\fBTCL_FLUSH_NONBLOCKING_ON_EXIT\fR, which when set and not equal to +.QW \fB0\fR +restores the previous behavior. .PP The command returns an empty string, and may generate an error if an error occurs while flushing output. If a command in a command -pipeline created with \fBopen\fR returns an error, \fBclose\fR -generates an error (similar to the \fBexec\fR command.) +pipeline created with \fBopen\fR returns an error (either by returning a +non-zero exit code or writing to its standard error file descriptor), +\fBclose\fR generates an error (similar to the \fBexec\fR command.) .PP The two-argument form is a .QW "half-close" : @@ -95,7 +104,7 @@ proc withOpenFile {filename channelVar script} { } .CE .SH "SEE ALSO" -file(n), open(n), socket(n), eof(n), Tcl_StandardChannels(3) +chan(n), file(n), open(n), socket(n), eof(n), Tcl_StandardChannels(3) .SH KEYWORDS blocking, channel, close, nonblocking, half-close '\" Local Variables: diff --git a/doc/configurable.n b/doc/configurable.n index 6477894..a138c33 100644 --- a/doc/configurable.n +++ b/doc/configurable.n @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -.TH configurable n 0.1 TclOO "TclOO Commands" +.TH configurable n 0.4 TclOO "TclOO Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! @@ -52,11 +52,11 @@ oo::class create ABC { constructor {} { \fBlink\fR Foo - # The method foo is now directly accessible as foo here + # The method Foo is now directly accessible as Foo here \fBlink\fR {bar Foo} - # The method foo is now directly accessible as bar + # The method Foo is now directly accessible as bar \fBlink\fR {::ExternalCall Foo} - # The method foo is now directly accessible in the global + # The method Foo is now directly accessible in the global # namespace as ExternalCall } @@ -71,13 +71,13 @@ oo::class create ABC { ABC create abc abc grill \fI\(-> Step 1:\fR - \fI\(-> This is foo in ::abc\fR + \fI\(-> This is Foo in ::abc\fR \fI\(-> Step 2:\fR - \fI\(-> This is foo in ::abc\fR + \fI\(-> This is Foo in ::abc\fR # Direct access via the linked command puts "Step 3:"; ExternalCall \fI\(-> Step 3:\fR - \fI\(-> This is foo in ::abc\fR + \fI\(-> This is Foo in ::abc\fR .CE .PP This example shows that multiple linked commands can be made in a call to @@ -88,7 +88,7 @@ oo::class create Ex { constructor {} { \fBlink\fR a b c # The methods a, b, and c (defined below) are all now - # directly acessible within methods under their own names. + # directly accessible within methods under their own names. } method a {} { diff --git a/doc/lremove.n b/doc/lremove.n index 8763ea6..bd4a5eb 100644 --- a/doc/lremove.n +++ b/doc/lremove.n @@ -16,7 +16,7 @@ lremove \- Remove elements from a list by index .SH DESCRIPTION .PP \fBlremove\fR returns a new list formed by simultaneously removing zero or -more elements of \fIlist\fR at each of the indices given by an arbirary number +more elements of \fIlist\fR at each of the indices given by an arbitrary number of \fIindex\fR arguments. The indices may be in any order and may be repeated; the element at index will only be removed once. The index values are interpreted the same as index values for the command \fBstring index\fR, @@ -11,85 +11,109 @@ .SH NAME 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 \fR?(\fB..\fR|\fBto\fR)? \fIend\fR ??\fBby\fR? \fIstep\fR? -\fBlseq \fIStart \fBcount\fR \fICount\fR ??\fBby\fR? \fIStep\fR? +\fBlseq \fIstart \fBcount\fR \fIcount\fR ??\fBby\fR? \fIstep\fR? -\fBlseq \fICount\fR ?\fBby \fIStep\fR? +\fBlseq \fIcount\fR ?\fBby \fIstep\fR? .BE .SH DESCRIPTION .PP The \fBlseq\fR command creates a sequence of numeric values using the given -parameters \fIStart\fR, \fIEnd\fR, and \fIStep\fR. The \fIoperation\fR -argument ".." or "to" defines the range. The "count" option is used -to define a count of the number of elements in the list. A short form use of -the command, with a -single count value, will create a range from 0 to count-1. - -The \fBlseq\fR command can produce both increasing and decreasing sequences. When -both Start and End are provided without a Step value, then if Start <= End, -the sequence will be increasing and if Start > End it will be decreasing. If a -Step vale is included, it's sign should agree with the direction of the +parameters \fIstart\fR, \fIend\fR, and \fIstep\fR. The \fIoperation\fR +argument "\fB..\fR" or "\fBto\fR" defines the range. The "\fBcount\fR" option +is used to define a count of the number of elements in the list. A short form +use of the command, with a single count value, will create a range from 0 to +count-1. + +The \fBlseq\fR command can produce both increasing and decreasing +sequences. When both \fIstart\fR and \fIend\fR are provided without a +\fIstep\fR value, then if \fIstart\fR <= \fIend\fR, the sequence will be +increasing and if \fIstart\fR > \fIend\fR it will be decreasing. If a +\fIstep\fR vale is included, it's sign should agree with the direction of the sequence (descending -> negative and ascending -> positive), otherwise an empty list is returned. For example: .CS \" - % lseq 1 to 5 ;# increasing - 1 2 3 4 5 +% \fBlseq\fR 1 to 5 ;# increasing +\fI\(-> 1 2 3 4 5 - % lseq 5 to 1 ;# decreasing - 5 4 3 2 1 +% \fBlseq\fR 5 to 1 ;# decreasing +\fI\(-> 5 4 3 2 1 - % lseq 6 to 1 by 2 ;# decreasing, step wrong sign, empty list +% \fBlseq\fR 6 to 1 by 2 ;# decreasing, step wrong sign, empty list - % lseq 1 to 5 by 0 ;# all step sizes of 0 produce an empty list +% \fBlseq\fR 1 to 5 by 0 ;# all step sizes of 0 produce an empty list +.\" +.CE +The numeric arguments, \fIstart\fR, \fIend\fR, \fIstep\fR, and \fIcount\fR, +may also be a valid expression. The expression will be evaluated and the +numeric result will be used. An expression that does not evaluate to a number +will produce an invalid argument error. +.PP +\fIStart\fR defines the initial value and \fIend\fR defines the limit, not +necessarily the last value. \fBlseq\fR produces a list with \fIcount\fR +elements, and if \fIcount\fR is not supplied, it is computed as + +.CS \" + \fIcount\fR = int( (\fIend\fR - \fIstart\fR + \fIstep\fR) / \fIstep\fR ) .\" .CE -The numeric arguments, \fIStart\fR, \fIEnd\fR, \fIStep\fR, and \fICount\fR, -may also be a valid expression. The expression will be evaluate and the -numeric result be used. An expression that does not evaluate to a number will -produce an invalid argument error. +.PP +The numeric arguments, \fIstart\fR, \fIend\fR, \fIstep\fR, and \fIcount\fR, +can also be a valid expression. the \fBlseq\fR command will evaluate the +expression (as if with \fBexpr\fR) +and use the numeric result, or return an error as with any invalid argument +value; a non-numeric expression result will result in an error. .SH EXAMPLES .CS .\" +\fBlseq\fR 3 +\fI\(-> 0 1 2\fR - lseq 3 - \(-> 0 1 2 - - lseq 3 0 - \(-> 3 2 1 0 +\fBlseq\fR 3 0 +\fI\(-> 3 2 1 0\fR - lseq 10 .. 1 by -2 - \(-> 10 8 6 4 2 +\fBlseq\fR 10 .. 1 by -2 +\fI\(-> 10 8 6 4 2\fR - set l [lseq 0 -5] - \(-> 0 -1 -2 -3 -4 -5 +set l [\fBlseq\fR 0 -5] +\fI\(-> 0 -1 -2 -3 -4 -5\fR - foreach i [lseq [llength $l]] { - puts l($i)=[lindex $l $i] - } - \(-> l(0)=0 - l(1)=-1 - l(2)=-2 - l(3)=-3 - l(4)=-4 - l(5)=-5 - - foreach i [lseq [llength $l]-1 0] { +foreach i [\fBlseq\fR [llength $l]] { + puts l($i)=[lindex $l $i] +} +\fI\(-> l(0)=0\fR +\fI\(-> l(1)=-1\fR +\fI\(-> l(2)=-2\fR +\fI\(-> l(3)=-3\fR +\fI\(-> l(4)=-4\fR +\fI\(-> l(5)=-5\fR + +foreach i [\fBlseq\fR {[llength $l]-1} 0] { puts l($i)=[lindex $l $i] - } - \(-> l(5)=-5 - l(4)=-4 - l(3)=-3 - l(2)=-2 - l(1)=-1 - l(0)=0 - - set sqrs [lmap i [lseq 1 10] {expr $i*$i}] - \(-> 1 4 9 16 25 36 49 64 81 100 +} +\fI\(-> l(5)=-5\fR +\fI\(-> l(4)=-4\fR +\fI\(-> l(3)=-3\fR +\fI\(-> l(2)=-2\fR +\fI\(-> l(1)=-1\fR +\fI\(-> l(0)=0\fR + +set i 17 + \fI\(-> 17\fR +if {$i in [\fBlseq\fR 0 50]} { # equivalent to: (0 <= $i && $i <= 50) + puts "Ok" +} else { + puts "outside :(" +} +\fI\(-> Ok\fR + +set sqrs [lmap i [\fBlseq\fR 1 10] { expr {$i*$i} }] +\fI\(-> 1 4 9 16 25 36 49 64 81 100\fR .\" .CE .SH "SEE ALSO" |