backgammon/
lib.rs

1/*
2 * BSD 2-Clause License
3 *
4 * Copyright (c) 2020-2025, 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//! # Backgammon: The Oldest Board Game in the World
29//! This crate provides a pure, canonical implementation of the game
30//! [*Backgammon.*](https://en.wikipedia.org/wiki/Backgammon)
31//!
32//! <img src="https://upload.wikimedia.org/wikipedia/commons/3/30/Backgammon_lg.png" height="100">
33//!
34//! ## Supported Doubling Cube Rules
35//! The following doubling cube [`rules`](`crate::rules::Rules`) are supported:
36//!
37//! * Beaver
38//! * Raccoon
39//! * Murphy
40//! * Jacoby
41//! * Crawford
42//! * Holland
43//!
44//! ## Examples
45//! Start a new backgammon match over the default number of points and with the default rules, as
46//! defined in [`Rules`](`crate::rules::Rules`):
47//! ```
48//! use backgammon::Match;
49//!
50//! let mut m = Match::new();
51//!
52//! ```
53//! Typically, you want to define the points for a match, hence:
54//! ```
55//! use backgammon::Match;
56//! use backgammon::rules::MatchRules;
57//!
58//! let mut m = Match::new().
59//! with_points(13);
60//!
61//! ```
62//! Depending on the style of tournament you decide to play, it makes sense to select one or more
63//! rules too:
64//! ```
65//! use backgammon::Match;
66//! use backgammon::rules::{MatchRules, GameRules};
67//!
68//! let mut m = Match::new();
69//! m.with_points(13).unwrap();
70//! m.with_jacoby().unwrap();
71//!
72//! ```
73//!
74//! Play a game by calling:
75//! ```
76//! use backgammon::Game;
77//! use backgammon::rules::{Roll,GameRules};
78//!
79//! let mut g = Game::new();
80//!
81//! // roll dices
82//! g.roll();
83//! ```
84//! ## Design Philosophy
85//! This library is designed to provide stateless Backgammon gameplay functionality. Because it does
86//! not track or store game states itself, you can easily implement wrappers that use this library
87//! along with an external database to manage and persist game states.
88//!
89//! ## Discussions and Support
90//! Remember that the APIs are not stable yet. Any support is very welcome. Please open an
91//! [Issue](https://codeberg.org/Backgammon/backgammon/issues) to discuss features or ask for help.
92
93#![warn(future_incompatible)]
94#![deny(
95    rustdoc::broken_intra_doc_links,
96    rustdoc::invalid_codeblock_attributes,
97    rustdoc::invalid_html_tags,
98    rustdoc::missing_crate_level_docs,
99    missing_debug_implementations,
100    missing_docs,
101    rustdoc::private_intra_doc_links,
102    single_use_lifetimes,
103    trivial_casts,
104    trivial_numeric_casts,
105    unreachable_pub,
106    unsafe_code,
107    unused_extern_crates,
108    unused_import_braces,
109    unused_qualifications,
110    unused_results,
111    unused_variables,
112    variant_size_differences
113)] // be tough on code quality
114
115pub use error::Error;
116pub use game::Game;
117pub use r#match::Match;
118
119/// Implements all possible Backgammon errors.
120mod error;
121/// Implements a Backgammon game.
122mod game;
123/// Implements a Backgammon match.
124mod r#match;
125/// Implements the board, the dices, the cube, and all other Backgammon rules.
126pub mod rules;
127/// Implements statistics.
128pub mod stats;
backgammon/lib.rs

backgammon/
lib.rs
