01_compiler_api

Compiler API

The Compiler API

Purpose

The ARES Compiler API is the primary interface for developers who want to build the power of ARES into their own tools, editors, or automated systems. It provides a structured way to communicate with the compiler, allowing you to submit source code, specify compilation targets, and receive detailed information about the resulting program and its algorithmic complexity.

Why it exists

While many users interact with ARES through a command-line tool, professional developers often need to automate tasks or integrate features into their own software (like a code editor plugin). The API exists to satisfy this need. It provides a stable, programmatic way to access all the compiler's advanced features—like intent inference and complexity profiling—without needing to worry about manual file management or shell commands. It allows ARES to serve as a high-level "logic engine" for other applications.

How it works

The API is built around a single main class that manages the entire compilation lifecycle.

  1. Initializing the Compiler. You create a new instance of the AresCompiler class, providing the root directory of your project so it can locate necessary resources. Technically, the constructor initializes the global Approach Registry and the Complexity Profiler. It loads all algorithmic templates into memory to ensure that future compilation requests can be processed with zero latency. This setup phase prepares the environment for a stable and consistent execution.
  2. The Compile Request. You call the compile() method, passing in your ARES source code string and a set of options (like the preferred target language). The compile method accepts a structured configuration object that conforms to the AresOptions interface. This allows you to programmatically control every aspect of the build, from the specific emitter used to the level of optimization applied. The system uses these options to determine the routing path early in the process.
  3. The Compilation Process. Internally, the compiler moves through all the standard pipeline phases (Lexing, Parsing, Semantic Analysis, etc.) just as it would for a file on your disk. The API manages the internal state of the compiler throughout the lifecycle. It captures and aggregates any warnings or diagnostic data generated during the parsing and profiling stages. This ensures that the caller receives a complete and accurate picture of the entire compilation event.
  4. The Result Object. Once finished, the API returns a comprehensive AresResult object. This object contains not just the final generated code, but also metadata about the inferred algorithms, the predicted complexity, and any warning or error messages. Mathematically, the results are returned as a tuple where the first element is the generated source string and the second is a metadata record. The error handling system uses standardized codes ranging from E100E_{100} (syntax) to E500E_{500} (internal error) to allow for automated troubleshooting. This structured output makes integration easy and predictable.

Intuition

Think of the Compiler API like a professional control panel for a high-performance machine. Instead of pressing the individual buttons by hand (using the command line), you connect the machine to your own computer and send it precise commands through a cable. You tell the machine what you want it to build, and it sends back the finished product along with a detailed report on how it was made. You are in complete control of the process from within your own environment.

Implementation details

The main entry point for the API is the AresCompiler class in src/index.ts. All data passed to and from the API is defined in src/types.ts to ensure consistency.

  • Result Metadata: The result includes an approaches list, naming every algorithm the system successfully inferred and used.
  • Target Options: You can force a specific target (like "cpp") or set it to "auto" to let the ARES Routing Engine decide for you.

Trace example

This is what happens when you use the API in a Node.js program:

  1. Import: You import the AresCompiler class into your script.
  2. Call: You call await compiler.compile('read x print x * 2').
  3. Internal Flow: The compiler tokenizes the text, builds a tree, and selects the best language.
  4. Answer: Your script receives a result object. You can then print the generated code to your console.

Related entities

  • src/index.ts: The core file that implements the AresCompiler class.
  • src/types.ts: The definition of all API input and output structures.
ARES