Added more examples

2 files changed, 79 insertions, 19 deletions

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),