penmanship 0.1.0

A Unicode character lookup library for converting text patterns to Unicode characters
Documentation 
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

# penmanship

[![Crates.io](https://img.shields.io/crates/v/penmanship.svg)](https://crates.io/crates/penmanship)
[![Documentation](https://docs.rs/penmanship/badge.svg)](https://docs.rs/penmanship)
[![Downloads](https://img.shields.io/crates/d/penmanship.svg)](https://crates.io/crates/penmanship)
[![License](https://img.shields.io/crates/l/penmanship.svg)](https://github.com/theroyalwhee0/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`:

```toml
[dependencies]
penmanship = "0.1"
```

Basic usage:

```rust
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:

```rust
// 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](docs/mappings.md).

## Feature Flags

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

```toml
[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](CONTRIBUTING.md) for guidelines.

## Security

For security vulnerabilities and reporting guidelines, see [SECURITY.md](SECURITY.md).

## Acknowledgments

- Emoji support provided by the [`emojis`](https://crates.io/crates/emojis) crate
- HTML entities based on the [WHATWG HTML Living Standard](https://html.spec.whatwg.org/entities.json)

## License

Copyright © 2025 Adam Mill

Licensed under the Apache License, Version 2.0. See [LICENSE.txt](LICENSE.txt) for details.