How thamizh-arasu/uttr works
UTTR is a single-language interpreter repository, organized around a classic source-to-execution pipeline with a few important runtime subsystems layered around it.
At the highest level, the repository splits into four major architectural zones:
1. Language front end
2. Runtime/object model
3. Module and standard library loading
4. Developer-facing execution and verification tools
1) Language front end: source text to AST
The front end is built from the usual interpreter stages:
• lexer.py turns raw .uttr source into tokens.
• parser.py consumes tokens and builds an abstract syntax tree.
• nodes/ contains the AST node types used by the parser and interpreter.
This is a handwritten language implementation in Python, not a generated parser or compiler. The grammar supports a procedure-oriented, English-like syntax with constructs such as:
• variable and constant binding
• conditionals
• check...whether...default switch cases
• cycle, as long as, and repeat while loops
• function definitions and calls
• lambdas
• list, tuple, set, dict, string, and regex literals
• attempt...handle error handling
• bring in / share module statements
• cut and skip loop control
The AST node files show the grammar shape clearly: there are dedicated node classes for all major expressions and statements, such as if_node.py, for_node.py, while_node.py, function_definition_node.py, attempt_handle_node.py, switch_case_node.py, and the literal/access nodes for collections and primitives.
A useful diagram boundary is that the parser does not execute anything; it only produces a tree of node objects. Those node objects are then handed to the interpreter.
2) Runtime execution: AST to values and side effects
The runtime center is interpreter.py. It walks the AST and evaluates nodes in the current execution context.
The interpreter depends on a small set of runtime infrastructure classes:
• context.py for call/context state
• symbol_table.py for variable and constant resolution
• position.py for source location tracking
• run_time_result.py for propagating success, return, break/continue, and errors
• parse_result.py for parser success/error propagation
This architecture means execution state is explicit and scoped. A context owns a symbol table and can link to a parent context, which is how function calls and module execution keep their own scope while still reaching outer symbols when appropriate.
The runtime value system is separated into values/:
• number_value.py
• string_value.py
• list_value.py
• tuple_value.py
• set_value.py
• dict_value.py
• regex_value.py
• error_value.py
• value.py as the common base
This is a strong architectural boundary: the interpreter does not manipulate Python primitive types directly once execution starts. Instead, each UTTR type has its own runtime object with behavior such as arithmetic, comparison, indexing, mutation, and stringification. That makes it much easier to reason about language semantics, immutability, and operator overloading.
The functions/ package provides the callable abstraction:
• base_function.py defines the common interface
• function.py handles user-defined UTTR functions
• builtin_function.py handles built-in functions like I/O, collection helpers, regex helpers, and run
This means function invocation is unified at runtime regardless of whether a function originated from UTTR source or was provided by the runtime.
3) Module system and standard library
Modules are a first-class subsystem, not a thin import wrapper.
Key files:
• module.py
• module_loader.py
• module_config.py
The README and file structure indicate a module system with:
• bring in for whole-module imports
• selective imports with aliases
• share for explicit exports
• automatic export of top-level definitions when not hidden by underscore naming
• module caching
• circular import detection
• path resolution across current file directory, current working directory, and stdlib/
This subsystem is important architecturally because imported functions preserve their defining context. That means a function imported from a module can still see other module-local symbols when invoked elsewhere. So a module is not just copied text; it behaves like a separately executed namespace with retained runtime identity.
The stdlib/ directory contains UTTR-authored standard library modules:
• math.uttr
• lists.uttr
• strings.uttr
These are part of the language distribution but are implemented in the language itself rather than in Python, which makes the module system both a user feature and a bootstrap mechanism for reusable libraries.
The module system is also a boundary between user code and language-provided code. The loader resolves imports, executes modules once, and reuses cached module state afterward.
4) Errors and diagnostics
The errors/ package defines the error hierarchy:
• error.py as the base
• illegal_character.py
• invalid_syntax.py
• run_time_error.py
• module_not_found_error.py
• circular_import_error.py
This separates lexical, parse, runtime, and module-resolution failures. Source-position-aware reporting is a major design goal, supported by position.py and strings_with_arrows.py, which produces the caret/arrow-style diagnostics shown in the README.
The runtime also supports UTTR-level error handling via attempt...handle, and values/error_value.py suggests caught errors are reified as runtime values with fields like message and type. That means there are two related error paths:
• engine-internal errors used to stop or report the interpreter
• language-level caught errors exposed to UTTR programs as values
That distinction is important for diagramming: not every error terminates execution immediately; some are intentionally captured and handled in the language.
5) Entry points and execution surfaces
There are two main execution surfaces:
• entry.py as the orchestration entry point
• shell.py as the REPL / command-line runner
entry.py likely wires together lexer, parser, interpreter, and the initial global symbol table setup. shell.py adds user interaction: running files or starting an interactive REPL session.
lexer_testing.py is a separate tool for token inspection and lexer diagnostics.
So, from an architecture diagram perspective, the typical flow is:
• source file or REPL input
• lexer
• parser
• AST
• interpreter
• runtime values / symbol tables / contexts
• output or errors
6) Repository structure as a product boundary
The repository clearly contains both implementation and specification assets:
• examples/ demonstrates language features and serves as executable documentation
• tests/ contains a substantial .uttr test suite and a Python runner
• debug/ stores targeted regression cases and lexer/parser behavior samples
• docs/ contains design notes for regex and import-context behavior
• assets/ contains branding/logo material, not part of execution
The tests are especially informative architecturally: they cover language semantics rather than just unit-testing small functions. That suggests the project is validated primarily through end-to-end execution of source programs through the full interpreter pipeline.
7) Main data flows
Source execution flow
1. A .uttr program enters through shell.py or entry.py.
2. lexer.py tokenizes source text using keyword definitions from tokens.py and character classes from constants.py.
3. parser.py transforms tokens into AST nodes from nodes/.
4. interpreter.py evaluates the AST.
5. Evaluation reads/writes symbol_table.py inside a context.py.
6. Values are represented by classes in values/.
7. Built-in and user-defined calls are unified through functions/.
8. Errors propagate through result wrappers and the error hierarchy.
Module import flow
1. An import statement reaches the interpreter.
2. The module loader resolves the target path.
3. The target module is parsed and executed in its own context.
4. Exported symbols are cached and exposed to the importing program.
5. Circular dependencies and missing modules are detected and reported as specialized errors.
Error flow
1. The lexer/parser/interpreter raises or returns a structured error.
2. Position metadata from position.py is attached.
3. strings_with_arrows.py formats readable source excerpts.
4. For attempt...handle, runtime errors can be wrapped into error_value.py and handled inside the language.
8) Technologies and operational profile
This is a pure Python project targeting Python 3.7+ and uses only the Python standard library. That matters architecturally because the runtime is self-contained: parsing, execution, modules, regex support, and tests all live inside the repository without external dependencies.
Regular expressions are implemented with Python’s re module under the hood, but exposed through UTTR syntax and runtime values. The README shows this is treated as a language feature, not a library addon.
9) How to think about the architecture diagram
If you are drawing a diagram, the cleanest set of boxes is:
• Input surface: REPL / file runner
• Language front end: lexer + parser + AST nodes
• Runtime engine: interpreter + execution result handling
• Runtime state: contexts + symbol tables + values + functions
• Module system: loader + config + standard library modules
• Diagnostics: error classes + arrow-based source rendering
• Validation content: examples + tests + debug cases
The important boundaries are:
• syntax processing versus execution
• user-defined values versus Python host objects
• normal program flow versus error-handling flow
• local module namespace versus imported/exported symbol visibility
• built-in runtime functions versus UTTR-authored stdlib modules
Overall, UTTR is a compact but fully layered interpreter platform, with a clear separation between language parsing, runtime semantics, module loading, and test/example content.
Main entry points: interpreter.py Interpreter · entry.py Entry · module_loader.py Modules · lexer.py Lexer
Components 20
Language front end
Tokenization, parsing, and AST construction.
Runtime engine
Execution state, values, and callable abstractions.
- Interpreter · Evaluates the AST and drives program execution.
interpreter.py - Context · Holds call/module execution state and links to parent scopes.
context.py - Symbols · Resolves variables and constants within a context.
symbol_table.py - Run result · Propagates returns, breaks, continues, and runtime errors.
run_time_result.py - Values · UTTR value objects such as numbers, strings, collections, regexes, and errors.
values/value.py - Functions · Unifies user-defined and built-in callable behavior.
functions/base_function.py
Module system
Import resolution, caching, and stdlib loading.
- Modules · Resolves, loads, caches, and exposes imported modules.
module_loader.py - Module model · Represents a loaded module and its exported namespace.
module.py - Stdlib · UTTR-authored standard library modules for math, lists, and strings.
stdlib/math.uttr
Diagnostics
Error types and source-aware reporting.
Execution tools
Entry points, REPL, and test harnesses.
Repo content
Examples, tests, docs, and debug programs.
- Tests · End-to-end UTTR test programs and the Python test runner.
tests/run_tests.py - Examples · Executable language examples and usage demonstrations.
examples/functions.uttr - Debug cases · Targeted lexer/parser/runtime edge cases and reproductions.
debug/test_lambda_basic.uttr - Docs · Architecture notes for imports and regex behavior.
docs/regex_design.md
Connections 25
- Entry → Lexer: starts · Orchestration begins by scanning source text.
- Entry → Parser: wires · Entry point feeds lexer output into parsing.
- Entry → Interpreter: runs · Initializes execution of the parsed program.
- Shell → Entry: delegates · Shell uses the entry pipeline for file execution and REPL actions.
- Lexer → Parser: tokens · Parser consumes lexer-produced tokens.
- Parser → AST nodes: builds · Parser instantiates AST node objects.
- AST nodes → Interpreter: executed by · Interpreter evaluates AST node types.
- Interpreter → Context: uses · Execution occurs within a scoped context.
- Context → Symbols: owns · Each context carries symbol storage.
- Interpreter → Run result: propagates · Evaluation returns structured flow-control results.
- Interpreter → Values: produces · Runtime semantics operate on UTTR value objects.
- Functions → Values: returns · Callable execution yields runtime values.
- Interpreter → Functions: invokes · User and built-in calls share one callable abstraction.
- Modules → Module model: creates · Loader materializes module instances and cached state.
- Modules → Stdlib: loads · Loader resolves UTTR standard library modules.
- Interpreter → Modules: imports · Import nodes trigger module resolution and execution.
- Modules → Context: scopes · Modules execute in their own linked context.
- Errors → Arrows: formats · Error reporting is rendered with source arrows.
- Lexer → Errors: reports · Illegal character failures surface as lexical errors.
- Parser → Errors: reports · Syntax failures surface as parser errors.
- Interpreter → Errors: reports · Runtime failures and import failures become structured errors.
- Tests → Entry: executes · The test harness runs programs through the interpreter pipeline.
- Examples → Entry: demonstrates · Examples are executable inputs for the main pipeline.
- Debug cases → Lexer: probes · Debug cases focus on lexing and parser edge cases.
- Docs → Modules: describes · Design notes document import and regex behavior.