# Todo: Enhancing the Language for Type-Checking and Elixir Transpilation

This document outlines the features and improvements required to enable robust type-checking for our language and to facilitate its transpilation into readable Elixir code.

## I. Type System Enhancements (Likely impacts `types.pl`, `parser.pl`)

- [ ] **Define Core Types:**
    - [ ] Formalize basic types: Integer, Float, String, Boolean.
    - [ ] Add support for Elixir-idiomatic types: Atoms/Symbols.
    - [ ] Define collection types: Lists, Maps (Hash-like structures).
    - [ ] Add support for Tuples.
- [ ] **Advanced Type Features:**
    - [ ] Implement Algebraic Data Types (ADTs) / Tagged Unions (e.g., `{:ok, value} | {:error, reason}`).
    - [ ] Introduce Structs/Records with named, typed fields.
    - [ ] Define Function Types (signatures for first-class functions).
    - [ ] Explore Generics/Parametric Polymorphism.
- [ ] **Type Annotations:**
    - [ ] Design syntax for type annotations for variables.
    - [ ] Design syntax for type annotations for function parameters.
    - [ ] Design syntax for type annotations for function return types.
    - [ ] Update `parser.pl` to parse these new syntax elements.
- [ ] **Type System Semantics:**
    - [ ] Define subtyping rules (if applicable).
    - [ ] Define type compatibility and coercion rules.

## II. Type Checker Implementation (Likely new modules, parts in `types.pl`)

- [ ] **AST (Abstract Syntax Tree) Enhancements:**
    - [ ] Ensure AST nodes (from `parser.pl`) can carry or be decorated with type information.
- [ ] **Type Inference:**
    - [ ] Implement a type inference algorithm (e.g., Hindley-Milner subset or simpler local inference).
- [ ] **Type Checking Algorithm:**
    - [ ] Develop a traversal algorithm for the AST to verify type correctness.
    - [ ] Create a type environment to store and look up type information for symbols (variables, functions).
- [ ] **Error Reporting:**
    - [ ] Implement clear and informative type error messages, including source locations.
- [ ] **Module System Integration:**
    - [ ] Ensure the type checker correctly handles types across modules/namespaces if the language supports them.

## III. Elixir Transpiler Development (Likely new modules/scripts, e.g., `transpiler.pl`)

- [ ] **AST to Elixir AST Mapping:**
    - [ ] Define a clear mapping from the source language AST nodes to Elixir AST constructs.
    - [ ] Handle lexical scoping and variable declarations, considering Elixir's scoping rules.
- [ ] **Code Generation:**
    - [ ] Implement a code generator that produces readable Elixir source code from the target Elixir AST.
    - [ ] Focus on generating idiomatic Elixir code.
- [ ] **Mapping Language Constructs:**
    - [ ] **Functions:**
        - [ ] Map function definitions to Elixir `def`/`defp`.
        - [ ] Handle function calls, arity, and default arguments.
        - [ ] Map anonymous functions/lambdas.
    - [ ] **Control Flow:**
        - [ ] Map conditional statements (if/else) to Elixir `if/else`, `cond`, or `case`.
        - [ ] Map loops (e.g., `for`, `while` in Perl) to Elixir's recursion, comprehensions, or `Enum` module functions.
    - [ ] **Data Structures:**
        - [ ] Map source language lists/arrays to Elixir lists.
        - [ ] Map source language hashes/maps to Elixir maps.
        - [ ] Map structs/records (if added) to Elixir structs or maps.
        - [ ] Map tuples (if added) to Elixir tuples.
    - [ ] **Operators:**
        - [ ] Map arithmetic, logical, and comparison operators, noting any semantic differences.
    - [ ] **Modules/Namespaces:**
        - [ ] Map source language modules/namespaces to Elixir `defmodule`.
        - [ ] Handle imports/exports (`require`, `import`, `alias` in Elixir).
