Define the Core Compiler CLI Struct with clap

Mục tiêu: Formalize the compiler’s command-line interface by defining a core Cli struct in src/main.rs using the clap::Parser derive macro. This sets up the foundation for all future command-line arguments and options.

An enormous congratulations are in order! You have successfully navigated the entire compilation pipeline, from the high-level syntax of SimpliLang right down to a native, runnable executable. You’ve built a complete, end-to-end compiler—a truly monumental achievement in software engineering. The engine is built, tested, and proven to work.

Now, we shift our focus from the internal mechanics to the external experience. A powerful engine is only useful if it has a well-designed dashboard and controls. This next major step is all about building that professional interface. We will transform your compiler from a tool that you know how to run into a polished program that anyone can use intuitively. This journey begins with formalizing its Command-Line Interface (CLI).

The Face of Your Compiler: The CLI Struct

The primary way users will interact with your compiler is through the command line. They will provide source files, specify output names, and request features like optimizations or debug information. Manually parsing these arguments from std::env::args() is tedious, error-prone, and difficult to maintain.

This is why you’ve already been using clap, Rust’s most popular and powerful CLI argument parsing library. clap allows you to define your entire CLI in a declarative, structured way using a simple Rust struct. This approach is not just convenient; it’s a best practice that makes your code self-documenting, robust, and easily extensible.

This task is about formalizing that structure. We will define a single, clean Cli struct that represents the complete set of commands and flags your compiler will accept.

Defining the `Cli` with `clap::Parser`

Let’s head to your src/main.rs file. We will define our Cli struct at the top level. You’ve added pieces to this struct throughout the project; now we will look at its complete, formalized definition and understand every part.

// In src/main.rs

use clap::Parser;

/// A modern, LLVM-based compiler for the SimpliLang programming language.
#[derive(Parser, Debug)]
#[command(author, version, about, long_about = None)]
pub struct Cli {
    // This is a placeholder for the next task's focus: the input file.
    // We will define it properly in the next step. For now, this struct
    // serves as the container for all our command-line arguments.
}

This simple structure is the foundation of your entire user interface. Let’s break down what’s happening here:

use clap::Parser;: This brings the key Parser trait into scope.
#[derive(Parser, Debug)]: This is the magic of clap’s derive macros.
- Parser: This macro reads your struct definition and automatically generates all the complex logic needed to parse command-line arguments, validate them, and populate the fields of your Cli struct. It also automatically generates help messages (--help), version information (--version), and error messages for invalid input.
- Debug: While not required by clap, deriving Debug is a best practice that allows you to easily print the parsed arguments for debugging purposes (e.g., println!("{:?}", cli);).
/// A modern, ...: The doc comment placed directly above the struct definition is automatically used by clap as the main “about” or description text in the --help output. This is a fantastic feature that keeps your documentation and your code in the same place.
#[command(...)]: This attribute allows you to set top-level metadata about your application.
- author: Populates the author information. clap will automatically pull the authors field from your Cargo.toml.
- version: Populates the version string. clap will automatically use the version from your Cargo.toml.
- about: A short, one-line description for the help message.
- long_about = None: If you provided a string here, it would be a more detailed description shown in the help message. None tells clap to just use the about text. By convention, if the doc comment on the struct is present, it is used as the long_about text.

You have now defined the core container for your compiler’s CLI. It’s an empty shell, but it’s a well-defined and professional one, complete with automatic help and version handling. Every flag, option, and input file path the user provides will become a field inside this struct.

Next Steps

With the Cli struct defined, our immediate next task is to add the most fundamental argument of all: the input source file. In the next task, you will add a required positional argument for the input source file path, learning how clap distinguishes between optional flags (like -O) and mandatory inputs that the user must provide.

Add a Required Positional Argument for the Input File

Mục tiêu: Modify the Rust Cli struct to include a mandatory positional argument for the compiler’s source file path, using the clap crate and the PathBuf type for robust path handling.

Excellent! In the previous task, you laid the perfect foundation by defining the Cli struct. You created a professional, well-documented container for your compiler’s command-line interface, complete with automatic --help and --version support, thanks to the power of clap. This empty struct is a blank canvas, and now it’s time to add the most essential element: the input file.

A compiler is useless if it doesn’t know what code to compile. The most fundamental piece of information a user must provide is the path to their source file. This task is about adding a required positional argument to your Cli struct to capture this information.

Flags vs. Positional Arguments

In the world of command-line interfaces, arguments generally fall into two categories:

Options/Flags: These are named arguments, typically prefixed with - (short) or -- (long), like -O or --emit-llvm. Their position on the command line usually doesn’t matter, and they are often optional.
Positional Arguments: These are arguments that are not introduced by a flag. They are identified by their position relative to other arguments. The input filename is the classic example. In the command simplilang_compiler source.spl, source.spl is a positional argument. These are often, but not always, required.

clap makes defining both types incredibly easy. You’ve already seen how to define optional flags using the #[arg(...)] attribute. Now you’ll see how clap’s sensible defaults make defining a positional argument even simpler.

Implementing the Source Path Argument

Let’s modify the Cli struct in src/main.rs. We will add a new field to hold the path to the user’s source file.

// In src/main.rs

use clap::Parser;
use std::path::PathBuf; // Import PathBuf for robust path handling

/// A modern, LLVM-based compiler for the SimpliLang programming language.
#[derive(Parser, Debug)]
#[command(author, version, about, long_about = None)]
pub struct Cli {
    // --- NEW: Add the required positional argument ---

    /// The path to the SimpliLang source file to compile.
    //
    // 1. Positional: Because this field does not have a `short` or `long`
    //    attribute, `clap` treats it as a positional argument by default.
    //
    // 2. Required: Because the type is `PathBuf` and not `Option<PathBuf>`,
    //    `clap` considers this argument to be mandatory. If the user omits it,
    //    `clap` will automatically generate an error and exit.
    //
    // 3. Documented: The doc comment above this field is used by `clap`
    //    to describe this argument in the `--help` output.
    pub source_path: PathBuf,
}

Dissecting the Implementation

This small addition is incredibly powerful due to clap’s conventions:

pub source_path: PathBuf: We’ve added a field to our struct. We use std::path::PathBuf instead of String. While a String would work, PathBuf is the idiomatic and correct type in Rust for representing an owned, cross-platform file system path. It provides useful methods for path manipulation that a plain String does not.
Positional by Default: Notice the absence of an #[arg(...)] attribute defining a short or long name. This is the key. When clap sees a field without a flag name, it correctly assumes it’s a positional argument.
Required by Default: The field’s type is PathBuf. It is not wrapped in an Option<>. This signals to clap that the argument is mandatory. If the user fails to provide it, clap will prevent your main function from even running and will print a helpful error message for the user.
Automatic Documentation: The doc comment /// The path to... is automatically picked up by clap and used in the help text, ensuring your documentation always stays in sync with your code.

