chore: enforcing API consistency (also across FFI)

Cargo.toml

@@ -51,7 +51,7 @@ napi = { version = "2.16", features = ["full"], optional = true }
 napi-derive = { version="2.16",  optional = true}
 
 # glue (python)
-pyo3 = { version = "0.22", features = ["extension-module"], optional = true}
+pyo3 = { version = "0.22", features = ["extension-module", "multiple-pymethods"], optional = true}
 
 # extra
 async-trait = { version = "0.1", optional = true }

dist/java/src/mp/code/Client.java

@@ -34,26 +34,26 @@ public final class Client {
 	 */
 	public static native Client connect(Config config) throws ConnectionException;
 
-	private static native User get_user(long self);
+	private static native User current_user(long self);
 
 	/**
 	 * Gets information about the current user.
 	 * @return a {@link User} object representing the user
 	 */
-	public User getUser() {
-		return get_user(this.ptr);
+	public User currentUser() {
+		return current_user(this.ptr);
 	}
 
-	private static native Workspace join_workspace(long self, String workspaceId) throws ConnectionException;
+	private static native Workspace attach_workspace(long self, String workspaceId) throws ConnectionException;
 
 	/**
 	 * Joins a {@link Workspace} and returns it.
 	 * @param workspaceId the id of the workspace to connect to
 	 * @return the relevant {@link Workspace}
 	 * @throws ConnectionException if an error occurs in communicating with the server
 	 */
-	public Workspace joinWorkspace(String workspaceId) throws ConnectionException {
-		return join_workspace(this.ptr, workspaceId);
+	public Workspace attachWorkspace(String workspaceId) throws ConnectionException {
+		return attach_workspace(this.ptr, workspaceId);
 	}
 
 	private static native void create_workspace(long self, String workspaceId) throws ConnectionRemoteException;
@@ -91,17 +91,26 @@ public void inviteToWorkspace(String workspaceId, String user) throws Connection
 		invite_to_workspace(this.ptr, workspaceId, user);
 	}
 
-	private static native String[] list_workspaces(long self, boolean owned, boolean invited) throws ConnectionRemoteException;
+	private static native String[] fetch_owned_workspaces(long self) throws ConnectionRemoteException;
 
 	/**
-	 * Lists available workspaces according to certain filters.
-	 * @param owned if owned workspaces should be included
-	 * @param invited if workspaces the user is invited to should be included
+	 * Lists workspaces owned by the current user.
 	 * @return an array of workspace IDs
 	 * @throws ConnectionRemoteException if an error occurs in communicating with the server
 	 */
-	public String[] listWorkspaces(boolean owned, boolean invited) throws ConnectionRemoteException {
-		return list_workspaces(this.ptr, owned, invited);
+	public String[] fetchOwnedWorkspaces() throws ConnectionRemoteException {
+		return fetch_owned_workspaces(this.ptr);
+	}
+
+	private static native String[] fetch_joined_workspaces(long self) throws ConnectionRemoteException;
+
+	/**
+	 * Lists workspaces the current user has joined.
+	 * @return an array of workspace IDs
+	 * @throws ConnectionRemoteException if an error occurs in communicating with the server
+	 */
+	public String[] fetchJoinedWorkspaces() throws ConnectionRemoteException {
+		return fetch_joined_workspaces(this.ptr);
 	}
 
 	private static native String[] active_workspaces(long self);

dist/java/src/mp/code/Workspace.java

@@ -1,9 +1,10 @@
 package mp.code;
 
 import java.util.Optional;
-import java.util.UUID;
 import java.util.function.Consumer;
 
+import lombok.Getter;
+import mp.code.data.User;
 import mp.code.exceptions.ConnectionException;
 import mp.code.exceptions.ConnectionRemoteException;
 import mp.code.exceptions.ControllerException;
@@ -24,24 +25,24 @@ public final class Workspace {
 		Extensions.CLEANER.register(this, () -> free(ptr));
 	}
 
-	private static native String get_workspace_id(long self);
+	private static native String id(long self);
 
 	/**
 	 * Gets the unique identifier of the current workspace.
 	 * @return the identifier
 	 */
-	public String getWorkspaceId() {
-		return get_workspace_id(this.ptr);
+	public String id() {
+		return id(this.ptr);
 	}
 
-	private static native CursorController get_cursor(long self);
+	private static native CursorController cursor(long self);
 
 	/**
 	 * Gets the {@link CursorController} for the current workspace.
 	 * @return the {@link CursorController}
 	 */
-	public CursorController getCursor() {
-		return get_cursor(this.ptr);
+	public CursorController cursor() {
+		return cursor(this.ptr);
 	}
 
 	private static native BufferController get_buffer(long self, String path);
@@ -56,17 +57,16 @@ public Optional<BufferController> getBuffer(String path) {
 		return Optional.ofNullable(get_buffer(this.ptr, path));
 	}
 
-	private static native String[] get_file_tree(long self, String filter, boolean strict);
+	private static native String[] search_buffers(long self, String filter);
 
 	/**
-	 * Gets the file tree for this workspace, optionally filtering it.
-	 * @param filter applies an optional filter to the outputs
-	 * @param strict whether it should be a strict match (equals) or not (startsWith)
+	 * Searches for buffers matching the filter in this workspace.
+	 * @param filter the filter to apply
 	 * @return an array containing file tree as flat paths
 	 */
 	@SuppressWarnings("OptionalUsedAsFieldOrParameterType")
-	public String[] getFileTree(Optional<String> filter, boolean strict) {
-		return get_file_tree(this.ptr, filter.orElse(null), strict);
+	public String[] searchBuffers(Optional<String> filter) {
+		return search_buffers(this.ptr, filter.orElse(null));
 	}
 
 	private static native String[] active_buffers(long self);
@@ -101,60 +101,62 @@ public void createBuffer(String path) throws ConnectionRemoteException {
 		create_buffer(this.ptr, path);
 	}
 
-	private static native BufferController attach_to_buffer(long self, String path) throws ConnectionException;
+	private static native BufferController attach_buffer(long self, String path) throws ConnectionException;
 
 	/**
 	 * Attaches to an existing buffer with the given path, if present.
 	 * @param path the path of the buffer to attach to
 	 * @return the {@link BufferController} associated with that path
 	 * @throws ConnectionException if an error occurs in communicating with the server, or if the buffer did not exist
 	 */
-	public BufferController attachToBuffer(String path) throws ConnectionException {
-		return attach_to_buffer(ptr, path);
+	public BufferController attachBuffer(String path) throws ConnectionException {
+		return attach_buffer(ptr, path);
 	}
 
-	private static native boolean detach_from_buffer(long self, String path);
+	private static native boolean detach_buffer(long self, String path);
 
 	/**
 	 * Detaches from a given buffer.
 	 * @param path the path of the buffer to detach from
 	 * @return a boolean, true only if there are still dangling references preventing controller from stopping
 	 */
-	public boolean detachFromBuffer(String path) {
-		return detach_from_buffer(this.ptr, path);
+	public boolean detachBuffer(String path) {
+		return detach_buffer(this.ptr, path);
 	}
 
-	private static native void fetch_buffers(long self) throws ConnectionRemoteException;
+	private static native String[] fetch_buffers(long self) throws ConnectionRemoteException;
 
 	/**
-	 * Updates the local list of buffers.
+	 * Updates and fetches the local list of buffers.
+	 * @return the updated list
 	 * @throws ConnectionRemoteException if an error occurs in communicating with the server
 	 */
-	public void fetchBuffers() throws ConnectionRemoteException {
-		fetch_buffers(this.ptr);
+	public String[] fetchBuffers() throws ConnectionRemoteException {
+		return fetch_buffers(this.ptr);
 	}
 
-	private static native void fetch_users(long self) throws ConnectionRemoteException;
+	private static native User[] fetch_users(long self) throws ConnectionRemoteException;
 
 	/**
-	 * Updates the local list of users.
+	 * Updates and fetches the local list of users.
+	 * @return the updated list
 	 * @throws ConnectionRemoteException if an error occurs in communicating with the server
 	 */
-	public void fetchUsers() throws ConnectionRemoteException {
-		fetch_buffers(this.ptr);
+	public User[] fetchUsers() throws ConnectionRemoteException {
+		return fetch_users(this.ptr);
 	}
 
-	private static native UUID[] list_buffer_users(long self, String path) throws ConnectionRemoteException;
+	private static native User[] fetch_buffer_users(long self, String path) throws ConnectionRemoteException;
 
 	/**
-	 * Lists the user attached to a certain buffer.
+	 * Fetches the users attached to a certain buffer.
 	 * The user must be attached to the buffer to perform this operation.
 	 * @param path the path of the buffer to search
-	 * @return an array of user {@link UUID UUIDs}
+	 * @return an array of {@link User}s 
 	 * @throws ConnectionRemoteException if an error occurs in communicating with the server, or the user wasn't attached
 	 */
-	public UUID[] listBufferUsers(String path) throws ConnectionRemoteException {
-		return list_buffer_users(this.ptr, path);
+	public User[] fetchBufferUsers(String path) throws ConnectionRemoteException {
+		return fetch_buffer_users(this.ptr, path);
 	}
 
 	private static native void delete_buffer(long self, String path) throws ConnectionRemoteException;
@@ -234,7 +236,8 @@ public void poll() throws ControllerException {
 	 * Represents a workspace-wide event.
 	 */
 	public static final class Event {
-		private final Type type;
+		/** The type of the event. */
+		public final @Getter Type type;
 		private final String argument;
 
 		Event(Type type, String argument) {
@@ -272,9 +275,24 @@ public Optional<String> getChangedBuffer() {
 			} else return Optional.empty();
 		}
 
-		enum Type {
+		/**
+		 * The type of workspace event.
+		 */
+		public enum Type {
+			/**
+			 * Somebody joined a workspace.
+			 * @see #getUserJoined() to get the name
+			 */
 			USER_JOIN,
+			/**
+			 * Somebody left a workspace
+			 * @see #getUserLeft() to get the name
+			 */
 			USER_LEAVE,
+			/**
+			 * The filetree was updated.
+			 * @see #getChangedBuffer() to see the buffer that changed
+			 */
 			FILE_TREE_UPDATED
 		}
 	}

dist/java/src/mp/code/data/TextChange.java

@@ -10,19 +10,18 @@
 @ToString
 @EqualsAndHashCode
 @RequiredArgsConstructor
-@SuppressWarnings("OptionalUsedAsFieldOrParameterType")
 public class TextChange {
 	/**
 	 * The starting position of the change.
 	 * If negative, it is clamped to 0.
 	 */
-	public final long start;
+	public final long startIdx;
 
 	/**
 	 * The ending position of the change.
 	 * If negative, it is clamped to 0.
 	 */
-	public final long end;
+	public final long endIdx;
 
 	/**
 	 * The content of the change.
@@ -37,7 +36,7 @@ public class TextChange {
 	 * @return true if this change represents a deletion
 	 */
 	public boolean isDelete() {
-		return this.start < this.end;
+		return this.startIdx < this.endIdx;
 	}
 
 	/**
@@ -64,14 +63,14 @@ public boolean isEmpty() {
 	 * @return the mutated string
 	 */
 	public String apply(String input) {
-		long preIndex = Math.min(this.start, input.length());
+		long preIndex = Math.min(this.startIdx, input.length());
 		String pre = "";
 		try {
 			pre = input.substring(0, (int) preIndex);
 		} catch(IndexOutOfBoundsException ignored) {}
 		String post = "";
 		try {
-			post = input.substring((int) this.end);
+			post = input.substring((int) this.endIdx);
 		} catch(IndexOutOfBoundsException ignored) {}
 		return pre + this.content + post;
 	}