Text files and recoverable failures

Choose the host and prepare

This guide uses ASPL 0.7.0 on both hosts. In the browser, files are temporary per-draft virtual bytes; native execution uses real filesystem paths relative to the process working directory. The API reference gives path rules and ceilings.

The supplied read example needs one filename line. For its default missing-file outcome, leave missing.txt absent. The supplied write example needs no input or imported asset; it replaces generated.txt with exactly generated\n. Before Run on a native host, choose a working directory where that replacement is intended.

Opening any supplied source creates a new draft with no run files and does not run it. Read the requirements first, open the intended draft, then import any data into that draft. Your other source drafts remain available.

Handle a missing file

Open the read example, select Run, then send missing.txt as the input line. It prints File: error: not-found\n and returns 0. The failed result does not end execution. On Linux, the same outcome requires that name to be absent in the process working directory.

fn start_main() -> i64 {
    print("File: ");
    let name = read_line();
    let content: result<string> = read_text_file(name);
    if (content::ok) {
        print(content::value);
    } else {
        print("error: ");
        print(content::error::code);
        print("\n");
    }
    return 0;
}

{
  "browser": {
    "check": "success",
    "class": "success",
    "output": "File: error: not-found\n",
    "processStatus": 0
  },
  "native": {
    "check": 0,
    "status": 0,
    "output": "File: error: not-found\n"
  }
}

The program tests ok before reading value or error::code. Preserve this branch check when adapting it. Use stable error codes to decide what to do; messages are for display.

Read imported text exactly

For a successful browser read:

1. Open the read example as a new draft.
2. Prepare a UTF-8 file named notes.txt containing exactly hello\n, a final LF after hello.
3. In that draft's Files control, import notes.txt before Run. Source import is a different action.
4. Select Run and send notes.txt. The output is exactly File: hello\n and status is 0.
5. Download notes.txt explicitly if you want a disk copy of those bytes.

For the same native read, place notes.txt in the working directory, download the source, and run aspl run read-file.aspl. Send notes.txt. Absolute native paths and subdirectories also work; browser names are flat and cannot name them.

Raw file import accepts arbitrary bytes. Reading a file containing a byte such as FF fails with invalid-utf8; the original file remains downloadable unchanged. A UTF-8 BOM, CRLF, NUL, or decomposed character remains in a successful read. No text cleanup happens automatically.

The browser displays invisible output controls with labels and CRLF as a line break. Download the file to inspect its exact bytes; the displayed representation does not modify it.

Write, read back, and download

fn start_main() -> i64 {
    print("Output: ");
    let saved: result<unit> = write_text_file("generated.txt", "generated\n");
    if (saved::ok) {
        print("saved\n");
    } else {
        print("error: ");
        print(saved::error::code);
        print("\n");
    }
    return 0;
}

{
  "browser": {
    "check": "success",
    "class": "success",
    "output": "Output: saved\n",
    "fileUpdates": [
      {
        "name": "generated.txt",
        "content": "generated\n"
      }
    ],
    "processStatus": 0
  },
  "native": {
    "check": 0,
    "status": 0,
    "output": "Output: saved\n"
  }
}

Run writes generated.txt with bytes 67 65 6E 65 72 61 74 65 64 0A, the UTF-8 text generated\n. It prints Output: saved\n. In the browser, open Files and Download generated.txt; a successful write alone does not save it to your computer. Natively, the file appears in the working directory. A later run replaces it with the same bytes.

To read it back in the same browser draft, copy the supplied read-file source into the current editor, then Run and send generated.txt. The output is File: generated\n. Opening the read example as another new draft would give it separate empty run files. Natively, run the read example from the same working directory.

An empty string writes an empty file. A write adds no newline beyond what you supply. A failed replacement preserves the previous file, but a completed write survives a later trap or Stop. On either host, checking has no file-writing effect.

Recoverable failures, traps, and source errors

not-found, invalid-utf8, and file-too-large are failed results you can inspect and recover from. Strict numeric parsing likewise returns invalid-number or number-out-of-range; input digits such as ٢ are not converted to ASCII.

Reading value from a failed result traps with wrong-result-branch. Reading value from result<unit> is a source error. Limits, host allocation failures, and cancellation have their own outcomes. Read recoverable results before treating any failed run as a failed result.

Keep source and temporary files separate

Saved draft source can return after refresh; run files cannot. Switching drafts, locale changes, same-tab Back, expansion, and Reset preserve that draft's files within this document. Reset restores source and clears output/input history while retaining files. File clear and draft deletion are separate confirmed actions. Export source and download each required data file before refreshing if you need both later.

Imports validate the whole batch. Invalid names, size limits, read failures, replacement cancellation, or Cancel change no existing files. Run locks file mutations and uses a stable snapshot. Imported and successfully written bytes are explicitly downloadable, including writes made before a later failure.

helper.aspl imported through Files is execution data, not a source-module. It cannot satisfy a browser source import. Native source modules belong to the native program's source graph and are loaded by the compiler, independently of these text-file operations.