1 files changed, 34 insertions, 10 deletions

diff --git a/src/lib.rs b/src/lib.rs
index edc0742..a0c237b 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,11 +1,14 @@
 #![no_std]
+#![doc = include_str!("../README.md")]
+
+#[cfg(feature = "alloc")]
+extern crate alloc;
 
 use core::fmt::{self, Debug, Display};
 use core::hash::Hash;
 
 #[cfg(feature="use-serde")]
 #[macro_use] extern crate serde_derive;
-
 #[cfg(feature="use-serde")]
 use serde::{Serialize, Deserialize};
 
@@ -15,19 +18,27 @@ pub use address::{AddressDisplayUsize, AddressDisplayU64, AddressDisplayU32, Add
 #[cfg(feature="address-parse")]
 pub use address::AddrParse;
 
+pub mod annotation;
+
+#[deprecated(since="0.3.0", note="yaxpeax_arch::color conflates output mechanism and styling, leaving it brittle and overly-restrictive. see `yaxpeax_arch::color_new`, which will replace `color` in a future version.")]
 mod color;
+#[allow(deprecated)] // allow exporting the deprecated items here to not break downstreams even further...
 pub use color::{Colorize, NoColors, YaxColors};
-
-#[cfg(feature="colors")]
-pub use color::ColorSettings;
+#[cfg(feature="color-new")]
+pub mod color_new;
 
 pub mod display;
+
 mod reader;
 pub use reader::{Reader, ReaderBuilder, ReadError, U8Reader, U16le, U16be, U32le, U32be, U64le, U64be};
 
+pub mod safer_unchecked;
+
+pub mod testkit;
+
 /// the minimum set of errors a `yaxpeax-arch` disassembler may produce.
 ///
-/// it is permissible for an implementor of `DecodeError` to have items that return `false` for
+/// it is permissible for an implementer of `DecodeError` to have items that return `false` for
 /// all these functions; decoders are permitted to error in way that `yaxpeax-arch` does not know
 /// about.
 pub trait DecodeError: PartialEq + Display + Debug + Send + Sync + 'static {
@@ -39,12 +50,12 @@ pub trait DecodeError: PartialEq + Display + Debug + Send + Sync + 'static {
     /// generally indicate an issue with the instruction itself. this is in contrast to one
     /// specific operand being invalid for the instruction, or some other issue to do with decoding
     /// data beyond the top-level instruction. the "opcode"/"operand" distinction is often fuzzy
-    /// and left as best-effort for decoder implementors.
+    /// and left as best-effort for decoder implementers.
     fn bad_opcode(&self) -> bool;
     /// did the decoder error because an operand of the instruction to decode is invalid?
     ///
     /// similar to [`DecodeError::bad_opcode`], this is a subjective distinction and best-effort on
-    /// the part of implementors.
+    /// the part of implementers.
     fn bad_operand(&self) -> bool;
     /// a human-friendly description of this decode error.
     fn description(&self) -> &'static str;
@@ -124,23 +135,34 @@ impl DecodeError for StandardPartialDecoderError {
     }
 }
 
+/*
+#[derive(Copy, Clone)]
+struct NoDescription {}
+
+impl fmt::Display for NoDescription {
+    fn fmt(&self, _: &mut fmt::Formatter) -> fmt::Result {
+        Ok(())
+    }
+}
+*/
+
 /// an interface to decode [`Arch::Instruction`] words from a reader of [`Arch::Word`]s. errors are
 /// the architecture-defined [`DecodeError`] implemention.
 pub trait Decoder<A: Arch + ?Sized> {
-    /// decode one instruction for this architecture from the [`yaxpeax_arch::Reader`] of this
+    /// decode one instruction for this architecture from the [`crate::Reader`] of this
     /// architecture's `Word`.
     fn decode<T: Reader<A::Address, A::Word>>(&self, words: &mut T) -> Result<A::Instruction, A::DecodeError> {
         let mut inst = A::Instruction::default();
         self.decode_into(&mut inst, words).map(|_: ()| inst)
     }
 
-    /// decode one instruction for this architecture from the [`yaxpeax_arch::Reader`] of this
+    /// decode one instruction for this architecture from the [`crate::Reader`] of this
     /// architecture's `Word`, writing into the provided `inst`.
     ///
     /// SAFETY:
     ///
     /// while `inst` MUST be left in a state that does not violate Rust's safety guarantees,
-    /// implementors are NOT obligated to leave `inst` in a semantically meaningful state if
+    /// implementers are NOT obligated to leave `inst` in a semantically meaningful state if
     /// decoding fails. if `decode_into` returns an error, callers may find contradictory and
     /// useless information in `inst`, as well as *stale data* from whatever was passed in.
     fn decode_into<T: Reader<A::Address, A::Word>>(&self, inst: &mut A::Instruction, words: &mut T) -> Result<(), A::DecodeError>;
@@ -215,6 +237,8 @@ pub trait Instruction {
     fn well_defined(&self) -> bool;
 }
 
+#[allow(deprecated)]
+#[deprecated(since="0.3.0", note="ShowContextual ties YaxColors and fmt::Write in a way that only sometimes composes. simultaneously, it is too generic on Ctx, making it difficult to implement and use. it will be revisited in the future.")]
 pub trait ShowContextual<Addr, Ctx: ?Sized, T: fmt::Write, Y: YaxColors> {
     fn contextualize(&self, colors: &Y, address: Addr, context: Option<&Ctx>, out: &mut T) -> fmt::Result;
 }