zuzu-js 0.1.0

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "zuzu-js",
+  "version": "0.1.0",
+  "description": "JavaScript runtime, compiler, and browser bundle for ZuzuScript.",
+  "main": "lib/zuzu.js",
+  "bin": {
+    "zuzu": "bin/zuzu",
+    "zuzu-js": "bin/zuzu-js",
+    "zuzu-js-compile": "bin/zuzu-js-compile",
+    "zuzu-js-electron": "bin/zuzu-js-electron"
+  },
+  "files": [
+    "bin/",
+    "dist/zuzu-browser.js",
+    "dist/zuzu-browser-worker.js",
+    "lib/",
+    "modules/",
+    "stdlib/modules/"
+  ],
+  "directories": {
+    "example": "examples",
+    "lib": "lib",
+    "test": "test"
+  },
+  "scripts": {
+    "electron:demo": "electron bin/zuzu-js-electron docs/examples/09_gui_dialogue_demo.zzs",
+    "test": "node test/cli.js && node test/argument-spread.js && node test/default-operator.js && node test/declaration-unpacking.js && node test/collection-copy.js && node test/std-marshal-cbor.js && node test/std-marshal-data-graph.js && node test/std-marshal-user-object.js && node test/std-marshal-code-table.js && node test/async-parity.js && node test/browser-stdlib-generator.js && node test/browser-gui.js && node test/electron-gui.js && node test/electron-renderer.js && node test/electron-packaging.js",
+    "test:electron": "node test/electron-gui.js && node test/electron-renderer.js && node test/electron-packaging.js"
+  },
+  "keywords": [
+    "zuzu",
+    "zuzuscript",
+    "language",
+    "runtime",
+    "compiler"
+  ],
+  "author": "",
+  "license": "Artistic-1.0 OR GPL-2.0-or-later",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/zuzuscript/zuzu-js.git"
+  },
+  "bugs": {
+    "url": "https://github.com/zuzuscript/zuzu-js/issues"
+  },
+  "homepage": "https://zuzulang.org/",
+  "engines": {
+    "node": ">=16"
+  },
+  "dependencies": {
+    "@xmldom/xmldom": "^0.9.10",
+    "adm-zip": "^0.5.17",
+    "better-sqlite3": "^11.10.0",
+    "cbor-x": "^1.6.4",
+    "cborg": "^5.1.1",
+    "compressjs": "^1.0.3",
+    "js-yaml": "^4.1.1",
+    "koffi": "^2.16.1",
+    "mysql2": "^3.22.3",
+    "node-forge": "^1.4.0",
+    "pg": "^8.20.0",
+    "xpath": "^0.0.34"
+  },
+  "devDependencies": {
+    "electron": "^41.3.0"
+  }
+}

package/stdlib/modules/javascript.zzm

@@ -0,0 +1,99 @@
+=encoding utf8
+
+=head1 NAME
+
+javascript - Evaluate JavaScript from ZuzuScript.
+
+=head1 SYNOPSIS
+
+  from javascript import JS, JSResult;
+
+  let r := JS.eval("[ 7, 8, 9 ]");
+  assert( r instanceof JSResult );
+
+  let j := r.toJSON();
+
+  let r2 := r.eval(" this[1] ");
+  assert( r2 instanceof JSResult );
+
+  let n;
+  n := r2.value() if r2.isSafe();
+
+=head1 IMPLEMENTATION SUPPORT
+
+This module is supported by zuzu-js on Node, Electron, and Browser. It
+is not supported by zuzu.pl or zuzu-rust.
+
+=head1 DESCRIPTION
+
+This runtime-supported module is only implemented by C<zuzu-js>.
+
+C<JS.eval(String code)> evaluates JavaScript and returns C<JSResult>.
+
+C<JSResult.eval(String code)> evaluates more JavaScript with the wrapped
+value bound to C<this>, again returning C<JSResult>.
+
+C<JSResult.isSafe()> reports whether C<value()> can convert the wrapped
+JavaScript value into a native Zuzu value.
+
+C<JSResult.value()> returns the converted Zuzu value for safe results.
+
+C<JSResult.toJSON()> serializes the wrapped JavaScript value as JSON.
+
+=head1 EXPORTS
+
+=head2 Classes
+
+=over
+
+=item C<JS>
+
+Runtime-supported JavaScript bridge class.
+
+=over
+
+=item C<< JS.eval(String code) >>
+
+Parameters: C<code> is JavaScript source text. Returns: C<JSResult>.
+Evaluates C<code> in the host JavaScript runtime.
+
+=back
+
+=item C<JSResult>
+
+Wrapper for a JavaScript value returned by C<JS.eval()> or
+C<JSResult.eval()>.
+
+=over
+
+=item C<< result.eval(String code) >>
+
+Parameters: C<code> is JavaScript source text. Returns: C<JSResult>.
+Evaluates C<code> with the wrapped JavaScript value bound to C<this>.
+
+=item C<< result.isSafe() >>
+
+Parameters: none. Returns: C<Boolean>. Returns true when C<value()> can
+convert the wrapped JavaScript value into a native ZuzuScript value.
+
+=item C<< result.value() >>
+
+Parameters: none. Returns: value. Converts and returns the wrapped
+JavaScript value when C<isSafe()> is true.
+
+=item C<< result.toJSON() >>
+
+Parameters: none. Returns: C<String>. Serializes the wrapped JavaScript
+value as JSON text.
+
+=back
+
+=back
+
+=head1 COPYRIGHT AND LICENCE
+
+B<< javascript >> 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/perl.zzm

