zuzu-js 0.1.0

package/stdlib/modules/std/internals.zzm

@@ -0,0 +1,139 @@
+=encoding utf8
+
+=head1 NAME
+
+std/internals - Runtime internals helpers for advanced modules.
+
+=head1 SYNOPSIS
+
+  from std/internals import class_name, classof, object_slots, ansi_esc,
+    ref_id, to_String, to_Number, to_Boolean, to_Regexp,
+    to_Regexp_with_flags,
+    make_instance, setprop, getprop, load_module;
+
+  let obj_class := class_name(some_object);
+  let obj_class_value := classof(some_object);
+  let slots := object_slots(some_object);
+  let id := ref_id(some_object);
+
+=head1 IMPLEMENTATION SUPPORT
+
+This module is supported by all implementations of ZuzuScript.
+
+=head1 DESCRIPTION
+
+This module provides low-level reflection helpers used by advanced
+pure-Zuzu modules (for example C<std/dump>). These functions are
+not intended for general application code.
+
+Special properties are lexical metadata, not symbol bindings.
+Calling C<setprop("paths", SomeClass)> does not create an identifier
+named C<paths>.
+
+=head1 EXPORTS
+
+=head2 Functions
+
+=over
+
+=item * C<class_name(value)>
+
+Parameters: C<value> is any value. Returns: C<String> or C<null>.
+Returns the class name for object instances.
+
+=item * C<classof(value)>
+
+Parameters: C<value> is any value. Returns: class value or C<null>.
+Returns the class value for object and collection values.
+
+=item * C<object_slots(value)>
+
+Parameters: C<value> is any value. Returns: C<Dict> or C<null>. Returns
+a dictionary of object slots, excluding private underscore-prefixed
+slots.
+
+=item * C<ansi_esc()>
+
+Parameters: none. Returns: C<String>. Returns a one-character ANSI
+escape string.
+
+=item * C<ref_id(value)>
+
+Parameters: C<value> is any value. Returns: C<String> or C<null>.
+Returns a stable reference id for reference-like values to support cycle
+detection.
+
+=item * C<to_String(value)>
+
+Parameters: C<value> is any value. Returns: C<String>. Coerces
+C<value> using the same rules as string operators.
+
+=item * C<to_Number(value)>
+
+Parameters: C<value> is any value. Returns: C<Number>. Coerces
+C<value> using the same rules as numeric operators.
+
+=item * C<to_Boolean(value)>
+
+Parameters: C<value> is any value. Returns: C<Boolean>. Coerces
+C<value> using the same rules as logical operators and conditions.
+
+=item * C<to_Regexp(value)>
+
+Parameters: C<value> is a regexp or pattern-like value. Returns:
+C<Regexp>. Returns C<value> unchanged when it is a regexp, otherwise
+coerces it to a string and compiles it as a regexp.
+
+=item * C<to_Regexp_with_flags(value, flags)>
+
+Parameters: C<value> is a regexp or pattern-like value and C<flags> is a
+string of regexp flags. Returns: C<Regexp>. Coerces C<value> to a pattern
+and compiles it using C<flags>.
+
+=item * C<make_instance(klass, dict := null)>
+
+Parameters: C<klass> is a class value and C<dict> is an optional slot
+dictionary. Returns: object. Creates an instance without calling
+C<__build__>.
+
+=item * C<load_module(module, symbol := null)>
+
+Parameters: C<module> is a module name and C<symbol> is an optional
+export name. Returns: C<Dict> or value. Loads a module and returns all
+exports, or one named export.
+
+=item * C<setprop(key, value)>
+
+Parameters: C<key> is a string and C<value> is any value. Returns:
+C<null>. Sets a lexically scoped runtime special property on the current
+frame.
+
+=item * C<getprop(key)>
+
+Parameters: C<key> is a string. Returns: value or C<null>. Returns a
+lexically scoped runtime special property via outward lexical lookup.
+
+=back
+
+=head1 EXAMPLES
+
+  from std/internals import setprop, getprop;
+  from std/path/z import ZPath;
+
+  setprop( "paths", ZPath );
+  say( getprop( "paths" ) );   // Class object
+
+  do {
+    setprop( "paths", null );
+    say( getprop( "paths" ) ); // null (shadowed in this block)
+  };
+
+  say( getprop( "paths" ) );   // ZPath (outer lexical value)
+
+=head1 COPYRIGHT AND LICENCE
+
+B<< std/internals >> 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/io/socks.zzm

