Mike Gerwitz

Activist for User Freedom

aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--tamer/src/ir/mod.rs11
-rw-r--r--tamer/src/obj/xmlo/asg_builder.rs52
-rw-r--r--tamer/src/obj/xmlo/mod.rs11
3 files changed, 74 insertions, 0 deletions
diff --git a/tamer/src/ir/mod.rs b/tamer/src/ir/mod.rs
index faf2673..3b94703 100644
--- a/tamer/src/ir/mod.rs
+++ b/tamer/src/ir/mod.rs
@@ -59,6 +59,17 @@
//! a graph data structure,
//! and is capable of representing entire programs composed of many
//! different packages.
+//!
+//! Lowering
+//! ========
+//! IRs are progressively _lowered_ to other IRs that are closer to the
+//! final representation emitted by the compiler ("lower"-level).
+//!
+//! - [`xmlo::reader`](crate::obj::xmlo::reader) produces
+//! [`XmloEvent`](crate::obj::xmlo::XmloEvent)s containing
+//! [`legacyir`].
+//! - [`xmlo::asg_builder`](crate::obj::xmlo::asg_builder) immediately lowers
+//! those into [`asg`].
pub mod asg;
pub mod legacyir;
diff --git a/tamer/src/obj/xmlo/asg_builder.rs b/tamer/src/obj/xmlo/asg_builder.rs
index 31ecf0c..b957c95 100644
--- a/tamer/src/obj/xmlo/asg_builder.rs
+++ b/tamer/src/obj/xmlo/asg_builder.rs
@@ -17,6 +17,57 @@
// You should have received a copy of the GNU General Public License
// along with this program. If not, see <http://www.gnu.org/licenses/>.
+//! Lower [Legacy IR](crate::ir::legacyir) derived from [`XmloEvent`]
+//! into [`Asg`].
+//!
+//! [`AsgBuilder`] is exclusively responsible for this lowering operation
+//! within the context of [`xmlo` object files](super).
+//!
+//! Usage
+//! =====
+//! [`AsgBuilder`] accepts any [`Iterator`] of [`XmloEvent`]s,
+//! but is intended to be paired with [`XmloReader`](super::XmloReader).
+//!
+//! To fully load an `xmlo` file and its dependencies,
+//! begin with [`AsgBuilder::import_xmlo`] and an empty
+//! [`AsgBuilderState`].
+//! Each call accepts the previous state and returns a new state that may be
+//! used both for introspection and for the next call to `import_xmlo`.
+//! [`AsgBuilderState::found`] can be used to recursively load relative
+//! package paths;
+//! it is wrapped in an [`Option`] so that [`take`](Option::take) can be
+//! used to take ownership over the data.
+//!
+//! ```
+//! use tamer::global;
+//! use tamer::ir::asg::{DefaultAsg, IdentObject};
+//! use tamer::obj::xmlo::{AsgBuilder, AsgBuilderState, XmloReader};
+//! use tamer::sym::{DefaultInterner, Interner};
+//! use fxhash::FxBuildHasher;
+//! use std::io::BufReader;
+//!
+//! let src_xmlo: &[u8] = br#"<package>
+//! <preproc:symtable>
+//! <preproc:sym name="foo" type="cgen" src="dep/package" />
+//! </preproc:symtable>
+//! <preproc:fragments>
+//! </preproc:fragments>
+//! </package>"#;
+//!
+//! let interner = DefaultInterner::new();
+//! let xmlo = XmloReader::new(src_xmlo, &interner);
+//! let mut asg = DefaultAsg::<'_, IdentObject, global::ProgIdentSize>::new();
+//!
+//! let state = asg.import_xmlo(xmlo, AsgBuilderState::<'_, FxBuildHasher, _>::new());
+//!
+//! // Use `state.found` to recursively load dependencies.
+//! let AsgBuilderState { found, .. } = state.expect("unexpected failure");
+//! assert_eq!(
+//! vec![&"dep/package"],
+//! found.unwrap().iter().collect::<Vec<_>>(),
+//! );
+//! ```
+
use super::reader::{XmloError, XmloEvent, XmloResult};
use crate::ir::asg::{
Asg, AsgError, IdentKind, IdentKindError, IdentObjectState, IndexType,
@@ -109,6 +160,7 @@ where
///
/// For more information on what data are processed,
/// see [`AsgBuilderState`].
+/// See the [module-level documentation](self) for example usage.
pub trait AsgBuilder<'i, O, S, Ix>
where
O: IdentObjectState<'i, O>,
diff --git a/tamer/src/obj/xmlo/mod.rs b/tamer/src/obj/xmlo/mod.rs
index 020bfc5..3e81d76 100644
--- a/tamer/src/obj/xmlo/mod.rs
+++ b/tamer/src/obj/xmlo/mod.rs
@@ -73,6 +73,17 @@
//! <!-- Expanded src -->
//! </package>
//! ```
+//!
+//! IR Lowering
+//! ===========
+//! `xmlo` files are represented by the [Legacy IR](crate::ir::legacyir),
+//! which is emitted during read by [`AsgBuilder`].
+//! For more information about how they are lowered into the
+//! [ASG](crate::ir::asg),
+//! see [`asg_builder`].
+//!
+//! For a summary of IRs and how they interact,
+//! see [`crate::ir`].
mod asg_builder;
mod reader;