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 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194
//! This crate can parse a C++ “mangled” linker symbol name into a Rust value //! describing what the name refers to: a variable, a function, a virtual table, //! etc. The description type implements `Display`, producing human-readable //! text describing the mangled name. Debuggers and profilers can use this crate //! to provide more meaningful output. //! //! C++ requires the compiler to choose names for linker symbols consistently //! across compilation units, so that two compilation units that have seen the //! same declarations can pair up definitions in one unit with references in //! another. Almost all platforms other than Microsoft Windows follow the //! [Itanium C++ ABI][itanium]'s rules for this. //! //! [itanium]: http://mentorembedded.github.io/cxx-abi/abi.html#mangling //! //! For example, suppose a C++ compilation unit has the definition: //! //! ```c++ //! namespace space { //! int foo(int x, int y) { return x+y; } //! } //! ``` //! //! The Itanium C++ ABI specifies that the linker symbol for that function must //! be named `_ZN5space3fooEii`. This crate can parse that name into a Rust //! value representing its structure. Formatting the value with `format!` or //! `to_string` would yield the string `"space::foo(int, int)"`, which is more //! meaningful to the C++ developer. #![deny(missing_docs)] #![deny(missing_debug_implementations)] #![deny(unsafe_code)] // Clippy stuff. #![allow(unknown_lints)] #![allow(inline_always)] #[macro_use] mod logging; pub mod ast; pub mod error; mod index_str; mod subs; use ast::{Demangle, Parse}; use error::{Error, Result}; use index_str::IndexStr; use std::fmt; /// A `Symbol` which owns the underlying storage for the mangled name. pub type OwnedSymbol = Symbol<Vec<u8>>; /// A `Symbol` which borrows the underlying storage for the mangled name. pub type BorrowedSymbol<'a> = Symbol<&'a [u8]>; /// A mangled symbol that has been parsed into an AST. /// /// This is generic over some storage type `T` which can be either owned or /// borrowed. See the `OwnedSymbol` and `BorrowedSymbol` type aliases. #[derive(Clone, Debug, PartialEq)] pub struct Symbol<T> { raw: T, substitutions: subs::SubstitutionTable, parsed: ast::MangledName, } impl<T> Symbol<T> where T: AsRef<[u8]> { /// Given some raw storage, parse the mangled symbol from it. /// /// ``` /// use cpp_demangle::Symbol; /// /// // First, something easy :) /// /// let mangled = b"_ZN5space3fooEibc"; /// /// let sym = Symbol::new(&mangled[..]) /// .expect("Could not parse mangled symbol!"); /// /// let demangled = format!("{}", sym); /// assert_eq!(demangled, "space::foo(int, bool, char)"); /// /// // Now let's try something a little more complicated! /// /// let mangled = /// b"__Z28JS_GetPropertyDescriptorByIdP9JSContextN2JS6HandleIP8JSObjectEENS2_I4jsidEENS1_13MutableHandleINS1_18PropertyDescriptorEEE"; /// /// let sym = Symbol::new(&mangled[..]) /// .expect("Could not parse mangled symbol!"); /// /// let demangled = format!("{}", sym); /// assert_eq!( /// demangled, /// "JS_GetPropertyDescriptorById(JSContext*, JS::Handle<JSObject*>, JS::Handle<jsid>, JS::MutableHandle<JS::PropertyDescriptor>)" /// ); /// ``` pub fn new(raw: T) -> Result<Symbol<T>> { let mut substitutions = subs::SubstitutionTable::new(); let parsed = { let input = IndexStr::new(raw.as_ref()); let (parsed, tail) = try!(ast::MangledName::parse(&mut substitutions, input)); if tail.is_empty() { parsed } else { return Err(Error::UnexpectedText.into()); } }; let symbol = Symbol { raw: raw, substitutions: substitutions, parsed: parsed, }; if cfg!(feature = "logging") { println!("Successfully parsed '{}' as AST = {:#?} substitutions = {:#?}", String::from_utf8_lossy(symbol.raw.as_ref()), symbol.parsed, symbol.substitutions); } Ok(symbol) } } impl<T> Symbol<T> { /// Parse a mangled symbol from input and return it and the trailing tail of /// bytes that come after the symbol. /// /// While `Symbol::new` will return an error if there is unexpected trailing /// bytes, `with_tail` simply returns the trailing bytes along with the /// parsed symbol. /// /// ``` /// use cpp_demangle::BorrowedSymbol; /// /// let mangled = b"_ZN5space3fooEibc and some trailing junk"; /// /// let (sym, tail) = BorrowedSymbol::with_tail(&mangled[..]) /// .expect("Could not parse mangled symbol!"); /// /// assert_eq!(tail, b" and some trailing junk"); /// /// let demangled = format!("{}", sym); /// assert_eq!(demangled, "space::foo(int, bool, char)"); /// ``` pub fn with_tail(input: &[u8]) -> Result<(BorrowedSymbol, &[u8])> { let mut substitutions = subs::SubstitutionTable::new(); let idx_str = IndexStr::new(input); let (parsed, tail) = try!(ast::MangledName::parse(&mut substitutions, idx_str)); let symbol = Symbol { raw: input, substitutions: substitutions, parsed: parsed, }; if cfg!(feature = "logging") { println!("Successfully parsed '{}' as AST = {:#?} substitutions = {:#?}", String::from_utf8_lossy(symbol.raw.as_ref()), symbol.parsed, symbol.substitutions); } Ok((symbol, tail.into())) } } impl<T> fmt::Display for Symbol<T> where T: AsRef<[u8]> { fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { let mut out = vec![]; { let mut ctx = ast::DemangleContext::new(&self.substitutions, self.raw.as_ref(), &mut out); try!(self.parsed.demangle(&mut ctx, None).map_err(|_| fmt::Error)); } write!(f, "{}", String::from_utf8_lossy(&out)) } }