add DisplayRules, docs, doc tests, ..

this includes `trait DisplayRules` as a generic mechanism to control
parts of instruction printing, a `DefaultRules` for the existing
formatting style, and `AbsoluteAddressFormatter` to print instructions
as at some location in an address space.

1 files changed, 24 insertions, 2 deletions

diff --git a/src/protected_mode/mod.rs b/src/protected_mode/mod.rs
index 6c0e674..f74592b 100644
--- a/src/protected_mode/mod.rs
+++ b/src/protected_mode/mod.rs
@@ -10,7 +10,13 @@ pub use crate::MemoryAccessSize;
 use crate::{Address, Word};
 
 #[cfg(feature = "fmt")]
-pub use self::display::{DisplayStyle, InstructionDisplayer};
+pub use self::display::{
+    DisplayStyle,
+    DisplayRules, DefaultRules,
+    InstructionDisplayer, InstructionRuleBundle
+};
+#[cfg(feature = "fmt")]
+pub use self::display::AbsoluteAddressFormatter;
 #[cfg(all(feature = "fmt", feature = "alloc"))]
 pub use self::display::InstructionTextBuffer;
 
@@ -3284,13 +3290,17 @@ impl Instruction {
     /// later. see the documentation on [`display::DisplayStyle`] for more.
     ///
     /// ```
-    /// use yaxpeax_x86::long_mode::{InstDecoder, DisplayStyle};
+    /// use yaxpeax_x86::long_mode::{InstDecoder, DisplayStyle, DefaultRules};
     ///
     /// let decoder = InstDecoder::default();
     /// let inst = decoder.decode_slice(&[0x33, 0xc1]).unwrap();
     ///
     /// assert_eq!("eax ^= ecx", inst.display_with(DisplayStyle::C).to_string());
     /// assert_eq!("xor eax, ecx", inst.display_with(DisplayStyle::Intel).to_string());
+    ///
+    /// // `display_with` is a short-hand for the default implementation of `DisplayRules`:
+    /// let formatted = format!("{}", DefaultRules::for_style(DisplayStyle::Intel).display(&inst));
+    /// assert_eq!("xor eax, ecx", formatted);
     /// ```
     pub fn display_with<'a>(&'a self, style: display::DisplayStyle) -> display::InstructionDisplayer<'a> {
         display::InstructionDisplayer {
@@ -3299,6 +3309,18 @@ impl Instruction {
         }
     }
 
+    // TODO: more docs
+    #[cfg(feature = "fmt")]
+    pub fn display_rules<'a, 'rules, Rules>(
+        &'a self,
+        rules: &'rules Rules
+    ) -> display::InstructionRuleBundle<'a, 'rules, Rules> {
+        display::InstructionRuleBundle {
+            instr: self,
+            rules,
+        }
+    }
+
     /// does this instruction include the `xacquire` hint for hardware lock elision?
     pub fn xacquire(&self) -> bool {
         if self.prefixes.repnz() {