ankigammon 1.0.0__py3-none-any.whl

ankigammon/utils/move_parser.py

@@ -0,0 +1,239 @@
+"""Parse and apply backgammon move notation."""
+
+import re
+from typing import List, Tuple
+
+from ankigammon.models import Position, Player
+
+
+class MoveParser:
+    """Parse and apply backgammon move notation."""
+
+    @staticmethod
+    def parse_move_notation(notation: str) -> List[Tuple[int, int]]:
+        """
+        Parse move notation into list of (from, to) tuples.
+
+        Args:
+            notation: Move notation (e.g., "13/9 6/5", "bar/22", "6/off")
+
+        Returns:
+            List of (from_point, to_point) tuples
+            Use 0 for X bar, 25 for O bar, 26 for bearing off
+
+        Examples:
+            "13/9 6/5" -> [(13, 9), (6, 5)]
+            "bar/22" -> [(0, 22)]  # X entering from bar
+            "6/off" -> [(6, 26)]  # Bearing off
+            "6/4(4)" -> [(6, 4), (6, 4), (6, 4), (6, 4)]  # Repetition notation
+        """
+        notation = notation.strip().lower()
+
+        # Handle special cases
+        if notation in ['double', 'take', 'drop', 'pass', 'accept', 'decline']:
+            return []  # Cube actions have no checker movement
+
+        moves = []
+
+        # Split by spaces or commas
+        parts = re.split(r'[\s,]+', notation)
+
+        for part in parts:
+            if not part or '/' not in part:
+                continue
+
+            # Check for repetition notation like "6/4(4)" meaning "move 4 checkers from 6 to 4"
+            repetition_count = 1
+            repetition_match = re.search(r'\((\d+)\)$', part)
+            if repetition_match:
+                repetition_count = int(repetition_match.group(1))
+                # Remove the repetition notation from the part
+                part = re.sub(r'\(\d+\)$', '', part)
+
+            # Handle compound notation like "6/5*/3" or "24/23/22"
+            # Split by '/' and remove asterisks to get all points in the sequence
+            segments = part.split('/')
+
+            # Remove asterisks from each segment
+            segments = [seg.rstrip('*') for seg in segments]
+
+            # If there are more than 2 segments, this is compound notation
+            # Convert it to consecutive moves: "6/5/3" -> [(6,5), (5,3)]
+            if len(segments) > 2:
+                for i in range(len(segments) - 1):
+                    from_str = segments[i]
+                    to_str = segments[i + 1]
+
+                    # Parse 'from' point
+                    if 'bar' in from_str:
+                        from_point = 0  # X bar (we'll adjust for O later)
+                    else:
+                        try:
+                            from_point = int(from_str)
+                        except ValueError:
+                            continue
+
+                    # Parse 'to' point
+                    if 'off' in to_str:
+                        to_point = 26  # Bearing off
+                    elif 'bar' in to_str:
+                        to_point = 0  # Will be adjusted based on context
+                    else:
+                        try:
+                            to_point = int(to_str)
+                        except ValueError:
+                            continue
+
+                    # Add the move repetition_count times
+                    for _ in range(repetition_count):
+                        moves.append((from_point, to_point))
+            else:
+                # Simple notation like "6/5" or "bar/22"
+                from_str = segments[0]
+                to_str = segments[1] if len(segments) > 1 else ''
+
+                if not to_str:
+                    continue
+
+                # Parse 'from' point
+                if 'bar' in from_str:
+                    from_point = 0  # X bar (we'll adjust for O later)
+                else:
+                    try:
+                        from_point = int(from_str)
+                    except ValueError:
+                        continue
+
+                # Parse 'to' point
+                if 'off' in to_str:
+                    to_point = 26  # Bearing off
+                elif 'bar' in to_str:
+                    # Hit - destination is the bar (rare in notation)
+                    to_point = 0  # Will be adjusted based on context
+                else:
+                    try:
+                        to_point = int(to_str)
+                    except ValueError:
+                        continue
+
+                # Add the move repetition_count times (handles notation like "6/4(4)")
+                for _ in range(repetition_count):
+                    moves.append((from_point, to_point))
+
+        return moves
+
+    @staticmethod
+    def apply_move(position: Position, notation: str, player: Player) -> Position:
+        """
+        Apply a move to a position and return the resulting position.
+
+        Args:
+            position: Initial position
+            notation: Move notation
+            player: Player making the move
+
+        Returns:
+            New position after the move
+        """
+        new_pos = position.copy()
+        moves = MoveParser.parse_move_notation(notation)
+
+        for from_point, to_point in moves:
+            # In backgammon notation, both players use the SAME numbering (1-24)
+            # The position array also uses this same numbering:
+            #   - points[1] = point 1 (O's 1-point)
+            #   - points[24] = point 24 (X's 1-point, O's 24-point)
+            #
+            # X moves from high numbers to low (24->1), O moves from low to high (1->24)
+            # No coordinate conversion is needed - notation matches position indices directly!
+
+            # The only special handling needed is for bar points:
+            # - X's bar is at position[0]
+            # - O's bar is at position[25]
+            # parse_move_notation() returns 0 for "bar", so correct it for O
+            if from_point == 0 and player == Player.O:
+                from_point = 25
+            if to_point == 0 and player == Player.X:
+                to_point = 25  # When X hits, opponent goes to bar 25
+
+            # Move checker
+            if from_point == 26:  # Bearing off (from)
+                # This shouldn't happen in normal notation
+                continue
+
+            # Remove from source
+            if new_pos.points[from_point] == 0:
+                # Invalid move - no checker to move
+                continue
+
+            if player == Player.X:
+                if new_pos.points[from_point] > 0:
+                    new_pos.points[from_point] -= 1
+                else:
+                    # Wrong player's checker
+                    continue
+            else:  # Player.O
+                if new_pos.points[from_point] < 0:
+                    new_pos.points[from_point] += 1
+                else:
+                    # Wrong player's checker
+                    continue
+
+            # Add to destination
+            if to_point == 26:  # Bearing off
+                if player == Player.X:
+                    new_pos.x_off += 1
+                else:
+                    new_pos.o_off += 1
+            else:
+                # Check for hitting
+                target_count = new_pos.points[to_point]
+
+                if player == Player.X:
+                    if target_count == -1:
+                        # Hit O's blot
+                        new_pos.points[25] -= 1  # Send to O's bar
+                        new_pos.points[to_point] = 1
+                    else:
+                        new_pos.points[to_point] += 1
+                else:  # Player.O
+                    if target_count == 1:
+                        # Hit X's blot
+                        new_pos.points[0] += 1  # Send to X's bar
+                        new_pos.points[to_point] = -1
+                    else:
+                        new_pos.points[to_point] -= 1
+
+        return new_pos
+
+    @staticmethod
+    def format_move(from_point: int, to_point: int, player: Player) -> str:
+        """
+        Format a single move as notation.
+
+        Args:
+            from_point: Source point (0-25, or 26 for bearing off)
+            to_point: Destination point
+            player: Player making the move
+
+        Returns:
+            Move notation string (e.g., "13/9", "bar/22", "6/off")
+        """
+        # Handle special points
+        if from_point == 0 and player == Player.X:
+            from_str = "bar"
+        elif from_point == 25 and player == Player.O:
+            from_str = "bar"
+        else:
+            from_str = str(from_point)
+
+        if to_point == 26:
+            to_str = "off"
+        elif to_point == 0 and player == Player.O:
+            to_str = "bar"
+        elif to_point == 25 and player == Player.X:
+            to_str = "bar"
+        else:
+            to_str = str(to_point)
+
+        return f"{from_str}/{to_str}"

