zuzu-js 0.1.0

package/stdlib/modules/std/path/zz.zzm

@@ -0,0 +1,100 @@
+=encoding utf8
+
+=head1 NAME
+
+std/path/zz - ZuzuScript-flavoured path selectors.
+
+=head1 SYNOPSIS
+
+  from std/path/zz import ZZPath;
+  
+  let data := { users: [ { name: "Ada" } ] };
+  say( ( new ZZPath( path: "/users/#0/name" ) ).first(data) );
+
+=head1 IMPLEMENTATION SUPPORT
+
+This module is supported by all implementations of ZuzuScript.
+
+=head1 DESCRIPTION
+
+This module provides the public C<ZZPath> class. It currently reuses the
+ZPath traversal, parser, lexer, assignment, and reference
+machinery while routing expression operators through
+C<std/path/zz/operators> and expression functions through
+C<std/path/zz/functions>.
+
+=head1 EXPORTS
+
+=head2 Classes
+
+=over
+
+=item C<ZZEvaluator>
+
+Evaluator class that supplies ZZPath operators and functions.
+
+=over
+
+=item C<< evaluator.operator_definitions() >>
+
+Parameters: none. Returns: C<Array>. Returns ZZPath operator
+definitions.
+
+=item C<< evaluator.function_definitions() >>
+
+Parameters: none. Returns: C<Array>. Returns ZZPath function
+definitions.
+
+=back
+
+=item C<< ZZPath({ path: String }) >>
+
+Constructs a ZZPath query object. Returns: C<ZZPath>. Inherits the
+public query, assignment, and reference methods from C<ZPath>.
+
+=over
+
+=item C<< path.get_evaluator() >>
+
+Parameters: none. Returns: C<ZZEvaluator>. Returns the evaluator used
+for this path.
+
+=item C<< node.find(path) >>
+
+C<ZZPath> inherits from C<ZPath>, so a C<ZZPath> object can be passed to
+C<std/path/z/node> C<Node.find()>.
+
+=back
+
+=back
+
+=head1 COPYRIGHT AND LICENCE
+
+B<< std/path/zz >> 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/path/z import ZPath;
+from std/path/z/evaluate import Evaluator as ZEvaluator;
+
+class ZZEvaluator extends ZEvaluator {
+	method operator_definitions () {
+		from std/path/zz/operators import STANDARD_OPERATORS;
+		return STANDARD_OPERATORS;
+	}
+
+	method function_definitions () {
+		from std/path/zz/functions import STANDARD_FUNCTIONS;
+		return STANDARD_FUNCTIONS;
+	}
+}
+
+class ZZPath extends ZPath {
+	method get_evaluator () {
+		return new ZZEvaluator();
+	}
+}

package/stdlib/modules/std/proc.zzm

@@ -0,0 +1,155 @@
+=encoding utf8
+
+=head1 NAME
+
+std/proc - Process execution, environment, and signals.
+
+=head1 SYNOPSIS
+
+  from std/proc import Proc, Env, sleep;
+
+  let pid := Proc.pid();
+  let home := Env.get("HOME", "");
+
+  let res := Proc.run(
+    "perl",
+    [ "-e", "print qq<ok\\n>;" ]
+  );
+
+  let seen := 0;
+  Proc.onsignal( "USR1", function () {
+    seen++;
+  } );
+  Proc.kill( "USR1", Proc.pid() );
+
+  sleep(0.1);
+
+=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 OS process helpers, environment variable helpers,
+signal send/receive primitives, process-identification helpers, and
+process exit.
+
+=head1 EXPORTS
+
+=head2 Classes
+
+=over
+
+=item C<Proc>
+
+Static methods:
+
+=over
+
+=item * C<pid()>
+
+Parameters: none. Returns: C<Number>. Returns the current process id.
+
+=item * C<< exit(code?) >>
+
+Parameters: C<code> is an optional numeric exit status. Returns:
+C<null>. Exits the current process.
+
+=item * C<< run(command, argv?, options?) >>
+
+Parameters: C<command> is an executable, C<argv> is an optional array of
+arguments, and C<options> controls execution. Returns: C<Dict>. Runs one
+process and returns its result.
+
+Options include C<stdin>, C<capture_stdout>, C<capture_stderr>,
+and C<merge_stderr>. Also supports C<env> injection, C<cwd>, and
+C<timeout>.
+
+=item * C<< run_async(command, argv?, options?) >>
+
+Parameters: same as C<run>. Returns: C<Task>. Awaitable version of
+C<run> resolving to the same result dictionary.
+
+=item * C<< pipeline(commands, options?) >>
+
+Parameters: C<commands> is an array of command specs and C<options>
+controls execution. Returns: C<Dict>. Runs commands in sequence, piping
+captured stdout from each step to the next step's stdin.
+
+=item * C<< pipeline_async(commands, options?) >>
+
+Parameters: same as C<pipeline>. Returns: C<Task>. Awaitable version of
+C<pipeline> resolving to the same result dictionary.
+
+=item * C<is_success(result)>
+
+Parameters: C<result> is a process result dictionary. Returns:
+C<Boolean>. Returns true when the command exited successfully.
+
+=item * C<status_text(result)>
+
+Parameters: C<result> is a process result dictionary. Returns:
+C<String>. Formats the process status for display.
+
+=item * C<kill(String signal, Number pid?)>
+
+Parameters: C<signal> is a signal name and C<pid> is an optional process
+id. Returns: C<null>. Sends a signal to a process.
+
+=item * C<onsignal(String signal, Function callback)>
+
+Parameters: C<signal> is a signal name and C<callback> is a handler.
+Returns: C<null>. Registers a process signal callback.
+
+=back
+
+=item C<Env>
+
+Static methods:
+
+=over
+
+=item * C<get(String name, Any default?)>
+
+Parameters: C<name> is an environment variable name and C<default> is an
+optional fallback. Returns: C<String> or value. Returns an environment
+variable value or the fallback.
+
+=item * C<set(String name, String value)>
+
+Parameters: C<name> is an environment variable name and C<value> is its
+new value. Returns: C<null>. Sets an environment variable.
+
+=item * C<remove(String name)>
+
+Parameters: C<name> is an environment variable name. Returns: C<null>.
+Removes an environment variable.
+
+=back
+
+=back
+
+=head2 Functions
+
+=over
+
+=item * C<< sleep(seconds) >>
+
+Parameters: C<seconds> is the delay in seconds. Returns: C<null>.
+Sleeps for the requested time; fractional seconds are allowed.
+
+=item * C<< sleep_async(seconds) >>
+
+Parameters: C<seconds> is the delay in seconds. Returns: C<Task>.
+Returns an awaitable task that completes after the requested delay.
+
+=back
+
+=head1 COPYRIGHT AND LICENCE
+
+B<< std/proc >> 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/result.zzm

