zuzu-js 0.1.0

package/stdlib/modules/std/time.zzm

@@ -0,0 +1,188 @@
+=encoding utf8
+
+=head1 NAME
+
+std/time - Time objects, formatting, and parsing.
+
+=head1 SYNOPSIS
+
+  from std/time import Time, TimeZone, Duration, TimeFormat, TimeParser;
+
+  let london := TimeZone.named("Europe/London");
+  let now := new Time(timezone: london);
+  let tomorrow := now.add_days(1);
+  let next_hour := now.add(Duration.hours(1));
+
+  let parsed := Time.parse("2026-03-20T12:00:00", timezone: london);
+  say TimeFormat.rfc3339().format(parsed);
+
+=head1 IMPLEMENTATION SUPPORT
+
+This module is supported by all implementations of ZuzuScript.
+
+=head1 DESCRIPTION
+
+This module provides immutable C<Time> objects for working with instants,
+timezones, calendar arithmetic, parsing, and serialization. C<TimeParser>
+remains available for compatibility with older strptime-style parsing.
+
+=head1 EXPORTS
+
+=head2 Classes
+
+=over
+
+=item C<< Time(Number epoch?, timezone: TimeZone|String?) >>
+
+Construct a time from an epoch value in seconds, or use the current
+time when omitted. C<timezone> controls the calendar view used by component
+accessors and calendar arithmetic. Returns: C<Time>.
+
+Common instance methods include:
+
+=over
+
+=item C<< time.sec() >>, C<< time.min() >>, C<< time.hour() >>
+
+Parameters: none. Returns: C<Number>. Returns the seconds, minutes, or
+hours component.
+
+=item C<< time.day_of_month() >>, C<< time.mon() >>, C<< time.month() >>, C<< time.year() >>, C<< time.yy() >>
+
+Parameters: none. Returns: C<Number>. Returns the local calendar date
+component.
+
+=item C<< time.day_of_week() >>, C<< time.day() >>, C<< time.day_of_year() >>, C<< time.month_last_day() >>
+
+Parameters: none. Returns: C<Number>. Returns derived local calendar
+component values.
+
+=item C<< time.epoch() >>
+
+Parameters: none. Returns: C<Number>. Returns epoch seconds.
+
+=item C<< time.timezone() >>
+
+Parameters: none. Returns: C<TimeZone>. Returns the timezone metadata for
+the time object.
+
+=item C<< time.with_timezone(TimeZone|String zone) >>
+
+Parameters: C<zone> is an IANA name, fixed offset, or C<TimeZone>. Returns:
+C<Time>. Keeps the same instant and changes the displayed timezone.
+
+=item C<< time.reinterpret_timezone(TimeZone|String zone) >>
+
+Parameters: C<zone> is an IANA name, fixed offset, or C<TimeZone>. Returns:
+C<Time>. Keeps the same displayed date/time fields and changes the instant.
+
+=item C<< time.hms(separator?) >>, C<< time.ymd(separator?) >>, C<< time.mdy(separator?) >>, C<< time.dmy(separator?) >>
+
+Parameters: C<separator> is an optional separator string. Returns:
+C<String>. Formats a time or date component string.
+
+=item C<< time.date() >>, C<< time.time() >>, C<< time.datetime() >>, C<< time.cdate() >>, C<< time.to_String() >>
+
+Parameters: none. Returns: C<String>. Formats the time using common date
+and time layouts.
+
+=item C<< time.strftime(String format) >>
+
+Parameters: C<format> is a strftime format string. Returns: C<String>.
+Formats the time with C<format>.
+
+=item C<< time.to_iso8601() >>, C<< time.to_rfc3339() >>, C<< time.to_rfc5322(include_weekday: Boolean?) >>
+
+Parameters: C<include_weekday> is an optional Boolean for C<to_rfc5322>.
+Returns: C<String>. Serializes the time using common machine and mail date
+formats. C<to_rfc5322> includes a weekday by default; pass
+C<include_weekday: false> to omit it.
+
+=item C<< time.tzoffset() >>
+
+Parameters: none. Returns: C<Number>. Returns the local timezone offset.
+
+=item C<< time.is_leap_year() >>
+
+Parameters: none. Returns: C<Boolean>. Returns true when the local year
+is a leap year.
+
+=item C<< time.week() >>, C<< time.week_year() >>, C<< time.julian_day() >>
+
+Parameters: none. Returns: C<Number>. Returns week-numbering and Julian
+day values.
+
+=item C<< time.add_seconds(Number n) >>, C<< time.add_minutes(Number n) >>, C<< time.add_hours(Number n) >>, C<< time.add_days(Number n) >>, C<< time.add_weeks(Number n) >>
+
+Parameters: C<n> is the amount to add. Returns: C<Time>. Seconds, minutes,
+and hours are elapsed-time operations. Days and weeks are calendar
+operations in the object's timezone.
+
+=item C<< time.add_months(Number n) >>, C<< time.add_years(Number n) >>
+
+Parameters: C<n> is the amount to add. Returns: C<Time>. Returns a new
+time offset by calendar months or years on supported builds.
+
+=item C<< time.subtract_seconds(Number n) >>, C<< time.subtract_minutes(Number n) >>, C<< time.subtract_hours(Number n) >>, C<< time.subtract_days(Number n) >>, C<< time.subtract_weeks(Number n) >>, C<< time.subtract_months(Number n) >>, C<< time.subtract_years(Number n) >>
+
+Parameters: C<n> is the amount to subtract. Returns: C<Time>.
+
+=item C<< time.add(Duration d) >>, C<< time.subtract(Duration d) >>
+
+Parameters: C<d> is a C<Duration>. Returns: C<Time>.
+
+=item C<< time.elapsed_seconds_until(Time other) >>, C<< time.compare(Time other) >>, C<< time.is_before(Time other) >>, C<< time.is_after(Time other) >>
+
+Parameters: C<other> is another C<Time>. Returns elapsed seconds, ordering,
+or boolean comparison results.
+
+=item C<< Time.parse(String text, timezone: TimeZone|String?) >>
+
+Parameters: C<text> is ISO 8601/RFC 3339 or RFC 5322 text. RFC 5322 input
+accepts common obsolete mail-date spellings including two-digit years,
+legacy US zones, and military zones other than C<J>. Zone-less ISO input
+requires an explicit C<timezone>. Returns: C<Time>.
+
+=item C<< TimeZone.utc() >>, C<< TimeZone.local() >>, C<< TimeZone.named(String name) >>, C<< TimeZone.offset(Number seconds) >>
+
+Returns timezone helper objects. Named zones use IANA timezone names.
+
+=item C<< Duration.seconds(Number n) >>, C<< Duration.minutes(Number n) >>, C<< Duration.hours(Number n) >>, C<< Duration.days(Number n) >>, C<< Duration.weeks(Number n) >>, C<< Duration.months(Number n) >>, C<< Duration.years(Number n) >>
+
+Returns immutable duration helper objects.
+
+=item C<< TimeFormat.iso8601() >>, C<< TimeFormat.rfc3339() >>, C<< TimeFormat.rfc5322() >>, C<< TimeFormat.strftime(String pattern) >>
+
+Returns formatter/parser helper objects.
+
+=item C<< TimeFormat.format(Time time) >>
+
+Parameters: C<time> is a C<Time>. Returns: C<String>. Formats C<time>
+using the helper object's format.
+
+=item C<< TimeFormat.parse(String text, timezone: TimeZone|String?) >>
+
+Parameters: C<text> is date-time text matching the helper object's format.
+RFC 5322 input may carry its own timezone. Zone-less input requires an
+explicit C<timezone>. Returns: C<Time>.
+
+=back
+
+=item C<< TimeParser(String format = "%Y-%m-%d") >>
+
+Creates a parser for the given format string. Returns: C<TimeParser>.
+
+=item C<< TimeParser->parse(String text) >>
+
+Parameters: C<text> is text matching the parser format. Returns:
+C<Time>. Parses text into a time object.
+
+=back
+
+=head1 COPYRIGHT AND LICENCE
+
+B<< std/time >> 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/tui.zzm

