diff options
| -rw-r--r-- | ChangeLog | 5 | ||||
| -rw-r--r-- | doc/binary.n | 96 |
2 files changed, 99 insertions, 2 deletions
@@ -1,3 +1,8 @@ +2008-10-07 Donal K. Fellows <dkf@users.sf.net> + + * doc/binary.n: Added better documentation of the [binary encode] and + [binary decode] subcommands. + 2008-10-07 Miguel Sofer <msofer@users.sf.net> * generic/tclBasic.c: Move [tailcall], [coroutine] and diff --git a/doc/binary.n b/doc/binary.n index a850205..b3147cb 100644 --- a/doc/binary.n +++ b/doc/binary.n @@ -1,10 +1,11 @@ '\" '\" Copyright (c) 1997 by Sun Microsystems, Inc. +'\" Copyright (c) 2008 by 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: binary.n,v 1.40 2008/09/10 22:48:41 dkf Exp $ +'\" RCS: @(#) $Id: binary.n,v 1.41 2008/10/07 22:31:42 dkf Exp $ '\" .so man.macros .TH binary n 8.0 Tcl "Tcl Built-In Commands" @@ -40,7 +41,86 @@ messages for example). .SH "BINARY ENCODE AND DECODE" .VS 8.6 .PP -\fIFIXME!\fR +When encoding binary data as a readable string, the starting binary data is +passed to the \fBbinary encode\fR command, together with the name of the +encoding to use and any encoding-specific options desired. Data which has been +encoded can be converted back to binary form using \fBbinary decode\fR. The +following formats and options are supported. +.TP +\fBbase64\fR +. +The \fBbase64\fB binary encoding is commonly used in mail messages and XML +documents, and uses mostly upper and lower case letters and digits. It has the +distinction of being able to be rewrapped arbitrarily without losing +information. +.RS +.PP +During encoding, the following options are supported: +.TP +\fB\-maxlen \fIlength\fR +. +Indicates that the output should be split into lines of no more than +\fIlength\fR characters. By default, lines are not split. +.TP +\fB\-wrapchar \fIcharacter\fR +. +Indicates that, when lines are split because of the \fB\-maxlen\fR option, +\fIcharacter\fR should be used to separate lines. By default, this is a +newline character, +.QW \en . +.PP +During decoding, the following options are supported: +.TP +\fB\-strict\fR +. +Instructs the decoder to throw an error if it encounters any characters that +are not strictly part of the encoding itself. Otherwise it ignores them. +.RE +.TP +\fBhex\fR +. +The \fBhex\fR binary encoding converts each byte to a pair of hexadecimal +digits in big-endian form. +.RS +.PP +No options are supported during encoding. During decoding, the following +options are supported: +.TP +\fB\-strict\fR +. +Instructs the decoder to throw an error if it encounters any characters that +are not strictly part of the encoding itself. Otherwise it ignores them. +.RE +.TP +\fBuuencode\fR +. +The \fBuuencode\fR binary encoding used to be common for transfer of data +between Unix systems and on USENET, but is less common these days, having been +largely superceded by the \fBbase64\fR binary encoding. +.RS +.PP +During encoding, the following options are supported: +'\" This is wrong! The uuencode format had more complexity than this! +.TP +\fB\-maxlen \fIlength\fR +. +Indicates that the output should be split into lines of no more than +\fIlength\fR characters. By default, lines are not split. +.TP +\fB\-wrapchar \fIcharacter\fR +. +Indicates that, when lines are split because of the \fB\-maxlen\fR option, +\fIcharacter\fR should be used to separate lines. By default, this is a +newline character, +.QW \en . +.PP +During decoding, the following options are supported: +.TP +\fB\-strict\fR +. +Instructs the decoder to throw an error if it encounters any characters that +are not strictly part of the encoding itself. Otherwise it ignores them. +.RE .VE 8.6 .SH "BINARY FORMAT" .PP @@ -798,7 +878,19 @@ proc \fIreadString\fR {channel} { return [encoding convertfrom utf-8 $data] } .CE +.PP +This converts the contents of a file (named in the variable \fIfilename\fR) to +base64 and prints them: +.CS +set f [open $filename rb] +set data [read $f] +close $f +puts [\fBbinary encode\fR base64 \-maxlen 64 $data] +.CE .SH "SEE ALSO" format(n), scan(n), tclvars(n) .SH KEYWORDS binary, format, scan +'\" Local Variables: +'\" mode: nroff +'\" End: |