Parsing Algebraic Notation

1. The Language of Chess: UCI Notation

To communicate moves, chess programs need a standardized, unambiguous format. While you might see moves written as "e4" or "Nf3" (Standard Algebraic Notation), engines often use a more explicit format called UCI Long Algebraic Notation.

As you just read, UCI long algebraic notation is beautifully simple and explicit:

• A standard move is [from_square][to_square], like e2e4.
• A promotion adds a character for the chosen piece, like e7e8q for promoting to a queen.
• Castling is just a king move of two squares, like e1g1.

Our goal is to write a function that takes a string in this format and produces the Move struct we defined in the previous lesson:

pub struct Move {
    pub from: Position,
    pub to: Position,
    pub promotion: Option<PieceType>,
}

This means we need to convert text coordinates like e2 into our Position { file: 4, rank: 1 } struct.

2. The Parsing Challenge

Parsing is the process of analyzing a string of symbols to determine its grammatical structure. In our case, it means taking a string like "e7e8q" and turning it into a structured Move object.

This process can fail. What if the user types "x9y0" or "hello"? A robust parser must handle these invalid inputs gracefully without crashing. This is where Rust's Result<T, E> enum is invaluable. Our parsing function will have a signature like this:
fn parse_move(input: &str) -> Result<Move, String>

It will either return Ok(Move) on success or Err(String) with an error message on failure.

3. Hands-On: Building a Move Parser

Let's build our parser. A good place for this new logic would be in a new file. You could create src/input.rs and declare it as a module in src/main.rs with mod input;.

Our main task is to break down the input string into its components: from-square, to-square, and an optional promotion piece. A helper function to parse a single square (like "e2") will be very useful.

Step 1: Parse a Single Square

Let's write a function parse_square(s: &str) -> Result<Position, String>. It takes a 2-character string and should return a Position.

// In src/input.rs (or a suitable module)

// Assuming you have these defined elsewhere
use crate::{Position, PieceType, Move}; 

fn parse_square(s: &str) -> Result<Position, String> {
    let mut chars = s.chars();
    let file_char = chars.next().ok_or("Invalid square: missing file")?;
    let rank_char = chars.next().ok_or("Invalid square: missing rank")?;

    let file = match file_char {
        'a' => 0, 'b' => 1, 'c' => 2, 'd' => 3,
        'e' => 4, 'f' => 5, 'g' => 6, 'h' => 7,
        _ => return Err(format!("Invalid file character: {}", file_char)),
    };

    // '1' has ASCII value 49. '1'.to_digit(10) gives 1. We subtract 1 for 0-indexing.
    let rank = rank_char.to_digit(10)
        .ok_or(format!("Invalid rank character: {}", rank_char))?
        .saturating_sub(1) as usize;

    if rank > 7 {
        return Err(format!("Invalid rank: {}", rank_char));
    }

    Ok(Position { rank, file })
}

This function:

1. Pulls out the file and rank characters.
2. Uses a match expression to convert the file character 'a'-'h' into a usize 0-7.
3. Uses the to_digit(10) method to convert the rank character '1'-'8' into a number. We subtract 1 to align with our 0-indexed board representation.
4. Returns a Result containing either the Position or an error String.

Step 2: Parse the Full Move String

Now we can use our helper function to build the main parser.

// In the same file as parse_square

pub fn parse_move(input: &str) -> Result<Move, String> {
    if input.len() < 4 || input.len() > 5 {
        return Err("Invalid move length. Use format e.g., 'e2e4' or 'e7e8q'".to_string());
    }

    let from = parse_square(&input[0..2])?;
    let to = parse_square(&input[2..4])?;

    let promotion = if input.len() == 5 {
        let promo_char = input.chars().nth(4).unwrap(); // Safe due to length check
        let piece_type = match promo_char.to_ascii_lowercase() {
            'q' => PieceType::Queen,
            'r' => PieceType::Rook,
            'b' => PieceType::Bishop,
            'n' => PieceType::Knight,
            _ => return Err(format!("Invalid promotion piece: {}", promo_char)),
        };
        Some(piece_type)
    } else {
        None
    };

    Ok(Move { from, to, promotion })
}

This function:

1. Checks for a valid input length (4 or 5 characters).
2. Uses string slicing (&input[0..2]) to get the "from" and "to" parts.
3. Calls parse_square for each part. The ? operator neatly propagates any errors.
4. If the string has a 5th character, it parses it as a promotion piece.
5. Finally, it assembles and returns the Move struct.

Step 3: Test Your Parser

Now you can test your new function. In your main function, you can add a simple test:

// in main.rs
mod input; // If you created src/input.rs

fn main() {
    let test_inputs = vec!["e2e4", "g1f3", "a7a8q", "e1g1", "bogo"];

    for input in test_inputs {
        match input::parse_move(input) {
            Ok(mv) => println!("'{}' -> Parsed move: {:?}", input, mv),
            Err(e) => println!("'{}' -> Error: {}", input, e),
        }
    }
    
    // You can remove this test code later and start building your game loop!
}

Running this should give you a clear idea if your parser is working as expected!

4. A Note on Using Crates

You've just built a parser from scratch, which is fantastic for understanding the mechanics. In the real world, for a complex domain like chess, developers often leverage existing, well-tested libraries (called "crates" in Rust).

Seeing this shows the power of leveraging community work. By building your own parser first, you now have a much deeper appreciation for what that function does under the hood. For our project, we'll stick with our own implementation as it's a great learning experience and keeps our dependencies minimal.

Conclusion

Excellent work! You have successfully built a crucial component that connects your game logic to the outside world. This parser is the "ears" of your chess engine, listening for player commands.

Key Takeaways:

• UCI Long Algebraic Notation (e2e4, e7e8q) is an explicit and computer-friendly format for describing chess moves.
• Parsing strings into structured data is a common programming task that requires careful handling of potential errors.
• Rust's Result<T, E> enum and the ? operator are the perfect tools for writing robust parsing logic that doesn't crash on invalid input.
• We broke the problem down by creating a helper function (parse_square) and then composing it into a larger function (parse_move).

Preview of the Next Lesson

Now that we can understand user commands, we need a way to orchestrate the game. In the next lesson, we will create a main game loop that alternates turns between players, asking for input, using our new parser to understand it, and updating the game state.