1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
//! `secondbest` is a Rust library for implementing the "Second Best" strategy game. This library
//! provides a complete implementation of the game rules, board representation, and game state management.
//!
//! # Game Overview
//!
//! "Second Best" is a strategic board game played on 8 positions arranged in a circle. Players take turns
//! placing pieces of their color (Black or White) or moving pieces already on the board. The game features
//! a unique mechanic where a player can declare "second best" after their opponent's move, forcing the opponent
//! to choose a different action.
//!
//! ## Game Setup
//!
//! - The game starts with an empty board of 8 positions arranged in a circle (N, NE, E, SE, S, SW, W, NW)
//! - Each position can hold up to 3 stacked pieces
//! - Black plays first, then players alternate turns
//! - On each turn, a player must either place a new piece or move an existing one of their color
//!
//! ## "Second Best" Mechanic
//!
//! The unique feature of this game is the "second best" declaration:
//!
//! - After an opponent makes their move (their first action in the turn), a player can declare "second best"
//! - This forces the opponent to choose a different action (their "second best" choice)
//! - A player can only declare "second best" after the opponent's first action in a turn, not after their second action
//! - The "second best" declaration can only be used once per turn
//!
//! ## Winning Conditions
//!
//! A player wins when they achieve one of the following:
//! - **Vertical Line-up**: Stack 3 of their pieces in a single position
//! - **Horizontal Line-up**: Have their pieces at the top of 4 consecutive positions
//! - **Priority Win**: If both players achieve a winning condition simultaneously, the player who made the last move wins
//! - **No Moves**: If a player has no legal moves available, they lose
//!
//! Note: Winning conditions are only checked after all "second best" declarations have been used.
//!
//! # Architecture
//!
//! The library is organized into several modules:
//!
//! - `board`: Core board representation and operations
//! - `BitBoard`: Low-level bit manipulation for efficient board state representation
//! - `Board`: High-level API for board manipulation
//! - `Position`: Enumeration of the 8 board positions (N, NE, E, SE, S, SW, W, NW)
//! - `Color`: Player colors (B for Black, W for White)
//! - `Action`: Game actions (Put or Move)
//!
//! - `game`: Game state management
//! - `Game`: Main game state controller
//! - `GameResult`: Game outcome representation
//!
//! - `error`: Error handling
//! - Various error types for different operations
//!
//! # Basic Usage
//!
//! ```rust
//! use secondbest::prelude::*;
//!
//! // Create a new game
//! let mut game = Game::new();
//!
//! // Apply actions (place pieces and move them)
//! game.apply_action(Action::Put(Position::N, Color::B)).unwrap();
//! game.apply_action(Action::Put(Position::S, Color::W)).unwrap();
//!
//! // Check game state
//! if game.can_declare_second_best() {
//! game.declare_second_best().unwrap();
//! }
//!
//! // Check for a winner
//! match game.result() {
//! GameResult::Finished { winner } => println!("Winner: {:?}", winner),
//! GameResult::InProgress => println!("Game still in progress"),
//! }
//! ```
//!
//! # Advanced Usage
//!
//! For lower-level control, you can work directly with the `Board` API:
//!
//! ```rust
//! use secondbest::prelude::*;
//!
//! let mut board = Board::default();
//!
//! // Place pieces
//! board.put(Position::N, Color::B).unwrap();
//!
//! // Check board state
//! let pieces_at_north = board.get_pieces_at(Position::N);
//! let black_piece_count = board.count_pieces(Color::B);
//!
//! // Check for winning conditions
//! if board.lines_up(Color::B) {
//! println!("Black has won!");
//! }
//! ```
//!
//! # Error Handling
//!
//! The library provides detailed error types for various operations:
//!
//! ```rust
//! use secondbest::prelude::*;
//! use secondbest::error::GameError;
//!
//! let mut game = Game::new();
//! let result = game.apply_action(Action::Put(Position::N, Color::B));
//!
//! match result {
//! Ok(()) => println!("Action applied successfully"),
//! Err(GameError::IllegalAction(_)) => println!("Illegal action"),
//! Err(GameError::GameAlreadyOver) => println!("Game is already over"),
//! Err(GameError::BoardError(_)) => println!("Board error occurred"),
//! Err(_) => println!("Other error occurred"),
//! }
//! ```
// 公開するモジュール
/// Prelude module that re-exports commonly used types and functions.
///
/// This module provides a convenient way to import the most frequently used
/// components of the library with a single `use` statement.
///
/// # Examples
///
/// ```
/// use secondbest::prelude::*;
///
/// // Now you can use Board, Color, Position, etc. directly
/// let mut board = Board::default();
/// let action = Action::Put(Position::N, Color::B);
/// ```