docs: improve documentation
This commit is contained in:
parent
5619ebebd5
commit
74ca8d15b6
6 changed files with 61 additions and 16 deletions
|
@ -35,3 +35,5 @@ pub fn render(rows: i32, cols: i32) void {
|
||||||
PRs are always welcome if you feel that something needs improvement/fixing! Make sure to follow [Conventional Commits](https://www.conventionalcommits.org/) and to run tests first, though.
|
PRs are always welcome if you feel that something needs improvement/fixing! Make sure to follow [Conventional Commits](https://www.conventionalcommits.org/) and to run tests first, though.
|
||||||
|
|
||||||
Run tests using `gyro build test`. Note that tests are run on the native target, not WASM.
|
Run tests using `gyro build test`. Note that tests are run on the native target, not WASM.
|
||||||
|
|
||||||
|
Documentation may be generated by running `gyro build -Ddocs`.
|
||||||
|
|
25
build.zig
25
build.zig
|
@ -1,7 +1,7 @@
|
||||||
const std = @import("std");
|
const std = @import("std");
|
||||||
const pkgs = @import("deps.zig").pkgs;
|
const pkgs = @import("deps.zig").pkgs;
|
||||||
|
|
||||||
pub fn build(b: *std.build.Builder) void {
|
pub fn build(b: *std.build.Builder) !void {
|
||||||
const docs = b.option(bool, "docs", "emit docs") orelse false;
|
const docs = b.option(bool, "docs", "emit docs") orelse false;
|
||||||
// Standard release options allow the person running `zig build` to select
|
// Standard release options allow the person running `zig build` to select
|
||||||
// between Debug, ReleaseSafe, ReleaseFast, and ReleaseSmall.
|
// between Debug, ReleaseSafe, ReleaseFast, and ReleaseSmall.
|
||||||
|
@ -16,6 +16,9 @@ pub fn build(b: *std.build.Builder) void {
|
||||||
|
|
||||||
if (docs) {
|
if (docs) {
|
||||||
lib.emit_docs = .{ .emit_to = "zig-out/docs" };
|
lib.emit_docs = .{ .emit_to = "zig-out/docs" };
|
||||||
|
const create_out_step = try b.allocator.create(std.build.Step);
|
||||||
|
create_out_step.* = CreateZigOutStep.step(b.allocator);
|
||||||
|
lib.step.dependOn(create_out_step);
|
||||||
}
|
}
|
||||||
|
|
||||||
lib.install();
|
lib.install();
|
||||||
|
@ -27,3 +30,23 @@ pub fn build(b: *std.build.Builder) void {
|
||||||
const test_step = b.step("test", "Run library tests");
|
const test_step = b.step("test", "Run library tests");
|
||||||
test_step.dependOn(&main_tests.step);
|
test_step.dependOn(&main_tests.step);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// A step to create the zig-out directory for documentation.
|
||||||
|
const CreateZigOutStep = struct {
|
||||||
|
pub fn step(ally: std.mem.Allocator) std.build.Step {
|
||||||
|
return std.build.Step.init(
|
||||||
|
.custom,
|
||||||
|
"Create zig-out",
|
||||||
|
ally,
|
||||||
|
&make,
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
fn make(_: *std.build.Step) anyerror!void {
|
||||||
|
// TODO: don't hardcode zig-out
|
||||||
|
std.fs.cwd().makeDir("zig-out") catch |e| {
|
||||||
|
if (e != error.PathAlreadyExists)
|
||||||
|
return e;
|
||||||
|
};
|
||||||
|
}
|
||||||
|
};
|
||||||
|
|
27
src/api.zig
27
src/api.zig
|
@ -1,16 +1,21 @@
|
||||||
|
//! This module contains Zellij's API.
|
||||||
|
//! Every function in this module is used to communicate with zellij.
|
||||||
|
|
||||||
const std = @import("std");
|
const std = @import("std");
|
||||||
const zz = @import("main.zig");
|
const zz = @import("main.zig");
|
||||||
const json = @import("json");
|
const json = @import("json");
|
||||||
const zapi = @import("zellij_api.zig");
|
const zapi = @import("zellij_api.zig");
|
||||||
const types = @import("types.zig");
|
const types = @import("types.zig");
|
||||||
|
|
||||||
|
/// Sends an object as JSON to zellij
|
||||||
pub fn sendObj(data: anytype) !void {
|
pub fn sendObj(data: anytype) !void {
|
||||||
var stdout = std.io.getStdOut();
|
var stdout = std.io.getStdOut();
|
||||||
try json.toWriter(data, stdout.writer());
|
try json.toWriter(data, stdout.writer());
|
||||||
try stdout.writeAll("\n");
|
try stdout.writeAll("\n");
|
||||||
}
|
}
|
||||||
|
|
||||||
pub fn recvObj(comptime T: type) !types.OwnedDeserData(T) {
|
/// Receives a JSON object from zellij
|
||||||
|
pub fn recvObj(comptime T: type) !zz.OwnedDeserData(T) {
|
||||||
var stdin = std.io.getStdIn();
|
var stdin = std.io.getStdIn();
|
||||||
|
|
||||||
const data = (try stdin.reader().readUntilDelimiterOrEofAlloc(
|
const data = (try stdin.reader().readUntilDelimiterOrEofAlloc(
|
||||||
|
@ -20,32 +25,37 @@ pub fn recvObj(comptime T: type) !types.OwnedDeserData(T) {
|
||||||
)) orelse unreachable;
|
)) orelse unreachable;
|
||||||
defer zz.allocator.?.free(data);
|
defer zz.allocator.?.free(data);
|
||||||
|
|
||||||
return types.OwnedDeserData(T).deserialize(zz.allocator.?, data);
|
return zz.OwnedDeserData(T).deserialize(zz.allocator.?, data);
|
||||||
}
|
}
|
||||||
|
|
||||||
// Subscription Handling
|
/// Subscribes to the given events.
|
||||||
|
/// `Plugin.update` will be called on the subscribed avents.
|
||||||
pub fn subscribe(event_types: []const types.EventType) !void {
|
pub fn subscribe(event_types: []const types.EventType) !void {
|
||||||
try sendObj(event_types);
|
try sendObj(event_types);
|
||||||
zapi.host_subscribe();
|
zapi.host_subscribe();
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Unsubscribe from the given events.
|
||||||
|
/// `Plugin.update` will no longer be called upon receiving the given events.
|
||||||
pub fn unsubscribe(event_types: []const types.EventType) !void {
|
pub fn unsubscribe(event_types: []const types.EventType) !void {
|
||||||
try sendObj(event_types);
|
try sendObj(event_types);
|
||||||
zapi.host_unsubscribe();
|
zapi.host_unsubscribe();
|
||||||
}
|
}
|
||||||
|
|
||||||
// Plugin Settings
|
/// If the plugin is set to be selectable, it will allow the user to tab into it,
|
||||||
|
/// and it will keep zellij alive if the other panes are closed.
|
||||||
pub fn setSelectable(selectable: bool) void {
|
pub fn setSelectable(selectable: bool) void {
|
||||||
zapi.host_set_selectable(@boolToInt(selectable));
|
zapi.host_set_selectable(@boolToInt(selectable));
|
||||||
}
|
}
|
||||||
|
|
||||||
// Query Functions
|
/// Returns the ID of this plugin, and zellij's PID.
|
||||||
pub fn getPluginIds() !types.OwnedDeserData(types.PluginIds) {
|
pub fn getPluginIds() !zz.OwnedDeserData(types.PluginIds) {
|
||||||
zapi.host_get_plugin_ids();
|
zapi.host_get_plugin_ids();
|
||||||
return try recvObj(types.PluginIds);
|
return try recvObj(types.PluginIds);
|
||||||
}
|
}
|
||||||
|
|
||||||
pub fn getZellijVersion() !types.OwnedDeserData([]const u8) {
|
/// Returns zellij's version string.
|
||||||
|
pub fn getZellijVersion() !zz.OwnedDeserData([]const u8) {
|
||||||
zapi.host_get_zellij_version();
|
zapi.host_get_zellij_version();
|
||||||
return try recvObj([]const u8);
|
return try recvObj([]const u8);
|
||||||
}
|
}
|
||||||
|
@ -55,14 +65,17 @@ pub fn openFile(path: []const u8) !void {
|
||||||
zapi.host_open_file();
|
zapi.host_open_file();
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Switches the currently selected zellij tab to the given index.
|
||||||
pub fn switchTabTo(tab_idx: u32) void {
|
pub fn switchTabTo(tab_idx: u32) void {
|
||||||
zapi.host_switch_tab_to(tab_idx);
|
zapi.host_switch_tab_to(tab_idx);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Triggers the `.Timer` event in the given amount of seconds.
|
||||||
pub fn setTimeout(secs: f64) void {
|
pub fn setTimeout(secs: f64) void {
|
||||||
zapi.host_set_timeout(secs);
|
zapi.host_set_timeout(secs);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Executes a system command. This must be enabled in the plugin's configuration.
|
||||||
pub fn execCmd(cmd: []const []const u8) !void {
|
pub fn execCmd(cmd: []const []const u8) !void {
|
||||||
try sendObj(cmd);
|
try sendObj(cmd);
|
||||||
zapi.host_exec_cmd();
|
zapi.host_exec_cmd();
|
||||||
|
|
13
src/main.zig
13
src/main.zig
|
@ -1,20 +1,21 @@
|
||||||
const std = @import("std");
|
const std = @import("std");
|
||||||
pub const types = @import("types.zig");
|
pub const types = @import("types.zig");
|
||||||
pub const Event = types.Event;
|
pub const Event = types.Event;
|
||||||
|
pub const OwnedDeserData = types.OwnedDeserData;
|
||||||
pub const api = @import("api.zig");
|
pub const api = @import("api.zig");
|
||||||
|
|
||||||
// This is the allocator that will be used by zellzig for communication.
|
/// This is the allocator that will be used by zellzig for communication.
|
||||||
// This must be set before events can be received.
|
/// This must be set before events can be received.
|
||||||
pub var allocator: ?std.mem.Allocator = null;
|
pub var allocator: ?std.mem.Allocator = null;
|
||||||
|
|
||||||
comptime {
|
test {
|
||||||
if (@import("builtin").is_test)
|
std.testing.refAllDecls(@This());
|
||||||
std.testing.refAllDecls(@This());
|
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Creates a plugin that can be called into by zellij. This function should take a
|
/// Creates a plugin that can be called into by zellij. This function should take a
|
||||||
/// struct type with the functions of your plugin. Usage of this function should
|
/// struct type with the functions of your plugin. Usage of this function should
|
||||||
/// look like this:
|
/// look like this:
|
||||||
|
///
|
||||||
/// ```zig
|
/// ```zig
|
||||||
/// // main.zig
|
/// // main.zig
|
||||||
/// const zz = @import("zellzig");
|
/// const zz = @import("zellzig");
|
||||||
|
@ -26,7 +27,7 @@ comptime {
|
||||||
/// const alloc = std.heap.GeneralPurposeAllocator(.{}){};
|
/// const alloc = std.heap.GeneralPurposeAllocator(.{}){};
|
||||||
/// zz.allocator = alloc.allocator();
|
/// zz.allocator = alloc.allocator();
|
||||||
/// }
|
/// }
|
||||||
/// pub fn update() void {}
|
/// pub fn update(event: zz.Event) void {}
|
||||||
/// pub fn render(rows: i32, cols: i32) void {}
|
/// pub fn render(rows: i32, cols: i32) void {}
|
||||||
/// ```
|
/// ```
|
||||||
pub fn createPlugin(comptime Plugin: type) void {
|
pub fn createPlugin(comptime Plugin: type) void {
|
||||||
|
|
|
@ -10,8 +10,12 @@ pub const dbs = .{
|
||||||
@import("deserialization_blocks/line_and_column.zig"),
|
@import("deserialization_blocks/line_and_column.zig"),
|
||||||
};
|
};
|
||||||
|
|
||||||
// required because the only way to properly free deserilized
|
/// This is a wrapper object around some data deserialized from JSON.
|
||||||
// json is using an arena alloc.
|
/// Its purpose is to manage the allocation of the data, as the data
|
||||||
|
/// created by the JSON deserializer needs to be managed using an arena allocator.
|
||||||
|
///
|
||||||
|
/// This object must be freed by calling `deinit`.
|
||||||
|
/// The data can be accessed using the `data` field.
|
||||||
pub fn OwnedDeserData(comptime T: type) type {
|
pub fn OwnedDeserData(comptime T: type) type {
|
||||||
return struct {
|
return struct {
|
||||||
data: T,
|
data: T,
|
||||||
|
|
|
@ -1,3 +1,5 @@
|
||||||
|
//! Raw Zellij API externs.
|
||||||
|
|
||||||
pub extern "zellij" fn host_subscribe() void;
|
pub extern "zellij" fn host_subscribe() void;
|
||||||
pub extern "zellij" fn host_unsubscribe() void;
|
pub extern "zellij" fn host_unsubscribe() void;
|
||||||
pub extern "zellij" fn host_set_selectable(selectable: i32) void;
|
pub extern "zellij" fn host_set_selectable(selectable: i32) void;
|
||||||
|
|
Loading…
Reference in a new issue