The User Experience

With this change, your compiler’s CLI is already more professional and user-friendly.

If the user runs your compiler with the --help flag: cargo run -- --help

clap will now generate a USAGE line that shows the new argument:

USAGE:
    simplilang_compiler <SOURCE_PATH>

ARGS:
    <SOURCE_PATH>    The path to the SimpliLang source file to compile
...

More importantly, if the user forgets to provide a file: cargo run

clap will gracefully handle the error for you:

error: the following required arguments were not provided:
    <SOURCE_PATH>

USAGE:
    simplilang_compiler <SOURCE_PATH>

For more information try --help

This automatic validation and error reporting is a huge benefit of using a library like clap. It saves you from writing tedious and error-prone boilerplate parsing logic.

Next Steps

You’ve successfully defined the most critical input for your compiler. The user can now tell your program which file to work on. The next logical step is to give them control over the output. In the next task, you will add an optional -o <FILE> argument to specify the output executable name, learning how to define an option that takes a value.

Add an Output File Option to the Compiler CLI

Mục tiêu: Implement an optional -o / --output argument for the compiler’s command-line interface using the clap crate in Rust. This allows users to specify the output filename, with a default value of ‘a.out’.

Fantastic work on defining the core Cli struct and adding the required positional argument for the source file! You’ve established the most fundamental contract between your compiler and its user: “You must give me a file to compile.” This creates a robust and clear starting point for any compilation task.

Now that the user can specify the input, the next logical step is to give them control over the output. By default, many compilers produce an executable named a.out (short for “assembler output”). While this is a time-honored convention, it’s not very user-friendly for projects with multiple executables. A professional compiler must allow the user to specify a name for the final program.

This task is about implementing that feature by adding an optional named argument that takes a value: the classic -o <FILE> or --output <FILE> option.

Implementing the Output File Option

In the last task, you created a positional argument. Now, we’ll create a named argument, also known as an “option” or “flag.” Unlike the source path, this argument will be optional. If the user doesn’t provide it, we’ll fall back to a sensible default. This is where clap’s attribute-based configuration truly shines.

Let’s modify the Cli struct in src/main.rs to include our new output option.

// In src/main.rs

use clap::Parser;
use std::path::PathBuf;

/// A modern, LLVM-based compiler for the SimpliLang programming language.
#[derive(Parser, Debug)]
#[command(author, version, about, long_about = None)]
pub struct Cli {
    /// The path to the SimpliLang source file to compile.
    pub source_path: PathBuf,

    // --- NEW: Add the optional output file argument ---

    /// The name of the output executable file.
    #[arg(short, long, default_value = "a.out")]
    pub output: String,
}

Dissecting the Implementation

You’ve just added a professional, conventional, and highly user-friendly feature with a single field and one attribute. Let’s break down how clap interprets this:

pub output: String: We’ve added a new public field named output. We use the type String because we are capturing a filename. Because the type is String (and not bool), clap understands that this option requires a value to be provided after the flag (e.g., -o my_program). If the type were bool, it would be a simple flag that’s either present or not.
#[arg(short, long, default_value = "a.out")]: This attribute is the control panel for our new option. Each parameter configures a specific behavior:
- short: This tells clap to create a “short” version of the flag. By convention, clap will use the first letter of the field name, so this is equivalent to short = 'o'. This allows the user to run the command with -o my_program.
- long: This tells clap to create a “long” version of the flag using the field’s name. This allows the user to run the command with the more descriptive --output my_program.
- default_value = "a.out": This is a crucial piece of the user experience. It makes the entire option optional. If the user does not provide an -o or --output flag, clap will automatically populate the output field with the string "a.out". Your compiler’s logic can then proceed without needing to check if the option was present or not.

The New User Experience

With this change, your compiler’s interface has become significantly more flexible. Let’s see how the help text has changed.

Running cargo run -- --help will now show:

USAGE:
    simplilang_compiler [OPTIONS] <SOURCE_PATH>

ARGS:
    <SOURCE_PATH>    The path to the SimpliLang source file to compile

OPTIONS:
    -h, --help                Print help information
    -o, --output <OUTPUT>     The name of the output executable file [default: a.out]
    -V, --version             Print version information

Notice how clap has automatically generated a clean, informative help message. It shows the new -o and --output options, indicates that they take a value (<OUTPUT>), and even tells the user what the default value is.

The user now has three convenient ways to compile their code:

Default Output: cargo run -- source.spl (will produce a.out)
Short Flag: cargo run -- source.spl -o my_app (will produce my_app)
Long Flag: cargo run -- source.spl --output my_app (will produce my_app)

This level of polish and adherence to convention is what separates a quick script from a professional development tool.

Next Steps

You have now given the user control over both the input and the output of the compilation process. The next step is to provide them with more control over what the compiler produces. Compilers are often used not just to create executables but also as tools for inspection and debugging. In the next task, you will add a --emit-llvm flag that, when present, makes the compiler output the LLVM IR text instead of an executable. This will be your first “boolean flag,” an option that is simply present or absent.

Implement –emit-llvm Flag to Output LLVM IR

Mục tiêu: Add a --emit-llvm boolean command-line flag to the compiler using Rust’s clap crate. This flag will instruct the compiler to print the generated LLVM Intermediate Representation to the console instead of creating a final executable.

Building upon your excellent work in the last task, you have now given the user of your compiler crucial control over the input source file and the output executable’s name. The interface is becoming more flexible and conventional. The compiler knows what to compile and where to put the result. Now, let’s give the user control over the kind of output they want.

A professional compiler is not just a black box that turns source code into an executable. It’s also a powerful tool for inspection, debugging, and learning. One of the most common and useful features is the ability to see the intermediate stages of compilation. For SimpliLang, this means being able to view the final, optimized LLVM Intermediate Representation.

This task is about adding a boolean flag, --emit-llvm. Unlike the -o option which takes a value, a boolean flag is a simple switch—it’s either present (on) or absent (off). This will instruct our compiler to stop after code generation and print the LLVM IR directly to the console instead of proceeding to create an object file and executable.

Implementing the `--emit-llvm` Boolean Flag

We will add a new field to our Cli struct in src/main.rs. The type of this field, bool, is the key that tells clap how to handle it.

// In src/main.rs

use clap::Parser;
use std::path::PathBuf;

