Added more examples

1 files changed, 34 insertions, 2 deletions

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