zuzu-js 0.1.0

package/stdlib/modules/std/defer.zzm

@@ -0,0 +1,75 @@
+=encoding utf8
+
+=head1 NAME
+
+std/defer - Run a callback when a guard object is demolished.
+
+=head1 SYNOPSIS
+
+  from std/defer import Guard;
+
+  let guard := new Guard( callback: fn () { cleanup(); } );
+  guard.disable();
+
+=head1 IMPLEMENTATION SUPPORT
+
+This module is supported by all implementations of ZuzuScript.
+
+=head1 DESCRIPTION
+
+C<Guard> is a small scope guard. It stores a callback and can be armed or
+disarmed before demolition.
+
+=head1 EXPORTS
+
+=head2 Classes
+
+=over
+
+=item C<< Guard({ callback: Function, armed?: Boolean }) >>
+
+Constructs a guard that calls C<callback> when the object is demolished.
+The guard starts armed unless C<armed> is supplied as false.
+
+=over
+
+=item C<< guard.enable() >>
+
+Parameters: none. Returns: C<null>. Arms the guard so demolition will run
+the callback.
+
+=item C<< guard.disable() >>
+
+Parameters: none. Returns: C<null>. Disarms the guard so demolition will
+not run the callback.
+
+=back
+
+=back
+
+=head1 COPYRIGHT AND LICENCE
+
+B<< std/defer >> 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
+
+class Guard {
+	let Boolean armed := true;
+	let Function callback;
+
+	method enable () {
+		armed := true;
+	}
+
+	method disable () {
+		armed := false;
+	}
+
+	method __demolish__ () {
+		callback();
+	}
+}

package/stdlib/modules/std/digest/crc32.zzm

@@ -0,0 +1,196 @@
+=encoding utf8
+
+=head1 NAME
+
+std/digest/crc32 - CRC32 digests for BinaryString values.
+
+=head1 SYNOPSIS
+
+  from std/digest/crc32 import *;
+
+  let payload := to_binary( "hello" );
+
+  let raw := crc32(payload);
+  let hex := crc32_hex(payload);
+  let b64 := crc32_b64(payload);
+
+=head1 IMPLEMENTATION SUPPORT
+
+This module is supported by all implementations of ZuzuScript.
+
+=head1 DESCRIPTION
+
+This module provides CRC32 digest helpers implemented in pure
+ZuzuScript.
+
+=head1 EXPORTS
+
+=head2 Functions
+
+=over
+
+=item * C<crc32(BinaryString value)>
+
+Parameters: C<value> is binary input data. Returns: C<BinaryString>.
+Returns the raw 4-byte CRC32 digest.
+
+=item * C<crc32_hex(BinaryString value)>
+
+Parameters: C<value> is binary input data. Returns: C<String>. Returns
+the digest as lowercase hexadecimal text.
+
+=item * C<crc32_b64(BinaryString value)>
+
+Parameters: C<value> is binary input data. Returns: C<String>. Returns
+the digest as Base64 text without trailing C<=> padding.
+
+=back
+
+=head1 COPYRIGHT AND LICENCE
+
+B<< std/digest/crc32 >> 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
+
+from std/string/base64 import encode, decode;
+from std/string import substr, index;
+
+let _HEX := "0123456789abcdef";
+let _B64_ALPHABET := "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+
+function _div_floor ( Number n, Number d ) {
+	return floor( n / 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 := ( b0 & 3 ) * 16;
+		let c2 := 64;
+		let c3 := 64;
+
+		if ( b1 ≢ null ) {
+			c1 += _div_floor( b1, 16 );
+			c2 := ( b1 & 15 ) * 4;
+			if ( b2 ≢ null ) {
+				c2 += _div_floor( b2, 64 );
+				c3 := b2 & 63;
+			}
+		}
+
+		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 decode(out);
+}
+
+function _u32_to_binary ( Number n ) {
+	let b0 := _div_floor( n, 16777216 ) & 255;
+	let b1 := _div_floor( n, 65536 ) & 255;
+	let b2 := _div_floor( n, 256 ) & 255;
+	let b3 := n & 255;
+	return _bytes_to_binary( [ b0, b1, b2, b3 ] );
+}
+
+function _byte_to_hex ( Number b ) {
+	let hi := _div_floor( b, 16 ) & 15;
+	let lo := b & 15;
+	return substr( _HEX, hi, 1 ) _ substr( _HEX, lo, 1 );
+}
+
+
+function _binary_to_bytes ( BinaryString raw ) {
+	let b64 := 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 ≢ "=" ) {
+			c2 := index( _B64_ALPHABET, ch2 );
+		}
+		if ( ch3 ≢ "=" ) {
+			c3 := index( _B64_ALPHABET, ch3 );
+		}
+
+		out.push( c0 * 4 + _div_floor( c1, 16 ) );
+		if ( c2 >= 0 ) {
+			out.push( ( c1 & 15 ) * 16 + _div_floor( c2, 4 ) );
+		}
+		if ( c3 >= 0 ) {
+			out.push( ( c2 & 3 ) * 64 + c3 );
+		}
+
+		i += 4;
+	}
+
+	return out;
+}
+
+function crc32 ( BinaryString value ) {
+	let bytes := _binary_to_bytes(value);
+	let crc := 4294967295;
+
+	for ( let b in bytes ) {
+		crc := crc ^ b;
+		let i := 0;
+		while ( i < 8 ) {
+			if ( ( crc & 1 ) ≡ 1 ) {
+				crc := _div_floor( crc, 2 ) ^ 3988292384;
+			}
+			else {
+				crc := _div_floor( crc, 2 );
+			}
+			i++;
+		}
+	}
+
+	crc := ( ~crc ) & 4294967295;
+
+	return _u32_to_binary(crc);
+}
+
+function crc32_hex ( BinaryString value ) {
+	let digest := _binary_to_bytes( crc32(value) );
+	let out := "";
+	for ( let b in digest ) {
+		out _= _byte_to_hex(b);
+	}
+	return out;
+}
+
+function crc32_b64 ( BinaryString value ) {
+	let out := encode( crc32(value) );
+	while ( length out > 0 and substr( out, length out - 1, 1 ) ≡ "=" ) {
+		out := substr( out, 0, length out - 1 );
+	}
+	return out;
+}

