tamer: Move {ir::legacyir=>obj::xmlo::legacyir}

The IRs really ought to live where they are owned, especially given that
"IR" is so generic that it makes no sense for there to be a single location
for them; they're just data structures coupled with different phases of
compilation.

This will be renamed next commit; see that for details.

This also removes some documentation describing the lowering process,
because it's undergone a number of changes and needs to be accurately
re-summarized in another location.  That will come at a later time after the
work is further along so that I don't have to keep spending the time
rewriting it.

DEV-10863

tamer/src/ir/asg/ident.rs

@@ -19,7 +19,7 @@
 
 //! Identifiers (a type of [object][super::object::IdentObject]).
 
-use crate::ir::legacyir::{SymAttrs, SymDtype, SymType};
+use crate::obj::xmlo::{SymAttrs, SymDtype, SymType};
 use crate::sym::{st, GlobalSymbolResolve, SymbolId};
 use std::convert::TryFrom;
 use std::error::Error;
@@ -29,7 +29,7 @@ use std::error::Error;
 /// Here, the term _calculation_ refers to a composable expression that
 ///   produces a numeric result.
 ///
-/// These are derived from [`legacyir::SymType`][crate::ir::legacyir::SymType]
+/// These are derived from [`SymType`][crate::obj::xmlo::SymType]
 ///   and will be generalized in the future.
 #[derive(Debug, PartialEq, Eq, Clone)]
 pub enum IdentKind {

tamer/src/ir/asg/object.rs

@@ -23,7 +23,7 @@
 //!  See [`super`] for available exports._
 
 use super::ident::IdentKind;
-use crate::ir::legacyir::SymAttrs;
+use crate::obj::xmlo::SymAttrs;
 use crate::sym::{GlobalSymbolResolve, SymbolId};
 use std::result::Result;
 

tamer/src/ir/mod.rs

@@ -19,6 +19,9 @@
 
 //! Intermediate representations for TAME programs.
 //!
+//! _This module is being removed in favor of more specific locations for
+//! the contained IRs._
+//!
 //! [Intermediate representations][ir] (IRs) are data structures used to
 //!   represent source data in a manner most suitable for a particular phase
 //!   of compilation.
@@ -27,51 +30,7 @@
 //!
 //! [ir]: https://en.wikipedia.org/wiki/Intermediate_representation
 //! [linkers]: crate::ld
-//!
-//!
-//! Implicit AST
-//! ============
-//! Each input language begins as an [abstract syntax tree][ast] (AST),
-//!   produced by the parser.
-//! For TAME languages that are XML-based,
-//!   the production of the AST is handled by [`quick_xml`],
-//!     and is effectively the same as the source XML.
-//! There is no explicit data structure to represent the AST of XML
-//!   sources.
-//!
-//! [ast]: https://en.wikipedia.org/wiki/Abstract_syntax_tree
-//!
-//!
-//! Summary of IRs
-//! ==============
-//! There are currently two IRs:
-//!
-//!   1. **[Legacy IR](legacyir)** corresponds very closely to the structure
-//!        of [`xmlo` object files](super::obj::xmlo).
-//!      It contains a lot of cruft and will be replaced in the future with
-//!        a more suitable IR.
-//!      This stores very limited context for the information it provides,
-//!        so it must quickly translate it to a higher-level IR for further
-//!        processing before context is lost.
-//!   2. The **[Abstract Semantic Graph (ASG)](asg)** is created from
-//!        lower-level IRs.
-//!      It stores relationships between identifiers and expressions within
-//!        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::XmloReader`](crate::obj::xmlo::XmloReader) produces
-//!     [`XmloEvent`](crate::obj::xmlo::XmloEvent)s containing
-//!     [`legacyir`].
-//!   - [`xmlo::AsgBuilder`](crate::obj::xmlo::AsgBuilder) immediately lowers
-//!       those into [`asg`].
 
 pub mod asg;
-pub mod legacyir;
 #[macro_use]
 pub mod xir;

tamer/src/ld.rs

@@ -68,7 +68,8 @@
 //!        process;
 //!          they do not persist in memory.
 //!      Only the required portions of the file are loaded.
-//!      See the [Legacy IR](crate::ir::legacyir) for more information.
+//!      See [`XmloReader`](crate::obj::xmlo::XmloReader) for more
+//!        information.
 //!
 //!   2. This information is used to populate the [ASG].
 //!      Information is added to the graph as it is discovered during object

tamer/src/ld/xmle/lower.rs

@@ -184,11 +184,9 @@ impl<Ix: IndexType> std::error::Error for SortError<Ix> {
 mod test {
     use super::*;
     use crate::{
-        ir::{
-            asg::{Dim, FragmentText, IdentObject, Source},
-            legacyir::SymDtype,
-        },
+        ir::asg::{Dim, FragmentText, IdentObject, Source},
         ld::xmle::{section::PushResult, Sections},
+        obj::xmlo::SymDtype,
         sym::GlobalSymbolIntern,
     };
 

tamer/src/ld/xmle/section.rs

@@ -262,7 +262,7 @@ impl std::fmt::Display for SectionsError {
 mod test {
     use super::*;
     use crate::ir::asg::{Dim, IdentKind, IdentObject, Source};
-    use crate::ir::legacyir::SymDtype;
+    use crate::obj::xmlo::SymDtype;
     use crate::sym::GlobalSymbolIntern;
 
     type Sut<'a> = Sections<'a>;

tamer/src/ld/xmle/xir/test.rs

@@ -21,7 +21,6 @@ use super::*;
 use crate::convert::ExpectInto;
 use crate::ir::{
     asg::{Dim, IdentKind, Source},
-    legacyir::SymDtype,
     xir::{
         pred::{not, open},
         tree::{parser_from, Attr},
@@ -29,6 +28,7 @@ use crate::ir::{
 };
 use crate::ld::xmle::section::PushResult;
 use crate::ld::xmle::Sections;
+use crate::obj::xmlo::SymDtype;
 use crate::sym::{GlobalSymbolIntern, GlobalSymbolResolve};
 use std::collections::HashSet;
 

tamer/src/obj/xmlo/asg_builder.rs

@@ -17,8 +17,7 @@
 //  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`].
+//! Lower [`xmlo` IR](crate::obj::xmlo) into [`Asg`].
 //!
 //! [`AsgBuilder`] is exclusively responsible for this lowering operation
 //!   within the context of [`xmlo` object files](super).
@@ -141,7 +140,7 @@ where
     ///
     /// This is an IR lowering operation.
     /// The [`XmloResult`] produces data gleaned from
-    ///   [`legacyir`](crate::ir::legacyir),
+    ///   [`xmlo`](crate::obj::xmlo),
     ///     and this process lowers it into the IR [`asg`](crate::ir::asg).
     ///
     /// Each call to this method augments the provided [`AsgBuilderState`];
@@ -327,7 +326,7 @@ impl Error for AsgBuilderError {
 mod test {
     use super::*;
     use crate::ir::asg::{DefaultAsg, FragmentText, IdentObject};
-    use crate::ir::legacyir::{PackageAttrs, SymAttrs, SymType};
+    use crate::obj::xmlo::{PackageAttrs, SymAttrs, SymType};
     use crate::sym::GlobalSymbolIntern;
     use std::collections::hash_map::RandomState;
 

tamer/src/obj/xmlo/mod.rs

@@ -73,20 +73,11 @@
 //!   <!-- 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 legacyir;
 mod reader;
 
 pub use asg_builder::{AsgBuilder, AsgBuilderState};
+pub use legacyir::{PackageAttrs, SymAttrs, SymDtype, SymType};
 pub use reader::{XmloError, XmloEvent, XmloReader};

tamer/src/obj/xmlo/reader.rs

@@ -17,7 +17,7 @@
 //  You should have received a copy of the GNU General Public License
 //  along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-use crate::ir::legacyir::{PackageAttrs, SymAttrs};
+use super::{PackageAttrs, SymAttrs};
 use crate::sym::SymbolId;
 use crate::tpwrap::quick_xml::{Error as XmlError, InnerXmlError};
 use std::fmt::Display;

tamer/src/obj/xmlo/reader/quickxml.rs

@@ -38,9 +38,7 @@
 //! How To Use
 //! ==========
 //! The event-based API for [`XmloReader`] is similar to that of
-//!   [`quick_xml`],
-//!     except that the [`XmloResult`] produces
-//!     [Legacy IR](crate::ir::legacyir).
+//!   [`quick_xml`].
 //! There is minor overhead incurred from parsing if the emitted events are
 //!   not used,
 //!     but it is quite minimal.
@@ -49,8 +47,8 @@
 //! _You should stop reading at [`XmloEvent::Eoh`];_
 //!   reading the remainder of the object file has not yet been implemented.
 
+use super::super::{PackageAttrs, SymAttrs, SymType};
 use super::{XmloError, XmloEvent, XmloResult};
-use crate::ir::legacyir::{PackageAttrs, SymAttrs, SymType};
 use crate::sym::{GlobalSymbolInternUnchecked, GlobalSymbolResolve, SymbolId};
 #[cfg(test)]
 use crate::test::quick_xml::MockBytesStart as BytesStart;

tamer/src/obj/xmlo/reader/quickxml/test.rs

@@ -19,7 +19,7 @@
 
 use super::super::{InnerXmlError, XmlError};
 use super::*;
-use crate::ir::legacyir::{SymDtype, SymType};
+use crate::obj::xmlo::{SymDtype, SymType};
 use crate::sym::GlobalSymbolIntern;
 use crate::test::quick_xml::*;