Dynamically parses, compiles and runs source code.
This function is exported by the KS module.
Note: Running source code requires the optional compiler component in the calling process; running an already-compiled script does not. See Optional Scripting Components and IsComponentAvailable.
Process := RunScript(Code , Async := false, Callback, Name := "*", Executable, Options)
Type: String
The source code to compile and execute, or the path of a script file. If a file of that name exists it is used. A .cks or .dll file is taken as an already-compiled script and run without being compiled.
If true, the function returns as soon as the child starts. If false or omitted, it waits until the child exits. A synchronous call drains standard output and standard error concurrently while it waits, so filling either pipe does not block the child, and waits as RunWait does, so timers, hotkeys and the Callback can run before it returns.
For an asynchronous call, read both StdOut and StdErr while a verbose child is running so neither pipe fills.
Type: Func
An optional function called with the ScriptProcess as its only parameter once the child exits. It is called on the real thread which called RunScript, and a pending callback keeps the script running.
The script name. The default is "*".
An executable path used to run the compiled assembly. If omitted, the current executable is used.
Type: String or Array
Command-line switches for this script. A string is split on whitespace, with double quotes grouping an argument which contains spaces and being removed:
RunScript(src, , , , , '--define:FEATURE_X --include "My include.ahk"')
An Array supplies each argument separately, which needs no quoting and is the reliable form when a value may contain quotes or trailing backslashes:
RunScript(src, , , , , ["--define:FEATURE_X", "--include", "My include.ahk"])
No switches are inherited from the calling script.
--define and --include apply to the compilation of Code; every other switch is passed to the child process.
Type: ScriptProcess
Returns an object which encapsulates the child process and its I/O.
An Error is thrown if the compiler component is needed but not installed, or if Code fails to compile; its message contains the compiler's report.
A ValueError is thrown if Options contains an invalid --define, an --include without a file or a second one, or any --define or --include when Code names an already-compiled script.
The object returned by RunScript encapsulates the child process and its redirected I/O. This object has the following methods and properties:
Process.HasExited: Returns 1 if the process has exited and 0 while it is still running.
Process.ExitCode: Returns the process exit code, or an empty string while the process is still running.
Process.ExitTime: Returns the time the process exited, in YYYYMMDDHH24MISS form, or an empty string while it is still running.
Process.StdOut: Returns the process's standard output as a File object, for reading.
Process.StdErr: Returns the process's standard error as a File object, for reading.
Process.StdIn: Returns the process's standard input as a File object, for writing. Call Close() on this File when the child reads until end-of-file.
Process.Kill(): Terminates the process.
Process.Close(): Closes the redirected streams, cancels a pending exit callback and releases the process's resources. It does not terminate a running process; use Kill for that.
A stream property returns the same object on every access after the first, so a partially read StdOut keeps its position.
#Import "Ks" { RunScript }
Process := RunScript('FileAppend "hello``n", "*"')
MsgBox Process.StdOut.Read()