glassjar 0.9.0 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -84,12 +84,13 @@ engine.binaryFiles; // Record<string, Uint8Array> — optional C/C++ binary file
84
84
  engine.cppArtifacts; // Optional selected sources, archives, and precompiled header
85
85
  engine.stdout; // Stdout — .on('data', (chunk: Uint8Array) => …) / .off(...)
86
86
  engine.stderr; // Stdout
87
- engine.stdin; // Stdin — .write(string | Uint8Array): Promise<void>
87
+ engine.stdin; // Stdin — .write(string | Uint8Array): Promise<void>; .end() closes input (end-of-file)
88
+ engine.program = { args, cwd, entry, env, collectFiles }; // how the next run starts, like a shell — see below
88
89
  engine.hostDevice; // Optional C/C++ and Python duplex byte device — see below
89
90
  engine.debugger; // Debugger — DAP interface; set .enabled = false to skip the handshake
90
91
  engine.lang; // Lang
91
92
 
92
- engine.run(); // Promise<RunResult> — { type: 'completed', exitCode } | { type: 'stopped' } | { type: 'error', error }
93
+ engine.run(); // Promise<RunResult> — { type: 'completed', exitCode, files? } | { type: 'stopped' } | { type: 'error', error }
93
94
  engine.stop(); // void — kills the worker; run() resolves with { type: 'stopped' }
94
95
 
95
96
  engine.debugger.send(message); // DAP request, returns response synchronously
@@ -104,6 +105,33 @@ See [Presentation filtering (Python)](./docs/integration.md#presentation-filteri
104
105
 
105
106
  ---
106
107
 
108
+ ## Starting programs like a shell
109
+
110
+ `engine.program` controls how the next run starts the student's program, so a host can
111
+ offer a terminal with `python greet.py Alice` or `./app < input.txt`:
112
+
113
+ ```ts
114
+ engine.program = {
115
+ args: ['Alice', 'two words'], // argv[1..] in C/C++ and Rust, sys.argv[1:] in Python
116
+ cwd: '/data', // relative paths resolve from here
117
+ entry: '/tools/greet.py', // Python script or Rust crate root (default main.py / main.rs)
118
+ env: { TERM: 'xterm-256color', COLUMNS: '100', LINES: '30' },
119
+ collectFiles: true // return what the program wrote
120
+ };
121
+ const result = await engine.run();
122
+ // result.files: { written: { '/data/out.txt': Uint8Array }, removed: ['/data/old.txt'], truncated }
123
+ ```
124
+
125
+ C/C++ chooses its files with `cppArtifacts.sources`. With `collectFiles`, the result lists
126
+ regular files the program created, changed or removed in `/` and the folders it was given
127
+ (at most 64 files, 1 MiB each, 4 MiB in all); the language's own files are never read.
128
+
129
+ `engine.stdin.end()` closes the program's input once it has read everything written so
130
+ far, like Ctrl+D or the end of a `< file`. C/C++ programs also show a pending `printf`
131
+ prompt before reading stdin, as on Linux.
132
+
133
+ ---
134
+
107
135
  ## Precompiled C++ inputs
108
136
 
109
137
  Set `binaryFiles` to bytes keyed by absolute virtual paths. Set `cppArtifacts`