eschac

src/lib.rs

@@ -0,0 +1,90 @@
+//! # eschac - a library for computing chess moves
+//!
+//! eschac implements fast legal move generation and a copy-make interface that enforces at compile
+//! time that no illegal move is played, with no runtime checks and no potential panics.
+//!
+//! ## Overview
+//!
+//! The most important type in eschac is [`Position`](position::Position), it represents a chess
+//! position from which legal moves are generated. [`Position::new`](position::Position::new)
+//! returns the starting position of a chess game, and arbitrary positions can be built using the
+//! [`Setup`](setup::Setup) type, but they must be validated and converted to a
+//! [`Position`](position::Position) to generate moves as eschac does not handle certain illegal --
+//! as in unreachable in a normal game -- positions (see
+//! [`IllegalPositionReason`](setup::IllegalPositionReason) to know more). Legal moves are then
+//! generated using the [`Position::legal_moves`](position::Position::legal_moves) method or
+//! obtained from chess notation like [`UciMove`](uci::UciMove) or [`San`](san::San). Moves are
+//! represented with the [`Move<'l>`](position::Move) type, which holds a reference to the origin
+//! position (hence the lifetime), this ensures the move is played on the correct position.
+//! Finally, moves are played using the [`Move::make`](position::Move) method which returns a new
+//! [`Position`](position::Position), and on it goes.
+//!
+//! ## Example
+//!
+//! ```
+//! # (|| -> Result<(), Box<dyn std::error::Error>> {
+//!
+//! use eschac::prelude::*;
+//!
+//! // read a position from a text record
+//! let setup = "7k/4P1rp/5Q2/5p2/1Pp1bP2/8/r4K1P/6R1 w - -".parse::<Setup>()?;
+//! let position = setup.validate()?;
+//!
+//! // read a move in algebraic notation
+//! let san = "Ke1".parse::<San>()?;
+//! let m = san.to_move(&position)?;
+//!
+//! // play the move (note the absence of error handling)
+//! let position = m.make();
+//!
+//! // generate all the legal moves on the new position
+//! let moves = position.legal_moves();
+//! for m in moves {
+//!     // print the UCI notation of each move
+//!     println!("{}", m.to_uci());
+//! }
+//! # Ok(()) });
+//! ```
+//!
+//! ## Comparison with [shakmaty](https://crates.io/crates/shakmaty)
+//!
+//! shakmaty is another Rust library for chess processing. It is written by Niklas Fiekas, whose
+//! work greatly inspired the development of eschac. For most purposes, shakmaty is probably a
+//! better option, as eschac comes short of its miriad of features.
+//!
+//! Both libraries have the same core features:
+//! - vocabulary to describe the chessboard (squares, pieces, etc.)
+//! - parsing and editing positions
+//! - parsing standard move notations
+//! - fast legal move generation and play
+//!
+//! **eschac** distinguishes itself with:
+//! - a focus on performance
+//! - a more compact board representation
+//! - its use of the borrow checker to guarantee only legal moves are played
+//!
+//! **shakmaty** will be more suitable for a lot of applications, with:
+//! - vocabulary to describe and work with games, not just positions
+//! - insufficient material detection
+//! - PGN parsing
+//! - Zobrist hashing
+//! - Syzygy endgame tablebases
+//! - chess960 and other variants
+//! - etc.
+
+pub(crate) mod array_vec;
+pub(crate) mod bitboard;
+pub(crate) mod magics;
+pub(crate) mod rays;
+
+pub mod board;
+pub mod lookup;
+pub mod position;
+pub mod san;
+pub mod setup;
+pub mod uci;
+
+/// The eschac prelude.
+pub mod prelude {
+    pub use crate::{position::Position, san::San, setup::Setup, uci::UciMove};
+}