Lietuviškojo skiemenuoklio API

API_LY.LT.h – programinė sąsaja (API) lietuviškų žodžių skiemenavimo dinaminėms bibliotekoms (DLL) „Windows“ terpei. Pateikiamos 32 ir 64 bitų šių bibliotekų (HYAPILT.dll) versijos. Greta jų pridedamas ir papildomas skiemenavimo išimčių žodynas.
Šiame pakete pateikiama API versija 1.0.0.1

Pastaba: skiemenavimui sukurtas atskira API tam, kad nekiltų galimų autorinių konfliktų su „Microsoft“ CSAPI sąsaja.

Šį API sudaro įvairios duomenų struktūros ir su jomis dirbančios 4-ios funkcijos: HyLT_Open, HyLT_Options, HyLT_Perform ir HyLT_Close.

Pirmiausia turi būti įvykdoma HyLT_Open, inicializuojanti skiemenavimo aplinką. Jei reikia, tada galima kviesti HyLT_Options, leidžiančia nustatyti įvairius skiemenavimo režimus; jei ji nekviečiama, naudojamos nutylimosios režimų reikšmės. HyLT_Perform atlieka vieno žodžio skiemenavimą. Kai visi žodžiai suskiemenuoti, būtina iškviesti HyLT_Close funkciją, atlaisvinanč ią resursus. Į paketą įtrauktas demonstracinis pradinis kodas C++ kalba, pailiustruojantis šių funkcijų naudojimą.

API funkcijos

HyLT_Open – skiemenavimo inicializavimas

