souper_ir/
lib.rs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
//! A library for manipulating [Souper] IR.
//!
//! [![](https://docs.rs/souper-ir/badge.svg)](https://docs.rs/souper-ir/)
//! [![](https://img.shields.io/crates/v/souper-ir.svg)](https://crates.io/crates/souper-ir)
//! [![](https://img.shields.io/crates/d/souper-ir.svg)](https://crates.io/crates/souper-ir)
//! ![CI](https://github.com/fitzgen/souper-ir/workflows/CI/badge.svg)
//!
//! This crate provides AST types for parsing or generating Souper IR. It is a
//! suitable building block either for writing a custom LHS extractor, or for
//! translating learned optimizations into your own peephole optimizations pass.
//!
//! ## AST
//!
//! The AST type definitions and builders live in the `souper_ir::ast` module.
//!
//! ## Parsing Souper IR
//!
//! When the `parse` Cargo feature is enabled, the `souper_ir::parse` module
//! contains functions for parsing Souper IR from a file or an in-memory string.
//!
//! ```
//! # #[cfg(feature = "parse")]
//! # fn foo() -> souper_ir::parse::Result<()> {
//! use std::path::Path;
//!
//! // We provide a filename to get better error messages.
//! let filename = Path::new("example.souper");
//!
//! let replacements = souper_ir::parse::parse_replacements_str("
//!     ;; x + x --> 2 * x
//!     %0 = var
//!     %1 = add %0, %0
//!     %2 = mul %0, 2
//!     cand %1, %2
//!
//!     ;; x & x --> x
//!     %0 = var
//!     %1 = and %0, %0
//!     cand %1, %0
//! ", Some(filename))?;
//! # let _ = replacements;
//! # Ok(())
//! # }
//! ```
//!
//! ## Emitting Souper IR's Text Format
//!
//! When the `stringify` Cargo feature is enabled, then the
//! `souper_ir::ast::Replacement`, `souper_ir::ast::LeftHandSide`, and
//! `souper_ir::ast::RightHandSide` types all implement `std::fmt::Display`. The
//! `Display` implementation writes the AST type out as Souper's text format.
//!
//! ```
//! # #[cfg(feature = "stringify")]
//! # fn foo() -> std::io::Result<()> {
//! use souper_ir::ast;
//!
//! // Build this Souper left-hand side:
//! //
//! //     %x:i32 = var
//! //     %y = mul %x, 2
//! //     infer %y
//! //
//! // We expect that Souper would be able to synthesize a right-hand side that
//! // does a left shift by one instead of a multiplication.
//!
//! let mut lhs = ast::LeftHandSideBuilder::default();
//!
//! let x = lhs.assignment(
//!     Some("x".into()),
//!     Some(ast::Type { width: 32 }),
//!     ast::AssignmentRhs::Var,
//!     vec![],
//! );
//!
//! let y = lhs.assignment(
//!     Some("y".into()),
//!     None,
//!     ast::Instruction::Mul {
//!         a: x.into(),
//!         b: ast::Constant { value: 2, r#type: None }.into(),
//!     },
//!     vec![],
//! );
//!
//! let lhs = lhs.finish(y, vec![]);
//!
//! // Now we can stringify the LHS (and then, presumably, give it to Souper)
//! // with `std::fmt::Display`:
//!
//! use std::io::Write;
//!
//! let mut file = std::fs::File::create("my-lhs.souper")?;
//! write!(&mut file, "{}", lhs)?;
//! # Ok(())
//! # }
//! ```
//! [Souper]: https://github.com/google/souper

#![deny(missing_debug_implementations)]
#![deny(missing_docs)]

pub mod ast;

#[cfg(feature = "parse")]
pub mod parse;

#[cfg(feature = "stringify")]
mod stringify;