1[manpage_begin base64 n 2.4.2]
2[keywords base64]
3[keywords encoding]
4[copyright {2000, Eric Melski}]
5[copyright {2001, Miguel Sofer}]
6[moddesc   {Text encoding & decoding binary data}]
7[titledesc {base64-encode/decode binary data}]
8[category  {Text processing}]
9[require Tcl 8]
10[require base64 [opt 2.4.2]]
11[description]
12[para]
13
14This package provides procedures to encode binary data into base64 and back.
15
16[list_begin definitions]
17
18[call [cmd ::base64::encode] [opt "[option -maxlen] [arg maxlen]"] [opt "[option -wrapchar] [arg wrapchar]"] [arg string]]
19
20Base64 encodes the given binary [arg string] and returns the encoded
21result. Inserts the character [arg wrapchar] every [arg maxlen]
22characters of output. [arg wrapchar] defaults to newline. [arg maxlen]
23defaults to [const 76].
24
25[para] [emph Note] that if [arg maxlen] is set to [const 0], the
26output will not be wrapped at all.
27
28[para]
29
30[emph {Note well}]: If your string is not simple ascii you should fix
31the string encoding before doing base64 encoding. See the examples.
32
33[para]
34
35The command will throw an error for negative values of [arg maxlen],
36or if [arg maxlen] is not an integer number.
37
38[call [cmd ::base64::decode] [arg "string"]]
39
40Base64 decodes the given [arg "string"] and returns the binary data.
41The decoder ignores whitespace in the string.
42
43[list_end]
44
45[section {EXAMPLES}]
46
47[example {
48% base64::encode "Hello, world"
49SGVsbG8sIHdvcmxk
50}]
51
52[example {
53% base64::encode [string repeat xyz 20]
54eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6
55eHl6eHl6eHl6
56% base64::encode -wrapchar "" [string repeat xyz 20]
57eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6
58}]
59
60[example {
61# NOTE: base64 encodes BINARY strings.
62% set chemical [encoding convertto utf-8 "C\u2088H\u2081\u2080N\u2084O\u2082"]
63% set encoded [base64::encode $chemical]
64Q+KCiEjigoHigoBO4oKET+KCgg==
65% set caffeine [encoding convertfrom utf-8 [base64::decode $encoded]]
66}]
67
68[vset CATEGORY base64]
69[include ../common-text/feedback.inc]
70[manpage_end]
71