Manual of Lua-DataFilter: base64

base64_encode and base64_decode - DataFilter algorithms for Base64 encoding and decoding

Overview

These two algorithms are part of the Lua-DataFilter package. See the overview documentation in lua-datafilter(3) for information about how to use them.

Default behaviour of base64_encode

base64_encode will produce a continuous stream of US-ASCII characters encoding the input data as Base64, using the standard alphabet (the uppercase letters A–Z, the lowercase letters a–z, the digits 0–9, and the characters + and /).

There will be no line breaks in the output, even at the end.

Padding = characters will be added at the end of the output if necessary to make it a multiple of four characters long.

Options for base64_encode

The following options are available to modify the default behaviour:

include_padding

This is true by default, but setting it to false will cause the padding = characters not to be put on the end of the output.

line_ending

This should be a string. If supplied it will be added to the encoded output after a line reaches a certain length. The default maximum line length is 76 characters, which is suitable for use in email.

max_line_length

This should be a number greater than zero. It will cause the output to be broken into lines no longer than the given number of characters. If the line_ending option isn't given, the lines will be terminated with a carriage return followed by a line feed (characters 13 and 10).

If you want to break the encoded data into lines, setting either of line_ending or max_line_length is sufficient. A line break will be added at the end of the file however long the last line is.

Default behaviour of base64_decode

Whitespace characters will be ignored on input, but any other characters not in the standard Base64 alphabet will cause an exception to be thrown.

If the number of padding = characters found at the end of the input is not correct, then an exception will be thrown.

Errors are always produced if padding = characters occur anywhere but at the end of the input (not including whitespace), or if the last character of input contains bits set which should just be padding bits, or if there is a final block of only one character (which isn't enough to encode a byte of output).

Options for base64_decode

The following options are available to modify the default behaviour:

allow_whitespace

Set this to false to cause an exception to be thrown if any whitespace characters are found in the input.

allow_invalid_characters

Set this to false to prevent errors from input containing characters outside the Base64 alphabet. They will be silently ignored. Even with this setting, padding characters occurring where they shouldn't will still cause an error.

allow_missing_padding

Setting this to true will silence the error which would normally be produced if the padding = characters are missing from the input.