demangle 0.3.0__py3-none-any.whl

demangle/schemes/rust/nodes.py

@@ -0,0 +1,194 @@
+"""The Rust symbol tree.
+
+Rust's spelling has no declarator syntax at all. A C++ type wraps the name it declares
+-- `int (*)(char)` -- which is why `core/spelling.py` carries a left/right pair and why
+MSVC needs a renderer of its own. Rust writes `&mut [u8; 4]` strictly left to right, and
+a path is just its components joined by `::`. So the structure worth recovering here is
+not a declarator shape: it is *which part of the name is which* -- the crate, the module
+path, the generic arguments, the trait an impl is for, the closure disambiguator.
+
+Every node holds `parts`: a tuple of plain strings and child nodes, in output order.
+Rendering concatenates them. That is deliberate and is the whole correctness argument
+for this module -- the printer in `_v0.py` emits one linear stream of fragments whether
+it is building text or a tree, so a tree's rendering cannot drift from the text path.
+It is not that the two are tested to agree; there is only one stream, and the tree is
+that stream with the boundaries remembered.
+
+Kinds are shared with the other schemes where they mean the same thing, so a tool can
+ask any tree for its `name` or `template` nodes without knowing which language produced
+it. `impl` and `namespace` are Rust's own: nothing in the C-family schemes means either.
+"""
+
+from ...core.ast import Node, rendered
+
+__all__ = [
+    "Generics",
+    "Impl",
+    "Namespace",
+    "Path",
+    "RustName",
+    "Symbol",
+    "Type",
+    "Value",
+    "render",
+]
+
+
+def render(part):
+    """Text for a part, which is either a plain fragment or a subtree."""
+    return part if isinstance(part, str) else part.render()
+
+
+class _Rust(Node):
+    """A node whose spelling is the fragments it was built from, in order.
+
+    `build()` hands a foreign builder finished text. Re-emitting the shape through the
+    shared builder would spell Rust's `&mut T` as C++'s `T&`, and a demangler that
+    answers two different things for one symbol is worse than one that answers text.
+    Inspecting the tree is unaffected -- that is what the structure is for.
+    """
+
+    __slots__ = ("parts",)
+
+    def __init__(self, parts):
+        self.parts = tuple(parts)
+        total = 0
+        for part in self.parts:
+            total += len(part) if isinstance(part, str) else part.size
+        self.size = total
+
+    def children(self):
+        return tuple(p for p in self.parts if isinstance(p, Node))
+
+    def render(self):
+        return "".join(render(p) for p in self.parts)
+
+    def spell(self, declarator="", style=None):
+        # `declarator` and `style` are accepted to match `Node.spell` and ignored. Rust
+        # has no declarator position to place one in, and the output styles exist only
+        # where llvm-cxxfilt and GNU c++filt disagree about C++.
+        return rendered(self.render)
+
+    def build(self, builder):
+        return builder.raw(self.render())
+
+    @property
+    def text(self):
+        """The rendered text, so a caller can read a node without spelling a whole tree."""
+        return self.render()
+
+
+class RustName(_Rust):
+    """A single identifier: a crate name, a module, a function, a field.
+
+    Named `RustName` rather than `Name` because `core.ast.Name` already exists and means
+    the same thing to a consumer -- hence the shared `kind` -- but spells itself through
+    the shared builder, which is not this scheme's speller.
+    """
+
+    __slots__ = ()
+    kind = "name"
+
+
+class Path(_Rust):
+    """A path: `std::collections::HashMap`, or a crate root on its own."""
+
+    __slots__ = ()
+    kind = "path"
+
+
+class Namespace(_Rust):
+    """A compiler-generated path component: `{closure#0}`, `{shim:vtable#0}`.
+
+    `tag` is the namespace letter from the mangling -- `C` for a closure, `S` for a
+    shim, or a vendor's own -- and `disambiguator` separates several in one scope.
+    """
+
+    __slots__ = ("disambiguator", "tag")
+    kind = "namespace"
+
+    def __init__(self, parts, tag, disambiguator):
+        super().__init__(parts)
+        self.tag = tag
+        self.disambiguator = disambiguator
+
+
+class Impl(_Rust):
+    """An inherent or trait impl: `<Foo>`, `<Foo as Bar>`.
+
+    `trait` is the trait's subtree for a trait impl and None for an inherent one, so a
+    caller can ask what a method implements without matching on rendered text.
+    """
+
+    __slots__ = ("self_type", "trait")
+    kind = "impl"
+
+    def __init__(self, parts, self_type, trait):
+        super().__init__(parts)
+        self.self_type = self_type
+        self.trait = trait
+
+
+class Generics(_Rust):
+    """A generic argument application, `Vec<u8>` or `Foo::<T>`.
+
+    `base` is what is being applied to and `arguments` are the arguments themselves,
+    both also present in `parts` -- the fields name them, `parts` orders them.
+    """
+
+    __slots__ = ("arguments", "base")
+    kind = "template"
+
+    def __init__(self, parts, base, arguments):
+        super().__init__(parts)
+        self.base = base
+        self.arguments = tuple(arguments)
+
+
+class Type(_Rust):
+    """A type. `form` says which shape: `reference`, `pointer`, `array`, `slice`,
+    `tuple`, `dyn`, `fn`, `basic`, `path`.
+
+    One class rather than nine because nothing walks these structurally -- a caller
+    asking "is this a reference" wants a field to test, and `kind` stays `type` so the
+    common query finds every one of them.
+    """
+
+    __slots__ = ("form",)
+    kind = "type"
+
+    def __init__(self, parts, form):
+        super().__init__(parts)
+        self.form = form
+
+
+class Value(_Rust):
+    """A const generic argument: an integer, a `bool`, a `char`, a structural const."""
+
+    __slots__ = ("form",)
+    kind = "literal"
+
+    def __init__(self, parts, form):
+        super().__init__(parts)
+        self.form = form
+
+
+class Symbol(_Rust):
+    """A whole Rust symbol.
+
+    `hash` is the value of the legacy scheme's trailing `17h<16 hex>` component -- the
+    sixteen digits, without the `h` marker or the length prefix. The mangling carries it
+    and the spelling drops it; it is recorded because it is the only thing telling two
+    monomorphisations of one generic function apart. `suffix` is whatever followed
+    the mangled name -- an LLVM `.llvm.<hash>` from the internaliser, a `.0` from a
+    promoted constant.
+    """
+
+    __slots__ = ("hash", "suffix", "vendor")
+    kind = "symbol"
+
+    def __init__(self, parts, hash=None, suffix="", vendor=""):
+        super().__init__(parts)
+        self.hash = hash
+        self.suffix = suffix
+        self.vendor = vendor

