std/string/quoted_printable

=encoding utf8

=head1 NAME

std/string/quoted_printable - Quoted-printable encoders and decoders.

=head1 SYNOPSIS

  from std/string/quoted_printable import encode, decode;

  let raw := to_binary( "Hello, world!\r\n" );

  let text := encode(raw);
  let bytes := decode(text);

  let binary_text := encode(raw, binary: true);
  let short_lines := encode(raw, line_length: 40, newline: "\n");

=head1 IMPLEMENTATION SUPPORT

This module is supported by all implementations of ZuzuScript.

=head1 DESCRIPTION

This module provides quoted-printable encoding and decoding helpers for
RFC 2045-style byte transport. Encoding returns ASCII C<String> text.
Decoding returns a C<BinaryString>, because quoted-printable is a byte
transfer encoding rather than a Unicode text format.

The C<binary> option controls how input line break bytes are encoded.
In the default non-binary mode, CRLF, CR, and LF bytes are normalized to
the configured C<newline> string. In binary mode, CR and LF bytes are
encoded as C<=0D> and C<=0A>.

=head1 EXPORTS

=head2 Functions

=over

=item * C<encode(BinaryString bytes, ... PairList options)>

Parameters: C<bytes> is binary input data and C<options> controls
encoding. Returns: C<String>. Encodes C<bytes> as quoted-printable ASCII
text.

=item * C<decode(String text, ... PairList options)>

Parameters: C<text> is quoted-printable text and C<options> controls
strictness. Returns: C<BinaryString>. Decodes quoted-printable text into
bytes.

=back

=head1 OPTIONS

=over

=item * C<line_length>

Maximum encoded line length. Defaults to C<76> and must be at least
C<4>.

=item * C<newline>

Output newline for hard line breaks and encoded soft breaks. Defaults
to CRLF.

=item * C<binary>

When true, encode CR and LF bytes as C<=0D> and C<=0A>. Defaults to
false.

=item * C<strict>

When true, malformed quoted-printable escape sequences throw during
decoding. Non-strict decoding preserves malformed escape text
literally.

=back

=head1 COPYRIGHT AND LICENCE

B<< std/string/quoted_printable >> is copyright Toby Inkster.

It is free software; you may redistribute it and/or modify it under
the terms of either the Artistic License 1.0 or the GNU General Public
License version 2.

=cut


let encode := null;
let decode := null;