ankigammon/utils/ogid.py

@@ -0,0 +1,335 @@
+"""OGID format parsing and encoding.
+
+OGID (OpenGammon Position ID) is a colon-separated format for representing
+complete backgammon board states.
+
+Format: P1:P2:CUBE[:DICE[:TURN[:STATE[:S1[:S2[:ML[:MID[:NCHECKERS]]]]]]]]
+
+Fields:
+1. P1 (White/X checkers): Base-26 encoded positions with repeated characters
+2. P2 (Black/O checkers): Base-26 encoded positions with repeated characters
+3. CUBE: Three-character cube state (owner, value, action)
+4. DICE: Two-character dice roll (optional)
+5. TURN: Player to move - W or B (optional)
+6. STATE: Two-character game state (optional)
+7. S1: White/X score (optional)
+8. S2: Black/O score (optional)
+9. ML: Match length with modifiers (optional)
+10. MID: Move ID (optional)
+11. NCHECKERS: Number of checkers per side (optional, default 15)
+
+Position encoding uses base-26:
+- Characters '0'-'9' = points 0-9
+- Characters 'a'-'p' = points 10-25
+- Point 0 = White's bar (X in our model)
+- Points 1-24 = board points
+- Point 25 = Black's bar (O in our model)
+- Repeated characters = multiple checkers on same point
+
+Example starting position:
+  White: 11jjjjjhhhccccc (2 on pt1, 5 on pt9, 3 on pt17, 5 on pt12)
+  Black: ooddddd88866666 (2 on pt24, 5 on pt13, 3 on pt8, 5 on pt6)
+  Full: 11jjjjjhhhccccc:ooddddd88866666:N0N::W:IW:0:0:1:0
+
+Note: In our internal model:
+  - White = Player.X (TOP player)
+  - Black = Player.O (BOTTOM player)
+  - Positive values = X checkers
+  - Negative values = O checkers
+"""
+
+import re
+from typing import Optional, Tuple, Dict
+
+from ankigammon.models import Position, Player, CubeState
+
+
+# Character to point mapping for base-26 encoding
+def _char_to_point(char: str) -> int:
+    """Convert a character to a point number (0-25)."""
+    if '0' <= char <= '9':
+        return ord(char) - ord('0')
+    elif 'a' <= char <= 'p':
+        return ord(char) - ord('a') + 10
+    else:
+        raise ValueError(f"Invalid position character: {char}")
+
+
+def _point_to_char(point: int) -> str:
+    """Convert a point number (0-25) to a character."""
+    if 0 <= point <= 9:
+        return chr(ord('0') + point)
+    elif 10 <= point <= 25:
+        return chr(ord('a') + point - 10)
+    else:
+        raise ValueError(f"Invalid point number: {point}")
+
+
+def parse_ogid(ogid: str) -> Tuple[Position, Dict]:
+    """
+    Parse an OGID string into a Position and metadata.
+
+    Args:
+        ogid: OGID string (e.g., "11jjjjjhhhccccc:ooddddd88866666:N0N::W:IW:0:0:1:0")
+
+    Returns:
+        Tuple of (Position, metadata_dict)
+    """
+    # Remove "OGID=" prefix if present
+    if ogid.upper().startswith("OGID="):
+        ogid = ogid[5:]
+
+    # Split into components
+    parts = ogid.split(':')
+    if len(parts) < 3:
+        raise ValueError(f"Invalid OGID format: expected at least 3 parts, got {len(parts)}")
+
+    white_pos = parts[0]  # White/X checkers
+    black_pos = parts[1]  # Black/O checkers
+    cube_str = parts[2]   # Cube state
+
+    # Parse position
+    position = _parse_ogid_position(white_pos, black_pos)
+
+    # Parse metadata
+    metadata = {}
+
+    # Parse cube state (3 characters: owner, value, action)
+    if len(cube_str) == 3:
+        cube_owner_char = cube_str[0]
+        cube_value_char = cube_str[1]
+        cube_action_char = cube_str[2]
+
+        # Cube value: 0->1, 1->2, 2->4, etc.
+        cube_value_log = int(cube_value_char)
+        metadata['cube_value'] = 2 ** cube_value_log
+
+        # Cube owner: W=White/X, B=Black/O, N=Neutral, D=Dead
+        if cube_owner_char == 'W':
+            metadata['cube_owner'] = CubeState.X_OWNS  # White = X in our model
+        elif cube_owner_char == 'B':
+            metadata['cube_owner'] = CubeState.O_OWNS  # Black = O in our model
+        elif cube_owner_char == 'N':
+            metadata['cube_owner'] = CubeState.CENTERED
+        else:  # D or ?
+            metadata['cube_owner'] = CubeState.CENTERED  # Default to centered
+
+        # Cube action (O=Offered, T=Taken, P=Passed, N=Normal)
+        metadata['cube_action'] = cube_action_char
+
+    # Parse optional fields
+    if len(parts) > 3 and parts[3]:
+        # Field 4: Dice
+        dice_str = parts[3]
+        if len(dice_str) == 2 and dice_str.isdigit():
+            d1 = int(dice_str[0])
+            d2 = int(dice_str[1])
+            if 1 <= d1 <= 6 and 1 <= d2 <= 6:
+                metadata['dice'] = (d1, d2)
+
+    if len(parts) > 4 and parts[4]:
+        # Field 5: Turn (W or B) - represents who is on roll
+        # W = White/X on roll, B = Black/O on roll
+        turn_str = parts[4].upper()
+        if turn_str == 'W':
+            metadata['on_roll'] = Player.X  # White = X
+        elif turn_str == 'B':
+            metadata['on_roll'] = Player.O  # Black = O
+
+    if len(parts) > 5 and parts[5]:
+        # Field 6: Game state (e.g., IW, FB)
+        metadata['game_state'] = parts[5]
+
+    if len(parts) > 6 and parts[6]:
+        # Field 7: White/X score
+        metadata['score_x'] = int(parts[6])
+
+    if len(parts) > 7 and parts[7]:
+        # Field 8: Black/O score
+        metadata['score_o'] = int(parts[7])
+
+    if len(parts) > 8 and parts[8]:
+        # Field 9: Match length (e.g., "7", "5C", "9G15")
+        match_str = parts[8]
+        match_regex = re.compile(r'(\d+)([LCG]?)(\d*)')
+        match = match_regex.match(match_str)
+        if match:
+            metadata['match_length'] = int(match.group(1))
+            if match.group(2):
+                metadata['match_modifier'] = match.group(2)  # L, C, or G
+            if match.group(3):
+                metadata['match_max_games'] = int(match.group(3))
+
+    if len(parts) > 9 and parts[9]:
+        # Field 10: Move ID
+        metadata['move_id'] = int(parts[9])
+
+    if len(parts) > 10 and parts[10]:
+        # Field 11: Number of checkers per side (default 15)
+        metadata['num_checkers'] = int(parts[10])
+
+    return position, metadata
+
+
+def _parse_ogid_position(white_str: str, black_str: str) -> Position:
+    """
+    Parse OGID position strings into a Position object.
+
+    Args:
+        white_str: White/X checker positions (e.g., "11jjjjjhhhccccc")
+        black_str: Black/O checker positions (e.g., "ooddddd88866666")
+
+    Returns:
+        Position object with checkers placed
+    """
+    position = Position()
+
+    # Parse White/X checkers (positive in our model)
+    for char in white_str:
+        point = _char_to_point(char)
+        position.points[point] += 1  # Positive for X
+
+    # Parse Black/O checkers (negative in our model)
+    for char in black_str:
+        point = _char_to_point(char)
+        position.points[point] -= 1  # Negative for O
+
+    # Calculate borne-off checkers (each player starts with 15)
+    total_x = sum(count for count in position.points if count > 0)
+    total_o = sum(abs(count) for count in position.points if count < 0)
+
+    position.x_off = 15 - total_x
+    position.o_off = 15 - total_o
+
+    return position
+
+
+def encode_ogid(
+    position: Position,
+    cube_value: int = 1,
+    cube_owner: CubeState = CubeState.CENTERED,
+    cube_action: str = 'N',
+    dice: Optional[Tuple[int, int]] = None,
+    on_roll: Optional[Player] = None,
+    game_state: str = '',
+    score_x: int = 0,
+    score_o: int = 0,
+    match_length: Optional[int] = None,
+    match_modifier: str = '',
+    match_max_games: Optional[int] = None,
+    move_id: Optional[int] = None,
+    num_checkers: Optional[int] = None,
+    only_position: bool = False,
+) -> str:
+    """
+    Encode a position and metadata as an OGID string.
+
+    Args:
+        position: The position to encode
+        cube_value: Doubling cube value
+        cube_owner: Who owns the cube
+        cube_action: Cube action (N=Normal, O=Offered, T=Taken, P=Passed)
+        dice: Dice values (if any)
+        on_roll: Player on roll
+        game_state: Game state code (e.g., "IW", "FB")
+        score_x: White/X player's score
+        score_o: Black/O player's score
+        match_length: Match length (points to win)
+        match_modifier: Match modifier (L, C, or G)
+        match_max_games: Max games for Galaxie format
+        move_id: Move sequence number
+        num_checkers: Number of checkers per side (only include if not 15)
+        only_position: If True, only encode position fields (1-3)
+
+    Returns:
+        OGID string
+    """
+    # Encode position strings
+    white_chars = []  # X/White checkers
+    black_chars = []  # O/Black checkers
+
+    for point_idx in range(26):
+        count = position.points[point_idx]
+        if count > 0:
+            # X/White checkers (positive)
+            white_chars.extend([_point_to_char(point_idx)] * count)
+        elif count < 0:
+            # O/Black checkers (negative)
+            black_chars.extend([_point_to_char(point_idx)] * abs(count))
+
+    # Sort characters (OGID format convention)
+    white_str = ''.join(sorted(white_chars))
+    black_str = ''.join(sorted(black_chars))
+
+    # Encode cube state (3 characters)
+    # Owner
+    if cube_owner == CubeState.X_OWNS:
+        cube_owner_char = 'W'  # White = X
+    elif cube_owner == CubeState.O_OWNS:
+        cube_owner_char = 'B'  # Black = O
+    else:
+        cube_owner_char = 'N'  # Neutral
+
+    # Value as log2
+    cube_value_log = 0
+    temp = cube_value
+    while temp > 1:
+        temp //= 2
+        cube_value_log += 1
+    cube_value_char = str(cube_value_log)
+
+    # Action
+    cube_action_char = cube_action
+
+    cube_str = f"{cube_owner_char}{cube_value_char}{cube_action_char}"
+
+    # Build OGID string
+    ogid_parts = [white_str, black_str, cube_str]
+
+    # If only_position is True, return just the first 3 fields
+    if only_position:
+        return ':'.join(ogid_parts)
+
+    # Add optional fields
+    # Field 4: Dice
+    if dice:
+        ogid_parts.append(f"{dice[0]}{dice[1]}")
+    else:
+        ogid_parts.append('')
+
+    # Field 5: Turn
+    if on_roll:
+        turn_char = 'W' if on_roll == Player.X else 'B'
+        ogid_parts.append(turn_char)
+    else:
+        ogid_parts.append('')
+
+    # Field 6: Game state
+    ogid_parts.append(game_state)
+
+    # Field 7-8: Scores
+    ogid_parts.append(str(score_x))
+    ogid_parts.append(str(score_o))
+
+    # Field 9: Match length
+    if match_length is not None:
+        match_str = str(match_length)
+        if match_modifier:
+            match_str += match_modifier
+        if match_max_games is not None:
+            match_str += str(match_max_games)
+        ogid_parts.append(match_str)
+    else:
+        ogid_parts.append('')
+
+    # Field 10: Move ID
+    if move_id is not None:
+        ogid_parts.append(str(move_id))
+    else:
+        ogid_parts.append('')
+
+    # Field 11: Number of checkers (only if not 15)
+    if num_checkers is not None and num_checkers != 15:
+        ogid_parts.append(str(num_checkers))
+
+    return ':'.join(ogid_parts)