@@ -0,0 +1,89 @@
+=encoding utf8
+
+=head1 NAME
+
+std/tui - Terminal UI helpers.
+
+=head1 SYNOPSIS
+
+  from std/tui import supports_ansi, colour_text, readline, write_line;
+
+  write_line( "Warning", "yellow" );
+  let path := readline( "File: ", "", filename_completions );
+
+=head1 IMPLEMENTATION SUPPORT
+
+This module is supported by all implementations of ZuzuScript.
+
+=head1 DESCRIPTION
+
+This runtime-supported module provides small terminal UI primitives for
+standard-library modules that need command-line fallbacks.
+
+=head1 EXPORTS
+
+=head2 Functions
+
+=over
+
+=item * C<ansi_esc()>
+
+Parameters: none. Returns: C<String>. Returns a one-character ANSI
+escape string.
+
+=item * C<supports_ansi()>
+
+Parameters: none. Returns: C<Boolean>. Returns true when stdout appears
+to be an ANSI-capable terminal.
+
+=item * C<colour_text(text, colour)>
+
+Parameters: C<text> is the value to display and C<colour> is a colour
+name or C<null>. Returns: C<String>. Returns C<text> wrapped in ANSI
+colour escapes when C<supports_ansi()> is true, otherwise returns
+C<text> unchanged.
+
+=item * C<write(text, colour)>
+
+Parameters: C<text> is the value to write and C<colour> is a colour name
+or C<null>. Returns: C<null>. Writes C<text> to stdout, optionally
+coloured.
+
+=item * C<write_line(text, colour)>
+
+Parameters: C<text> is the value to write and C<colour> is a colour name
+or C<null>. Returns: C<null>. Writes C<text> followed by a newline to
+stdout, optionally coloured.
+
+=item * C<readline(prompt, default, completion_callback)>
+
+Parameters: C<prompt> is prompt text, C<default> is the initial value,
+and C<completion_callback> is C<null> or a completion function. Returns:
+C<String> or C<null>. Reads a line from stdin.
+
+=item * C<readline_supports_completion()>
+
+Parameters: none. Returns: C<Boolean>. Returns true when the runtime can
+provide native readline completion.
+
+=item * C<filename_completions(text)>
+
+Parameters: C<text> is the partial path. Returns: C<Array>. Returns file
+and directory path completions for C<text>.
+
+=item * C<directory_completions(text)>
+
+Parameters: C<text> is the partial path. Returns: C<Array>. Returns
+directory path completions for C<text>.
+
+=back
+
+=head1 COPYRIGHT AND LICENCE
+
+B<< std/tui >> 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

