backgammon/
lib.rs

1/*
2 * BSD 2-Clause License
3 *
4 * Copyright (c) 2020-2026, Carlo Strub <cs@carlostrub.ch>
5 *
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions are met:
8 *
9 * 1. Redistributions of source code must retain the above copyright notice, this
10 *    list of conditions and the following disclaimer.
11 *
12 * 2. Redistributions in binary form must reproduce the above copyright notice,
13 *    this list of conditions and the following disclaimer in the documentation
14 *    and/or other materials provided with the distribution.
15 *
16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
19 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
20 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
22 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
23 * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
24 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
25 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26 */
27
28//! [![status-badge](https://ci.codeberg.org/api/badges/15563/status.svg)](https://ci.codeberg.org/repos/15563)
29//!
30//! # Backgammon: The Oldest Board Game in the World
31//! This crate provides a pure, canonical implementation of the game
32//! [*Backgammon.*](https://en.wikipedia.org/wiki/Backgammon)
33//!
34//! <img src="https://upload.wikimedia.org/wikipedia/commons/3/30/Backgammon_lg.png" height="100">
35//!
36//! ## Supported Doubling Cube Rules
37//! The following doubling cube [`rules`](`crate::rules::Rules`) are supported:
38//!
39//! * Beaver
40//! * Raccoon
41//! * Murphy
42//! * Jacobi
43//! * Crawford
44//! * Holland
45//!
46//! ## Examples
47//! ### Creating a Match
48//! To create a new backgammon match, load the prelude module and define a mutable match:
49//! ```
50//! use backgammon::prelude::*;
51//!
52//! let mut m = Match::new();
53//!
54//! ```
55//! Depending on the style of tournament, it is possible to set any number of
56//! [`rules`](`crate::rules::Rules`):
57//! ```
58//! use backgammon::prelude::*;
59//!
60//! fn play_match() -> Result<(), Error> {
61//!
62//! let mut m = Match::new();
63//! m.set_points(13)?;
64//! m.set_jacobi(true)?;
65//!
66//! Ok(())
67//! }
68//! ```
69//! ### The first roll
70//! In a physical game, both players roll with one die. Then, the higher roll defines the first
71//! player.
72//! ```
73//! use backgammon::prelude::*;
74//!
75//! fn play_match() -> Result<(), Error> {
76//!
77//! let mut m = Match::new();
78//! m.roll(Player::Nobody)?;
79//!
80//! Ok(())
81//! }
82//! ```
83//!
84//! ### Playing an Example Game
85//! To see this library in action, run the included example:
86//! ```console
87//! cargo run --example backgammon_tui
88//! ```
89//! For more examples, have a look at the [examples](https://codeberg.org/Backgammon/backgammon/src/branch/main/examples)
90//! directory.
91//!
92//!
93//! ## Design Philosophy
94//! This library is designed to provide stateless Backgammon gameplay functionality. Because it does
95//! not track or store game states itself, you can easily implement wrappers that use this library
96//! along with an external database to manage and persist game states.
97//!
98//! ## Discussions and Support
99//! Remember that the APIs are not stable yet. Any support is very welcome. Please open an
100//! [Issue](https://codeberg.org/Backgammon/backgammon/issues) to discuss features or ask for help.
101
102#![warn(future_incompatible)]
103#![deny(
104    rustdoc::broken_intra_doc_links,
105    rustdoc::invalid_codeblock_attributes,
106    rustdoc::invalid_html_tags,
107    rustdoc::missing_crate_level_docs,
108    missing_debug_implementations,
109    missing_docs,
110    rustdoc::private_intra_doc_links,
111    single_use_lifetimes,
112    trivial_casts,
113    trivial_numeric_casts,
114    unreachable_pub,
115    unsafe_code,
116    unused_extern_crates,
117    unused_import_braces,
118    unused_qualifications,
119    unused_results,
120    unused_variables,
121    variant_size_differences
122)] // be tough on code quality
123
124pub use error::Error;
125pub use game::Game;
126pub use r#match::{Match, MatchState};
127
128/// Implements all possible Backgammon errors.
129mod error;
130/// Implements a Backgammon game.
131mod game;
132/// Implements a Backgammon match.
133mod r#match;
134/// Implements the board, the dice, the cube, and all other Backgammon rules.
135///
136/// _Caveat:_ Unless you know what you are doing, you should not use this module directly. Only
137/// use the [Match struct](./struct.Match.html) in your implementation.
138pub mod rules;
139/// Implements statistics.
140pub mod stats;
141
142/// Provides commonly used types and structures for ease of use in external modules. It is
143/// recommended to always use the prelude module for convenience.
144pub mod prelude {
145    pub use crate::rules::MatchRules;
146    pub use crate::rules::prelude::*;
147    pub use crate::{Error, Match, MatchState};
148}
backgammon/lib.rs

backgammon/
lib.rs