/// A modern, LLVM-based compiler for the SimpliLang programming language.
#[derive(Parser, Debug)]
#[command(author, version, about, long_about = None)]
pub struct Cli {
    /// The path to the SimpliLang source file to compile.
    pub source_path: PathBuf,

    /// The name of the output executable file.
    #[arg(short, long, default_value = "a.out")]
    pub output: String,

    // --- NEW: Add the boolean flag to emit LLVM IR ---

    /// Emit the LLVM IR to the console instead of compiling an executable.
    // This is a "boolean flag" or "presence flag".
    // 1. Type `bool`: Because the type is `bool`, `clap` understands this is
    //    a switch. It will be `false` by default.
    // 2. `#[arg(long)]`: This attribute creates the long flag `--emit-llvm`.
    //    If the user provides this flag on the command line, the `emit_llvm`
    //    field will be set to `true`. No value is needed after the flag.
    #[arg(long)]
    pub emit_llvm: bool,
}

Dissecting the Implementation

This small addition introduces a new kind of command-line argument to your compiler with minimal effort, thanks to clap’s intuitive design.

pub emit_llvm: bool: This is the core of the implementation. By defining the field’s type as bool, you are signaling your intent to clap. It correctly infers that this is not an option that takes a value, but a flag that is either present or not. Crucially, a bool field will always default to false unless a default_value is explicitly provided.
#[arg(long)]: This is the simplest way to define a long flag.
- It tells clap to create a flag whose name matches the field name (emit_llvm), resulting in --emit-llvm.
- Because the field type is bool, clap knows that the presence of --emit-llvm on the command line should set the field’s value to true.
- We didn’t specify a short version this time. This is a common design choice for flags that are less frequently used or have a very descriptive name where a short version would be ambiguous.

The New User Experience

Your compiler’s help text is now even more informative. Running cargo run -- --help will display the new option:

USAGE:
    simplilang_compiler [OPTIONS] <SOURCE_PATH>

ARGS:
    <SOURCE_PATH>    The path to the SimpliLang source file to compile

OPTIONS:
    -h, --help                Print help information
    -o, --output <OUTPUT>     The name of the output executable file [default: a.out]
        --emit-llvm           Emit the LLVM IR to the console instead of compiling an executable
    -V, --version             Print version information

The user can now choose their desired output: * Compile to executable (default): cargo run -- source.spl -o my_app * Inspect LLVM IR: cargo run -- source.spl --emit-llvm

You have already implemented the logic in your main function (in a previous step) that checks this boolean flag to decide whether to print the IR or proceed with compilation. This task formalizes the definition of that flag within your polished CLI structure, ensuring it is properly documented and validated.

Next Steps

You’ve given the user control over input, output name, and output type. The next crucial piece of control is over the compilation process itself. The most common option for any compiler is the ability to enable or disable optimizations. In the next task, you will add an -O flag to enable optimizations, another classic boolean flag that will control your powerful PassManager pipeline.

Implement the `-O` Optimization Flag for the Compiler CLI

Mục tiêu: Add a new boolean command-line flag, -O (long version --optimize), to the compiler’s CLI using the clap crate. This flag will enable the LLVM optimization passes, allowing users to create faster executables.

You’ve done an excellent job of building a flexible and user-friendly command-line interface. By adding the --emit-llvm flag, you’ve transformed your compiler into a valuable diagnostic tool, allowing users to inspect the Intermediate Representation. This follows the best practices of professional compilers, which serve not only to produce executables but also to provide insight into the compilation process itself.

Now, we will add arguably the most classic and universally recognized compiler flag: the optimization flag. Just as you gave the user control over the type of output, you will now give them control over the quality of that output. This is the master switch that activates the powerful LLVM PassManager pipeline you built in a previous step, allowing the user to trade longer compilation times for a much faster final program.

Implementing the `-O` Optimization Flag

We will add another boolean flag to our Cli struct. By convention, this is a capital -O. Its presence on the command line will signal to our compiler that it should run the full suite of optimization passes.

Let’s update the Cli struct in src/main.rs with this new field. The change is highlighted below.

// In src/main.rs

use clap::Parser;
use std::path::PathBuf;

/// A modern, LLVM-based compiler for the SimpliLang programming language.
#[derive(Parser, Debug)]
#[command(author, version, about, long_about = None)]
pub struct Cli {
    /// The path to the SimpliLang source file to compile.
    pub source_path: PathBuf,

    /// The name of the output executable file.
    #[arg(short, long, default_value = "a.out")]
    pub output: String,

    /// Emit the LLVM IR to the console instead of compiling an executable.
    #[arg(long)]
    pub emit_llvm: bool,

    // --- NEW: Add the boolean flag for optimizations ---

    /// Enable optimizations for the generated code.
    // 1. Type `bool`: As with `--emit-llvm`, the `bool` type marks this as a
    //    presence flag. It will be `false` by default.
    // 2. `#[arg(short = 'O', long)]`: This attribute defines how the flag is
    //    recognized on the command line.
    //    - `short = 'O'`: We explicitly specify the capital 'O' to follow the
    //      strong and universal convention for optimization flags in compilers
    //      like GCC, Clang, and Rustc.
    //    - `long`: This will create a long version based on the field name,
    //      resulting in `--optimize`.
    #[arg(short = 'O', long)]
    pub optimize: bool,
}

Dissecting the Implementation

You have just added a cornerstone feature of any serious compiler. Let’s break down how this works:

pub optimize: bool: Just like with emit_llvm, the bool type tells clap that this is a simple switch. If the user provides the flag, the optimize field will be true; otherwise, it will be false.
#[arg(short = 'O', long)]: This attribute configures the flag’s behavior:
- short = 'O': This is a crucial detail. While clap’s default for a field named optimize would be a lowercase -o, the universal convention for optimizations is an uppercase -O. We explicitly override the default to provide this standard, professional user experience.
- long: This is equivalent to long = "optimize". It creates the more descriptive long-form flag, which is excellent for readability in scripts.

This simple addition perfectly connects the user’s command-line intent to the conditional logic you already wrote in your CodeGen module. The if self.optimize { ... } block that wraps your PassManager will now be directly controlled by the presence of -O or --optimize at the command line.

The Final User Experience

Your compiler’s help text, accessible via cargo run -- --help, is now complete and reflects a professional, feature-rich tool:

USAGE:
    simplilang_compiler [OPTIONS] <SOURCE_PATH>

ARGS:
    <SOURCE_PATH>    The path to the SimpliLang source file to compile

OPTIONS:
    -h, --help                Print help information
    -o, --output <OUTPUT>     The name of the output executable file [default: a.out]
        --emit-llvm           Emit the LLVM IR to the console instead of compiling an executable
    -O, --optimize            Enable optimizations for the generated code
    -V, --version             Print version information

