greek-conversion
v0.14.1
Published
A small library to convert a polytonic greek string from/into various representations.
Downloads
65
Maintainers
Readme
greek-conversion
This library needs some feedback before getting its first stable release!
A small, yet powerful, JavaScript library for converting both polytonic and monotonic Greek from/into many representations.
Summary
Usage
With a package manager (recommended)
In order to use this library in your project, simply type:
npm install greek-conversion
Import the library's functionalities as needed:
// ES6 modules syntax
import { KeyType, toTransliteration } from 'greek-conversion'
// CommonJS syntax
const { KeyType, toTransliteration } = require('greek-conversion')
Then use them:
// Let's transliterate some Thucydides
toTransliteration(
'Ἕλλησιν ἐγένετο καὶ μέρει τινὶ τῶν βαρβάρων, ' + // Hellēsin egeneto kai
'ὡς δὲ εἰπεῖν καὶ ἐπὶ πλεῖστον ἀνθρώπων.', // merei tini tōn barbarōn,
KeyType.GREEK, // hōs de eipein kai epi
{ removeDiacritics: true } // pleiston anthrōpōn.
)
The old way
This is primarily intended for the use of the library in the browser in the absence of a modern development environment.
You can either import the library from the unpkg CDN (https://www.unpkg.com/greek-conversion
) or download the latest release on Github then include greekConversion.min.js
into your project (but you could experience a CORS issue in this case and need to use a local server to run your project).
As the library is built as a module, the <script>
tag needs to be set as type="module"
(which is supported by all modern browsers).
You can then call the library's functions as exemplified below:
<script type="module">
import { KeyType, toGreek } from 'https://www.unpkg.com/greek-conversion' // or './greekConversion.min.js'
console.log(toGreek('anthrōpos', KeyType.TRANSLITERATION)) // ανθρωπος
</script>
Core functions
Summary
This library provides three main functions to convert a greek string: toBetaCode
, toGreek
& toTransliteration
. You can refer to the conversion chart for further information about the expected input & output.
Functions signature is consistently:
str: string,
fromType: KeyType,
settings: Preset | MixedPreset | IConversionOptions = {}
fromType
can be set to BETA_CODE | TLG_BETA_CODE | GREEK | TRANSLITERATION
(e.g. KeyType.GREEK
).
settings
can be filled with:
- a
Preset
; - a user-defined
IConversionOptions
object; - a preset mixed with user-defined conversion options (
[Preset, IConversionOptions]
).
Conversion presets
The available presets are:
- For beta code:
| Preset | Description |
| ------ | ----------- |
| SIMPLE_BC
| A simplified beta code style for faster writing |
| TLG
| Thesaurus Linguae Graecae |
- For transliteration:
| Preset | Description | Scope |
| ------ | ----------- | ----- |
| ALA_LC
| American Library Association – Library of Congress | Ancient and Medieval Greek (before 1454) |
| ALA_LC_MODERN
| Alternative form of the preceding | Modern Greek (after 1453) |
| BNF_ADAPTED
| Bibliothèque nationale de France (adapted) | Ancient Greek |
| ISO
| ISO 843 (1997) type 1 (transliteration) | Ancient and Modern Greek |
| SBL
| Society of Biblical Literature | Ancient Greek |
Conversion options
The IConversionOptions
interface provides the following controls over the conversion process:
removeDiacritics?: boolean, // remove diacritics, except those that represent letters
removeExtraWhitespace?: boolean, // remove potential extra whitespace
betaCodeStyle?: {
skipSanitization?: boolean, // prevent the deletion of non-beta code characters
useTLGStyle?: boolean // use the Thesaurus Linguae Graecae style. e.g. 'Ἄϊδι' → '*)/AI+DI'
},
greekStyle?: {
useBetaVariant?: boolean, // use the typographic variant 'ϐ' [U+03D0] within a word
useGreekQuestionMark?: boolean, // use greek question marks ';' [U+037E] rather than regular semicolons
useLunateSigma?: boolean, // use lunate sigmas 'ϲ, Ϲ' rather than regular sigmas
useMonotonicOrthography?: boolean // only output monotonic accents (tonos, diaeresis)
},
transliterationStyle?: {
setCoronisStyle?: Coronis, // set Coronis enum to PSILI | APOSTOPHE | NO (defaults to: PSILI)
useCxOverMacron?: boolean, // use a circumflex rather than a macron for eta, omega, etc
beta_v?: boolean, // transliterate 'β' as 'v' (defaults to: 'b')
gammaNasal_n?: boolean, // transliterate 'γ' as 'n' when nasalization occurs
eta_i?: boolean, // transliterate 'η' as 'ī' (defaults to: 'ē')
muPi_b?: boolean, // transliterate 'μπ' as 'b' at the beginning of a word
nuTau_d?: boolean, // transliterate 'ντ' as 'd̲' at the beginning of a word
xi_ks?: boolean, // transliterate 'ξ' as 'ks' (defaults to: 'x')
rho_rh?: boolean, // transliterate 'ρ' as 'rh' even if it doesn't have a rough breathing
phi_f?: boolean, // transliterate 'φ' as 'f' (defaults to: 'ph')
chi_kh?: boolean, // transliterate 'χ' as 'kh' (defaults to: 'ch')
upsilon_y?: boolean, // transliterate 'υ' as 'y' (defaults to: 'u')
lunatesigma_s?: boolean // transliterate 'ϲ' [U+03F2] as 's' (defaults to: 'c')
},
additionalChars?: // extend the default mapping with additional chars
AdditionalChar[] | AdditionalChar // (use AdditionalChar.ALL to enable the whole set)
A more detailed description of these conversion options is available on this page.
Examples
Basic examples
toBetaCode('ανθρωπος', KeyType.GREEK) // anqrwpos
toGreek('A)/i+da', KeyType.BETA_CODE) // Ἄϊδα
toGreek('*)/AI+DA', KeyType.TLG_BETA_CODE) // Ἄϊδα
toTransliteration('ἄϋλος', KeyType.GREEK, { removeDiacritics: true }) // aulos
Using presets
toTransliteration('Φίληβος ἢ Περὶ ἡδονῆς', KeyType.GREEK, Preset.ISO) // Fílīvos ī̀ Perì hīdonī̃s
toTransliteration('Φίληβος ἢ Περὶ ἡδονῆς', KeyType.GREEK, Preset.ALA_LC) // Philēbos ē Peri hēdonēs
Using a mixed preset
toTransliteration('Φίληβος ἢ Περὶ ἡδονῆς', KeyType.GREEK, [
Preset.ALA_LC,
{ removeDiacritics: false }
]) // Phílēbos ḕ Perì hēdonē̃s
Using customized greek
const style = {
greekStyle: {
useLunateSigma: true
}
}
toGreek('ICHTHUS ZŌNTŌN', KeyType.TRANSLITERATION) // ἸΧΘΥΣ ΖΩΝΤΩΝ
toGreek('ICHTHUS ZŌNTŌN', KeyType.TRANSLITERATION, style) // ἸΧΘΥϹ ΖΩΝΤΩΝ
Using customized transliteration
const style = {
transliterationStyle: {
useCxOverMacron: true,
chi_kh: true
}
}
toTransliteration('τέχνη', KeyType.GREEK) // téchnē
toTransliteration('τέχνη', KeyType.GREEK, style) // tékhnê
Self-conversion (reflect settings)
toBetaCode('O(pli/ths', KeyType.BETA_CODE, Preset.TLG) // *(OPLI/THS
toBetaCode('*(OPLI/THS', KeyType.TLG_BETA_CODE) // O(pli/ths
const grStyle = { greekStyle: { useLunateSigma: true } }
toGreek('ἅγιος', KeyType.GREEK, grStyle) // ἅγιοϲ
const trStyle = { transliterationStyle: { lunatesigma_s: true } }
toTransliteration('Cōkrátēc', KeyType.TRANSLITERATION, trStyle) // Sōkrátēs
OOP style
Summary
You can use the GreekString
object if you want to manage several representations of a greek string. Conversions are made only as necessary.
GreekString
constructor is:
str: string,
fromType: KeyType,
settings?: Preset | MixedPreset | IConversionOptions
You can access each representation by calling the following properties: betaCode
, greek
& transliteration
.
Note that settings
is also applied to the input string in order to have truly equivalent representations. You can retrieve the original string using the source
property.
Example
import { GreekString, KeyType } from 'greek-conversion'
const person = new GreekString(
'ἄνθρωπος',
KeyType.GREEK,
{ removeDiacritics: true }
)
person.betaCode // anqrwpos
person.greek // ανθρωπος
person.transliteration // anthrōpos
person.source // ἄνθρωπος
Helper functions
applyGreekVariants (greekStr: string, options?: IGreekStyle): string
Applies beta/sigma variants and transforms πσ
into ψ
.
This function evaluates booleans useBetaVariant
& useLunateSigma
provided by the IGreekStyle
interface.
removeDiacritics (str: string, type: KeyType): string
Removes all the diacritics from a given string. The set of diacritical marks depends of the greek string representation.
removeGreekVariants (greekStr: string, removeLunateSigma?: boolean): string
Removes beta and sigma variants.
Limitations
This is what you should know before using this library:
- Greek numerals are not supported yet (see Add support for greek numerals).
License
Copyright (C) 2021, 2022, 2023, 2024 Antoine Boquet
This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
You should have received a copy of the GNU Affero General Public License along with this program. If not, see https://www.gnu.org/licenses/agpl-3.0.fr.html.