@@ -0,0 +1,105 @@
+=encoding utf8
+
+=head1 NAME
+
+perl - Evaluate Perl code from ZuzuScript.
+
+=head1 SYNOPSIS
+
+  from perl import Perl, PerlResult;
+
+  let r := Perl.eval("[ 7, 8, 9 ]");
+  assert( r instanceof PerlResult );
+
+  let j := r.toJSON();
+
+  let r2 := r.eval(" $_->[1] ");
+  assert( r2 instanceof PerlResult );
+
+  let n;
+  n := r2.value() if r2.isSafe();
+
+=head1 IMPLEMENTATION SUPPORT
+
+This module is supported by zuzu.pl. It is not supported by zuzu-rust or
+zuzu-js.
+
+=head1 DESCRIPTION
+
+This builtin module bridges to the host Perl interpreter.
+
+C<Perl.version()> returns the current Perl version string.
+
+C<Perl.eval(String code)> evaluates Perl in scalar context and
+returns C<PerlResult>.
+
+C<PerlResult> wraps the underlying Perl value. Use C<isSafe()> to
+check whether C<value()> can convert it into a native Zuzu value.
+
+C<toJSON()> attempts to encode the wrapped value as JSON text.
+
+C<eval(String code)> evaluates more Perl with the wrapped value in
+C<$_>, again returning C<PerlResult>.
+
+=head1 EXPORTS
+
+=head2 Classes
+
+=over
+
+=item C<Perl>
+
+Runtime-supported Perl bridge class.
+
+=over
+
+=item C<< Perl.version() >>
+
+Parameters: none. Returns: C<String>. Returns the host Perl interpreter
+version.
+
+=item C<< Perl.eval(String code) >>
+
+Parameters: C<code> is Perl source text. Returns: C<PerlResult>.
+Evaluates C<code> in scalar context in the host Perl interpreter.
+
+=back
+
+=item C<PerlResult>
+
+Wrapper for a Perl value returned by C<Perl.eval()> or
+C<PerlResult.eval()>.
+
+=over
+
+=item C<< result.eval(String code) >>
+
+Parameters: C<code> is Perl source text. Returns: C<PerlResult>.
+Evaluates C<code> with the wrapped Perl value available in C<$_>.
+
+=item C<< result.isSafe() >>
+
+Parameters: none. Returns: C<Boolean>. Returns true when C<value()> can
+convert the wrapped Perl value into a native ZuzuScript value.
+
+=item C<< result.value() >>
+
+Parameters: none. Returns: value. Converts and returns the wrapped Perl
+value when C<isSafe()> is true.
+
+=item C<< result.toJSON() >>
+
+Parameters: none. Returns: C<String>. Serializes the wrapped Perl value
+as JSON text.
+
+=back
+
+=back
+
+=head1 COPYRIGHT AND LICENCE
+
+B<< perl >> 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/archive.zzm

