demangle-mode

https://github.com/liblit/demangle-mode.git


    git clone 'git://github.com/liblit/demangle-mode.git'

★7

Demangle Mode

demangle-mode is an Emacs minor mode that automatically demangles C++ symbols. For example, in this mode:

_ZNSaIcED2Ev displays as std::allocator<char>::~allocator()
_ZTISt10ostrstream displays as typeinfo for std::ostrstream
_GLOBAL__I_abc displays as global constructors keyed to abc

How to Use

Quick Start

Install demangle-mode from the fantastic MELPA repository: , . Or save demangle-mode.el somewhere in your Emacs load-path, then use M-x load-library RET demangle-mode RET to load the package.

Now use M-x demangle-mode to toggle demangling on or off in any buffer. Turn on font-lock-mode as well: demangle-mode uses this to stay in sync as buffer contents change.

Advanced Usage

If you did not install from the MELPA repository, add (autoload 'demangle-mode "demangle-mode" nil t) to your Emacs init file to load demangle-mode whenever you start Emacs.

If you always want demangling on in certain major modes, add demangle-mode to the appropriate major-mode hook, such as:

(add-hook 'llvm-mode-hook #'demangle-mode)

File and directory variables allow selective activation. For example, -*- eval: (demangle-mode) -*- anywhere on the first line of a file will turn on demangle-mode for that file only. To activate demangling for all LLVM assembly files in a specific directory, save the following text as .dir-locals.el in that same directory:

((llvm-mode
  (eval . (demangle-mode))))

Customization

Explore the demangle-mode customization group for configurable options that affect this mode’s behavior: M-x customize-group RET demangle-mode RET. You can choose between two styles of showing mangled/demangled symbols:

show the demangled symbol (read-only) on screen, with the original mangled symbol available as a help message or tooltip; or
show the mangled symbol on screen, with the demangled symbol available as a help message or tooltip.

Customization changes the default style. A mode-specific menu allows switching between these styles per-buffer when demangle-mode is on.

Additionally, you can customize the display face (font, color, underline, etc.) used for highlighting mangled and demangled symbols. The default highlighting face uses a thin gray box or wavy gray underline, depending on the output terminal’s capabilities.

Background and Motivation

Name mangling is “a way of encoding additional information in the name of a function, structure, class or another datatype in order to pass more semantic information from the compilers to linkers.” For example, a C++ function named print taking a single int parameter might mangle to _Z5printi. A different print function taking two chars might mangle to _Z5printcc. This lets linkers and other tools distinguish the two functions.

Most programmer-facing C++ tools demangle symbols back to their human-readable forms when producing output. Sometimes, though, we must work with “raw” text containing mangled, hard-to-read symbols. For example, LLVM assembly source from the Clang C++ compiler contains many raw, mangled symbols. It can be useful to demangle these in-place to make such files easier to read and understand. demangle-mode scratches that itch.

Compatibility Notes

demangle-mode uses font-lock-mode to recognize and change the display style of mangled symbols. If you want demangle-mode on in some buffer, you should usually turn on font-lock-mode as well. If you use demangle-mode without font-lock-mode, demangling happens only when explicitly requested (e.g., via M-x font-lock-fontify-buffer).

demangle-mode sets the help-echo and display text properties on mangled symbols. This could interfere with other packages or user actions that set these properties.

demangle-mode recognizes the popular Itanium ABI mangling scheme plus a few Linux/GCC extensions. Adding other mangled forms would be easy, if needed.

Demangling uses the c++filt command. On GNU systems, this is part of binutils. If you need demangle-mode at all, you probably have binutils installed already.

Known Issues and Design Limitations

The standard search commands are unaware of demangled symbol text. If _ZNSaIcED2Ev is being displayed as std::allocator<char>::~allocator(), incremental search and related commands will find this text as a match for SaI but not for ::.

When showing the demangled version of a symbol using a boxed face, the right edge of the box is missing in Emacs 24.3 and earlier. This was a known bug; the fix appears in Emacs 24.4 and later.

The faces used for mangled and demangled symbols are identical to each other, and picked somewhat arbitrarily. I welcome suggestions for nicer ways to mark such symbols or distinguish the mangled and demangled variants.

Building atop font-lock-mode simplifies keeping demangled symbols current as buffer contents change. However, this may surprise a user who turns on demangle-mode without font-lock-mode, then sees nothing happen.

Running c++filt once per symbol is too slow. Instead, we demangle in an asynchronous background process. This boosts performance but complicates the implementation. Demangling directly within Emacs would be clean and fast. Unfortunately, I know of no pure Emacs Lisp implementation of name demangling and do not wish to create one myself. Demanglers as C libraries do exist, but Emacs offers no in-process way to call into such a library.