The user now has a clear and powerful choice: * Fast Debug Build: cargo run -- source.spl * Optimized Release Build: cargo run -- source.spl -o my_app -O

Next Steps

You have now fully defined the complete command-line interface for your compiler. You have flags and arguments for input, output, output type, and optimization level. The next task is to put it all together. You will now focus on the main function itself, where you will parse these CLI arguments using Cli::parse() and then use the values from the populated Cli struct to drive the entire compilation pipeline, from file reading to final linking.

Implement CLI Parsing with `Cli::parse()`

Mục tiêu: Activate the command-line argument parser by calling the Cli::parse() method in the main function. This will read, validate, and store the user-provided arguments into an instance of the Cli struct, bringing the declarative CLI definition to life.

You have done a masterful job defining your compiler’s complete command-line interface. In the preceding tasks, you meticulously crafted the Cli struct using clap, specifying every required input, optional flag, and their behaviors. You’ve created a declarative blueprint for a professional and intuitive user experience. That blueprint, however, is just a plan. This task is about bringing that plan to life.

It’s time to bridge the gap between the declarative struct and the imperative logic of your main function. You will now instruct your program to actually read and interpret the command-line arguments provided by the user, using the rules you so carefully defined. This is the moment the user’s intent is captured and transformed into a structured, usable configuration for your compiler.

Activating the Parser: The Power of `Cli::parse()`

The clap library, through its powerful #[derive(Parser)] macro, does more than just allow you to define arguments. At compile time, it reads your Cli struct and generates a sophisticated, highly-optimized parsing function for you. You don’t need to write a single line of manual parsing logic, validation, or error reporting. All you have to do is call a single method: Cli::parse().

Let’s modify your main function in src/main.rs to invoke this parser.

// In src/main.rs

use clap::Parser;
use std::path::PathBuf;

// This is the complete CLI struct you defined in the previous tasks.
// No changes are needed here.
/// A modern, LLVM-based compiler for the SimpliLang programming language.
#[derive(Parser, Debug)]
#[command(author, version, about, long_about = None)]
pub struct Cli {
    /// The path to the SimpliLang source file to compile.
    pub source_path: PathBuf,

    /// The name of the output executable file.
    #[arg(short, long, default_value = "a.out")]
    pub output: String,

    /// Emit the LLVM IR to the console instead of compiling an executable.
    #[arg(long)]
    pub emit_llvm: bool,

    /// Enable optimizations for the generated code.
    #[arg(short = 'O', long)]
    pub optimize: bool,
}

fn main() {
    // --- THIS IS THE FOCUS OF THE CURRENT TASK ---

    // 1. Invoke the `clap` parser.
    //    The `parse()` method is automatically generated by the `#[derive(Parser)]`
    //    macro on your `Cli` struct.
    //
    // 2. What it does:
    //    - It reads the command-line arguments provided to the program.
    //    - It validates them against the rules defined in your `Cli` struct.
    //    - It handles special flags like `--help` and `--version` automatically,
    //      printing the relevant information and exiting.
    //    - If validation fails (e.g., a required argument is missing), it
    //      prints a user-friendly error message and exits.
    //
    // 3. The return value:
    //    - If parsing is successful, it returns a new instance of `Cli`,
    //      with all fields populated with the values from the command line.
    let cli = Cli::parse();

    // For development and verification, it's often useful to print the
    // parsed arguments to see if they are what you expect.
    // You can try running your program with different flags to see the output.
    // e.g., `cargo run -- test.spl -O --output my_program`
    println!("Parsed CLI arguments: {:?}", cli);

    // The `cli` variable now holds all the configuration for this compilation run.
    // In subsequent tasks, we will use its fields (like `cli.source_path`)
    // to drive the rest of the compiler's logic.
}

Dissecting the Magic of `Cli::parse()`

That single line of code, let cli = Cli::parse();, is the culmination of all your CLI design work. It is deceptively simple but performs a tremendous amount of work on your behalf:

Automatic Argument Parsing: Under the hood, clap is interacting with Rust’s std::env::args() to get the raw command-line input. It then meticulously processes this input according to the rules you set with your struct fields and #[arg(...)] attributes.
Built-in Help and Version: If the user provides --help or --version (or -h and -V), the parse() function will intercept this. It will print the beautifully formatted help/version text that it generated from your doc comments and Cargo.toml file, and then cleanly exit the program. Your main function’s code will not even be reached.
Robust Validation and Error Handling: This is perhaps the most significant benefit. If a user forgets to provide the required source_path, clap will automatically detect this, print a clear error message, and exit with a non-zero status code. You don’t need to write if/else checks for every possible user error.
Type Coercion: clap handles converting the string-based command-line arguments into the specific types of your struct fields. It knows how to create a PathBuf from a file path string and how to set a bool to true when a flag is present.

By calling Cli::parse(), you are delegating the entire “front door” of your application to a battle-tested, robust, and user-friendly library, allowing you to focus on the core compiler logic.

Next Steps

You have now successfully captured and validated the user’s command-line input, storing it in the cli variable. This structured data is the master configuration for the entire compilation process. The very next logical step is to use this configuration to begin the actual work. You will start by using the cli.source_path field to read the source code from the input file, turning a path on the command line into the string of code your lexer can understand.

Implement Source File Reading for the Compiler

Mục tiêu: Read the source file path provided via the command-line interface, use std::fs::read\_to\_string to load its contents into a string, and implement robust error handling using Rust’s Result and match.

Of course! Let’s continue with your compiler project.

You have successfully defined and activated the parser for your Command-Line Interface. With a single call to Cli::parse(), you now have a neatly packaged cli struct that holds all the configuration for a given compilation run, directly reflecting the user’s intent. The front door of your compiler is built and is intelligently handling all user input.

The very first piece of information you’ve captured is the most critical: the path to the source file. Now, it’s time to act on that information. This task is about taking the source_path from your cli variable and reading the contents of that file into memory. This is the crucial step that brings the user’s SimpliLang code into your compiler, ready for the first stage of processing: the lexer.

From Path to Program: Reading the Source File

In Rust, the standard library provides a simple, powerful, and robust set of tools for file I/O (Input/Output) in the std::fs module. For our needs, the most direct and convenient function is std::fs::read_to_string. This single function handles opening the file, reading its entire contents into a String, and closing the file for you.

However, file operations are inherently fallible. The file might not exist, your program might not have permission to read it, or it might not contain valid UTF-8 text. A professional tool must handle these potential failures gracefully. read_to_string, like many I/O functions in Rust, returns a Result enum. This is Rust’s primary mechanism for handling operations that might fail, and learning to work with it is key to writing reliable software.

