penmanship

A Rust library for Unicode character lookup via text patterns. Convert text aliases like "...", "alpha", "(c)" to their corresponding Unicode characters (…, α, ©).

Features

• no_std compatible: Works in embedded and bare-metal environments
• Zero runtime overhead: Uses compile-time perfect hash maps via phf
• No allocations: Returns static string references
• Feature-gated: Enable only the character categories you need
• Comprehensive: Supports punctuation, math, Greek letters, fractions, currency, symbols, HTML entities, emoji, and more
• Safe: Forbids unsafe code and maintains strict quality standards

Quick Start

Add penmanship to your Cargo.toml:

[dependencies]
penmanship = "0.1"

Basic usage:

use penmanship::lookup;

fn main() {
    // Look up Unicode characters by pattern
    if let Some((character, description)) = lookup("...") {
        println!("{} - {}", character, description);
        // Output: … - horizontal ellipsis
    }

    if let Some((character, _)) = lookup("alpha") {
        println!("{}", character);  // Output: α
    }

    if let Some((character, _)) = lookup("(c)") {
        println!("{}", character);  // Output: ©
    }

    // Unknown patterns return None
    assert_eq!(lookup("unknown"), None);
}

Supported Categories

All categories are enabled by default via the full feature. Examples:

// Punctuation
lookup("...")       // … - horizontal ellipsis
lookup("em")        // — - em dash
lookup("'l")        // ' - left single quotation mark

// Math
lookup("!=")        // ≠ - not equal to
lookup("->")        // → - rightwards arrow
lookup("infinity")  // ∞ - infinity

// Greek letters (case-sensitive)
lookup("alpha")     // α - greek small letter alpha
lookup("Alpha")     // Α - greek capital letter alpha

// Fractions
lookup("1/2")       // ½ - fraction one half

// Currency
lookup("euro")      // € - euro sign

// Symbols
lookup("(c)")       // © - copyright sign
lookup("deg")       // ° - degree sign

// Superscripts & Subscripts
lookup("^2")        // ² - superscript two
lookup("_2")        // ₂ - subscript two

// HTML entities (2200+ supported)
lookup(" ")    // (non-breaking space)
lookup("&lt;")      // < - less than

// Emoji (1800+ shortcodes)
lookup(":smile:")   // 😄 - grinning face with smiling eyes
lookup(":heart:")   // ❤️ - red heart

For a complete list of all supported patterns, see docs/mappings.md.

Feature Flags

By default, all categories are enabled via the full feature. To use only specific categories:

[dependencies]
penmanship = { version = "0.1", default-features = false, features = ["punctuation", "math", "greek"] }

Available features:

• full (default) - All categories
• punctuation - Punctuation and typography
• math - Mathematical operators and symbols
• greek - Greek letters
• fractions - Fraction characters
• currency - Currency symbols
• symbols - Miscellaneous symbols
• superscripts - Superscript characters
• subscripts - Subscript characters
• html - HTML named character references
• emoji - Emoji shortcode lookup (requires emojis crate)

Design Philosophy

• no_std compatible: No standard library required, works in embedded environments
• Compile-time: All mappings use perfect hash functions computed at compile time
• Zero allocations: All strings are static references
• Library-only: Pure library with no binary, focused on being a building block
• Feature-gated: Pay only for what you use

Development Notes

• This project uses a whitelist approach to .gitignore
• 100% test coverage maintained
• Strict linting: no unsafe code, all items documented

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

Security

For security vulnerabilities and reporting guidelines, see SECURITY.md.

Acknowledgments

• Emoji support provided by the emojis crate
• HTML entities based on the WHATWG HTML Living Standard

License

Copyright © 2025 Adam Mill

Licensed under the Apache License, Version 2.0. See LICENSE.txt for details.