Aprašymas:
int WINAPI HyLT_Open(LPWSTR plthyID, long *plthyMajor, long *plthyMinor, LPCWSTR plthyDicFile

Jos parametrai:
plthyID – nuoroda į simbolių masyvą, į kurį gražinama skiemenuokio identifikatorius;
plthyMajor – nuoroda į ilgo sveikojo skaičiaus (long) kintamąjį, į kurį gražinama skiemenavimo komponentės pagrindinės versijos (major) reikšmė (pvz., jei versija 3.5, tai plthyMajor įgaus reikšmę 3);
plthyMinor - nuoroda į ilgo sveikojo skaičiaus (long) kintamąjį, į kurį gražinama skiemenavimo komponentės patikslintos versijos (minor) reikšmė (pvz., jei versija 3.5, tai plthyMinor įgaus reikšmę 5);
plthyDicFile – nuoroda į teksto eilutę, aprašančią skiemenavimo išimčių failo vardą. Šis tekstinis failas nurodo skiemenavimo taisykles tiems žodžiams, kuriems nebus taikomas pagrindinis skiemenavimo algoritmas.
Su paketu pateikiamas ir pradinis išimčių žodynas. Jei žodynas nenaudojamas, nurodoma NULL parametro reikšmė.

Funkcija gražina sveiką skaičių, nurodantį ar įvykdyta sėkmingai (reikšmė HyLT_NoErrors). Klaidos atveju reikšmė HyLT_Error.

HyLT_Options – skiemenavimo režimų nustatymas

Aprašymas: int WINAPI HyLT_Options(long plthySessionID, HyLT_OptionAction phyltAction,
        HyLT_OPTIONS *plthyOptions, const HyLT_DECODINGTABLES *plthyDecoding);

Jos parametrai:
plthySessionID - ilgas sveikasis skaičius (long) nurodantis skiemenavimo sesiją. Jis turi būti toks pat, kaip naudojamas kitose funkcijose;
phyltAction – operacijos veiksmas. Galimos reikšmės:
      HyLT_SetOptions – nustatyti režimus;>BR>       HyLT_GetOptions – gauti režimų reikšmes.
plthyOptions – nuoroda į HyLT_OPTIONS struktūrą, kuri naudojama nustatyti ar gauti režimo reikšmes. Struktūros aprašas pateikiamas atskirai;
plthyDecoding – nuododa į HyLT_DECODINGTABLES struktūrą, nurodančią naudojamą lietuviškų raidžių kodavimą. Nutylimasis kodavimas yra Windows-1257.
Jei nebūtina keisti kodavimo, nurodoma NULL parametro reikšmė.
Pastaba: šis režimas nėra realizuotas šioje versijoje ir numatytas ateities išplėtimams.

Funkcija gražina sveiką skaičių, nurodantį ar įvykdyta sėkmingai (reikšmė HyLT_NoErrors). Klaidos atveju reikšmė HyLT_Error.

HyLT_Perform – vieno žodžio skiemenavimas

Aprašymas:
int WINAPI HyLT_Perform(long plthySessionID, LPCWSTR phyltWord, HyLT_Output *phyltOutput)

Jos parametrai:
plthySessionID - ilgas sveikasis skaičius (long) nurodantis skiemenavimo sesiją. Jis turi būti toks pat, kaip naudojamas kitose funkcijose;
phyltWord – nuoroda į skiemenuojamą žodį (simbolių eilutę);
phyltOutput – nuoroda į HyLT_Output struktūrą, pateikiančią informaciją apie skiemenavimo rezultatą. Struktūros aprašas pateikiamas atskirai.

Funkcija gražina sveiką skaičių, nurodantį ar įvykdyta sėkmingai (reikšmė HyLT_NoErrors). Klaidos atveju reikšmė HyLT_Error.

HyLT_Close – skiemenavimo užbaigimas

Aprašymas:
int WINAPI HyLT_Close(long plthySessionID);

Jos parametrai:
plthySessionID - ilgas sveikasis skaičius (long) nurodantis skiemenavimo sesiją. Jis turi būti toks pat, kaip naudotas kitose funkcijose.

Funkcija gražina sveiką skaičių, nurodantį ar įvykdyta sėkmingai (reikšmė HyLT_NoErrors). Klaidos atveju reikšmė HyLT_Error.

Naudojamų duomenų struktūrų aprašymai

HyLT_OPTIONS

HyLT_OPTIONS struktūra aprašo skiemenavimo parametrus. Jos elementai:
HyLT_KeepLeft – nurodo neskiemenuojamos žodžio pradžios ilgį. Nutylimoji reikšmė 0 (t.y. žodis skiemenuojamas nuo pačios pradžios).
Pavyzdžiai:
Jei HyLT_KeepLeft=2, žodis „parašiutas“ skiemenuojamas taip: „pa-ra-šiu-tas“.
Jei HyLT_KeepLeft=3, žodis „parašiutas“ skiemenuojamas taip: „para-šiu-tas“.
HyLT_KeepRight – nurodo neskiemenuojamos žodžio galo ilgį. Nutylimoji reikšmė 0 (t.y. žodis skiemenuojamas iki pačios pabaigos).
Jei HyLT_KeepRight=3, žodis „parašiutas“ skiemenuojamas taip: „pa-ra-šiu-tas“.
Jei HyLT_KeepRight=5, žodis „parašiutas“ skiemenuojamas taip: „pa-ra-šiutas“.
HyLT_minLength – minimalus skiemenuojamo žodžio ilgis. Nutylimoji reikšmė 0. kuri nurodo, kad skiemenuojamos bet kokio ilgio žodis.
Jei HyLT_minLength=5, žodis „labas“ neskiemenuojamas (lieka „labas“).
Tuo tarpu žodis „lydeka“ skiemenuojamas („ly-de-ka“).
HyLT_acceptQWX – nurodo, ar reikia skiemenuoti žodžius, turinčius q, x arba w raidžių. Nutylimojo reikšmė yra TRUE.
Jei HyLT_acceptQWX=TRUE, tai žodis „seqvision“ suskiemenuojamas taip: „seq-vi-sion“.
Jei HyLT_acceptQWX=FALSE, tai žodis „seqvision“ nėra skiemenuojamas (lieka „seqvision“).

HyLT_Output

HyLT_Output struktūra saugo žodžio skiemenavimo rezultatą. Jos elementai: HyLT_Length – suskiemenuoto žodžio ilgis;
HyLT_HyphenPlaces – nuoroda į masyvą, nurodantį skiemenavimo pozicijas.
Masyvo elementas gali turėti dvi reikšmes:
      HyLT_NoHyphen – toje pozicijoje nedėti skiemenavimo ženklo;
      HyLT_HyphenPlace - toje pozicijoje (t.y. po raidės toje pozicijoje) dėti skiemenavimo ženklą.
Pvz., skiemenuojant žodį „labas“, šis masyvas įgauna reikšmes:
[NoHyphen, HyLT_HyphenPlace, NoHyphen, NoHyphen, NoHyphen]

HyLT_CapitalisationCase – požymis, apibūdinantis didžiųjų raidžių naudojimą skiemenuotame žodyje.
Galimos reikšmės:
      OnlyLower – žodyje vien mažosios raidės;
      HyLT_InitialCapital – pirma žodžio raidė didžioji;
      HyLT_OnlyUpper – žodyje vien didžiosios raidės;
      HyLT_MixedCase - mišrus didžiųjų ir mažųjų raidžių variantas (kaip, pvz., žodyje „MacDonnald“).

HyLT_WQXCase – požymis, nurodantis ar žodyje buvo bent kuri „svetima“ (q, x, w) raidė.
Galimos reikšmės:
      TRUE – buvo q, x, w raidžių;
      FALSE - nebuvo q, x, w raidžių.

Išimčių žodyno formatas

Į išimčių žodyną surašomi suskiemenuoti žodžiai – po vieną žodį į eilutę. Žodžiai užrašomi tuo kodavimu, koks nustatytas skiemenavimo režimuose (nutylint – Windows-1257).
Pvz., an-al-fa-be-tas

Tačiau leidžiama žodžio pabaigoje nurodyti simbolį *, kuris reiškia „bet kokie galimi žodžio tęsiniai“. Tai naudinga išvengiant pasikartojimų kaitomoms galūnėms.
Pvz., galima nurodyti an-al-fa-bet*, kas reikš ir „an-al-fa-be-tas“, ir „„an-al-fa-be-tams“, ir „an-al-fa-be-tinius“, ir t.t.

Pastaba: su API pateikiamas žodynas yra užkoduotas Unicode (UTF16) kodavimu.