esoteric_vm/
lib.rs

1//! An esoteric virtual machine.
2//!
3//! Create a new machine with [`Machine::default`] and load
4//! machine code and data to it with [`Machine::load`].
5//!
6//! # Examples
7//!
8//! ```rust
9//! use esoteric_vm::{esoteric_assembly, Machine};
10//!
11//! # fn main() -> Machine {
12//! // initialize a new machine
13//! let mut machine = Machine::default();
14//!
15//! // assembly code for the machine
16//! let asm = esoteric_assembly! {
17//!     // initialize dot pointer so that IO operations work
18//!
19//!     // push a dot character to stack
20//!     0: pushi b'.';
21//!     // pop to address 28657
22//!     2: pop 28657;
23//!
24//!     // set dot pointer to 28657 (has to be a prime or semiprime, which is also a fibonacci number)
25//!     5: ldidp 28657;
26//!
27//!     // -----------------
28//!
29//!     // print hello world
30//!     8: writeline 13;
31//!
32//!     // halt machine
33//!     11: Ωtheendisnear;
34//!     12: Ωskiptothechase;
35//!
36//!     // hello world text
37//!     13: data b"Hello, world!\n\0";
38//! };
39//!
40//! // load machine code
41//! machine.load(&asm, 0);
42//!
43//! // run machine until it halts
44//! machine.run();
45//!
46//! // return the machine's register A (unused)
47//! machine
48//! # }
49//! ```
50
51#![warn(
52    clippy::pedantic,
53    clippy::complexity,
54    clippy::cognitive_complexity,
55    clippy::correctness,
56    clippy::nursery,
57    clippy::perf,
58    clippy::style,
59    clippy::suspicious,
60    clippy::arithmetic_side_effects,
61    clippy::little_endian_bytes,
62    clippy::dbg_macro,
63    clippy::decimal_literal_representation,
64    clippy::exit,
65    clippy::expect_used,
66    clippy::unwrap_used,
67    clippy::host_endian_bytes,
68    clippy::if_then_some_else_none,
69    clippy::indexing_slicing,
70    missing_docs,
71    clippy::missing_docs_in_private_items,
72    clippy::mixed_read_write_in_expression,
73    clippy::multiple_unsafe_ops_per_block,
74    clippy::panic,
75    clippy::partial_pub_fields,
76    clippy::pub_without_shorthand,
77    clippy::self_named_module_files,
78    clippy::semicolon_inside_block,
79    clippy::todo,
80    clippy::undocumented_unsafe_blocks,
81    clippy::wildcard_enum_match_arm
82)]
83#![deny(clippy::must_use_candidate, unsafe_op_in_unsafe_fn)]
84
85pub mod instruction;
86pub mod machine;
87/// Utilities used throughout the crate.
88pub(crate) mod utils {
89    pub mod array_debug;
90    pub mod constant_size_string;
91    pub mod multi_index;
92    pub mod non_invalidatable;
93    pub mod primes;
94}
95pub mod assembly;
96
97pub use machine::Machine;