package/stdlib/modules/std/digest/md5.zzm

@@ -0,0 +1,54 @@
+=encoding utf8
+
+=head1 NAME
+
+std/digest/md5 - MD5 digests for BinaryString values.
+
+=head1 SYNOPSIS
+
+  from std/digest/md5 import *;
+
+  let payload := to_binary( "hello" );
+
+  let raw := md5(payload);
+  let hex := md5_hex(payload);
+  let b64 := md5_b64(payload);
+
+=head1 IMPLEMENTATION SUPPORT
+
+This module is supported by all implementations of ZuzuScript.
+
+=head1 DESCRIPTION
+
+This module provides MD5 digest helpers.
+
+=head1 EXPORTS
+
+=head2 Functions
+
+=over
+
+=item * C<md5(BinaryString value)>
+
+Parameters: C<value> is binary input data. Returns: C<BinaryString>.
+Returns the raw 16-byte MD5 digest.
+
+=item * C<md5_hex(BinaryString value)>
+
+Parameters: C<value> is binary input data. Returns: C<String>. Returns
+the digest as lowercase hexadecimal text.
+
+=item * C<md5_b64(BinaryString value)>
+
+Parameters: C<value> is binary input data. Returns: C<String>. Returns
+the digest as Base64 text without trailing C<=> padding.
+
+=back
+
+=head1 COPYRIGHT AND LICENCE
+
+B<< std/digest/md5 >> 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.

package/stdlib/modules/std/digest/sha.zzm

@@ -0,0 +1,83 @@
+=encoding utf8
+
+=head1 NAME
+
+std/digest/sha - SHA digests for BinaryString values.
+
+=head1 SYNOPSIS
+
+  from std/digest/sha import *;
+
+  let payload := to_binary( "hello" );
+  let key := to_binary( "shared-secret" );
+
+  let hex256 := sha256_hex(payload);
+  let raw512 := sha512(payload);
+  let auth := hmac_sha256_hex(payload, key);
+
+=head1 IMPLEMENTATION SUPPORT
+
+This module is supported by all implementations of ZuzuScript.
+
+=head1 DESCRIPTION
+
+This module provides SHA digest and HMAC helpers.
+
+=head1 EXPORTS
+
+=head2 Functions
+
+For each of C<sha1>, C<sha224>, C<sha256>, C<sha384>, and
+C<sha512>, this module exports three function forms:
+
+=over
+
+=item * C<< NAME(BinaryString value) >>
+
+Parameters: C<value> is binary input data. Returns: C<BinaryString>.
+Returns the raw digest.
+
+=item * C<< NAME_hex(BinaryString value) >>
+
+Parameters: C<value> is binary input data. Returns: C<String>. Returns
+lowercase hexadecimal text.
+
+=item * C<< NAME_b64(BinaryString value) >>
+
+Parameters: C<value> is binary input data. Returns: C<String>. Returns
+Base64 text without trailing C<=> padding.
+
+=back
+
+=head2 HMAC Functions
+
+For each of C<hmac_sha1>, C<hmac_sha224>, C<hmac_sha256>,
+C<hmac_sha384>, and C<hmac_sha512>, this module exports:
+
+=over
+
+=item * C<< NAME(BinaryString value, BinaryString key) >>
+
+Parameters: C<value> is binary input data and C<key> is the HMAC key.
+Returns: C<BinaryString>. Returns a raw HMAC digest.
+
+=item * C<< NAME_hex(BinaryString value, BinaryString key) >>
+
+Parameters: C<value> is binary input data and C<key> is the HMAC key.
+Returns: C<String>. Returns lowercase hexadecimal HMAC text.
+
+=item * C<< NAME_b64(BinaryString value, BinaryString key) >>
+
+Parameters: C<value> is binary input data and C<key> is the HMAC key.
+Returns: C<String>. Returns Base64 HMAC text with no trailing C<=>
+padding.
+
+=back
+
+=head1 COPYRIGHT AND LICENCE
+
+B<< std/digest/sha >> 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.