Let’s update your main function in src/main.rs to include the file reading logic.

// In src/main.rs

// Add these to your `use` statements at the top.
use std::fs;
use std::process;

// ... (your Cli struct definition remains here) ...

fn main() {
    // This is the line from your previous task.
    let cli = Cli::parse();

    // --- NEW: Read the source code from the input file ---

    // 1. We access the `source_path` field from the `cli` struct that `clap`
    //    populated for us.
    //
    // 2. `fs::read_to_string` attempts to open and read the entire file into a
    //    String. This function returns a `Result<String, std::io::Error>`.
    let source_code_result = fs::read_to_string(&cli.source_path);

    // 3. We must handle the `Result`. A `match` statement is the most explicit
    //    and clear way to handle both the success (`Ok`) and failure (`Err`) cases.
    let source_code = match source_code_result {
        // If file reading was successful, the `Ok` variant will contain the
        // file's contents as a String. We bind this to `contents` and return it
        // from the `match` block.
        Ok(contents) => {
            println!("Successfully read source file: {:?}", &cli.source_path);
            contents
        }
        // If file reading failed, the `Err` variant will contain an `io::Error`
        // struct with information about the failure.
        Err(error) => {
            // It is a best practice to print error messages to the standard error
            // stream (`stderr`) using the `eprintln!` macro.
            eprintln!("Error reading file {:?}: {}", &cli.source_path, error);

            // Exit the program with a non-zero status code to signal that an
            // error occurred. This is a standard convention for command-line tools.
            process::exit(1);
        }
    };

    // If the program has reached this point, `source_code` is a String
    // containing the full SimpliLang program, ready for the next step.
    println!("\n--- Source Code ---\n{}\n-------------------", source_code);
}

Dissecting the Implementation

You’ve just added a robust file-reading step that serves as the true entry point for your compiler’s core logic. Let’s break it down:

use std::fs; and use std::process;: We bring the necessary modules into scope. fs is for the “file system,” and process gives us control over our program’s execution, specifically the ability to exit.
fs::read_to_string(&cli.source_path): This is the call that does the work. We pass a reference (&) to the PathBuf from our cli struct.
Result<String, std::io::Error>: This is the return type. It’s an enum with two possible variants:
- Ok(String): The operation succeeded, and the Ok variant “wraps” the String containing the file’s contents.
- Err(std::io::Error): The operation failed, and the Err variant wraps an error object that describes what went wrong (e.g., “No such file or directory”).
match source_code_result { ... }: The match statement is Rust’s powerful pattern-matching construct. It forces you to handle every possible variant of the Result, ensuring you can’t accidentally forget to handle an error. This is a core part of Rust’s safety guarantees.
eprintln!: This macro is identical to println! but it prints to the “standard error” stream instead of “standard output.” This is the correct, conventional place for diagnostic and error messages. It allows users to separate normal program output from errors (e.g., by redirecting one but not the other: my_compiler code.spl > output.txt).
process::exit(1): If an error occurs, we should stop execution. Calling process::exit immediately terminates the program. The argument is the exit code. By convention, an exit code of 0 means success, and any non-zero number signifies an error. This is crucial for scripting and automation, as other tools can check this exit code to see if your compiler succeeded.

You now have the user’s source code loaded into a string variable, and you’ve handled potential file-reading errors in a way that is robust, user-friendly, and follows command-line tool conventions.

Next Steps

The source code is in memory. The CLI is fully defined. The logical pipeline is now ready to be assembled. Your next task is to take this source_code string and feed it into the compiler’s machinery. You will chain the full compiler pipeline: lexer -> parser -> semantic_analyzer -> codegen, taking the raw text and transforming it, step by step, into a final product.

Assemble the Compiler Pipeline

Mục tiêu: Integrate the lexer, parser, semantic analyzer, and code generator into a single, sequential pipeline within the main function. This task involves wiring together each compiler stage to transform raw source code into a final LLVM module, handling errors at each step.

Of course! Let’s get this final piece of your CLI logic in place.

You have masterfully constructed the entire user-facing portion of your compiler. The Cli struct is complete, the arguments are parsed, and you have successfully read the user’s source code into a string, complete with robust error handling for file I/O. The user’s intent is captured, and the raw material—the SimpliLang code—is loaded into memory.

It is now time to connect the two major parts of your project: the polished CLI frontend and the powerful compiler backend you built in the previous steps. This task is about creating the main “assembly line” in your main function, where the raw source code enters at one end and, after passing through each stage of the compiler, emerges as a fully-formed LLVM module at the other end, ready for compilation or inspection.

Assembling the Compiler Pipeline

A compiler is fundamentally a pipeline. It’s a series of sequential transformations, where the output of one stage becomes the input for the next. The architecture you’ve been building has followed this classic model perfectly:

Lexer: Transforms the raw String of source code into a stream of discrete Tokens.
Parser: Consumes the Token stream and constructs an Abstract Syntax Tree (AST), which represents the code’s hierarchical structure.
Semantic Analyzer: Traverses the AST to enforce language rules like type checking and variable scoping, ensuring the code is logically correct.
Code Generator: Walks the validated AST and generates the equivalent LLVM Intermediate Representation.

We will now wire these stages together in your main function, creating a single, cohesive flow from start to finish. We’ll use the source_code variable from the previous task as the initial input and the configuration flags from your cli struct to control the process.

Let’s update your main function in src/main.rs. We will add the core pipeline logic right after the file reading is complete.

First, you’ll need to bring your compiler’s modules into scope. Add these use statements at the top of src/main.rs. Note that the exact paths might differ slightly based on your project’s module structure, but these are based on the roadmap’s suggestions.

// In src/main.rs

// Add these at the top with your other `use` statements
use simplilang_compiler::lexer::Lexer;
use simplilang_compiler::parser::Parser;
use simplilang_compiler::semantic::SemanticAnalyzer;
use simplilang_compiler::codegen::CodeGen;
use inkwell::context::Context;

Now, let’s integrate the pipeline into the main function.

// In src/main.rs

