lc3_ensemble/lib.rs
1//! A LC-3 parser, assembler, and simulator.
2//!
3//! This is meant to be a general suite to use LC-3 assembly
4//! (meant as a backend for Georgia Tech's CS 2110 LC3Tools).
5//!
6//! # Usage
7//!
8//! To convert LC-3 source code to an object file, it must be parsed and assembled:
9//! ```
10//! use lc3_ensemble::parse::parse_ast;
11//! use lc3_ensemble::asm::{assemble, assemble_debug, ObjectFile};
12//!
13//! let code = "
14//! .orig x3000
15//! AND R0, R0, #0
16//! AND R0, R0, #7
17//! HALT
18//! .end
19//! ";
20//! let ast = parse_ast(code).unwrap();
21//!
22//! // Assemble AST into object file:
23//! # {
24//! # let ast = ast.clone();
25//! let obj_file: ObjectFile = assemble(ast).unwrap();
26//! # }
27//! // OR:
28//! let obj_file: ObjectFile = assemble_debug(ast, code).unwrap();
29//! ```
30//!
31//! Once an object file has been created, it can be executed with the simulator:
32//! ```
33//! # // Parsing and assembling was shown in the previous example, so this doesn't need to be shown again.
34//! # use lc3_ensemble::parse::parse_ast;
35//! # use lc3_ensemble::asm::{assemble_debug};
36//! #
37//! # let code = ".orig x3000\nHALT\n.end";
38//! # let ast = parse_ast(code).unwrap();
39//! # let obj_file = assemble_debug(ast, code).unwrap();
40//! #
41//! use lc3_ensemble::sim::Simulator;
42//!
43//! let mut simulator = Simulator::new(Default::default());
44//! simulator.load_obj_file(&obj_file);
45//! simulator.run().unwrap(); // <-- Result can be handled accordingly
46//! ```
47//!
48//! If more granularity is needed for simulation, there are also step-in and step-out functions.
49//! See the [`sim`] module for more details.
50#![warn(missing_docs)]
51
52pub mod parse;
53pub mod ast;
54pub mod asm;
55pub mod sim;
56pub mod err;