nbun/efci

1. This is a Haskell-based Curry interpreter. The repository is split into a small executable front end, an interpreter/runtime core, a transformation layer, and a set of effect handlers that model Curry semantics such as nondeterminism, state, reader context, memoization, error handling, and IO.

2. The executable entry point is app/Main.hs, which wires the CLI/REPL behavior to the interpreter code in src/. src/App.hs is the top-level application orchestration module, while the user-facing commands described in the README (:q, :o, :time, :fcy) indicate an interactive interpreter loop rather than a batch compiler.

3. Source programs are Curry files (.curry). The repository includes a curry-frontend submodule, which is the external frontend used to parse/translate Curry source into FlatCurry, the intermediate representation used by this interpreter. The bundled data/Prelude.curry and benchmarks/data/Prelude.curry show that Prelude loading is part of the normal runtime setup.

4. The core execution pipeline appears to be: Curry source or interactive input → frontend-generated FlatCurry → internal transformation/intermediate forms → effectful evaluation. src/Pipeline.hs is the obvious coordination point for these stages, and src/Transformation/FCY2AE.hs suggests a translation from FlatCurry into an algebraic-effects-based representation.

5. The interpreter itself is split across multiple execution styles or evaluation layers. src/InterpFL.hs suggests a FlatCurry interpreter, while src/Monolith.hs implies an alternative “all-in-one” interpreter path. The README’s “rotate between interpretation modes” strongly suggests the CLI can switch among these modes at runtime.

6. Effects are the main architectural boundary. Under src/Effect/General/ are reusable effect handlers for Error, Memoization, ND (nondeterminism), Reader, and State. Under src/Effect/FlatCurry/ are handlers specialized to FlatCurry constructs such as constructors, declarations, functions, let-bindings, and IO. This indicates the interpreter is structured as a stack of effect handlers rather than a single monolithic evaluator.

7. The effect infrastructure is supported by generic runtime machinery in src/Free.hs, src/DelCont.hs, and src/Data/Union.hs. These modules likely implement the underlying free/effect representation, delimited continuations, and type-safe effect unions used by the handlers. src/Signature.hs and src/Type.hs appear to define the typed interface for operations and Curry/FlatCurry types.

8. src/Debug.hs is a supporting diagnostics layer, likely used for tracing or development output. This is consistent with an interpreter project where visibility into evaluation order, sharing, and nondeterminism is important.

9. examples/ contains small Curry programs used to exercise language features such as arithmetic, binary data, nondeterminism, sharing semantics, and special effects. benchmarks/ contains larger benchmark programs plus a benchmark driver (benchmarks/Main.hs) and benchmark output (benchmarks/result/bench.csv), showing that performance and semantics across different evaluation strategies are both first-class concerns.

10. tests/Main.hs provides the test entry point, while stack.yaml, effective-curry-interpreter.cabal, and fourmolu.yaml show the project is built and formatted as a standard Haskell package. The README’s note about “not all external functions are implemented” implies there is a runtime boundary between the interpreted Curry core and host-provided primitives.

11. A useful architecture diagram would show three external inputs feeding the system: interactive user expressions, Curry source modules, and benchmark/example programs. Those all flow into the frontend/FlatCurry layer, then into the effect-based interpreter, and finally back to the REPL/benchmark/test harness as evaluated results, nondeterministic outcomes, or runtime errors.