#1670: jsh.shell.jsh JSAPI -> Fifty

davidpcaldwell · Oct 15, 2024 · 899e68c · 899e68c
1 parent da61a5d
commit 899e68c
Show file tree

Hide file tree

Showing 3 changed files with 36 additions and 34 deletions.
diff --git a/jrunscript/jsh/shell/jsh.fifty.ts b/jrunscript/jsh/shell/jsh.fifty.ts
@@ -568,24 +568,49 @@ namespace slime.jsh.shell {
 
 		export type Result = ForkResult | EngineResult
 
-		export interface Invocation {
+		export type evaluate<I,R> = (p: I) => R
+
+		export interface Invocation<R = Result> {
+			/**
+			 * The pathname of the script to run.
+			 */
 			script: slime.jrunscript.file.File
+
 			arguments?: Argument[]
+
+			/**
+			 * If `true`, the script is forced to execute in a separate process. Otherwise, jsh may attempt to execute it in-process
+			 * if it deems the script to be compatible with its execution environment.
+			 */
+			fork?: boolean
+
+			//	TODO	is the below comment correct, or does it pertain to the loader?
+			/**
+			 * The classpath to use when running the `jsh` launcher.
+			 */
+			classpath?: string
+
 			environment?: any
 			stdio?: any
 			directory?: any
 			workingDirectory?: any
 			properties?: { [x: string]: string }
 
+			/**
+			 * A function which is called after the script executes, and receives information about the result. It specifies the
+			 * return value of the call to `jsh` by returning a value.
+			 */
+			evaluate?: evaluate<Result,R>
+
 			on?: slime.jrunscript.shell.run.old.Argument["on"]
 		}
 
-		export interface EngineInvocation<R = EngineResult> extends Invocation {
+		export interface EngineInvocation<R = EngineResult> extends Invocation<R> {
 			fork?: false
 			evaluate?: (p: EngineResult) => R
 		}
 
-		export interface ForkInvocation<R = ForkResult> extends Invocation {
+		export interface ForkInvocation<R = ForkResult> extends Invocation<R> {
 			shell?: slime.jrunscript.file.Directory
 			fork?: true
 			vmarguments?: any

diff --git a/jrunscript/jsh/shell/jsh.js b/jrunscript/jsh/shell/jsh.js
@@ -134,6 +134,11 @@
 		}
 
 		$exports.shell = (
+			/**
+			 *
+			 * @param { slime.jsh.shell.old.shell.Argument } p
+			 * @returns
+			 */
 			function(p) {
 				if (arguments.length >= 2) {
 					$api.deprecate(function() {
@@ -285,7 +290,7 @@
 							script: p.script,
 							arguments: p.arguments
 						};
-						result.classpath = p["classpath"];
+						result.classpath = p.classpath;
 						return p.evaluate(result);
 					}
 				}
@@ -422,8 +427,8 @@
 				}
 			};
 
-			if (p["classpath"]) {
-				launcherProperties["jsh.shell.classpath"] = String(p["classpath"]);
+			if (p.classpath) {
+				launcherProperties["jsh.shell.classpath"] = String(p.classpath);
 			}
 
 			copySystemPropertyToLauncherPropertiesIfPresent("jsh.engine.rhino.classpath");

diff --git a/jrunscript/jsh/shell/plugin.jsh.api.html b/jrunscript/jsh/shell/plugin.jsh.api.html
@@ -151,37 +151,9 @@ <h1>Exports</h1>
 									</span>
 								</li>
 								-->
-								<li class="value">
-									<div class="name">script</div>
-									<span class="type"><a href="../../rhino/file/api.html#types.file">file</a></span>
-									<span>The pathname of the script to run.</span>
-								</li>
 								<!--	TODO	update the below using jsapi:reference	-->
-								<li class="value">
-									<div class="name">arguments</div>
-									<span class="type">Array</span>
-									<span>An argument with the same semantics as the second argument to <code>shell</code>.</span>
-								</li>
-								<li class="value">
-									<div class="name">fork</div>
-									<span class="type">boolean</span>
-									<span>
-										If <code>true</code>, the script is forced to execute in a separate process. Otherwise,
-										jsh may attempt to execute it in-process if it deems the script to be compatible with its
-										execution environment.
-									</span>
-								</li>
-								<li class="value">
-									<div class="name">classpath</div>
-									<span class="type">string</span>
-									<span>The classpath to use when running the jsh launcher.</span>
-								</li>
 								<li class="function">
 									<div class="name">evaluate</div>
-									<span>
-										A function which is called after the script executes, and receives information about the
-										result. It specifies the return value of the call to <code>jsh</code> by returning a value.
-									</span>
 									<div class="arguments">
 										<div class="label">Arguments</div>
 										<ol>