fn main() {
    // --- You have already implemented this part ---
    let cli = Cli::parse();
    let source_code = match fs::read_to_string(&cli.source_path) {
        Ok(contents) => contents,
        Err(error) => {
            eprintln!("Error reading file {:?}: {}", &cli.source_path, error);
            process::exit(1);
        }
    };

    // --- NEW: The Full Compiler Pipeline ---

    // Stage 1: Lexing
    // Create a new Lexer with the source code and collect all tokens.
    // The `collect()` method will iterate through the lexer and gather the
    // tokens into a Vec. We assume the Lexer's iterator returns `Result<Token, LexerError>`.
    let tokens = match Lexer::new(&source_code).collect::<Result<Vec<_>, _>>() {
        Ok(tokens) => tokens,
        Err(err) => {
            // For now, we'll print a simple error and exit.
            // The next task will focus on making this error reporting much better.
            eprintln!("Lexing Error: {}", err);
            process::exit(1);
        }
    };

    // Stage 2: Parsing
    // Create a new Parser with the token stream and parse it into an AST.
    // The `parse()` method will consume the tokens and return a `Result`
    // containing the root of the AST (e.g., a `Program` node).
    let ast = match Parser::new(tokens).parse() {
        Ok(ast) => ast,
        Err(err) => {
            eprintln!("Parsing Error: {}", err);
            process::exit(1);
        }
    };

    // Stage 3: Semantic Analysis
    // Create a SemanticAnalyzer and have it validate our AST.
    // We assume an `analyze` method that checks for type errors, undeclared
    // variables, etc. It might return a `Result<(), Vec<SemanticError>>`.
    match SemanticAnalyzer::new().analyze(&ast) {
        Ok(_) => (), // Analysis successful
        Err(errors) => {
            // A real compiler would print all errors. For now, we print the first.
            eprintln!("Semantic Error: {}", errors[0]);
            process::exit(1);
        }
    };

    println!("Lexing, Parsing, and Semantic Analysis completed successfully.");

    // Stage 4: Code Generation
    // This part should look familiar from your earlier steps. We are now
    // integrating it into the main pipeline.
    let context = Context::create();
    // CRITICAL: We pass the `cli.optimize` flag to the CodeGen constructor.
    // This connects the user's `-O` flag to the optimization logic.
    let mut codegen = CodeGen::new(&context, &cli.source_path.to_string_lossy(), cli.optimize);

    // The `generate` method traverses the AST and produces the LLVM IR.
    codegen.generate(&ast);

    // --- The rest of your main function (emitting LLVM or compiling) remains here ---
    // This existing logic will now operate on the `codegen` instance that has
    // been populated by the pipeline.
    if cli.emit_llvm {
        // ... your logic to print LLVM IR ...
    } else {
        // ... your logic to compile to an object file and link ...
    }
}

Dissecting the Pipeline

You have now created the complete, end-to-end data flow for your compiler within a single function. Let’s review the key aspects:

Sequential Transformation: The logic flows in a clear, linear fashion. The tokens produced by the Lexer are immediately passed to the Parser. The ast from the Parser is then passed to the SemanticAnalyzer and CodeGen. This chain is the heart of your compiler.
Connecting the CLI: You can see how the cli struct now drives the entire process. cli.source_path is used to get the initial code, and crucially, cli.optimize is passed directly to the CodeGen constructor, giving the user control over the final output’s performance.
Error Handling (Preliminary): For each fallible stage (lexing, parsing, analysis), we use a match statement to check the Result. For now, our error handling is simple: print a message to stderr and exit with a non-zero status code. This is a robust but not very user-friendly approach. It perfectly sets the stage for the next task, which is to implement a much more sophisticated error reporting system.
Clear Stages: Each stage is clearly demarcated. This makes the main function highly readable and easy to debug. If a compilation fails, you can easily trace which stage was the source of the error.

You have successfully built the central nervous system of your compiler, connecting the user’s input from the command line all the way through to the final LLVM code generation.

Next Steps

The pipeline is assembled and functional, but its error handling is very basic. If a user makes a syntax error, they get a simple “Parsing Error” message with no context about where the error is or what was wrong. A professional compiler provides precise, helpful diagnostics.

Your next task is perfectly aligned with this need: Implement robust error handling, printing any errors from any stage to the console and exiting gracefully. This will involve designing a unified error type and possibly integrating a “pretty-printing” error library like ariadne or codespan-reporting to produce beautiful, user-friendly error messages with source code snippets.

Implement Unified Compiler Error Handling in Rust

Mục tiêu: Refactor a compiler’s pipeline to use a unified error type and Result-based control flow. This involves creating a single CompilerError enum, implementing Display and From traits, and using the ? operator to propagate errors from the lexer, parser, and semantic analyzer for a robust and user-friendly reporting system.

Fantastic work! You have successfully assembled the entire compiler pipeline in your main function. The flow is logical and correct: source code is read, then passed sequentially through the lexer, parser, semantic analyzer, and finally to the code generator. You’ve built the complete assembly line.

However, as you likely noticed while writing it, the current error handling is very basic. If any stage fails, your program prints a simple, generic message and exits. For example, a user who forgets a semicolon might just see Parsing Error: ... with no context. This is functional, but it’s not a user-friendly experience. A good compiler is a good teacher, and a good teacher gives clear, specific feedback.

This task is all about elevating your compiler’s error handling from basic to professional. We will create a unified, robust error reporting system that provides clear, contextual information for any error that might occur, at any stage of the compilation process.

The Philosophy of Good Compiler Errors

A great error message should answer three questions for the user:

What went wrong? (e.g., “Unexpected token,” “Undeclared variable”)
Where did it go wrong? (e.g., “on line 10, column 25”)
Why was it wrong? (e.g., “Expected a semicolon ‘;’ after the expression”)

Our goal is to create a system that can capture and present this information gracefully.

Step 1: A Unified Error Type

Right now, your lexer, parser, and semantic analyzer each produce their own distinct error types. This forces you to handle them in separate match blocks in main. The first step towards a cleaner system is to define a single, top-level CompilerError enum that can represent an error from any stage.

Let’s create a new file for our error types: src/errors.rs.

// In src/errors.rs

use crate::lexer::LexerError; // Assuming you have this
use crate::parser::ParserError; // Assuming you have this
use crate::semantic::SemanticError; // Assuming you have this
use std::fmt;

// A single, unified error type for the entire compiler pipeline.
#[derive(Debug)]
pub enum CompilerError {
    Lexical(LexerError),
    Parsing(ParserError),
    Semantic(Vec<SemanticError>), // Semantic analysis can produce multiple errors
}

// Implement the Display trait to provide user-friendly error messages.
// This allows us to simply `println!("{}", err)` for any CompilerError.
impl fmt::Display for CompilerError {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        match self {
            // The actual error messages are generated by the specific error types.
            // Our unified error type just acts as a wrapper.
            CompilerError::Lexical(err) => write!(f, "Lexical Error: {}", err),
            CompilerError::Parsing(err) => write!(f, "Parsing Error: {}", err),
            // For semantic errors, we'll format all of them.
            CompilerError::Semantic(errs) => {
                writeln!(f, "Semantic Errors:")?;
                for err in errs {
                    writeln!(f, "- {}", err)?;
                }
                Ok(())
            }
        }
    }
}