{
	from std/string import chr, index, ord, substr;
	from std/string/base64 import
		encode as _base64_encode,
		decode as _base64_decode;

	let _B64_ALPHABET := "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
		_ "abcdefghijklmnopqrstuvwxyz0123456789+/";
	let _HEX := "0123456789ABCDEF";

	function _div_floor ( Number n, Number d ) {
		return floor( n / d );
	}

	function _mod ( Number n, Number d ) {
		return n - _div_floor( n, d ) * d;
	}

	function _bytes_to_binary ( Array bytes ) {
		let out := "";
		let i := 0;
		let n := bytes.length();

		while ( i < n ) {
			let b0 := bytes[i];
			let b1 := null;
			let b2 := null;
			if ( i + 1 < n ) {
				b1 := bytes[i + 1];
			}
			if ( i + 2 < n ) {
				b2 := bytes[i + 2];
			}

			let c0 := _div_floor( b0, 4 );
			let c1 := _mod( b0, 4 ) * 16;
			let c2 := 64;
			let c3 := 64;

			if ( not( b1 == null ) ) {
				c1 += _div_floor( b1, 16 );
				c2 := _mod( b1, 16 ) * 4;
				if ( not( b2 == null ) ) {
					c2 += _div_floor( b2, 64 );
					c3 := _mod( b2, 64 );
				}
			}

			out _= substr( _B64_ALPHABET, c0, 1 );
			out _= substr( _B64_ALPHABET, c1, 1 );
			out _= c2 == 64 ? "=" : substr( _B64_ALPHABET, c2, 1 );
			out _= c3 == 64 ? "=" : substr( _B64_ALPHABET, c3, 1 );
			i += 3;
		}

		return _base64_decode(out);
	}

	function _binary_to_bytes ( BinaryString raw ) {
		let b64 := _base64_encode(raw);
		let out := [];
		let i := 0;
		let n := length b64;

		while ( i < n ) {
			let c0 := index( _B64_ALPHABET, substr( b64, i, 1 ) );
			let c1 := index( _B64_ALPHABET, substr( b64, i + 1, 1 ) );
			let ch2 := substr( b64, i + 2, 1 );
			let ch3 := substr( b64, i + 3, 1 );
			let c2 := -1;
			let c3 := -1;
			if ( ch2 ne "=" ) {
				c2 := index( _B64_ALPHABET, ch2 );
			}
			if ( ch3 ne "=" ) {
				c3 := index( _B64_ALPHABET, ch3 );
			}

			out.push( c0 * 4 + _div_floor( c1, 16 ) );
			if ( c2 >= 0 ) {
				out.push( _mod( c1, 16 ) * 16 + _div_floor( c2, 4 ) );
			}
			if ( c3 >= 0 ) {
				out.push( _mod( c2, 4 ) * 64 + c3 );
			}

			i += 4;
		}

		return out;
	}

	function _parse_options ( PairList options ) {
		let line_length := 76;
		let newline := "\r\n";
		let binary := false;
		let strict := false;

		for ( let option in options.enumerate() ) {
			let key := option.key;
			let value := option.value;

			if ( key eq "line_length" ) {
				line_length := value;
			}
			else if ( key eq "newline" ) {
				newline := value;
			}
			else if ( key eq "binary" ) {
				binary := value;
			}
			else if ( key eq "strict" ) {
				strict := value;
			}
			else {
				die `quoted_printable option '${key}' is not supported`;
			}
		}

		if ( not( line_length instanceof Number ) ) {
			die "quoted_printable line_length option expects Number";
		}
		if ( line_length < 4 ) {
			die "quoted_printable line_length option must be at least 4";
		}
		if ( not( newline instanceof String ) ) {
			die "quoted_printable newline option expects String";
		}
		if ( not( binary instanceof Boolean ) ) {
			die "quoted_printable binary option expects Boolean";
		}
		if ( not( strict instanceof Boolean ) ) {
			die "quoted_printable strict option expects Boolean";
		}

		return {
			line_length: int(line_length),
			newline: newline,
			binary: binary,
			strict: strict,
		};
	}

	function _is_safe_literal ( Number b ) {
		return ( b >= 33 and b <= 60 ) or ( b >= 62 and b <= 126 );
	}

	function _byte_to_hex_token ( Number b ) {
		return "="
			_ substr( _HEX, _div_floor( b, 16 ), 1 )
			_ substr( _HEX, _mod( b, 16 ), 1 );
	}

	function _simple_token_length ( Number b, Boolean final_byte ) {
		if ( ( b == 9 or b == 32 ) and not final_byte ) {
			return 1;
		}
		if ( _is_safe_literal(b) ) {
			return 1;
		}
		return 3;
	}

	function _space_tab_needs_escape (
		Array bytes,
		Number i,
		Number column,
		Number line_length,
	) {
		let n := bytes.length();
		if ( i + 1 >= n ) {
			return true;
		}

		let j := i + 1;
		while ( j < n and ( bytes[j] == 9 or bytes[j] == 32 ) ) {
			j++;
		}
		if ( j >= n ) {
			return true;
		}

		let next_is_final := i + 2 >= n;
		let next_len := _simple_token_length( bytes[i + 1], next_is_final );
		let max := next_is_final ? line_length : line_length - 1;
		return column + 1 + next_len > max;
	}

	function _token_for_byte (
		Array bytes,
		Number i,
		Number column,
		Number line_length,
	) {
		let b := bytes[i];

		if ( b == 9 or b == 32 ) {
			if ( _space_tab_needs_escape( bytes, i, column, line_length ) ) {
				return _byte_to_hex_token(b);
			}
			return chr(b);
		}

		if ( _is_safe_literal(b) ) {
			return chr(b);
		}

		return _byte_to_hex_token(b);
	}

	function _emit_token (
		String out,
		Number column,
		String token,
		Boolean more_after,
		Number line_length,
		String newline,
	) {
		let max := more_after ? line_length - 1 : line_length;
		let updated_out := out;
		let updated_column := column;

		if ( updated_column > 0 and updated_column + ( length token ) > max ) {
			updated_out _= "=" _ newline;
			updated_column := 0;
		}

		updated_out _= token;
		updated_column += length token;

		return [ updated_out, updated_column ];
	}

	function _encode_segment (
		Array bytes,
		Number line_length,
		String newline,
	) {
		let out := "";
		let column := 0;
		let i := 0;
		let n := bytes.length();

		while ( i < n ) {
			let token := _token_for_byte( bytes, i, column, line_length );
			let emitted := _emit_token(
				out,
				column,
				token,
				i + 1 < n,
				line_length,
				newline,
			);
			out := emitted[0];
			column := emitted[1];
			i++;
		}

		return out;
	}

	function _encode_text_bytes (
		Array bytes,
		Number line_length,
		String newline,
	) {
		let out := "";
		let line := [];
		let i := 0;
		let n := bytes.length();

		while ( i < n ) {
			let b := bytes[i];
			if ( b == 13 or b == 10 ) {
				out _= _encode_segment( line, line_length, newline );
				out _= newline;
				line := [];

				if ( b == 13 and i + 1 < n and bytes[i + 1] == 10 ) {
					i++;
				}
			}
			else {
				line.push(b);
			}

			i++;
		}

		out _= _encode_segment( line, line_length, newline );
		return out;
	}

	function _hex_value ( String ch ) {
		let cp := ord(ch);
		if ( cp >= 48 and cp <= 57 ) {
			return cp - 48;
		}
		if ( cp >= 65 and cp <= 70 ) {
			return cp - 55;
		}
		if ( cp >= 97 and cp <= 102 ) {
			return cp - 87;
		}
		return -1;
	}

	function _decode_text_bytes ( String text, Boolean strict ) {
		let out := [];
		let i := 0;
		let n := length text;

		while ( i < n ) {
			let ch := substr( text, i, 1 );
			let cp := ord( text, i );

			if ( cp > 127 ) {
				die "quoted_printable.decode rejects non-ASCII input";
			}

			if ( ch eq "=" ) {
				if ( i + 1 >= n ) {
					die "malformed quoted-printable escape" if strict;
					out.push(61);
					i++;
					next;
				}

				let ch1 := substr( text, i + 1, 1 );
				if ( ch1 eq "\r" ) {
					if ( i + 2 < n and substr( text, i + 2, 1 ) eq "\n" ) {
						i += 3;
					}
					else {
						i += 2;
					}
					next;
				}
				if ( ch1 eq "\n" ) {
					i += 2;
					next;
				}

				if ( i + 2 < n ) {
					let hi := _hex_value(ch1);
					let lo := _hex_value( substr( text, i + 2, 1 ) );
					if ( hi >= 0 and lo >= 0 ) {
						out.push( hi * 16 + lo );
						i += 3;
						next;
					}
				}

				die "malformed quoted-printable escape" if strict;
				out.push(61);
				i++;
				next;
			}

			out.push(cp);
			i++;
		}

		return out;
	}

	encode := function ( BinaryString bytes, ... PairList options ) {
		let opts := _parse_options(options);
		let raw := _binary_to_bytes(bytes);

		if ( opts{binary} ) {
			return _encode_segment(
				raw,
				opts{line_length},
				opts{newline},
			);
		}

		return _encode_text_bytes(
			raw,
			opts{line_length},
			opts{newline},
		);
	};

	decode := function ( String text, ... PairList options ) {
		let opts := _parse_options(options);
		return _bytes_to_binary( _decode_text_bytes( text, opts{strict} ) );
	};
}