diff options
Diffstat (limited to 'lib')
| -rw-r--r-- | lib/astal/io/application.vala | 36 | ||||
| -rw-r--r-- | lib/astal/io/cli.vala | 16 | ||||
| -rw-r--r-- | lib/astal/io/file.vala | 17 | ||||
| -rw-r--r-- | lib/astal/io/process.vala | 75 | ||||
| -rw-r--r-- | lib/astal/io/time.vala | 44 | ||||
| -rw-r--r-- | lib/astal/io/variable.vala | 4 |
6 files changed, 170 insertions, 22 deletions
diff --git a/lib/astal/io/application.vala b/lib/astal/io/application.vala index b32de34..60a7d3e 100644 --- a/lib/astal/io/application.vala +++ b/lib/astal/io/application.vala @@ -4,6 +4,10 @@ public errordomain AppError { TAKEOVER_FAILED, } +/** + * This interface is used as a placeholder for the Astal Application class. + * It is not meant to be used by consumers. + */ public interface Application : Object { public abstract void quit() throws Error; public abstract void inspector() throws Error; @@ -16,6 +20,10 @@ public interface Application : Object { } } +/** + * Starts a [[email protected]] and binds `XDG_RUNTIME_DIR/astal/<instance_name>.sock`. + * This socket is then used by the astal cli. Not meant for public usage, but for [[email protected]_socket]. + */ public SocketService acquire_socket(Application app, out string sock) throws Error { var name = app.instance_name; foreach (var instance in get_instances()) { @@ -65,6 +73,10 @@ public SocketService acquire_socket(Application app, out string sock) throws Err return service; } +/** + * Get a list of running Astal.Application instances. + * It is the equivalent of `astal --list`. + */ public static List<string> get_instances() { var list = new List<string>(); var prefix = "io.Astal."; @@ -87,6 +99,10 @@ public static List<string> get_instances() { return list; } +/** + * Quit an an Astal instances. + * It is the equivalent of `astal --quit -i instance`. + */ public static void quit_instance(string instance) { try { IApplication proxy = Bus.get_proxy_sync( @@ -101,6 +117,10 @@ public static void quit_instance(string instance) { } } +/** + * Open the Gtk debug tool of an an Astal instances. + * It is the equivalent of `astal --inspector -i instance`. + */ public static void open_inspector(string instance) { try { IApplication proxy = Bus.get_proxy_sync( @@ -115,6 +135,10 @@ public static void open_inspector(string instance) { } } +/** + * Toggle a Window of an Astal instances. + * It is the equivalent of `astal -i instance --toggle window`. + */ public static void toggle_window_by_name(string instance, string window) { try { IApplication proxy = Bus.get_proxy_sync( @@ -129,7 +153,11 @@ public static void toggle_window_by_name(string instance, string window) { } } -public static string send_message(string instance_name, string msg) { +/** + * Send a message to an Astal instances. + * It is the equivalent of `astal -i instance content of the message`. + */ +public static string send_message(string instance, string msg) { var rundir = Environment.get_user_runtime_dir(); var socket_path = @"$rundir/astal/$instance_name.sock"; var client = new SocketClient(); @@ -146,11 +174,17 @@ public static string send_message(string instance_name, string msg) { } } +/** + * Read the socket of an Astal.Application instance. + */ public async string read_sock(SocketConnection conn) throws IOError { var stream = new DataInputStream(conn.input_stream); return yield stream.read_upto_async("\x04", -1, Priority.DEFAULT, null, null); } +/** + * Write the socket of an Astal.Application instance. + */ public async void write_sock(SocketConnection conn, string response) throws IOError { yield conn.output_stream.write_async(response.concat("\x04").data, Priority.DEFAULT); } diff --git a/lib/astal/io/cli.vala b/lib/astal/io/cli.vala index 1db0b2e..8fc0523 100644 --- a/lib/astal/io/cli.vala +++ b/lib/astal/io/cli.vala @@ -1,12 +1,12 @@ -private static bool version; -private static bool help; -private static bool list; -private static bool quit; -private static bool inspector; -private static string? toggle_window; -private static string? instance_name; +static bool version; +static bool help; +static bool list; +static bool quit; +static bool inspector; +static string? toggle_window; +static string? instance_name; -private const OptionEntry[] options = { +const OptionEntry[] options = { { "version", 'v', OptionFlags.NONE, OptionArg.NONE, ref version, null, null }, { "help", 'h', OptionFlags.NONE, OptionArg.NONE, ref help, null, null }, { "list", 'l', OptionFlags.NONE, OptionArg.NONE, ref list, null, null }, diff --git a/lib/astal/io/file.vala b/lib/astal/io/file.vala index b2d480c..e57f449 100644 --- a/lib/astal/io/file.vala +++ b/lib/astal/io/file.vala @@ -1,4 +1,7 @@ namespace AstalIO { +/** + * Read the contents of a file synchronously. + */ public string read_file(string path) { var str = ""; try { @@ -9,12 +12,18 @@ public string read_file(string path) { return str; } +/** + * Read the contents of a file asynchronously. + */ public async string read_file_async(string path) throws Error { uint8[] content; yield File.new_for_path(path).load_contents_async(null, out content, null); return (string)content; } +/** + * Write content to a file synchronously. + */ public void write_file(string path, string content) { try { FileUtils.set_contents(path, content); @@ -23,6 +32,9 @@ public void write_file(string path, string content) { } } +/** + * Write content to a file asynchronously. + */ public async void write_file_async(string path, string content) throws Error { yield File.new_for_path(path).replace_contents_async( content.data, @@ -33,6 +45,11 @@ public async void write_file_async(string path, string content) throws Error { null); } +/** + * Monitor a file for changes. If the path is a directory, monitor it recursively. + * The callback will be called passed two parameters: the path of the file + * that changed and an [[email protected]] indicating the reason. + */ public FileMonitor? monitor_file(string path, Closure callback) { try { var file = File.new_for_path(path); diff --git a/lib/astal/io/process.vala b/lib/astal/io/process.vala index e8637ab..8767012 100644 --- a/lib/astal/io/process.vala +++ b/lib/astal/io/process.vala @@ -1,3 +1,6 @@ +/** + * `Process` provides shortcuts for [[email protected]] with sane defaults. + */ public class AstalIO.Process : Object { private void read_stream(DataInputStream stream, bool err) { stream.read_line_utf8_async.begin(Priority.DEFAULT, null, (_, res) => { @@ -23,34 +26,56 @@ public class AstalIO.Process : Object { private Subprocess process; public string[] argv { construct; get; } + + /** + * When the underlying subprocess writes to its stdout + * this signal is emitted with that line. + */ public signal void stdout (string out); + + /** + * When the underlying subprocess writes to its stderr + * this signal is emitted with that line. + */ public signal void stderr (string err); + /** + * Force quit the subprocess. + */ public void kill() { process.force_exit(); } + /** + * Send a signal to the subprocess. + */ public void signal(int signal_num) { process.send_signal(signal_num); } + /** + * Write a line to the subprocess' stdin synchronously. + */ public void write(string in) throws Error { in_stream.put_string(in); } - public void write_async(string in) { - in_stream.write_all_async.begin( - in.data, - Priority.DEFAULT, null, (_, res) => { - try { - in_stream.write_all_async.end(res, null); - } catch (Error err) { - printerr("%s\n", err.message); - } - } - ); + /** + * Write a line to the subprocess' stdin asynchronously. + */ + public async void write_async(string in) { + try { + yield in_stream.write_all_async(in.data, in.data.length, null, null); + } catch (Error err) { + printerr("%s\n", err.message); + } } + /** + * Start a new subprocess with the given command. + * + * The first element of the vector is executed with the remaining elements as the argument list. + */ public Process.subprocessv(string[] cmd) throws Error { Object(argv: cmd); process = new Subprocess.newv(cmd, @@ -65,12 +90,22 @@ public class AstalIO.Process : Object { read_stream(err_stream, false); } + /** + * Start a new subprocess with the given command + * which is parsed using [[email protected]_argv]. + */ public static Process subprocess(string cmd) throws Error { string[] argv; Shell.parse_argv(cmd, out argv); return new Process.subprocessv(argv); } + /** + * Execute a command synchronously. + * The first element of the vector is executed with the remaining elements as the argument list. + * + * @return stdout of the subprocess + */ public static string execv(string[] cmd) throws Error { var process = new Subprocess.newv( cmd, @@ -88,12 +123,24 @@ public class AstalIO.Process : Object { throw new IOError.FAILED(err_str.strip()); } + /** + * Execute a command synchronously. + * The command is parsed using [[email protected]_argv]. + * + * @return stdout of the subprocess + */ public static string exec(string cmd) throws Error { string[] argv; Shell.parse_argv(cmd, out argv); return Process.execv(argv); } + /** + * Execute a command asynchronously. + * The first element of the vector is executed with the remaining elements as the argument list. + * + * @return stdout of the subprocess + */ public static async string exec_asyncv(string[] cmd) throws Error { var process = new Subprocess.newv( cmd, @@ -111,6 +158,12 @@ public class AstalIO.Process : Object { throw new IOError.FAILED(err_str.strip()); } + /** + * Execute a command asynchronously. + * The command is parsed using [[email protected]_argv]. + * + * @return stdout of the subprocess + */ public static async string exec_async(string cmd) throws Error { string[] argv; Shell.parse_argv(cmd, out argv); diff --git a/lib/astal/io/time.vala b/lib/astal/io/time.vala index 1446441..29e7e1f 100644 --- a/lib/astal/io/time.vala +++ b/lib/astal/io/time.vala @@ -1,10 +1,21 @@ +/** + * `Time` provides shortcuts for GLib timeout functions. + */ public class AstalIO.Time : Object { - public signal void now (); - public signal void cancelled (); private Cancellable cancellable; private uint timeout_id; private bool fulfilled = false; + /** + * Emitted when the timer ticks. + */ + public signal void now (); + + /** + * Emitted when the timere is cancelled. + */ + public signal void cancelled (); + construct { cancellable = new Cancellable(); cancellable.cancelled.connect(() => { @@ -26,6 +37,9 @@ public class AstalIO.Time : Object { }); } + /** + * Start an interval timer with a [[email protected]]. + */ public Time.interval_prio(uint interval, int prio = Priority.DEFAULT, Closure? fn) { connect_closure(fn); Idle.add_once(() => now()); @@ -35,6 +49,9 @@ public class AstalIO.Time : Object { }, prio); } + /** + * Start a timeout timer with a [[email protected]]. + */ public Time.timeout_prio(uint timeout, int prio = Priority.DEFAULT, Closure? fn) { connect_closure(fn); timeout_id = Timeout.add(timeout, () => { @@ -44,6 +61,9 @@ public class AstalIO.Time : Object { }, prio); } + /** + * Start an idle timer with a [[email protected]]. + */ public Time.idle_prio(int prio = Priority.DEFAULT_IDLE, Closure? fn) { connect_closure(fn); timeout_id = Idle.add(() => { @@ -53,18 +73,38 @@ public class AstalIO.Time : Object { }, prio); } + /** + * Start an interval timer. Ticks immediately then every `interval` milliseconds. + * + * @param interval Tick every milliseconds. + * @param fn Optional callback. + */ public static Time interval(uint interval, Closure? fn) { return new Time.interval_prio(interval, Priority.DEFAULT, fn); } + /** + * Start a timeout timer which ticks after `timeout` milliseconds. + * + * @param timeout Tick after milliseconds. + * @param fn Optional callback. + */ public static Time timeout(uint timeout, Closure? fn) { return new Time.timeout_prio(timeout, Priority.DEFAULT, fn); } + /** + * Start a timer which will tick when there are no higher priority tasks pending. + * + * @param fn Optional callback. + */ public static Time idle(Closure? fn) { return new Time.idle_prio(Priority.DEFAULT_IDLE, fn); } + /** + * Cancel timer and emit [[email protected]::cancelled] + */ public void cancel() { cancellable.cancel(); } diff --git a/lib/astal/io/variable.vala b/lib/astal/io/variable.vala index 2a395b4..312a27a 100644 --- a/lib/astal/io/variable.vala +++ b/lib/astal/io/variable.vala @@ -1,3 +1,7 @@ +/* + * Base class for [[email protected]] mainly meant to be used + * in higher level language bindings such as Lua and Gjs. + */ public class AstalIO.VariableBase : Object { public signal void changed (); public signal void dropped (); |