Document R2Shell (Previously known as R2PapiShell)

typescript/examples/draft-shell.qjs

@@ -3,7 +3,7 @@
 
 
 
-const SH = new R2PapiShell (R);
+const SH = new R2Shell (R);
 
 SH.system("git --help");
 

typescript/r2papi.ts

@@ -1,7 +1,7 @@
 // r2papi main file
 
 // import { R, Module, Process, Thread } from "./global.js"
-import { R2PapiShell } from "./shell.js";
+import { R2Shell } from "./shell.js";
 import { r2, R2Pipe } from "./r2pipe.js";
 
 export type InstructionType = "mov" | "jmp" | "cmp" | "nop" | "call" | "add" | "sub";
@@ -390,8 +390,8 @@ export class R2Papi {
 	at(a: string) : NativePointer {
 		return new NativePointer(a);
 	}
-	getShell(): R2PapiShell {
-		return new R2PapiShell (this);
+	getShell(): R2Shell {
+		return new R2Shell (this);
 	}
 	// Radare/Frida
 	version(): string {

typescript/shell.ts

@@ -2,16 +2,47 @@
 
 import { R2Papi } from "./r2papi.js";
 
-export class R2PapiShell {
+/**
+ * Interface to hold the name and description for every filesystem type parser implementation.
+ *
+ * @typedef FileSystemType
+ */
+export interface FileSystemType {
+	name: string;
+	description: string;
+}
+
+/**
+ * Class that interacts with the `r2ai` plugin (requires `rlang-python` and `r2i` r2pm packages to be installed).
+ * Provides a way to script the interactions with different language models using javascript from inside radare2.
+ *
+ * @typedef R2Shell
+ */
+export class R2Shell {
+	/**
+	 * Keep a reference to the associated r2papi instance
+	 *
+	 * @type {R2Papi}
+	 */
 	public rp: R2Papi;
 
+	/**
+	* Create a new instance of the R2Shell
+	*
+        * @param {R2Papi} take the R2Papi intance to used as backend to run the commands
+        * @returns {R2Shell} instance of the shell api
+ 	*/
 	constructor(papi: R2Papi) {
 		this.rp = papi;
 	}
 
 	/**
 	* Create a new directory in the host system, if the opational recursive argument is set to
 	* true it will create all the necessary subdirectories instead of just the specified one.
+	*
+        * @param {string} text path to the new directory to be created
+        * @param {boolean?} disabled by default, but if it's true, it will create subdirectories recursively if necessary
+        * @returns {boolean} true if successful
  	*/
 	mkdir(file: string, recursive?:boolean): boolean {
 		if (recursive === true) {
@@ -24,6 +55,9 @@ export class R2PapiShell {
 
 	/**
 	* Deletes a file
+	*
+        * @param {string} path to the file to remove
+        * @returns {boolean} true if successful
  	*/
 	unlink(file: string): boolean {
 		this.rp.call (`rm ${file}`);
@@ -32,63 +66,121 @@ export class R2PapiShell {
 
 	/**
 	* Change current directory
+	*
+        * @param {string} path to the directory
+        * @returns {boolean} true if successful
  	*/
 	chdir(path:string) : boolean {
 		this.rp.call (`cd ${path}`);
 		return true;
 	}
 
+	/**
+	* List files in the current directory
+	*
+        * @returns {string[]} array of file names
+ 	*/
 	ls(): string[] {
 		return this.rp.call(`ls -q`).trim().split('\n')
 	}
 
+	/**
+	* TODO: Checks if a file exists (not implemented)
+	*
+        * @returns {boolean} true if the file exists, false if it does not
+ 	*/
 	fileExists(path: string) : boolean {
 		// TODO
 		return false;
 	}
+
 	/**
 	* Opens an URL or application
-	* calls `xdg-open` on linux, `start` on windows, `open` on Mac
+	* Execute `xdg-open` on linux, `start` on windows, `open` on Mac
+	*
+        * @param {string} URI or file to open by the system
  	*/
 	open(arg: string): void {
 		this.rp.call (`open ${arg}`);
 	}
 
+	/**
+	* Run a system command and get the return code
+	*
+        * @param {string} system command to be executed
+        * @returns {number} return code (0 is success)
+ 	*/
 	system(cmd: string): number {
 		this.rp.call (`!${cmd}`);
 		return 0;
 	}
 
-	run(path: string): number {
-		this.rp.call (`rm ${path}`);
-		return 0;
-	}
-	mount(fstype: string, path: string) : boolean {
-		this.rp.call (`m ${fstype} ${path}`);
+	/**
+	* Mount the given offset on the specified path using the filesytem.
+	* This is not a system-level mountpoint, it's using the internal filesystem abstraction of radare2.
+	*
+        * @param {string} filesystem type name (see .
+        * @param {string} system command to be executed
+        * @param {string|number}
+        * @returns {number} return code (0 is success)
+ 	*/
+	mount(fstype: string, path: string, offset: string|number) : boolean {
+		if (!offset) {
+			offset = 0;
+		}
+		this.rp.call (`m ${fstype} ${path} ${offset}`);
 		return true;
 	}
+	/**
+	* Unmount the mountpoint associated with the given path.
+	*
+        * @param {string} path to the mounted filesystem
+        * @returns {void} TODO: should return boolean
+ 	*/
 	umount(path: string) : void {
 		this.rp.call (`m-${path}`);
 	}
-	chdir2(path: string) : boolean {
-		if (path === undefined) {
-			path = "/";
-		}
+	/**
+	* Change current directory on the internal radare2 filesystem
+	*
+        * @param {string} path name to change to
+        * @returns {void} TODO: should return boolean
+ 	*/
+	chdir2(path: string) : void {
 		this.rp.call (`mdq ${path}`);
-		return true;
 	}
+	/**
+	* List the files contained in the given path within the virtual radare2 filesystem.
+	*
+        * @param {string} path name to change to
+        * @returns {void} TODO: should return boolean
+ 	*/
 	ls2(path: string) : string[] {
-		if (path === undefined) {
-			path = "/";
-		}
 		return this.rp.call (`mdq ${path}`).trim().split('\n');
 	}
-	enumerateMountpoints(): string[] {
-		return this.rp.cmdj ("mlj");
+	/**
+	 * Enumerate all the mountpoints set in the internal virtual filesystem of radare2
+	 * @returns {any[]} array of mount
+	 */
+	enumerateFilesystemTypes(): any[] {
+		return this.rp.cmdj ("mLj");
 	}
+	/**
+	 * Enumerate all the mountpoints set in the internal virtual filesystem of radare2
+	 * @returns {any[]} array of mount
+	 */
+	enumerateMountpoints(): any[] {
+		return this.rp.cmdj ("mj")['mountpoints'];
+	}
+	/**
+	 * TODO: not implemented
+	 */
 	isSymlink(file:string) : boolean {
 		return false;
 	}
+	/**
+	 * TODO: not implemented
+	 */
 	isDirectory(file:string) : boolean {
 		return false;
 	}