@@ -0,0 +1,132 @@
+=encoding utf8
+
+=head1 NAME
+
+std/archive - Small archive and compression helpers.
+
+=head1 SYNOPSIS
+
+  from std/archive import Archive;
+  from std/io import Path;
+
+  let archive := {
+    entries: [
+      { path: "hello.txt", data: to_binary( "Hello\n" ) },
+      { path: "nested/world.txt", data: to_binary( "World\n" ) },
+    ],
+  };
+
+  let bytes := Archive.encode( archive, "tar.gz" );
+  let roundtrip := Archive.decode(bytes);
+
+  let path := Path.tempdir().child("hello.zip");
+  Archive.dump( path, archive );
+  let loaded := Archive.load(path);
+
+=head1 IMPLEMENTATION SUPPORT
+
+This module is supported by zuzu.pl, zuzu-rust, and zuzu-js on Node and
+Electron. It is not supported by zuzu-js in the browser.
+
+=head1 DESCRIPTION
+
+This module provides a small, runtime-supported archive API centred on
+one exported class, C<Archive>.
+
+=head1 EXPORTS
+
+=head2 Classes
+
+=over
+
+=item C<Archive>
+
+Runtime-supported archive namespace class.
+
+=over
+
+=item C<< Archive.decode(BinaryString bytes, String format?) >>
+
+Parameters: C<bytes> is archive or compressed data and C<format> is an
+optional format name. Returns: C<Dict>. Decodes C<bytes> into an archive
+value.
+
+=item C<< Archive.encode(Dict archive, String format?) >>
+
+Parameters: C<archive> is an archive value and C<format> is an optional
+format name. Returns: C<BinaryString>. Encodes C<archive> into archive
+or compressed data.
+
+=item C<< Archive.load(Path path, String format?) >>
+
+Parameters: C<path> is a C<std/io> C<Path> and C<format> is an optional
+format name. Returns: C<Dict>. Reads and decodes an archive file.
+
+=item C<< Archive.dump(Path path, Dict archive, String format?) >>
+
+Parameters: C<path> is a C<std/io> C<Path>, C<archive> is an archive
+value, and C<format> is an optional format name. Returns: C<null>.
+Encodes and writes an archive file.
+
+=back
+
+=back
+
+Archive values use this shape:
+
+  {
+    format: "zip",
+    entries: [
+      { path: "hello.txt", data: BinaryString },
+      { path: "nested/world.txt", data: BinaryString },
+    ],
+  }
+
+Only regular file payloads are preserved in this API. Directory
+entries and extended archive metadata are ignored so the interface
+remains practical to port to other backends later.
+
+When constructing archives for C<encode> or C<dump>, each entry may
+provide either:
+
+=over
+
+=item * C<data> as a C<BinaryString>
+
+=item * C<data_from> as a C<std/io::Path>
+
+=back
+
+For single-stream compression formats such as C<gz> and C<bz2>,
+C<entries> contains exactly one file entry.
+
+=head1 SUPPORTED FORMATS
+
+Host runtimes may support:
+
+=over
+
+=item * C<zip>
+
+=item * C<tar>
+
+=item * C<tar.gz> and C<tgz>
+
+=item * C<tar.bz2> and C<tbz2>
+
+=item * C<gz>
+
+=item * C<bz2>
+
+=back
+
+This module is intended for host runtimes with archive and compression
+support. Browser runtimes should not be assumed to support it.
+
+=head1 COPYRIGHT AND LICENCE
+
+B<< std/archive >> 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/cache/lru.zzm

@@ -0,0 +1,174 @@
+=encoding utf8
+
+=head1 NAME
+
+std/cache/lru - Pure ZuzuScript in-memory LRU cache.
+
+=head1 SYNOPSIS
+
+  from std/cache/lru import Cache;
+
+  let cache := new Cache( capacity: 20 );
+
+  let item := cache.get( "item-key", function ( item_key ) {
+    # Called only on cache miss.
+    return calculate_some_expensive_value( item_key );
+  } );
+
+  cache.empty();
+
+=head1 IMPLEMENTATION SUPPORT
+
+This module is supported by all implementations of ZuzuScript.
+
+=head1 DESCRIPTION
+
+This module provides a tiny in-memory least-recently-used (LRU)
+cache written in pure ZuzuScript.
+
+Keys are stored in an internal C<Dict>, and are assumed to be
+strings. Values may be any ZuzuScript value.
+
+=head1 EXPORTS
+
+=head2 Classes
+
+=over
+
+=item C<< Cache({ capacity?: Number }) >>
+
+Construct a cache with a maximum number of entries.
+Returns: C<Cache>. Defaults to C<128>.
+
+=item C<< cache.get(String item_key, Function producer) >>
+
+Parameters: C<item_key> is a string key and C<producer> is a function
+called on cache miss. Returns: value. Returns the cached value or stores
+and returns C<producer(item_key)>.
+
+=item C<< cache.peek(String item_key, fallback?) >>
+
+Parameters: C<item_key> is a string key and C<fallback> is optional.
+Returns: value. Returns the cached value without changing recency, or
+C<fallback>/C<null> on a miss.
+
+=item C<< cache.set(String item_key, value) >>
+
+Parameters: C<item_key> is a string key and C<value> is any value.
+Returns: value. Stores C<value> and marks it as recently used.
+
+=item C<< cache.has(String item_key) >>
+
+Parameters: C<item_key> is a string key. Returns: C<Boolean>. Returns
+true if the cache currently contains C<item_key>.
+
+=item C<< cache.size() >>
+
+Parameters: none. Returns: C<Number>. Returns the current number of
+cached entries.
+
+=item C<< cache.capacity() >>
+
+Parameters: none. Returns: C<Number>. Returns the configured maximum
+number of entries.
+
+=item C<< cache.empty() >>
+
+Parameters: none. Returns: C<null>. Removes all entries from the cache.
+
+=back
+
+=head1 COPYRIGHT AND LICENCE
+
+B<< std/cache/lru >> 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 Cache {
+	let Number capacity := 128;
+	let Dict _items := {};
+	let Array _order := [];
+
+	method __build__ () {
+		die "Cache capacity must be greater than zero" if capacity <= 0;
+	}
+
+	method _drop_key_from_order ( String item_key ) {
+		let kept := [];
+		let i := 0;
+		while ( i < _order.length() ) {
+			let key := _order[i];
+			if ( key ≢ item_key ) {
+				kept.push(key);
+			}
+			i++;
+		}
+		_order := kept;
+	}
+
+	method _touch ( String item_key ) {
+		self._drop_key_from_order(item_key);
+		_order.push(item_key);
+	}
+
+	method _evict_if_needed () {
+		while ( _order.length() > capacity ) {
+			let oldest := _order.shift();
+			if ( _items.exists(oldest) ) {
+				_items.remove(oldest);
+			}
+		}
+	}
+
+	method set ( String item_key, value ) {
+		_items.set( item_key, value );
+		self._touch(item_key);
+		self._evict_if_needed();
+		return value;
+	}
+
+	method get ( String item_key, producer ) {
+		if ( _items.exists(item_key) ) {
+			self._touch(item_key);
+			return _items.get(item_key);
+		}
+
+		die "Cache.get expects a producer Function" if not( producer instanceof Function );
+
+		let value := producer(item_key);
+		self.set( item_key, value );
+		return value;
+	}
+
+	method peek ( String item_key, fallback? ) {
+		if ( _items.exists(item_key) ) {
+			self._touch(item_key);
+			return _items.get(item_key);
+		}
+
+		return fallback;
+	}
+
+	method has ( String item_key ) {
+		return _items.exists(item_key);
+	}
+
+	method size () {
+		return _items.length();
+	}
+
+	method capacity () {
+		return capacity;
+	}
+
+	method empty () {
+		_items.clear();
+		_order.clear();
+		return self;
+	}
+}