@@ -0,0 +1,149 @@
+=encoding utf8
+
+=head1 NAME
+
+std/result - A simple Result object for explicit success and failure values.
+
+=head1 SYNOPSIS
+
+  from std/result import Result;
+
+  let r := Result.ok(42);
+
+  if ( r.is_ok() ) {
+    say r.unwrap();
+  }
+
+=head1 IMPLEMENTATION SUPPORT
+
+This module is supported by all implementations of ZuzuScript.
+
+=head1 DESCRIPTION
+
+C<Result> is a small, subclassable object modelled on a simplified version
+of Rust's C<Result> concept. It is useful when a function, task, or worker
+wants to return an explicit success or failure value without throwing an
+exception.
+
+It is a normal ZuzuScript class. Workers do not require C<Result>; any value
+supported by C<std/marshal> may be returned.
+
+=head1 EXPORTS
+
+=head2 Classes
+
+=over
+
+=item C<Result>
+
+Container for either an ok value or an error value.
+
+=over
+
+=item C<< Result.ok(value) >>
+
+Parameters: C<value> is any success value. Returns: C<Result>. Creates an
+ok result wrapping C<value>.
+
+=item C<< Result.err(error) >>
+
+Parameters: C<error> is any error value. Returns: C<Result>. Creates an
+error result wrapping C<error>.
+
+=item C<< result.is_ok() >>
+
+Parameters: none. Returns: C<Boolean>. Returns true when the result is an
+ok value.
+
+=item C<< result.is_err() >>
+
+Parameters: none. Returns: C<Boolean>. Returns true when the result is an
+error value.
+
+=item C<< result.value() >>
+
+Parameters: none. Returns: value. Returns the stored ok value, or
+C<null> for an error result.
+
+=item C<< result.error() >>
+
+Parameters: none. Returns: value. Returns the stored error value, or
+C<null> for an ok result.
+
+=item C<< result.unwrap() >>
+
+Parameters: none. Returns: value. Returns the ok value, or throws if the
+result is an error.
+
+=item C<< result.unwrap_err() >>
+
+Parameters: none. Returns: value. Returns the error value, or throws if
+the result is ok.
+
+=back
+
+=back
+
+=head1 COPYRIGHT AND LICENCE
+
+B<< std/result >> 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 Result {
+	let Boolean _is_ok := true;
+	let _value := null;
+	let _error := null;
+
+	static method ok ( value ) {
+		return new self(
+			_is_ok: true,
+			_value: value,
+			_error: null,
+		);
+	}
+
+	static method err ( error ) {
+		return new self(
+			_is_ok: false,
+			_value: null,
+			_error: error,
+		);
+	}
+
+	method is_ok () {
+		return _is_ok;
+	}
+
+	method is_err () {
+		return not _is_ok;
+	}
+
+	method value () {
+		return _value;
+	}
+
+	method error () {
+		return _error;
+	}
+
+	method unwrap () {
+		if ( _is_ok ) {
+			return _value;
+		}
+
+		die `called Result.unwrap() on an err value: ${_error}`;
+	}
+
+	method unwrap_err () {
+		if ( not _is_ok ) {
+			return _error;
+		}
+
+		die `called Result.unwrap_err() on an ok value: ${_value}`;
+	}
+}