@yehuthi/hebrew
Version:
Hebrew utilities
214 lines (145 loc) โข 6.51 kB
Markdown
# hebrew.js ๐
A JavaScript/TypeScript library for Hebrew text processing and manipulation. This library provides utilities for working with Hebrew diacritics (niqqud and cantillation marks / te'amim) and converting between Hebrew and Paleo-Hebrew scripts.
## โจ Features
- **๐ Diacritic Identification / Removal**: Identify or strip diacritics from Hebrew text.
- **๐ Script Conversion**: Convert Hebrew text to Paleo-Hebrew script
- **๐ TypeScript Support**: Full TypeScript definitions included
- **โก Zero Dependencies**: Lightweight with no external dependencies
- **๐ฆ Multiple Module Formats**: Supports CommonJS, ES modules, and UMD
## ๐ฆ Installation
```bash
npm install @yehuthi/hebrew
```
Or using pnpm:
```bash
pnpm add @yehuthi/hebrew
```
## ๐ Usage
### ๐ฅ Basic Import
```javascript
import * as hebrew from '@yehuthi/hebrew';
```
### ๐งน Removing Diacritics
The library can remove different types of diacritics from Hebrew text:
```javascript
// Sample Hebrew text with full diacritics
const hebrewText = "ืึผึฐืจึตืืฉืึดึืืช ืึผึธืจึธึฃื ืึฑืึนืึดึืื ืึตึฅืช ืึทืฉึผืึธืึทึืึดื ืึฐืึตึฅืช ืึธืึธึฝืจึถืฅื";
// Remove all diacritics (niqqud and cantillation)
const stripped = hebrew.remove_diacritics(hebrewText);
// Result: "ืืจืืฉืืช ืืจื ืืืืื ืืช ืืฉืืื ืืืช ืืืจืฅื"
// Remove only niqqud (vowel diacritics)
const withoutNiqqud = hebrew.remove_diacritics(hebrewText, hebrew.char_niqqud);
// Result: "ืืจืืฉึืืช ืืจึฃื ืืืึืื ืึฅืช ืืฉืึืื ืืึฅืช ืืืจืฅื"
// Remove only cantillation marks
const withoutCantillation = hebrew.remove_diacritics(hebrewText, hebrew.char_taam);
// Result: "ืึผึฐืจึตืืฉืึดืืช ืึผึธืจึธื ืึฑืึนืึดืื ืึตืช ืึทืฉึผืึธืึทืึดื ืึฐืึตืช ืึธืึธึฝืจึถืฅื"
```
### ๐บ Converting to Paleo-Hebrew
Convert modern Hebrew text to Paleo-Hebrew script:
```javascript
const modernHebrew = "ืืจืืฉืืช ืืจื ืืืืื ืืช ืืฉืืื ืืืช ืืืจืฅ";
const paleoHebrew = hebrew.to_paleo(modernHebrew);
// Result: "๐ค๐ค๐ค๐ค๐ค๐ค ๐ค๐ค๐ค ๐ค๐ค๐ค๐ค๐ค ๐ค๐ค ๐ค๐ค๐ค๐ค๐ค ๐ค
๐ค๐ค ๐ค๐ค๐ค๐ค"
```
### ๐ค Character-Level Functions
Check individual characters for diacritics:
```javascript
import * as hebrew from '@yehuthi/hebrew';
// Check if a character is a niqqud
hebrew.char_niqqud('ึธ'); // true
hebrew.char_niqqud('ื'); // false
// Check if a character is a cantillation mark
hebrew.char_taam('ึ'); // true
hebrew.char_taam('ื'); // false
// Check if a character is any type of diacritic
hebrew.char_diacritic('ึธ'); // true
hebrew.char_diacritic('ึ'); // true
hebrew.char_diacritic('ื'); // false
```
## ๐ API Reference
### ๐ง Core Functions
#### `remove_diacritics(input: string, type?: function): string`
Removes diacritics from Hebrew text.
- **Parameters:**
- `input`: The Hebrew text to process
- `type`: Optional function to determine which diacritics to remove (defaults to removing all diacritics)
- **Returns:** String with specified diacritics removed
#### `to_paleo(str: string): string`
Converts Hebrew text to Paleo-Hebrew script.
- **Parameters:**
- `str`: Hebrew text to convert
- **Returns:** Text converted to Paleo-Hebrew script
### ๐ Character Detection Functions
#### `char_niqqud(char: string): boolean`
Checks if a character is a niqqud (vowel diacritic).
#### `char_taam(char: string): boolean`
Checks if a character is a cantillation mark (ta'am).
#### `char_diacritic(char: string): boolean`
Checks if a character is any type of diacritic (niqqud or cantillation).
### ๐ข Character Code Functions
#### `char_code_is_niqqud(charCode: number): boolean`
Checks if a character code represents a niqqud.
#### `is_taam_code(charCode: number): boolean`
Checks if a character code represents a cantillation mark.
#### `is_diacritic_code(charCode: number): boolean`
Checks if a character code represents any type of diacritic.
### ๐บ Paleo-Hebrew Conversion Functions
#### `char_to_paleo(char: string): string | undefined`
Converts a single Hebrew character to Paleo-Hebrew.
#### `char_to_paleo_unchecked(char: string): string`
Converts a single Hebrew character to Paleo-Hebrew (unchecked version).
#### `char_code_to_paleo(charCode: number): number | undefined`
Converts a Hebrew character code to Paleo-Hebrew character code.
#### `char_code_to_paleo_unchecked(charCode: number): number`
Converts a Hebrew character code to Paleo-Hebrew character code (unchecked version).
## ๐ก Examples
### ๐ Processing Biblical Text
```javascript
import * as hebrew from '@yehuthi/hebrew';
// Genesis 1:1 with full diacritics
const genesis1_1 = "ืึผึฐืจึตืืฉืึดึืืช ืึผึธืจึธึฃื ืึฑืึนืึดึืื ืึตึฅืช ืึทืฉึผืึธืึทึืึดื ืึฐืึตึฅืช ืึธืึธึฝืจึถืฅื";
// Remove all diacritics for plain text
const plainText = hebrew.remove_diacritics(genesis1_1);
console.log(plainText); // "ืืจืืฉืืช ืืจื ืืืืื ืืช ืืฉืืื ืืืช ืืืจืฅื"
// Convert to Paleo-Hebrew
const paleoText = hebrew.to_paleo(plainText);
console.log(paleoText); // "๐ค๐ค๐ค๐ค๐ค๐ค ๐ค๐ค๐ค ๐ค๐ค๐ค๐ค๐ค ๐ค๐ค ๐ค๐ค๐ค๐ค๐ค ๐ค
๐ค๐ค ๐ค๐ค๐ค๐คื"
```
### ๐ Text Analysis
```javascript
import * as hebrew from '@yehuthi/hebrew';
function analyzeHebrewText(text) {
const chars = [...text];
const niqqudCount = chars.filter(hebrew.char_niqqud).length;
const taamCount = chars.filter(hebrew.char_taam).length;
const totalDiacritics = chars.filter(hebrew.char_diacritic).length;
return {
totalCharacters: chars.length,
niqqudCount,
taamCount,
totalDiacritics,
plainTextRatio: (chars.length - totalDiacritics) / chars.length
};
}
const analysis = analyzeHebrewText("ืึผึฐืจึตืืฉืึดึืืช ืึผึธืจึธึฃื ืึฑืึนืึดึืื");
console.log(analysis);
```
## ๐ ๏ธ Development
### ๐จ Building
```bash
pnpm build
```
### ๐งช Testing
```bash
pnpm test
```
### ๐ Project Structure
- `src/index.ts` - Main library code
- `src/index.test.ts` - Test suite
- `dist/` - Built distribution files (CommonJS, ES modules, UMD)
## ๐ License
MIT License - see [LICENSE](LICENSE) file for details.
## ๐ค Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## ๐ท๏ธ Keywords
Hebrew, alphabet, script, letters, phoenician, niqqud, taamim, diacritics, paleo-hebrew, text processing