mlem_asm/
lib.rs

1//! mlem-asm is an assembler library for MLeM, the Machine Learning Machine.
2//! This is a Harvard architecture machine with immutable programs, 8 general purpouse registers,
3//! and a hardware-supported stack with stack and base pointers.
4//! 
5//! # Assembly Language
6//! mlem-asm assembles the mlasm language into CBOR-encoded data that can be read and executed by MLeM.
7//! The mlasm language looks like so:
8//!
9//! ```lmasm,ignore
10//! ; Anything following a semicolon is a comment.
11//! ; Lines can be terminated with a semicolon, or not. The following two lines are equivalent:
12//! noop
13//! noop;
14//! ; Instructions that require arguments look like so:
15//! move R:R0 R:R1 ; Set R1 equal to R0
16//! ```
17//! 
18//! # Examples
19//! Here is an example of parsing a program and converting it into CBOR.
20//!
21//! ```
22//! use mlem_asm::*;
23//! use std::io::Cursor;
24//! let valid_program = "
25//!    noop
26//!    move R:R0 R:SP;
27//!    input R:R0;
28//!    ; comment only
29//!
30//!    ";
31//!
32//!    let mut buffer = Cursor::new(Vec::<u8>::new());
33//!
34//!    let program = parse_program(valid_program).unwrap();
35//!    program_to_writer(&program, &mut buffer).unwrap();
36//!    assert_eq!(buffer.get_ref(), 
37//!               &[217, 217, 247, 131, 0, 131, 2, 130, 
38//!                 0, 0, 130, 0, 8, 130, 4, 130, 0, 0])
39//!   
40//! ```
41
42extern crate serde_cbor;
43
44extern crate mlem;
45pub use mlem::{Address, Instruction, Register, Program};
46
47#[cfg(test)]
48mod test;
49
50pub mod parse;
51pub use parse::{parse_program};
52pub mod lex;
53
54use std::io::Write;
55/// Writes an assembled program to a writer in packed, self-describing CBOR (a format MLeM can natively consume.)
56/// 
57/// Writing to, i.e., a file allows you to save assembled "binaries" that MLeM can execute; you can also pass 
58/// data over the network for distributed processing.
59pub fn program_to_writer(p: &Program, mut w: &mut Write) -> Result<(), serde_cbor::Error> {
60    use serde_cbor::ser::to_writer_packed_sd;
61    to_writer_packed_sd(&mut w, &p)
62}