life_backend/lib.rs
1//! A backend implementation of Conway's Game of Life.
2//!
3//! This library provides several functionalities for simulating Life-like cellular
4//! automata, including Conway's Game of Life.
5//!
6//! The following operations are supported:
7//!
8//! - Parsing or writing patterns of Life-like cellular automata
9//! (Plaintext and RLE formats are supported)
10//! - Parsing or writing rules in the birth/survival notation (e.g., `"B3/S23"`)
11//! - Managing a board, a two-dimensional orthogonal grid map of live and dead cells
12//! (The type of the x- and y-coordinates of positions is generalized)
13//! - Creating a new game based on a given rule and board, advancing the generation
14//! and querying the state
15//!
16//! It does not provide frontend functionality for viewing or editing patterns
17//! through a user interface.
18//!
19//! # Examples
20//!
21//! The following code example demonstrates how to create a new game from a pattern
22//! file, advance the game and print its final state:
23//!
24//! ```
25//! use life_backend::format;
26//! use life_backend::{Board, Game, Position};
27//!
28//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
29//! // Read a pattern file
30//! let handler = format::open("patterns/glider.rle")?;
31//!
32//! // Create a new game (the type parameter is `i16`)
33//! let rule = handler.rule();
34//! let board = handler
35//! .live_cells()
36//! .map(Position::try_from)
37//! .collect::<Result<Board<i16>, _>>()?;
38//! let mut game = Game::new(rule, board);
39//!
40//! // Advance the generation
41//! let generation = 4;
42//! for _ in 0..generation {
43//! game.advance();
44//! }
45//!
46//! // Print the last state
47//! let bbox = game.board().bounding_box();
48//! let population = game.board().iter().count();
49//! println!("Generation {generation}: bounding-box = {bbox}, population = {population}");
50//! println!("{game}");
51//! # Ok(())
52//! # }
53//! ```
54//!
55//! `examples/game.rs` is a simple Game of Life program. It creates a new game from
56//! a pattern file, advances the game and prints its state to the standard output.
57//! You can run this program like as:
58//!
59//! ```shell
60//! $ cargo run --example game -- --generation=1 patterns/glider.rle
61//! ...
62//! Generation 0: bounding-box = (x:[0, 2], y:[0, 2]), population = 5
63//! .O.
64//! ..O
65//! OOO
66//!
67//! Generation 1: bounding-box = (x:[0, 2], y:[1, 3]), population = 5
68//! O.O
69//! .OO
70//! .O.
71//! ```
72
73// Lint settings for documentation
74#![warn(missing_docs)]
75#![warn(rustdoc::missing_crate_level_docs)]
76
77mod rule;
78pub use rule::Rule;
79
80mod position;
81pub use position::Position;
82
83mod boardrange;
84pub use boardrange::BoardRange;
85
86mod board;
87pub use board::Board;
88
89mod game;
90pub use game::Game;
91
92pub mod format;
93pub use format::Format;