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
1. With a package manager (recommended)
2. The old way
Core functions
OOP style
1. Summary
2. Example
Helper functions
Limitations
License

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

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.