demangle/schemes/rust/options.py

@@ -0,0 +1,36 @@
+"""Whether to spell the hash rustc writes into a symbol to keep it unique.
+
+Both Rust manglings carry one and neither spells it by default, because it is noise to a
+reader: `core::fmt::write` says what the function is and
+`core::fmt::write::h05af221e174051e9` says the same thing with a machine's bookkeeping
+after it. But it is the *only* thing telling two monomorphisations of one generic
+function apart, so a caller symbolising a profile or diffing two builds needs it.
+
+This is rustc-demangle's own choice, spelled as a formatting flag rather than an option:
+`{}` on its `Demangle` prints the hash and `{:#}` suppresses it. `rustfilt` prints the
+suppressed form, and so does this by default. What the flag reaches differs between the
+two manglings, which is why it is one option and not two:
+
+* legacy appends the path's trailing `17h<16 hex>` component -- `a::f::h05af221e174051e9`;
+* v0 prints the crate's *disambiguator* wherever a crate root is spelled --
+  `features[9f05e0465351d495]::apply_hrtb`, at every occurrence rather than the first.
+"""
+
+from dataclasses import dataclass
+
+__all__ = ["DEFAULT_OPTIONS", "RustOptions"]
+
+
+@dataclass(frozen=True, slots=True)
+class RustOptions:
+    """How much of a Rust name to spell."""
+
+    keep_hash: bool = False
+    """Spell the disambiguating hash rather than dropping it.
+
+    Off by default, which is what `rustfilt` and every corpus here is scored against.
+    """
+
+
+#: What the shipped styles use.
+DEFAULT_OPTIONS = RustOptions()

demangle/schemes/swift/__init__.py

