rusty_systems/
lib.rs

1//! A crate for procedurally generating content using L-systems.
2//!
3//! **NOTE:** this crate is still under early development, and might change rapidly.
4//! The next released version will likely have breaking changes.
5//!
6//! # Introduction
7//!
8//! This crate currently supports producing strings using *context-free* and
9//! *stochastic* [L-Systems][wiki]. 
10//!
11//! The [system module](system) contains the primary tools for defining
12//! and running these grammars. As a convenience, the [`geometry`] module
13//! contains types for easily handling the interpretation of the grammar's output
14//! in a 2D space. Note that the geometry tools are not meant to be complete or high performance —
15//! it's meant to only be utilitarian.
16//!
17//! # Parsing and Derivation
18//!
19//! The easiest way to parse:
20//!
21//! ```
22//! use rusty_systems::prelude::*;
23//! use rusty_systems::parser;
24//!
25//! let system = System::new();
26//! system.parse_production("CompanyName -> Surname Surname").unwrap();
27//!
28//! let starting_axiom = parser::parse_prod_string("CompanyName").unwrap();
29//! let result = system.derive(starting_axiom, RunSettings::default()).unwrap();
30//!
31//! println!("The resulting string is:\n{result}");
32//!
33//! ```
34//!
35//! If you would like to parse without using a [`System`] instance,
36//! you can use the following underlying functions:
37//!
38//! * [`parser::parse_production`] to parse individual productions.
39//! 
40//! See [`parser`] for more information, and for generic parsing
41//! functions that do not need you to use [`System`].
42//!
43//! # Features
44//!
45//! Some features that you might find useful:
46//!
47//! * **Some support for interpreting L-Systems as defined in [the Algorithmic Beauty of Plants (ABOP)][abop].**
48//!   See the [abop module](interpretation::abop) documentation.
49//! * **Some native, limited support for geometric primitives.**
50//!   See the [geometry module](geometry). This is not meant as a replacement for libraries
51//!   such as [nalgebra][nalgebra], just as something convenient to use.
52//! * **Native support for creating and outputting SVGs.**
53//!   See the [svg module](interpretation::svg).
54//! * **A command line app, `lsystem`, for creating SVGs of systems from ABOP.**
55//!   You can read about using this tool [here][lsystem-tool]
56//!
57//! # Examples
58//!
59//! The crate's example directory has various examples:
60//!
61//! * [Vector graphics plant][skia-plant]
62//!
63//!   This example uses two rules to produce a small plant. The symbols
64//!   are interpreted using a classic [logo turtle][logo-turtle] interpretation
65//!   to produce vector graphics. While the example uses [tiny skia][tiny-skia],
66//!   this can be replaced with any vector graphic library.
67//!
68//!   If you clone the code repository, you can run this using:
69//!
70//!   ```cargo run --example skia-plant ```
71//!
72//! # Learn more about L-Systems
73//!
74//! If you would like to learn more about L-Systems, the original *Algorithmic Beauty of Plants*
75//! book by Prusinkiewicz and Lindenmayer is [available for free, online][abop].
76//!
77//! # Code repository, license, and versioning.
78//! 
79//! This crate has a website available at 
80//! [https://theriver.github.io/rusty-systems/][website].
81//!
82//! The code repository is hosted on [GitHub](https://github.com/TheRiver/rusty-systems/) and
83//! is distributed under an [MIT license][license]. A [changelog][changelog] is also available.
84//!
85//! This crate versioning uses [semantic versioning][semver].
86//!
87//! [wiki]: https://en.wikipedia.org/wiki/L-system
88//! [abop]: http://algorithmicbotany.org/papers/#abop
89//! [skia-plant]: https://github.com/TheRiver/rusty-systems/blob/main/examples/skia-plant/main.rs
90//! [logo-turtle]: https://en.wikipedia.org/wiki/Logo_(programming_language)
91//! [tiny-skia]: https://github.com/RazrFalcon/tiny-skia
92//! [semver]: https://semver.org/
93//! [docs]: https://docs.rs/rusty-systems/latest/rusty_systems/
94//! [license]: https://github.com/TheRiver/rusty-systems/blob/main/LICENSE
95//! [changelog]: https://github.com/TheRiver/rusty-systems/blob/main/CHANGELOG.md
96//! [website]: https://theriver.github.io/rusty-systems/
97//! [nalgebra]: https://nalgebra.org/
98//! [lsystem-tool]: https://theriver.github.io/rusty-systems/lsystem/
99
100pub mod error;
101pub mod symbols;
102pub mod productions;
103pub mod strings;
104pub mod system;
105pub mod geometry;
106pub mod interpretation;
107pub mod parser;
108
109/// Some commonly used members of the crate re-exported for easy access.
110/// 
111/// Use it like so:
112/// 
113/// ```rust
114/// use rusty_systems::prelude::*;
115/// ```
116pub mod prelude {
117    pub use super::error::Error;
118    pub use super::strings::ProductionString;
119    pub use super::symbols::Symbol;
120    pub use super::system::System;
121    pub use super::system::RunSettings;
122    pub use super::system::family::SystemFamily;
123    pub use crate::interpretation::Interpretation;
124}
125
126use prelude::*;
127
128/// A result type for functions that can return errors.
129pub type Result<T> = std::result::Result<T, Error>;
rusty_systems/lib.rs

rusty_systems/
lib.rs