package/stdlib/modules/std/clib.zzm

@@ -0,0 +1,112 @@
+=encoding utf8
+
+=head1 NAME
+
+std/clib - Dynamic C library loading and scalar FFI calls.
+
+=head1 SYNOPSIS
+
+  from std/clib import CLib;
+
+  let lib := CLib.open("stdlib/test-fixtures/example_clib/libgreet.so");
+  let greet := lib.func(
+    "greet",
+    [],
+    {
+      type: "binary",
+      terminated_by: "nul",
+      free: "greet_free"
+    }
+  );
+
+  say to_string(greet.call());
+
+=head1 IMPLEMENTATION SUPPORT
+
+This module is supported by zuzu.pl, zuzu-rust, and zuzu-js on Node and
+Electron. It is not supported by zuzu-js in the browser.
+
+=head1 DESCRIPTION
+
+This runtime-supported module loads C dynamic libraries and calls
+exported C functions through explicitly declared signatures.
+
+The first implementation supports C<null>, booleans, 64-bit integers,
+64-bit floats, and C<BinaryString> byte buffers. Other data types are
+out of scope.
+
+The runtime copies returned binary data before returning it to
+ZuzuScript. If a return descriptor includes C<free>, that symbol is
+called after the copy so libraries can return owned memory safely.
+
+On Unix-like systems, dynamic libraries usually use C<.so> on Linux and
+C<.dylib> on macOS. Windows libraries usually use C<.dll>. Exact
+availability depends on the host runtime. Browser runtimes reject this
+module as unsupported.
+
+=head1 EXPORTS
+
+=head2 Classes
+
+=over
+
+=item C<CLib>
+
+Static methods:
+
+=over
+
+=item C<< CLib.open(String path) >>
+
+Parameters: C<path> is a dynamic library path. Returns: C<CLibrary>.
+Loads a dynamic library.
+
+=back
+
+=item C<CLibrary>
+
+Methods:
+
+=over
+
+=item C<< func(String name, Array params, return_type, options?) >>
+
+Parameters: C<name> is a symbol name, C<params> describes parameter
+types, C<return_type> describes the return type, and C<options> is
+optional. Returns: C<CFunction>. Looks up a symbol and returns a
+callable C function wrapper.
+
+=item C<< has_symbol(String name) >>
+
+Parameters: C<name> is a symbol name. Returns: C<Boolean>. Returns
+whether the loaded library exports the named symbol.
+
+=item C<close()>
+
+Parameters: none. Returns: C<null>. Invalidates the library and
+functions created from it.
+
+=back
+
+=item C<CFunction>
+
+Methods:
+
+=over
+
+=item C<call(...)>
+
+Parameters: arguments must match the declared C signature. Returns:
+value. Calls the C function using the declared signature.
+
+=back
+
+=back
+
+=head1 COPYRIGHT AND LICENCE
+
+B<< std/clib >> 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.