@@ -0,0 +1,139 @@
+=encoding utf8
+
+=head1 NAME
+
+std/io/socks - socket programming helpers for Zuzu.
+
+=head1 SYNOPSIS
+
+  from std/io/socks import *;
+
+  let srv := listen_tcp( "127.0.0.1", 0 );
+  let cli := connect_tcp( "127.0.0.1", srv.port() );
+  let peer := srv.accept();
+
+  cli.say( "hello" );
+  let line := peer.next_line();
+
+=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 practical API for TCP, UDP, and Unix domain
+sockets.
+
+When possible, method names mirror other stream APIs:
+C<read>, C<write>, C<print>, C<say>, C<next_line>,
+C<each_line>, and C<close>.
+
+=head1 EXPORTS
+
+=head2 Functions
+
+=over
+
+=item C<< listen_tcp(String host?, Number port?, Number backlog?) >>
+
+Parameters: C<host>, C<port>, and C<backlog> are optional bind
+settings. Returns: C<TCPServer>. Creates a TCP listening socket.
+
+=item C<< connect_tcp(String host, Number port, Bool raw?) >>
+
+Parameters: C<host> and C<port> identify the server, and C<raw> controls
+line decoding. Returns: C<TCPSocket>. Connects to a TCP server.
+
+=item C<< bind_udp(String host?, Number port?, Bool raw?) >>
+
+Parameters: C<host>, C<port>, and C<raw> are optional bind settings.
+Returns: C<UDPSocket>. Binds a UDP socket.
+
+=item C<< connect_udp(String host, Number port, Bool raw?) >>
+
+Parameters: C<host> and C<port> identify the peer, and C<raw> controls
+byte handling. Returns: C<UDPSocket>. Creates a connected UDP socket.
+
+=item C<< listen_unix(String path, Number backlog?) >>
+
+Parameters: C<path> is the socket path and C<backlog> is optional.
+Returns: C<UnixServer>. Creates a Unix domain stream server.
+
+=item C<< connect_unix(String path, Bool raw?) >>
+
+Parameters: C<path> is the socket path and C<raw> controls line
+decoding. Returns: C<UnixSocket>. Connects to a Unix domain stream
+server.
+
+=back
+
+=head2 Classes
+
+=head3 Socket methods
+
+=over
+
+=item C<< socket.read(Number length?) >>
+
+Parameters: C<length> is an optional byte count. Returns:
+C<BinaryString> or C<String>. Reads data from the socket.
+
+=item C<< socket.write(value) >>, C<< socket.print(value) >>, C<< socket.say(value) >>
+
+Parameters: C<value> is data to send. Returns: C<null>. Writes data to
+the socket, with C<say> adding a newline.
+
+=item C<< socket.next_line() >>
+
+Parameters: none. Returns: C<String>, C<BinaryString>, or C<null>.
+Reads the next line.
+
+=item C<< socket.each_line(callback) >>
+
+Parameters: C<callback> is called for each line. Returns: C<null>.
+Iterates over incoming lines.
+
+=item C<< socket.close() >>
+
+Parameters: none. Returns: C<null>. Closes the socket.
+
+=item C<< socket.is_open() >>
+
+Parameters: none. Returns: C<Boolean>. Returns true when the socket is
+open.
+
+=back
+
+=head3 TCPSocket
+
+C<peer_host()> and C<peer_port()> take no parameters and return the
+remote host C<String> and port C<Number>.
+
+=head3 TCPServer
+
+C<accept()> returns C<TCPSocket>, C<port()> returns C<Number>,
+C<host()> returns C<String>, and C<close()> closes the server and
+returns C<null>.
+
+=head3 UDPSocket
+
+C<send(value, host?, port?)> returns C<null>; C<recv()> returns a
+received datagram value; C<port()> and C<host()> return the bound port
+and host; C<close()> closes the socket.
+
+=head3 UnixSocket / UnixServer
+
+Unix sockets support stream methods, and C<UnixServer> offers
+C<accept()> returning C<UnixSocket>, C<path()> returning C<String>, and
+C<close()> returning C<null>.
+
+=head1 COPYRIGHT AND LICENCE
+
+B<< std/io/socks >> 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/io.zzm