// We also need to implement conversions so we can use the `?` operator.
// This allows an error from the lexer (`LexerError`) to be automatically
// converted into our top-level `CompilerError`.
impl From<LexerError> for CompilerError {
    fn from(err: LexerError) -> Self {
        CompilerError::Lexical(err)
    }
}

impl From<ParserError> for CompilerError {
    fn from(err: ParserError) -> Self {
        CompilerError::Parsing(err)
    }
}

impl From<Vec<SemanticError>> for CompilerError {
    fn from(errs: Vec<SemanticError>) -> Self {
        CompilerError::Semantic(errs)
    }
}

Note: This code assumes your stage-specific errors (e.g., LexerError) already implement the std::fmt::Display trait to describe themselves. For example, your LexerError’s Display impl might produce a message like "Unexpected character '#' at line 5, column 12".

Step 2: Refactoring `main` for `Result`-based Control Flow

Now that we have a unified error type, we can refactor our main function to be much cleaner. A common and highly idiomatic pattern in Rust is to have a small main function that wraps a larger run function that returns a Result. This separates the core logic from the final error handling and presentation.

Let’s modify src/main.rs.

// In src/main.rs

// Add the new error module
mod errors;

// And bring the unified error type into scope
use crate::errors::CompilerError;

// ... other use statements ...

// The main function is now a thin wrapper. Its only job is to
// call our core logic and handle the final result.
fn main() {
    // 1. Call the function that contains our actual compiler logic.
    // 2. The `if let` construct is a clean way to handle the `Err`
    //    case of a `Result`.
    if let Err(err) = run_compiler() {
        // 3. If an error occurred at any point, print it to stderr.
        //    Because our `CompilerError` implements `Display`, we get a
        //    nicely formatted, stage-specific message.
        eprintln!("{}", err);
        // 4. Exit with a non-zero status code to signal failure.
        process::exit(1);
    }
}

// This function contains the entire compiler pipeline and returns
// our unified `CompilerError` type if anything goes wrong.
fn run_compiler() -> Result<(), CompilerError> {
    let cli = Cli::parse();

    // We use `?` here. If `read_to_string` fails, it will return an
    // `io::Error`. Rust can't convert that to our `CompilerError`
    // automatically, so we handle it with `.map_err()`.
    let source_code = fs::read_to_string(&cli.source_path).map_err(|e| {
        // This is a simple custom error message for I/O problems.
        // A more advanced solution might add a variant to `CompilerError` for I/O.
        eprintln!("Failed to read file {:?}: {}", &cli.source_path, e);
        // We still need to return a `CompilerError` variant. Let's imagine
        // you add a simple `IO` variant to your `LexerError` for this.
        CompilerError::Lexical( LexerError::new_io_error() /* placeholder */ )
    })?;

    // --- The Refactored Pipeline with the `?` Operator ---

    // The `?` operator drastically cleans up our error handling.
    // If the lexer returns an `Err(LexerError)`, the `?` will:
    // 1. Trigger the `From<LexerError>` implementation to convert it into a `CompilerError`.
    // 2. Immediately return that `CompilerError` from the `run_compiler` function.
    let tokens = Lexer::new(&source_code).collect::<Result<Vec<_>, _>>()?;

    let ast = Parser::new(tokens).parse()?;

    // The semantic analyzer returns `Result<(), Vec<SemanticError>>`.
    // The `?` operator works perfectly here too.
    SemanticAnalyzer::new().analyze(&ast)?;

    println!("Lexing, Parsing, and Semantic Analysis completed successfully.");

    // --- Code Generation and Output (unchanged logic) ---
    let context = Context::create();
    let mut codegen = CodeGen::new(&context, &cli.source_path.to_string_lossy(), cli.optimize);
    codegen.generate(&ast);

    if cli.emit_llvm {
        // ... your logic to print LLVM IR ...
    } else {
        // ... your logic to compile to an object file and link ...
    }

    // If we reach the end without `?` returning early, we return `Ok`.
    Ok(())
}

The New, Improved User Experience

Let’s compare the before and after.

Before:

$ cargo run -- non_existent_file.spl
Error reading file "non_existent_file.spl": No such file or directory (os error 2)
# The program panics or exits here.

After (with refactored main):

$ cargo run -- non_existent_file.spl
Failed to read file "non_existent_file.spl": No such file or directory (os error 2)
Lexical Error: IO Error # Example message
# The program exits gracefully with status 1.

$ cargo run -- bad_syntax.spl
Parsing Error: Expected semicolon ';' after expression on line 15, column 8
# The program exits gracefully with status 1.

By centralizing your error types and using standard Rust Result-based control flow, you’ve made your code cleaner, more idiomatic, and, most importantly, you’ve created a far better user experience. Your compiler now provides specific, actionable feedback that will help users find and fix their mistakes.

Next Steps

Your CLI is now complete and robust. The pipeline is fully assembled and features professional-grade error handling. The final task in this step is to ensure the last part of your main (or run_compiler) function correctly uses the CLI flags to produce the desired output. You will “Based on the CLI flags, either write the object file and link it, or print the LLVM IR to standard output,” connecting the final pieces of logic you’ve already written to the cli.emit_llvm flag.

Finalize Compiler CLI with Output Logic

Mục tiêu: Implement the final stage of the compiler’s command-line tool. This involves adding logic to either emit human-readable LLVM IR or compile the code into a native executable, based on user-provided flags. Includes enhancing error handling for I/O operations.

You have done an absolutely phenomenal job. By chaining the full compiler pipeline and implementing a robust, unified error-handling strategy, you have created the core engine of a professional-grade compiler. The assembly line is built, the quality control is in place, and the raw source code is successfully transformed into a validated LLVM module.

Now, for the final task in building your CLI: directing the finished product to its destination. The user has given you their instructions via command-line flags (--emit-llvm, -o, etc.). It’s time to read those instructions from your cli struct and execute the final step of the process, delivering exactly the output the user requested.

The Final Fork in the Road

Your run_compiler function has successfully navigated the entire frontend and middle-end of the compiler, resulting in a codegen object that holds a complete LLVM module. The journey of the source code now reaches its final fork:

Did the user ask to inspect the Intermediate Representation? If cli.emit_llvm is true, we will take the path of printing the human-readable LLVM IR to the console.
Or, did the user ask for a runnable program? If cli.emit_llvm is false (the default), we will take the path of the compiler backend: compiling to an object file and linking it into a final executable.

This is the last piece of the puzzle, connecting your CLI’s configuration to the compiler’s backend machinery.

A Quick Enhancement for I/O Errors