package/stdlib/modules/std/uuid.zzm

@@ -0,0 +1,223 @@
+=encoding utf8
+
+=head1 NAME
+
+std/uuid - Pure ZuzuScript UUID v1 generator.
+
+=head1 SYNOPSIS
+
+  from std/uuid import create_uuid, create_uuid_binary;
+
+  let text := create_uuid();
+  let raw := create_uuid_binary();
+
+=head1 IMPLEMENTATION SUPPORT
+
+This module is supported by all implementations of ZuzuScript.
+
+=head1 DESCRIPTION
+
+This module implements UUID version 1 generation using only
+ZuzuScript code.
+
+=head1 EXPORTS
+
+=head2 Functions
+
+=over
+
+=item * C<create_uuid_binary()>
+
+Parameters: none. Returns: C<BinaryString>. Returns a single UUID as 16
+raw bytes.
+
+=item * C<create_uuid()>
+
+Parameters: none. Returns: C<String>. Returns a single UUID as
+lowercase hexadecimal text with hyphens in the usual C<8-4-4-4-12>
+layout.
+
+=back
+
+=head1 COPYRIGHT AND LICENCE
+
+B<< std/uuid >> 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/math import Math;
+from std/string import substr;
+from std/string/base64 import decode;
+from std/time import Time;
+
+let _B64_ALPHABET := "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+let _HEX_ALPHABET := "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 _rand_int ( Number max ) {
+	return floor( Math.rand(max) );
+}
+
+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 ( b1 ≢ null ) {
+			c1 += _div_floor( b1, 16 );
+			c2 := _mod( b1, 16 ) * 4;
+			if ( b2 ≢ null ) {
+				c2 += _div_floor( b2, 64 );
+				c3 := _mod( b2, 64 );
+			}
+		}
+
+		out _= substr( _B64_ALPHABET, c0, 1 );
+		out _= substr( _B64_ALPHABET, c1, 1 );
+		if ( c2 ≡ 64 ) {
+			out _= "=";
+		}
+		else {
+			out _= substr( _B64_ALPHABET, c2, 1 );
+		}
+		if ( c3 ≡ 64 ) {
+			out _= "=";
+		}
+		else {
+			out _= substr( _B64_ALPHABET, c3, 1 );
+		}
+
+		i += 3;
+	}
+
+	return decode(out);
+}
+
+function _timestamp_words () {
+	// Seconds between 1582-10-15 and 1970-01-01.
+	let epoch_offset := 12219292800;
+	let seconds := new Time().epoch() + epoch_offset;
+	let ticks := _rand_int(10000000);
+
+	let words := [
+		_mod( seconds, 65536 ),
+		_mod( _div_floor( seconds, 65536 ), 65536 ),
+		_mod( _div_floor( seconds, 4294967296 ), 65536 ),
+		0,
+		0,
+	];
+
+	let scale := 10000000;
+	let i := 0;
+	let carry := 0;
+	while ( i < words.length() ) {
+		let product := words[i] * scale + carry;
+		words[i] := _mod( product, 65536 );
+		carry := _div_floor( product, 65536 );
+		i++;
+	}
+
+	let add_i := 0;
+	let add_carry := ticks;
+	while ( add_carry > 0 and add_i < words.length() ) {
+		let sum := words[add_i] + _mod( add_carry, 65536 );
+		words[add_i] := _mod( sum, 65536 );
+		add_carry := _div_floor( add_carry, 65536 ) + _div_floor( sum, 65536 );
+		add_i++;
+	}
+
+	return words;
+}
+
+function _create_uuid_bytes () {
+	let words := _timestamp_words();
+	let time_low := words[0] + words[1] * 65536;
+	let time_mid := words[2];
+	let time_hi_and_version := _mod( words[3], 4096 ) + 4096;
+
+	let clock_seq := _rand_int(16384);
+	let clock_seq_hi_and_reserved := _mod( _div_floor( clock_seq, 256 ), 64 ) + 128;
+	let clock_seq_low := _mod( clock_seq, 256 );
+
+	let node := [];
+	let j := 0;
+	while ( j < 6 ) {
+		node.push( _rand_int(256) );
+		j++;
+	}
+	// Multicast bit set means this is not an IEEE MAC address.
+	node[0] := node[0] | 1;
+
+	return [
+		_mod( _div_floor( time_low, 16777216 ), 256 ),
+		_mod( _div_floor( time_low, 65536 ), 256 ),
+		_mod( _div_floor( time_low, 256 ), 256 ),
+		_mod( time_low, 256 ),
+		_mod( _div_floor( time_mid, 256 ), 256 ),
+		_mod( time_mid, 256 ),
+		_mod( _div_floor( time_hi_and_version, 256 ), 256 ),
+		_mod( time_hi_and_version, 256 ),
+		clock_seq_hi_and_reserved,
+		clock_seq_low,
+		node[0],
+		node[1],
+		node[2],
+		node[3],
+		node[4],
+		node[5],
+	];
+}
+
+function _byte_to_hex ( Number b ) {
+	let hi := _div_floor( b, 16 );
+	let lo := _mod( b, 16 );
+	return substr( _HEX_ALPHABET, hi, 1 ) _ substr( _HEX_ALPHABET, lo, 1 );
+}
+
+function _bytes_to_uuid_text ( Array bytes ) {
+	let out := "";
+	let i := 0;
+	while ( i < 16 ) {
+		out _= _byte_to_hex( bytes[i] );
+		if ( i ≡ 3 or i ≡ 5 or i ≡ 7 or i ≡ 9 ) {
+			out _= "-";
+		}
+		i++;
+	}
+	return out;
+}
+
+function create_uuid_binary () {
+	return _bytes_to_binary( _create_uuid_bytes() );
+}
+
+function create_uuid () {
+	return _bytes_to_uuid_text( _create_uuid_bytes() );
+}