@@ -0,0 +1,157 @@
+=encoding utf8
+
+=head1 NAME
+
+std/io - Filesystem paths and standard stream helpers.
+
+=head1 SYNOPSIS
+
+  from std/io import Path, STDIN, STDOUT, STDERR;
+
+  let p := new Path("notes.txt");
+  p.spew_utf8("hello\n");
+
+  p.each_line( line => {
+    STDOUT.print(line);
+  } );
+
+=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 path objects built on path semantics, an
+iterator for directory traversal, and objects for standard I/O
+streams.
+
+=head1 EXPORTS
+
+=head2 Classes
+
+=over
+
+=item C<Path>
+
+Represents a filesystem path.
+
+Construction and conversion:
+
+=over
+
+=item * C<< new Path(String path = "") >>
+
+=item * C<to_String>
+
+=back
+
+Path queries and transforms:
+
+=over
+
+=item * C<basename>, C<canonpath>, C<realpath>, C<volume>
+
+=item * C<absolute>, C<child>, C<parent>, C<sibling>
+
+=item * C<is_absolute>, C<is_relative>, C<is_rootdir>
+
+=item * C<subsumes>, C<exists>, C<is_file>, C<is_dir>
+
+=back
+
+Filesystem actions:
+
+=over
+
+=item * C<copy>, C<move>, C<remove>, C<mkdir>, C<mkdir_exclusive>,
+C<remove_tree>
+
+C<mkdir_exclusive()> performs one non-recursive directory creation
+attempt. It returns true if the directory was created, false if the
+path already exists, and throws for other filesystem errors.
+
+=item * C<touch>, C<touchpath>, C<chmod>
+
+=item * C<size>, C<size_human>, C<stat>, C<lstat>
+
+=back
+
+Text and binary I/O:
+
+=over
+
+=item * C<spew>, C<append>, C<slurp>, C<lines> (BinaryString)
+
+=item * C<spew_utf8>, C<append_utf8>, C<slurp_utf8>, C<lines_utf8> (String)
+
+=item * C<spew_async>, C<append_async>, C<slurp_async>, C<lines_async>
+return awaitable C<Task> values for binary file I/O
+
+=item * C<spew_utf8_async>, C<append_utf8_async>, C<slurp_utf8_async>,
+C<lines_utf8_async> return awaitable C<Task> values for UTF-8 file I/O
+
+=item * C<edit_lines>, C<edit_lines_utf8>
+
+=item * C<each_line(callback, raw?)> where C<raw=true> yields C<BinaryString>
+
+=item * C<next_line(raw?)> where C<raw=true> returns C<BinaryString>
+
+=back
+
+Traversal helpers:
+
+=over
+
+=item * C<children(...)>
+
+=item * C<iterator(...)> returning C<PathIterator>
+
+=item * C<visit(callback, ...)>
+
+=back
+
+Static helpers:
+
+=over
+
+=item * C<Path.cwd()>, C<Path.rootdir()>
+
+=item * C<Path.tempfile(...)>, C<Path.tempdir(...)>
+
+=item * C<Path.glob(pattern, options?)>
+
+=item * C<Path.join(parts)>
+
+=item * C<Path.split(path)>
+
+=item * C<Path.normalize(path)>
+
+=back
+
+=item C<PathIterator>
+
+Directory iterator object with C<next()>.
+
+=item C<STDIN>
+
+Read helpers: C<next_line(raw?)>, C<each_line(callback, raw?)>.
+With C<raw=true>, values are C<BinaryString>; otherwise C<String>.
+
+=item C<STDOUT>
+
+Write helpers: C<print(...)>, C<say(...)>.
+
+=item C<STDERR>
+
+Write helpers: C<print(...)>, C<say(...)>.
+
+=back
+
+=head1 COPYRIGHT AND LICENCE
+
+B<< std/io >> 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.