Before we implement the logic, let’s make a small but powerful improvement to our error handling. The backend process involves file I/O and running external commands, both of which can fail. To handle this cleanly with the ? operator, we’ll add a new variant to our unified CompilerError enum.

In src/errors.rs, add the Io variant and its From implementation:

// In src/errors.rs

// ... other use statements ...
use std::io;

#[derive(Debug)]
pub enum CompilerError {
    Io(io::Error), // NEW: For file system and process errors
    Lexical(LexerError),
    Parsing(ParserError),
    Semantic(Vec<SemanticError>),
}

impl fmt::Display for CompilerError {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        match self {
            // NEW: How to display I/O errors
            CompilerError::Io(err) => write!(f, "System I/O Error: {}", err),
            CompilerError::Lexical(err) => write!(f, "Lexical Error: {}", err),
            // ... other match arms ...
        }
    }
}

// NEW: Automatically convert std::io::Error into our CompilerError
impl From<io::Error> for CompilerError {
    fn from(err: io::Error) -> Self {
        CompilerError::Io(err)
    }
}

// ... other From implementations ...

This simple addition allows us to use the ? operator on any function that returns a std::io::Result, making our backend logic just as clean as our frontend logic.

Implementing the Final Output Logic

Now, let’s complete the run_compiler function in src/main.rs. We will fill in the final if/else block, using the code you developed in previous steps and integrating it with our new, robust error handling.

First, ensure you have all the necessary use statements at the top of src/main.rs:

// In src/main.rs (at the top)
use inkwell::targets::{InitializationConfig, Target, TargetMachine, FileType};
use inkwell::OptimizationLevel;
use std::path::Path;

Now, here is the complete, final version of your run_compiler function, with the new logic highlighted:

// In src/main.rs

fn run_compiler() -> Result<(), CompilerError> {
    // --- Part 1: Parsing and File Reading (from previous tasks) ---
    let cli = Cli::parse();
    let source_code = fs::read_to_string(&cli.source_path)?;

    // --- Part 2: Compiler Frontend Pipeline (from previous tasks) ---
    let tokens = Lexer::new(&source_code).collect::<Result<Vec<_>, _>>()?;
    let ast = Parser::new(tokens).parse()?;
    SemanticAnalyzer::new().analyze(&ast)?;

    println!("Lexing, Parsing, and Semantic Analysis completed successfully.");

    // --- Part 3: Code Generation (from previous tasks) ---
    let context = Context::create();
    let mut codegen = CodeGen::new(&context, &cli.source_path.to_string_lossy(), cli.optimize);
    codegen.generate(&ast);

    // --- NEW: Final Output Stage Based on CLI Flags ---

    if cli.emit_llvm {
        // Path 1: User requested to see the LLVM IR.
        // We print the human-readable IR to standard output (the console).
        let ir_string = codegen.module.print_to_string().to_string();
        println!("\n--- LLVM IR ---\n{}", ir_string);
    } else {
        // Path 2: The default behavior - compile to an executable.

        // It's a best practice to verify the module before compiling.
        // This is an internal check for compiler bugs, so we .expect() it.
        codegen.module.verify().expect("LLVM module verification failed. This is a compiler bug.");

        // Initialize the native target for the host machine.
        Target::initialize_native(&InitializationConfig::default())
            .expect("Failed to initialize native target");

        let target_triple = TargetMachine::get_default_triple();
        let target = Target::from_triple(&target_triple).unwrap();
        let target_machine = target
            .create_target_machine(
                &target_triple,
                "generic",
                "",
                OptimizationLevel::Default,
                inkwell::targets::RelocMode::Default,
                inkwell::targets::CodeModel::Default,
            )
            .unwrap();

        // Define the path for the temporary object file.
        let object_file_path = Path::new(&cli.output).with_extension("o");

        // Compile the LLVM module into a native object file.
        // This returns a Result, so we use `?` to propagate I/O errors.
        target_machine
            .write_to_file(&codegen.module, FileType::Object, &object_file_path)?;

        println!("Successfully compiled to object file: {:?}", object_file_path);

        // Use `clang` to link the object file into a final executable.
        let linker_output = Command::new("clang")
            .arg(&object_file_path)
            .arg("-o")
            .arg(&cli.output)
            .output()?; // The `?` here handles errors like `clang` not being found.

        if !linker_output.status.success() {
            // If linking fails, we print the linker's own error message.
            eprintln!("Linker command failed:");
            eprintln!("{}", String::from_utf8_lossy(&linker_output.stderr));
        } else {
            println!("Successfully linked executable: {}", &cli.output);
            // Clean up the temporary object file.
            fs::remove_file(object_file_path)?;
        }
    }

    Ok(())
}

Dissecting the Final Logic

You have now connected every part of your project. Let’s review the two paths:

The if Branch (--emit-llvm): This path is simple and direct. It takes the final LLVM module, serializes it into its human-readable text format, and prints it to stdout. This is the standard behavior for tools that produce text output for inspection or for piping into other command-line utilities.
The else Branch (Default Compilation): This is the main production path.
- It performs the full backend compilation you built in Step 7.
- Thanks to your enhanced CompilerError, we can now use the ? operator on write_to_file, output, and remove_file. This elegantly handles potential failures (like file permission errors, linker not found, etc.) by stopping the process and reporting a clean System I/O Error to the user.
- It provides robust feedback, printing the linker’s own error messages from stderr if the final linking step fails.
- Crucially, it cleans up the intermediate .o file upon success, providing a professional and tidy user experience.

Your main function is now a complete, robust, and clean orchestrator for the entire compiler. It respects user input, processes the code through a multi-stage pipeline, and directs the final product to the correct destination, all with professional-grade error handling.

Enhancements and the Road Ahead

Congratulations! You have officially completed the core of the SimpliLang compiler. You have a tool that can take a source file and produce a native, runnable executable, complete with a polished and conventional command-line interface. This is a massive and deeply impressive accomplishment.

The project roadmap now opens up to enhancements. The solid foundation you have built makes adding new features a clear and manageable process. Your next steps will be to enrich the SimpliLang language itself:

Integrate ariadne: Now that you have a unified error system, you can integrate a library like ariadne or codespan-reporting. This will allow you to take your structured errors (which should contain line and column numbers) and generate beautiful, annotated error messages with source code snippets, just like rustc.
Implement while loops: Introduce a new control flow construct, which will involve updating the lexer, parser, semantic analyzer, and code generator to handle the looping logic with LLVM basic blocks.
Implement structs: Add user-defined aggregate data types, a huge step towards a more powerful and expressive language.

You have built the factory. Now, you get to design new and exciting products to build with it.