@@ -0,0 +1,247 @@
+"""Swift mangled names.
+
+A port of the Swift compiler's own demangler -- `lib/Demangling/Demangler.cpp` and
+`lib/Demangling/NodePrinter.cpp` -- because nothing smaller is enough. Swift's mangling
+is postfix and compresses aggressively against three tables that span a whole name, so a
+symbol cannot be read a piece at a time, and how a piece is *spelled* depends on where it
+sits in the tree. `_demangler.py` and `_printer.py` are those two files; `nodes.py`
+records the structure of the printer's traversal.
+
+Conformance is exact against `swift-demangle` from the 5.10.1 toolchain:
+
+* every `$s` symbol in the shipped Swift runtime and Foundation -- 48,368 of them --
+  spelled identically, with nothing refused;
+* all 376 cases in the compiler's own `test/Demangle/Inputs/manglings.txt`, which is a
+  much harder set: SIL function types, function-signature specialisations, key paths,
+  autodiff thunks, macro expansions, and the Swift 3 mangling.
+
+The Swift 3 mangling -- `_T` followed by anything but `0` -- is a different grammar with
+its own demangler in the compiler, and `_old_demangler.py` is a port of that one. It
+still matters: the ObjC runtime holds a Swift class's name in that form, so it turns up
+in any Apple binary with interop in it. It builds the same tree, so the printer spells it
+with no idea which mangling it came from, and all 247 of the compiler's own Swift 3 test
+cases come out exactly.
+"""
+
+from ...core.ast import Node
+from ...core.errors import LimitExceeded, NotMangledError, ParseError
+from ...core.limits import DEFAULT_LIMITS
+from ...core.plugin import LanguagePlugin
+from ...core.registry import register
+from . import nodes
+from ._demangler import MANGLING_PREFIXES, async_main_entry_point_length, demangle_symbol, demangle_type
+from ._old_demangler import demangle_old_symbol
+from ._printer import print_root
+from .options import DEFAULT_OPTIONS, SIMPLIFIED_OPTIONS, SwiftOptions
+from .resolve import ContextResolver, Image, elf_image, macho_image
+from .symbolic import SymbolicReference, end_of_name, scan
+
+#: What each builder class answered to `_wants_structure`, asked once per class.
+_STRUCTURED = {}
+
+
+def detect(name):
+    """One of the prefixes either mangling uses.
+
+    `_T` covers Swift 3 as well as `_T0`; the two are different grammars and
+    `demangle_symbol` dispatches between them, but from the outside they are one scheme.
+    """
+    if not name:
+        return False
+    if name.startswith("__"):
+        # The Mach-O form: one underscore more than the compiler wrote, which
+        # `swift-demangle` takes off before reading. `__$s` is `_$s`, itself a prefix.
+        name = name[1:]
+    if async_main_entry_point_length(name):
+        # `async_Main`, the one Swift symbol with no prefix: the entry point of an
+        # `async` `@main`, which the reference's `isSwiftSymbol` claims by name.
+        return True
+    return name.startswith(MANGLING_PREFIXES) or name.startswith("_T")
+
+
+def _wants_structure(builder):
+    cls = type(builder)
+    answer = _STRUCTURED.get(cls)
+    if answer is None:
+        answer = _STRUCTURED[cls] = isinstance(builder.raw(""), Node)
+    return answer
+
+
+def parse(mangled, builder, limits=DEFAULT_LIMITS, options=DEFAULT_OPTIONS):
+    """Parse a Swift mangled name into `builder`."""
+    if not mangled:
+        raise NotMangledError(mangled, "empty name")
+    if not detect(mangled):
+        raise NotMangledError(mangled, "not a Swift mangled name")
+    if len(mangled) > limits.max_input:
+        raise LimitExceeded(mangled, "input length", limits.max_input)
+
+    # A Mach-O symbol table carries one more leading underscore than the compiler
+    # wrote, so `__T04demo5PointVMn`, `__$s...` and `__TtC...` are `_T0...`, `_$s...`
+    # and `_TtC...` -- and `swift-demangle` strips exactly one underscore from a name
+    # that opens with two before reading it. `_$s` needs no such help: the compiler's
+    # own prefix for a Mach-O symbol is listed as a prefix in its own right.
+    name = mangled[1:] if mangled.startswith("__") else mangled
+    try:
+        root = demangle_symbol(name)
+    except RecursionError as error:
+        raise LimitExceeded(mangled, "recursion depth", limits.max_depth) from error
+    return _finish(mangled, root, builder, limits, options)
+
+
+def parse_type(mangled, builder, limits=DEFAULT_LIMITS, options=DEFAULT_OPTIONS):
+    """Parse a Swift *type* mangling -- `Si`, `SaySiG` -- rather than a whole symbol.
+
+    `Demangler::demangleType` rather than `demangleSymbol`, and what a metadata typeref
+    holds: a type mangling carries none of the `$s` a symbol opens with, so nothing about
+    it says it is Swift, and it is only readable because the caller said so.
+
+    A type mangling that reads as nothing is refused rather than spelled. The reference
+    hands back the whole input wrapped in a `Suffix` node when nothing at all parsed,
+    which prints as `with unmangled suffix "..."` -- true, but not a demangling of
+    anything, so it comes back here as the `ParseError` it is.
+    """
+    if not mangled:
+        raise NotMangledError(mangled, "empty type")
+    if len(mangled) > limits.max_input:
+        raise LimitExceeded(mangled, "input length", limits.max_input)
+    try:
+        root = demangle_type(mangled)
+    except RecursionError as error:
+        raise LimitExceeded(mangled, "recursion depth", limits.max_depth) from error
+    if root is not None and root.kind == "Suffix":
+        raise ParseError(mangled, None, "not a type this reads")
+    return _finish(mangled, root, builder, limits, options)
+
+
+def _finish(mangled, root, builder, limits, options=DEFAULT_OPTIONS):
+    """Turn a reference-demangler root into what `builder` collects, or refuse it."""
+    if root is None:
+        raise ParseError(mangled, None, "not a name this reads")
+    options = options or DEFAULT_OPTIONS
+
+    if _wants_structure(builder):
+        tree = nodes.build(root, options)
+        if tree is None:
+            raise ParseError(mangled, None, "not a name this reads")
+        if tree.size > limits.max_output:
+            raise LimitExceeded(mangled, "output length", limits.max_output)
+        return tree
+
+    text = print_root(root, options)
+    if not text:
+        raise ParseError(mangled, None, "not a name this reads")
+    if len(text) > limits.max_output:
+        raise LimitExceeded(mangled, "output length", limits.max_output)
+    return builder.raw(text)
+
+
+PLUGIN = LanguagePlugin(
+    name="swift",
+    node_kinds=(
+        "extension",
+        "function",
+        "generics",
+        "module",
+        "name",
+        "symbol",
+        "template",
+        "type",
+        "variable",
+    ),
+    detect=detect,
+    parse=parse,
+    parse_type=parse_type,
+    description="Swift symbol mangling",
+    options_type=SwiftOptions,
+    aliases=(),
+    # `priority` is ascending: *lower is offered first*. After D, before Rust. `$s` and
+    # `_T0` collide with nothing; `_$S` collides with Free Pascal, which is offered
+    # earlier and wins those.
+    # `$s`, `_$s`, `$S`, `_$S`, `_T0`, `_Tt` and `@__swiftmacro_` -- and `async_Main`,
+    # the entry point of an `async` `@main`, which is the one Swift symbol with no
+    # prefix at all.
+    first_characters="$_@a",
+    priority=45,
+)
+
+register(PLUGIN)
+
+
+def demangle_symbolic(name, resolver=None, *, whole_symbol=None):
+    """Read a mangled name that may hold symbolic references, and spell it.
+
+    `name` is `bytes`, not `str`, because a name holding a symbolic reference is not
+    text: the reference's four-byte offset is arbitrary bytes. This is the entry a
+    metadata typeref takes, and the only one that can take it.
+
+    `resolver` is called with `(reference, offset-of-its-offset-field-within-name)` and
+    returns a *mangled fragment* naming what the reference points at, or None to decline.
+    `resolve.ContextResolver` is one, over an `Image`; a caller with a debugger or a
+    memory dump writes its own. With no resolver at all, a name holding a reference is
+    refused -- which is what the reference demangler does, and better than inventing a
+    name for something the bytes do not carry.
+
+    `whole_symbol` says whether to read the name as a whole symbol or as a type. Left
+    None it is decided by the mangling prefix, which is what tells the two apart: a
+    symbol carries `$s` or `_T`, a typeref carries nothing.
+
+    Returns the spelling, or None if the name could not be read.
+    """
+    if isinstance(name, str):
+        raise TypeError("demangle_symbolic reads bytes; a name holding a reference is not text")
+    # latin-1 maps every byte to the code point of the same value and back again, so the
+    # grammar can be read a character at a time without the bytes ever being interpreted
+    # as text. Swift spells a non-ASCII identifier in punycode, so nothing here is lost.
+    text = name.decode("latin-1")
+    if whole_symbol is None:
+        whole_symbol = detect(text)
+    try:
+        root = demangle_symbol(text, resolver) if whole_symbol else demangle_type(text, resolver)
+    except RecursionError:
+        return None
+    if root is None:
+        return None
+    if root.kind == "Suffix":
+        # `demangleType` hands back the whole input as a `Suffix` node when nothing at
+        # all parsed. That is the reference saying it could not read the name, and it
+        # comes back as None here rather than as the words `with unmangled suffix`
+        # wrapped around the bytes -- which is not a demangling of anything.
+        return None
+    spelled = print_root(root)
+    return spelled or None
+
+
+def typerefs(blob):
+    """Split a metadata blob of NUL-terminated mangled names into those names.
+
+    Not `blob.split(b"\0")`: a symbolic reference's offset is arbitrary bytes and very
+    often holds a zero, so splitting cuts names in half. See `symbolic.end_of_name`.
+    """
+    from .symbolic import names
+
+    return names(blob)
+
+
+__all__ = [
+    "DEFAULT_OPTIONS",
+    "PLUGIN",
+    "SIMPLIFIED_OPTIONS",
+    "ContextResolver",
+    "Image",
+    "SwiftOptions",
+    "SymbolicReference",
+    "demangle_old_symbol",
+    "demangle_symbol",
+    "demangle_symbolic",
+    "demangle_type",
+    "detect",
+    "elf_image",
+    "end_of_name",
+    "macho_image",
+    "parse",
+    "parse_type",
+    "print_root",
+    "scan",
+    "typerefs",
+]