- [ ] **Standard Library Mapping:**
    - [ ] Identify core functions in the source language's standard library.
    - [ ] Provide Elixir equivalents or implement shims/wrappers in Elixir.
- [ ] **Error Handling:**
    - [ ] Map error handling mechanisms (e.g., `die`/`warn`, exceptions in Perl) to Elixir's `try/rescue/catch` or idiomatic error tuples (`{:ok, ...}` / `{:error, ...}`).
- [ ] **Comments and Formatting:**
    - [ ] Investigate preserving comments from source to target Elixir code.
    - [ ] Implement basic code formatting for generated Elixir, or leverage Elixir's own formatter.

## IV. Language Features for Elixir Compatibility (Impacts `parser.pl`, `types.pl`)

- [ ] **Immutability:**
    - [ ] Analyze current mutability semantics. Perl is highly mutable.
    - [ ] Encourage or enforce immutability for data structures where possible to align with Elixir.
    - [ ] Provide clear strategies for handling state if mutable constructs are kept or how they map to Elixir's process state or other patterns.
- [ ] **Pattern Matching:**
    - [ ] Consider adding or enhancing pattern matching capabilities in the source language, as it's central to Elixir.
    - [ ] Update `parser.pl` and type checker for any new pattern matching syntax.
- [ ] **Concurrency:**
    - [ ] If the source language has concurrency features, plan how to map them to Elixir's actor model (Processes, GenServers, Tasks).
    - [ ] If not, consider if adding high-level concurrency constructs inspired by Elixir is feasible or desirable.
- [ ] **Truthiness/Falsiness:**
    - [ ] Define clear mapping for Perl's flexible truthy/falsy values to Elixir's stricter `false` and `nil`.

## V. Specific Perl-to-Elixir Considerations

- [ ] **Perlisms:**
    - [ ] Identify common Perl idioms and determine how they will be handled (e.g., context sensitivity like scalar/list context, implicit variables like `$_`, ` @_`). This is a major challenge.
    - [ ] Decide on a strategy for Perl's extensive built-in functions and special variables. Many might not have direct Elixir equivalents.
- [ ] **Regular Expressions:**
    - [ ] Map Perl's powerful regex features and syntax to Elixir's `Regex` module.
- [ ] **References:**
    - [ ] Determine how Perl references (to scalars, arrays, hashes, etc.) will be handled. Elixir does not have direct pointer-like references in the same way; this might involve transforming data structures or using process dictionaries/ETS carefully.
- [ ] **Sigils:**
    - [ ] Decide how Perl's sigils (`$`, `@`, `%`) will be treated. They might be dropped if type information makes them redundant, or mapped to naming conventions.

## VI. Tooling and Infrastructure

- [ ] **Build Process:**
    - [ ] Integrate type checking and transpilation into the build/compilation pipeline.
- [ ] **Testing (Extend `tests.pl` or new test suites):**
    - [ ] Add tests specifically for the type checker (unit tests for type rules, integration tests).
    - [ ] Add tests for the transpiler:
        - [ ] Unit tests for individual construct mappings.
        - [ ] Property-based tests if applicable.
        - [ ] End-to-end tests: compile source language code, transpile to Elixir, run the Elixir code, and verify output/behavior.
- [ ] **Documentation:**
    - [ ] Document the new type system (supported types, annotation syntax).
    - [ ] Document how to write code in the source language that transpiles effectively and idiomatically to Elixir.
    - [ ] Document known limitations or tricky areas of the transpiler.
- [ ] **Debugging Support (`log.pl`):**
    - [ ] Enhance `log.pl` or add new logging for debugging the type checker and transpiler.
    - [ ] Consider source map generation if feasible for debugging transpiled code.

This list is a comprehensive starting point and will likely evolve as development progresses and more is understood about the existing codebase and specific challenges.
The files `parser.pl` and `types.pl` are expected to see significant changes. New modules for transpilation (e.g., `transpiler.pl` or similar) will need to be created. `tests.pl` will need to be expanded significantly.