https://github.com/kulp/mangling

Generate safe, recognizable identifiers from byte streams
https://github.com/kulp/mangling

identifiers mangling

Last synced: 17 days ago
JSON representation

Generate safe, recognizable identifiers from byte streams

• Host: GitHub
• URL: https://github.com/kulp/mangling
• Owner: kulp
• License: mit
• Created: 2020-04-10T19:26:12.000Z (over 4 years ago)
• Default Branch: develop
• Last Pushed: 2024-08-31T17:54:05.000Z (3 months ago)
• Last Synced: 2024-10-02T08:05:31.376Z (about 1 month ago)
• Topics: identifiers, mangling
• Language: Rust
• Homepage: https://docs.rs/mangling/
• Size: 134 KB
• Stars: 0
• Watchers: 3
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# mangling

[![crates.io](https://img.shields.io/crates/v/mangling.svg)](https://crates.io/crates/mangling)

[![Rust](https://github.com/kulp/mangling/workflows/Rust/badge.svg)](https://github.com/kulp/mangling/actions?query=workflow%3ARust+branch%3Adevelop)

[![codecov](https://codecov.io/gh/kulp/mangling/branch/develop/graph/badge.svg)](https://codecov.io/gh/kulp/mangling)

[![Docs.rs](https://docs.rs/mangling/badge.svg)](https://docs.rs/mangling/)

## Purpose

This library provides for reversibly generating identifiers (hereinafter "mangled names") that are valid under C-language rules, from arbitrary byte streams, while maintaining a measure of human readability.

## Examples

[See `lib.rs` for examples](https://github.com/kulp/mangling/blob/develop/src/lib.rs#L77-L85) of strings with their manglings.

## Rationale

The functionality of `mangling` was hoisted out of a compiler that needed to translate identifiers for Java symbols (e.g. method names and signatures) into symbols valid for the generated assembly language. Although the mangling process can encode any stream of bytes into a (longer) string of ASCII characters, and then convert the output back again, it is not intended to provide general encoding/decoding facilities. Instead, it is meant to provide an easy, reliable way for compiler writers to generate human-recognizable identifiers without having to invent their own mangling scheme.

## Features

### Schemes

At present, only one mangling scheme is supported, with a fixed format defined in the library documentation. The mangling scheme is simple, and may not be original, but is not known to be shared with any other system, so no interoperability guarantees are provided. Future revisions may change the API to allow some level of configurability or replacement of the encoding scheme.

### Requirements

1. Totality (every byte stream can be encoded into a unique mangled name)

1. Injectivity (each mangled name can be decoded to a unique byte stream)

#### Minimum Supported Rust Version

The minimum supported Rust version is documented in `Cargo.toml` via the `rust-version` key. The MSRV for `mangling` may change at any time, but usually for good reasons.

### Goals

1. Correctness (the implementation matches its documented behavior)

1. Consistency (the implementation behaves in a predictable manner)

1. Readability (mangled names are visibly related to input streams)

1. Compactness (mangled names are comparable in length to inputs)

1. Performance (processing is computationally efficient in time and space)

## Feedback

Any demonstrated failure of `mangling` to meet its stated requirements should be reported through Github, and pull requests are welcomed.