Skip to content

stdlib pages do not mark which functions are effect fn #2

Description

@O6lvl4

Found in a per-page audit where every documented function was executed.

io, fs, process, env, http and random pages list functions without saying which are effect fn. Calling one from a pure fn is a compile error (E006), so this is the first thing a reader needs and the pages are silent about it.

The split is not guessable, which is what makes it worth documenting:

  • fs: everything is effect fn except temp_dir. The trap is exists / is_dir / is_file / is_symlink — they return Bool, so they read as pure, but they are effectful.
  • io: read_line, print, read_all are effect; read_byte, read_n_bytes, write, write_bytes are pure.
  • process: effect — exec, exit, stdin_lines, exec_in, exec_with_stdin, exec_status, spawn, kill. Pure — args, env, pid, sleep, is_alive.
  • env: all effect except os.
  • http: effect — serve, get, post, put, patch, delete, request. Everything else (response, json, with_headers, status, body, req_*, query_params, …) is pure.
  • random: all four functions are effect fn and the page says nothing, so every example on it only works inside an effect fn.

stdlib/args.md already states this explicitly and can serve as the pattern.

Related: a false blanket claim

stdlib/overview.md line 99 says "All I/O functions are effect fn and return Result." Both halves are false — see the pure functions listed above, and fs.exists / is_dir / is_file / is_symlink are effect but return Bool, not Result. Readers will lean on that sentence precisely because the per-page marking is missing.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions