From 8a37e6f38645afc534c9f7f45d2b90c0c3f87ee5 Mon Sep 17 00:00:00 2001 From: dkf Date: Thu, 16 Nov 2006 09:34:17 +0000 Subject: Added more examples --- ChangeLog | 21 ++++++++++++--------- doc/apply.n | 62 ++++++++++++++++++++++++++++++++++++++++++++----------------- doc/chan.n | 36 +++++++++++++++++++++++++++++++++-- 3 files changed, 91 insertions(+), 28 deletions(-) diff --git a/ChangeLog b/ChangeLog index c5de807..6beb789 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,7 @@ +2006-11-16 Donal K. Fellows + + * doc/apply.n, doc/chan.n: Added examples. + 2006-11-15 Don Porter TIP#270 IMPLEMENTATION @@ -5,7 +9,7 @@ * generic/tcl.decls: New public routines Tcl_ObjPrintf, * generic/tclStringObj.c: Tcl_AppendObjToErrorInfo, Tcl_Format, * generic/tclInt.h: Tcl_AppendLimitedToObj, - Tcl_AppendFormatToObj and Tcl_AppendPrintfToObj. Former internal + Tcl_AppendFormatToObj and Tcl_AppendPrintfToObj. Former internal versions removed. * generic/tclDecls.h: make genstubs @@ -33,12 +37,11 @@ * unix/tclUnixFCmd.c: * tools/genStubs.tcl: Updated script to no longer produce the - _ANSI_ARGS_ wrapper in generated declarations. Also revised to - accept variadic prototypes with more than one fixed argument. - (This is possible since TCL_VARARGS and its limitations are no - longer in use). - * generic/tcl.h: Some reordering so that macro definitions - do not interfere with the now _ANSI_ARGS_-less stub declarations. + _ANSI_ARGS_ wrapper in generated declarations. Also revised to accept + variadic prototypes with more than one fixed argument. (This is + possible since TCL_VARARGS and its limitations are no longer in use). + * generic/tcl.h: Some reordering so that macro definitions do + not interfere with the now _ANSI_ARGS_-less stub declarations. * generic/tclDecls.h: make genstubs * generic/tclIntDecls.h: @@ -71,8 +74,8 @@ * generic/tclIO.c: When [gets] on a binary channel needs to use the "iso8859-1" encoding, save a copy of that encoding per-thread to - avoid repeated freeing and re-loading of it from the file system. - This replaces the cached copy of this encoding that the platform + avoid repeated freeing and re-loading of it from the file system. This + replaces the cached copy of this encoding that the platform initialization code used to keep in pre-8.5 releases. 2006-11-13 Daniel Steffen diff --git a/doc/apply.n b/doc/apply.n index 31099ce..1e69e69 100644 --- a/doc/apply.n +++ b/doc/apply.n @@ -1,4 +1,7 @@ '\" +'\" Copyright (c) 2006 Miguel Sofer +'\" Copyright (c) 2006 Donal K. Fellows +'\" .so man.macros .TH apply n "" Tcl "Tcl Built-In Commands" .BS @@ -8,7 +11,6 @@ apply \- Apply an anonymous function .SH SYNOPSIS \fBapply \fIfunc\fR ?\fIarg1 arg2 ...\fR? .BE - .SH DESCRIPTION .PP The command \fBapply\fR applies the function \fIfunc\fR to the arguments @@ -44,24 +46,50 @@ with '::'. The semantics of \fBapply\fR can also be described by: .PP .CS - proc apply {fun args} { - set len [llength $fun] - if {($len < 2) || ($len > 3)} { - error "can't interpret \\"$fun\\" as anonymous function" - } - lassign $fun argList body ns - set name ::$ns::[getGloballyUniqueName] - set body0 { - rename [lindex [info level 0] 0] {} - } - proc $name $argList ${body0}$body - set code [catch {uplevel 1 $name $args} res opt] - return -options $opt $res - } +proc apply {fun args} { + set len [llength $fun] + if {($len < 2) || ($len > 3)} { + error "can't interpret \\"$fun\\" as anonymous function" + } + lassign $fun argList body ns + set name ::$ns::[getGloballyUniqueName] + set body0 { + rename [lindex [info level 0] 0] {} + } + proc $name $argList ${body0}$body + set code [catch {uplevel 1 $name $args} res opt] + return -options $opt $res +} +.CE +.SH EXAMPLES +This shows how to make a simple general command that applies a transformation +to each element of a list. +.CS +proc map {lambda list} { + set result {} + foreach $item $list { + lappend result [\fBapply\fR $lambda $item] + } + return $result +} +map {x {return [string length $x]:$x}} {a bb ccc dddd} + \fI=> 1:a 2:bb 3:ccc 4:dddd\fR +map {x {expr {$x**2 + 3*$x - 2}}} {-4 -3 -2 -1 0 1 2 3 4} + \fI=> 2 -2 -4 -4 -2 2 8 16 26\fR +.CE +.PP +The \fBapply\fR command is also useful for defining callbacks for use in the +\fBtrace\fR command: +.CS +set vbl "123abc" +trace add variable vbl write {\fBapply\fR {v1 v2 op} { + upvar 1 $v1 v + puts "updated variable to \\"$v\\"" +}} +set vbl 123 +set vbl abc .CE - .SH "SEE ALSO" proc(n), uplevel(n) - .SH KEYWORDS argument, procedure, anonymous function diff --git a/doc/chan.n b/doc/chan.n index 34b3cfa..6b912c1 100644 --- a/doc/chan.n +++ b/doc/chan.n @@ -1,10 +1,10 @@ '\" -'\" Copyright (c) 2005 Donal K. Fellows +'\" Copyright (c) 2005-2006 Donal K. Fellows '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: chan.n,v 1.5 2006/11/15 09:23:01 dkf Exp $ +'\" RCS: @(#) $Id: chan.n,v 1.6 2006/11/16 09:34:17 dkf Exp $ .so man.macros .TH chan n 8.5 Tcl "Tcl Built-In Commands" .BS @@ -673,6 +673,38 @@ Sets the byte length of the underlying data stream for the channel named \fIchannelId\fR to be \fIlength\fR (or to the current byte offset within the underlying data stream if \fIlength\fR is omitted). The channel is flushed before truncation. +.SH EXAMPLE +This opens a file using a known encoding (CP1252, a very common encoding +on Windows), searches for a string, rewrites that part, and truncates the +file after a further two lines. +.CS +set f [open somefile.txt r+] +\fBchan configure\fR $f -encoding cp1252 +set offset 0 + +\fI# Search for string "FOOBAR" in the file\fR +while {[\fBchan gets\fR $f line] >= 0} { + set idx [string first FOOBAR $line] + if {$idx > -1} { + \fI# Found it; rewrite line\fR + + \fBchan seek\fR $f [expr {$offset + $idx}] + \fBchan puts\fR -nonewline $f BARFOO + + \fI# Skip to end of following line, and truncate\fR + \fBchan gets\fR $f + \fBchan gets\fR $f + \fBchan truncate\fR $f + + \fI# Stop searching the file now\fR + break + } + + \fI# Save offset of start of next line for later\fR + set offset [\fBchan tell\fR $f] +} +\fBchan close\fR $f +.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), -- cgit v0.12