1base64(n)            Text encoding & decoding binary data            base64(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       base64 - base64-encode/decode binary data
9

SYNOPSIS

11       package require Tcl  8
12
13       package require base64  ?2.5?
14
15       ::base64::encode ?-maxlen maxlen? ?-wrapchar wrapchar? string
16
17       ::base64::decode string
18
19______________________________________________________________________________
20

DESCRIPTION

22       This  package provides procedures to encode binary data into base64 and
23       back.
24

BEWARE: VARIATIONS IN DECODING BEHAVIOUR

26       The Tcl core provides since version 8.6 commands for the de- and encod‐
27       ing of base64 data. These are
28
29
30                  binary encode base64
31                  binary decode base64
32
33
34       Beware that while these are signature compatible with the commands pro‐
35       vided by this package, the decoders are not behaviourally compatible.
36
37       The core decoder command accepts the option -strict, enabling the  user
38       to  choose  between  strict  and  lax modes. In the strict mode invalid
39       characters, and partial data at the end of the input  are  reported  as
40       errors. In lax mode they are ignored.
41
42       All  the implementations provided by this package on the other hand im‐
43       plement a mix of the above, and the user cannot choose. Partial data at
44       the  end  of the input is reported as error, and invalid characters are
45       ignored.
46
47       Beware of these differences when switching code from one to other.
48

API

50       ::base64::encode ?-maxlen maxlen? ?-wrapchar wrapchar? string
51              Base64 encodes the given binary string and returns  the  encoded
52              result.  Inserts  the character wrapchar every maxlen characters
53              of output. wrapchar defaults to newline. maxlen defaults to 76.
54
55              Note that if maxlen is set to 0, the output will not be  wrapped
56              at all.
57
58              Note well: If your string is not simple ASCII you should fix the
59              string encoding before doing base64 encoding. See the examples.
60
61              The command will throw an error for negative values  of  maxlen,
62              or if maxlen is not an integer number.
63
64       ::base64::decode string
65              Base64  decodes  the  given  string and returns the binary data.
66              The decoder ignores whitespace in the string.
67

IMPLEMENTATION NOTES

69       This package contains three different implementations  for  base64  de-
70       and  encoding, and chooses among them based on the environment it finds
71       itself in.
72
73       All three implementations have the same behaviour.   See  also  Beware:
74       Variations in decoding behaviour at the beginning of this document.
75
76       [1]    If  Tcl  8.6  or higher is found the commands are implemented in
77              terms of the then-available builtin commands.
78
79       [2]    If the Trf extension cand be loaded the commands are implemented
80              in terms of its commands.
81
82       [3]    If  neither  of the above are possible a pure Tcl implementation
83              is used. This is of course much slower.
84

EXAMPLES

86              % base64::encode "Hello, world"
87              SGVsbG8sIHdvcmxk
88
89
90
91              % base64::encode [string repeat xyz 20]
92              eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6
93              eHl6eHl6eHl6
94              % base64::encode -wrapchar "" [string repeat xyz 20]
95              eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6
96
97
98
99              # NOTE: base64 encodes BINARY strings.
100              % set chemical [encoding convertto utf-8 "C\u2088H\u2081\u2080N\u2084O\u2082"]
101              % set encoded [base64::encode $chemical]
102              Q+KCiEjigoHigoBO4oKET+KCgg==
103              % set caffeine [encoding convertfrom utf-8 [base64::decode $encoded]]
104
105

BUGS, IDEAS, FEEDBACK

107       This document, and the package it describes, will  undoubtedly  contain
108       bugs  and other problems.  Please report such in the category base64 of
109       the  Tcllib  Trackers  [http://core.tcl.tk/tcllib/reportlist].   Please
110       also  report any ideas for enhancements you may have for either package
111       and/or documentation.
112
113       When proposing code changes, please provide unified diffs, i.e the out‐
114       put of diff -u.
115
116       Note  further  that  attachments  are  strongly  preferred over inlined
117       patches. Attachments can be made by going  to  the  Edit  form  of  the
118       ticket  immediately  after  its  creation, and then using the left-most
119       button in the secondary navigation bar.
120

KEYWORDS

122       base64, encoding
123

CATEGORY

125       Text processing
126

128       Copyright (c) 2000, Eric Melski
129       Copyright (c) 2001, Miguel Sofer
130
131
132
133
134tcllib                                2.5                            base64(n)
Impressum