Added more examples

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  <dkf@users.sf.net>
+
+	* doc/apply.n, doc/chan.n: Added examples.
+
 2006-11-15  Don Porter  <dgp@users.sourceforge.net>
 
 	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  <das@users.sourceforge.net>
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),