Encapsulation limits of all-defined-out in Racket modules

Answering the Question First

When a module contains both public API functions and private helpers, simply writing

(provide (all-defined-out))

will export every top‑level identifier, including the helpers. Racket does not offer a built‑in "private flag" for individual definitions, so you must explicitly exclude the unwanted names or move them to a different scope.

Mechanisms to Exclude Identifiers

• Move the helper to a sub‑module – Anything defined inside an internal module is invisible to the outer module’s exports.

  (module my-lib racket
    (define (public-fn x) (* x 2))
  
    (module private racket
      (define (helper y) (+ y 1)))
  
    (provide public-fn))
  

• Use except-out – Wrap all-defined-out in (except-out …) to strip specific names.

  (provide (except-out (all-defined-out) helper1 helper2))
  

• Define the helper as a local binding – Bind it inside a let, local, or letrec so it never becomes a top‑level identifier.

  (let ([helper (lambda (x) (+ x 1))])
    (define (public-fn y) (* (helper y) 2)))
  

• Rename and don’t provide – If a macro generates a name you don’t want exported, avoid a top‑level define for it or use (provide (rename-out …)) to expose a different name while keeping the original hidden.

Confirmed Facts

• all-defined-out only exports top‑level identifiers that have a name in the module body.
• Definitions inside internal modules, local scopes, or generated by macros without a top‑level name are not exported.
• Racket provides (except-out) to remove specific names from an exported list.
• There is no syntax-level “private” annotation for individual definitions.

Practical Verification Steps

1. Create a test module with a public function and a helper defined at the top level.
2. Export everything with (provide (all-defined-out)) and load the module in the REPL.
3. Run (module->exports 'your-module) to confirm that the helper appears in the export list.
4. Replace the provide line with (provide (except-out (all-defined-out) helper)) and verify the helper is no longer exported.
5. Alternatively, move the helper to a module private block and confirm it is still invisible to consumers.

Recommendation

For the most maintainable approach, keep truly private helpers inside a sub‑module or local binding. If you prefer to keep the helper at the top level (e.g., for debugging), wrap the provide clause with (except-out …) to exclude it. This gives you the automated export of all-defined-out while preserving encapsulation of the selected identifiers.