Introduction

NHunspell Online Help

Introduction

Introduction | This is the first topic | Next topic
Introduction | This is the first topic | Next topic

About Hunspell and NHunspell

The spell checker library Hunspell is a state of the art spell checker for languages with complex word compunding and rich morphology. It was written by László Németh for spell checking of the Hungarian language and can be used with utf8 encoded unicode directories. Hunspell is based on MySpell and can use MySpell directories too.

Hunspell is the default spell checker of OpenOffice, Mozilla Thunderbird and Firefox, Google Chrome and the Apple MAC OS/X operating system since version 10.6 "Snow Leopard". Hunspell is based an MySpell and can use the MySpell dictionaries. It is an alternative to GNU Aspell, ISpell, PSpell and Enchant

NHunspell ist a DotNet implementation for Hunspell by Thomas Mayerhofer. You can download the original DLLs from http://nhunspell.sourceforge.net.

From the DLL distribution, Delphi needs the file "HunspellX86.DLL" only, which is a 32 bit unmanaged code version of the Hunspell DLL. Contrary to other versions of Hunspell, NHunspell is strictly Unicode (all DLL functions require widestrings).

The advantage of NHunspell over other implementations is, that the DLL handles codepage conversions of the various dictionaries internally and includes better memory management. It furthermore implements the hyphenation functions in the same DLL and can be initialized with a memory pointer instead of the file name of a dictionary. The latter is mandatory to support OpenOffice 3 dictionaries (.oxt).

License

NHunspell and TNHunspell are licensed under: GPL/LGPL/MPL. Free use in commercial applications is permitted according to the LGPL and MPL licenses. Your commercial application can link against the NHunspell DLLs.

Paszip (part of this package to unpack OXT dictionary files) is licensed under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

Dictionaries for NHunspell

This Delphi implementation supports all spelling and hyphenation dictionaries for OpenOffice 3.x. Thesaurus is currently not supported.

Download OpenOffice 3 dictionaries: http://extensions.services.openoffice.org/en/dictionaries


Files

Files

Files | Previous topic | Next topic
Files | Previous topic | Next topic

NHunspell consists of the following files:

Root folder

HunspellX86.dll Unmanaged code 32 bit implementation of Hunspell, copyright Thomas Mayerhofer (http://nhunspell.sourceforge.net). You must distribute this DLL with your application.
NHunspell.pas Implements the TNHunspell class that encapsulates loading of OXT dictionaries and implements spelling and hyphenation functions, copyright Alexander Halser (http://www.ec-software.com)
NHunXml.pas Tiny XML parser for OXT headers, copyright Alexander Halser
PasZip.pas Zip archive reader, copyright Arnaud Bouchez (http://synopse.info)

\Dictionaries

*.oxt OpenOffice 3 dictionaries. Place more dictionaries in this folder.

\Demo

NHunspellTest.dpr NHunspell demo application to test spelling and hyphenation.
NHunspellAddict.dpr Addict demo with OpenOffice dictionaries.

\Addict4

ad3MainDictionary.pas Replacement unit (patch) for Addict 4.

\Help

NHunspell.chm NHunspell help file.
NHunspell.hmxz NHunspell help file source. This is a Help & Manual project file. If you would like to contribute to this open source project and need to update the help file, please write to alexander.halser@ec-software.com for a complementary license.


History

History

History | Previous topic | Next topic
History | Previous topic | Next topic

Version 1.1.0 (2011-02-25)

· Complete rewrite of the TNHunspell class for better support of multiple dictionaries in a single OXT container.
· Support for older dictionaries (OpenOffice 2, uncompressed dictionary files) has been dropped.
· Additional unit introduced to use the commercial Addict spell checker (http://www.addictivesoftware.com) with Hunspell dictionaries.

Version 1.0.0 (2010-08-09)

· Initial release.


Understanding OXT dictionary files

Understanding OXT dictionary files

Understanding OXT dictionary files | Previous topic | Next topic
Understanding OXT dictionary files | Previous topic | Next topic

OXT is short for "OpenOffice Extension". There are not only dictionaries with a file extension ".oxt", but other extensions as well. An OXT is a container file, a simple ZIP archive. To view its content, rename it to .zip and open it with your favorite ZIP reader.

Content of an OXT dictionary file

Whether an OXT container is a dictionary extension or not, is decribed by the internal XML files in the archive. A dictionary container contains one or more dictionary data files. The important point here is: "or more".

The English dictionary extension dict-en.oxt for instance, contains spelling and hyphenation dictionaries as well as a thesaurus. The spelling dictionaries are separated into multiple sub-languages, such as Australien, U.S., U.K. English and others.

So while an OXT container file may include multiple English dictionaries, we need to use a particular dictionary for the spelling check. TNHunspell addresses this by scanning multiple OXT container files and building a list of available dictionary items, each for a particular (sub-) language.


Using TNHunspell

Using TNHunspell

Using TNHunspell | Previous topic | Next topic
Using TNHunspell | Previous topic | Next topic

To use TNHunspell, all you need to do is to include the NHunspell.pas unit. This unit creates one global instance of TNHunspell, called HUNSPELL. This TNHunspell instance is a simple object which holds a list of dictionaries. After creation, the list is empty and has to be initialized before use.

Finding dictionaries

As explained here, an OXT container file may contain multiple dictionary data files. To find out what an OXT container contains, TNHunspell has two functions - ReadOXT and ReadFolder. ReadOXT scans a single OXT archive while ReadFolder scans an entire folder for OXT files.

Let's assume that your application has a sub-folder called "Spellcheck" where OXT dictionary files are located. In this case you would start initializing Hunspell like this:

with HUNSPELL do

begin

ClearDictionaries;

if not ReadFolder(ExtractFilePath(Application.Exename)+'Spellcheck') then

showmessage('No dictionaries found!')

else

showmessage(Format('%d spelling, %d hyphenation dictionaries found', [SpellDictionaryCount, HyphenDictionaryCount]));

end;

If the scan was successful, our global HUNSPELL instance has initialized the two lists with spelling and hyphenation dictionaries. You can perform multiple scans on multiple folders, if there are more than one dictionary folder.

If you scan multiple folders and a duplicate dictionary is found (e.g. a duplicate OXT container file), the duplicate dictionaries are ignored. For comparison, TNHunspell uses the InternalFileID property.

After finding the available dictionaries

After executing the ReadFolder function, you have got a list of available dictionaries, the dictionary instances have been created (either as TNHSpellDictionary or TNHHyphenDictionary) and their properties (e.g. DisplayName, LanguageName, Publisher, Version) have been intialized.

At this point, the dictionary data has not been loaded. The dictionaries are yet not active. We need to activate and load them, but typically not all of them, just that particular language that we want.

You will either do this by presenting a configuration dialog to the user or - if the configuration has been saved somewhere - go through the dictionary list and activate it. Example:

var

i: integer;

myActiveIDs: TStringlist;

tmpDict: TNHSpellDictionary;

begin

myActiveIDs := TStringlist.create;

myActiveIDs.add('dict-en.oxt::en_US.aff::en_US.dic'); //activate US

myActiveIDs.add('dict-en.oxt::en_UK.aff::en_UK.dic'); //activate UK as well

try

for i := 0 to myActiveIDs.count-1 do

begin

tmpDict := HUNSPELL.FindSpellDictionary( myActiveIDs[i] );

if assigned(tmpDict) then

tmpDict.Active := true //just a boolean value to store "Active", doesn't automatically load it!

else

Showmessage('Not found: ' + myActiveIDs[i]);

end;

finally

FreeAndNil(myActiveIDs);

end;

HUNSPELL.UpdateAndLoadDictionaries; //load them!

end;

In the example above, myActiveIDs contains a list with the InternalFileIDs of the dictionaries you want to be active.

TNHunspell is now ready for spell checking.

Spelling check

For the spelling check, you need to call the TNHSpellDictionary.Spell function. If there is more than one active dictionary, you need to repeat this call for every active dictionary.

function TForm1.CheckThisWord(const ThisWord: string): Boolean;

var

i: integer;

begin

with HUNSPELL do

for i := 0 to SpellDictionaryCount-1 do

if SpellDictionaries[i].Active then

begin

result := SpellDictionaries[i].Spell(ThisWord); //true = word found

if result then break;

end;

end;

Suggestions for misspelled words

If a word his misspelled, you call TNHSpellDictionary.Suggest function. If there is more than one active dictionary, you might repeat this call for every active dictionary (unless you allow suggestions from one main dictionary only).

procedure TForm1.SuggestReplacements(const ThisWord: string);

var

i: integer;

strSuggestions: TStringlist;

begin

strSuggestions := TStringlist.create;

try

with HUNSPELL do

for i := 0 to SpellDictionaryCount-1 do

if SpellDictionaries[i].Active then

SpellDictionaries[i].Suggest(ThisWord, strSuggestions);

Listbox1.Items.assign(strSuggestions);

finally

FreeAndNil(strSuggestions);

end;

end;


TNHunspell for Addict

TNHunspell for Addict

TNHunspell for Addict | Previous topic | Next topic
TNHunspell for Addict | Previous topic | Next topic

Addict (http://www.addictivesoftware.com) is a widely-used commercial Delphi component to implement a full-featured spell checking engine. It comes with a set of components and its own dictionaries for various languages.

Note that Addict is commercial software, not open-source!

What is the connection between Addict and Hunspell?

Hunspell is a dictionary implementation only. This Delphi wrapper for Hunspell is no different. It lets you check, stem, analyze or hyphenate a single word.

In the real world, however, a spell checker does much more than that. It parses multiple paragraphs, decides what is a word, checks for duplicate words, filters out quotes and internet addresses, implements dialogs for configuration, for the spelling check and for suggestions, supports custom user dictionaries and a lot more.

Addict does all of this and it does it very well. It is implemented in many Delphi applications (like in Help & Manual) and replacing it completely would be a huge undertaking for many software developers. Moreover, there are many 3rd-party parsers for Addict for almost every Delphi component that deals with text.

Addict has only one small disadvantage: the dictionaries are proprietary, the free OpenOffice dictionaries used by Hunspell are larger and are available for languages that Addict currently not supports.

So the logical step was to combine them, to use Addict as the general-purpose spell checker and patch it to use OpenOffice dictionaries instead of the proprietary ones.

Patch for Addict

The patch for Addict uses a replacement unit for the implementation of the TMainDictionary class in Addict. You find this unit here.

Requirements

· You need Addict v4 or higher and you need Delphi 2009 or higher. The combination of Addict with Hunspell requires the Unicode VCL!

Installation of the patch

· Locate the source folder of Addict in your Delphi library (should be named "\Addict4").
· Make a backup copy of the original file ad3MainDictionary.pas.
· Overwrite the file with ad3MainDictionary.pas from the \NHunspell\Addict4 folder.
· Check out the demo application NHunspellAddict.dpr for more instructions.


TNHunspell

TNHunspell

TNHunspell | Previous topic | Next topic
TNHunspell | Previous topic | Next topic

Unit: NHunspell.pas

TNHunspell is an non-visual class to implement handling of multiple spelling and hyphenation dictionaries.

Do not create TNHunspell manually!

A global instance of TNHunspell - named HUNSPELL - is automatically created in the initialization function of NHunspell.pas. Whenever you use the spell checker, refer to this global instance.

TNHunspell loads the DLL HunspellX86.dll dynamically at runtime.


ClearDictionaries

ClearDictionaries

ClearDictionaries | Previous topic | Next topic
ClearDictionaries | Previous topic | Next topic

procedure ClearDictionaries;

Clears the SpellDictionaries and HyphenDictionaries list and releases the dictionary instances.

This function has no parameters.


Create

Create

Create | Previous topic | Next topic
Create | Previous topic | Next topic

constructor Create;

Creates a new instance of TNHunspell.

This function has no parameters.


Destroy

Destroy

Destroy | Previous topic | Next topic
Destroy | Previous topic | Next topic

destructor Destroy; override;

Frees an instance of TNHunspell.

This function has no parameters.


FindHyphenDictionary

FindHyphenDictionary

FindHyphenDictionary | Previous topic | Next topic
FindHyphenDictionary | Previous topic | Next topic

function FindSpellDictionary(const AInternalID: String): TNHSpellDictionary;

Finds a spell dictionary by the internal file ID and returns the dictionary instance.

Parameters:

Name | Type | Description
AInternalID | String | Refers to the InternalFileID property of a dictionary.


FindSpellDictionary

FindSpellDictionary

FindSpellDictionary | Previous topic | Next topic
FindSpellDictionary | Previous topic | Next topic

function FindHyphenDictionary(const AInternalID: String): TNHHyphenDictionary;

Finds a hyphenation dictionary by the internal file ID and returns the dictionary instance.

Parameters:

Name | Type | Description
AInternalID | String | Refers to the InternalFileID property of the dictionary.


ReadFolder

ReadFolder

ReadFolder | Previous topic | Next topic
ReadFolder | Previous topic | Next topic

function ReadFolder(FolderName: String): Boolean;

Reads all *.OXT files in a given folder and updates the SpellDictionaries and HyphenDictionaries list. This function searches a folder for OXT container files, and calls ReadOXT for each item found. Note that this function does not scan sub-folders.

Parameters:

Name | Type | Description
Foldername | String | Full path to a directory that contains one or more .OXT container files.


ReadOXT

ReadOXT

ReadOXT | Previous topic | Next topic
ReadOXT | Previous topic | Next topic

function ReadOXT(const FileName: String): Boolean;

Reads a single *.OXT file and updates the SpellDictionaries and HyphenDictionaries list.

Parameters:

Name | Type | Description
Filename | String | Filename including path of an .OXT package file.

Note:

This function reads an OXT container file, extracts the header information and creates one or more TNHSpellDictionary and/or TNHHyphenDictionary objects, which are added to the corresponding list of TNHunspell.

It does not load the dictionaries into memory! To activate and load a dictionary, set its Active property to true, then call UpdateAndLoadDictionaries.

If the list already contains this dictionary, the original dictionary is kept and the new instance released.


RemoveHyphenDictionary

RemoveHyphenDictionary

RemoveHyphenDictionary | Previous topic | Next topic
RemoveHyphenDictionary | Previous topic | Next topic

procedure RemoveHyphenDictionary(index: integer);

Removes a hyphenation dictionary from the HyphenDictionaries list. The THNHyphenDictionary instance is unloaded and destroyed.

Parameters:

Name | Type | Description
Index | Integer | Zero-based index of the dictionary.


RemoveSpellDictionary

RemoveSpellDictionary

RemoveSpellDictionary | Previous topic | Next topic
RemoveSpellDictionary | Previous topic | Next topic

procedure RemoveSpellDictionary(index: integer);

Removes a spelling dictionary from the SpellDictionaries list. The THNSpellDictionary instance is unloaded and destroyed.

Parameters:

Name | Type | Description
Index | Integer | Zero-based index of the dictionary.


UpdateAndLoadDictionaries

UpdateAndLoadDictionaries

UpdateAndLoadDictionaries | Previous topic | Next topic
UpdateAndLoadDictionaries | Previous topic | Next topic

procedure UpdateAndLoadDictionaries;

Loads all spelling and hyphenation dictionaries that are marked active, unloads all dictionaries that are marked not active.

The dictionary instances are not destroyed, just the Hunspell handle and the dictionary data in memory is released. Dictionary header information such as DisplayName, LanguageName or Publisher is still available.

Example:

var

i: integer;

begin

for i := 0 to Hunspell.SpellDictionaryCount-1 do

Hunspell.SpellDictionaries[i].Active := true;

Hunspell.UpdateAndLoadDictionaries;

end;


SpellDictionaryCount

SpellDictionaryCount

SpellDictionaryCount | Previous topic | Next topic
SpellDictionaryCount | Previous topic | Next topic

property SpellDictionaryCount: Integer

Returns the number of entries in SpellDictionaries.


HyphenDictionaryCount

HyphenDictionaryCount

HyphenDictionaryCount | Previous topic | Next topic
HyphenDictionaryCount | Previous topic | Next topic

property HyphenDictionaryCount: Integer

Returns the number of entries in HyphenDictionaries.


SpellDictionaries

SpellDictionaries

SpellDictionaries | Previous topic | Next topic
SpellDictionaries | Previous topic | Next topic

property SpellDictionaries[Index: Integer]: TNHSpellDictionary

Returns an instance of a TNHSpellDictionary.

Parameters:

Name | Type | Description
Index | Integer | Zero-based index of the dictionary.


HyphenDictionaries

HyphenDictionaries

HyphenDictionaries | Previous topic | Next topic
HyphenDictionaries | Previous topic | Next topic

property HyphenDictionaries[Index: Integer]: TNHHyphenDictionary

Returns an instance of a TNHHyphenDictionary.

Parameters:

Name | Type | Description
Index | Integer | Zero-based index of the dictionary.


TNHSpellDictionary

TNHSpellDictionary

TNHSpellDictionary | Previous topic | Next topic
TNHSpellDictionary | Previous topic | Next topic

Geben Sie hier den Text ein.


Add

Add

Add | Previous topic | Next topic
Add | Previous topic | Next topic

function Add(const Word: UnicodeString): Boolean;

Adds the specified word to the internal dictionary.

Parameters:

Name | Type | Description
Word | UnicodeString | The word to add to the dictionary

Return value

Returns true, if the word was added successfully.


AddWithAffix

AddWithAffix

AddWithAffix | Previous topic | Next topic
AddWithAffix | Previous topic | Next topic

function AddWithAffix(const Word, AffixModel: UnicodeString): Boolean;

Adds the word and the affix.

Parameters:

Name | Type | Description
Word | UnicodeString | The word to add to the dictionary
AffixModel | UnicodeString | Hunspell affix model to use

Return value

Returns true, if the word was added successfully.


Analyze

Analyze

Analyze | Previous topic | Next topic
Analyze | Previous topic | Next topic

procedure Analyze(const Word: UnicodeString; var AWordList: TUnicodestrings);

Analyzes the specified word.

Parameters:

Name | Type | Description
Word | UnicodeString | The word to add to the dictionary
AWordList | TUnicodestrings | Stringlist to retrieve return values


Load

Load

Load | Previous topic | Next topic
Load | Previous topic | Next topic

function Load: Boolean

Loads a the dictionary data into memory.

You will rarely use this method directly. Instead, set the Active property of the dictionary to true, then call Hunspell.UpdateAndLoadDictionaries.

Return value

Returns true, if the specified dictionary was successfully loaded.


Spell

Spell

Spell | Previous topic | Next topic
Spell | Previous topic | Next topic

function Spell(const Word: UnicodeString): Boolean;

Spell check the word.

Parameters:

Name | Type | Description
Word | UnicodeString | The word to spell check

Return value

Returns true, if the word is correctly spelt. Returns false if the word is incorrectly spelt or was not found in the dictionary. If Spell returns false, use Suggest to retrieve a list of suggestions.


Stem

Stem

Stem | Previous topic | Next topic
Stem | Previous topic | Next topic

procedure Stem(const Word: UnicodeString; var AWordList: TUnicodestrings);

Stems the specified word.

Parameters:

Name | Type | Description
Word | UnicodeString | The word to stem
AWordList | TUnicodestrings | Stringlist to retrieve return values


Suggest

Suggest

Suggest | Previous topic | Next topic
Suggest | Previous topic | Next topic

procedure Suggest(const Word: UnicodeString; var AWordList: TUnicodestrings);

Get a list of suggestions for the specified word.

Parameters:

Name | Type | Description
Word | UnicodeString | The word to get suggestions for
AWordList | TUnicodestrings | Stringlist to retrieve suggestion values

Example:

var
spell: TNHunspell;
tmpStr: TWidestrings;
begin
spell := TNHunspell.Create;
spell.Load('dict-en.oxt', [dtSpelling, dtHyphenation]);
if spell.Active then
begin
if spell.Spell('Abracadabra') then
Showmessage('correctly spelt')
else
begin
tmpStr := TWidestringlist.create;
spell.Suggest('Abracadabra', tmpStr);
if tmpStr.count = 0 then
showmessage('No suggestions')
else
showmessage('Suggestions: ' + tmpStr.Text);
FreeAndNil(tmpStr);
end;
end;
spell.free;
end;


Unload

Unload

Unload | Previous topic | Next topic
Unload | Previous topic | Next topic

procedure Unload;

Unloads a dictionary and releases the memory consumed by the dictionary data.

This function has no parameters.


Active

Active

Active | Previous topic | Next topic
Active | Previous topic | Next topic

property Active: Boolean

Determines if a dictionary is active and can be used. Active is automatically set to true by the Load function and set to false by Unload.

Changing the Active property does nothing. You need to call TNHunspell.UpdateAndLoadDictionaries for the Active property to take effect.

Example:

var

i: integer;

begin

for i := 0 to Hunspell.SpellDictionaryCount-1 do

Hunspell.SpellDictionaries[i].Active := true;

Hunspell.UpdateAndLoadDictionaries;

end;


DictionaryFileName

DictionaryFileName

DictionaryFileName | Previous topic | Next topic
DictionaryFileName | Previous topic | Next topic

property DictionaryFileName: String

Read-only.

DictionaryFileName stores the file name of the OXT container file. The purpose of this property is to remember the original file name for subsequent calls to Load.


DisplayName

DisplayName

DisplayName | Previous topic | Next topic
DisplayName | Previous topic | Next topic

property DisplayName: UnicodeString

Read-only.

DisplayName returns name of the dictionary, usually in the language of the dictionary.

This value is assigned to the OXT package file. If the package file contains more than one dictionary (e.g. English US/UK/Australia), TNHunspell will treat the sub-languages as separate dictionaries, but they all share the same value.


ID

ID

ID | Previous topic | Next topic
ID | Previous topic | Next topic

property ID: UnicodeString

Read-only.

Returns the ID of the dictionary package, given by the publisher. Every OpenOffice dictionary has a global identifier assigned by the publisher of the dictionary package.

This value is assigned to the OXT package file. If the package file contains more than one dictionary (e.g. English US/UK/Australia), TNHunspell will treat the sub-languages as separate dictionaries, but they all share the same value.

Note:

Do not confuse this value with InternalFileID.


InternalFileID

InternalFileID

InternalFileID | Previous topic | Next topic
InternalFileID | Previous topic | Next topic

property InternalFileID: String

Read-only.

The InternalFileID property is a unique identifier of a dictionary inside an OXT package. This property is used to refer to dictionaries internally and you might use it to store the configuration of your application in, for instance, the Windows registry.

The InternalFileID looks like this: dict-en.oxt::en_US.aff::en_US.dic

The first part refers to the OXT container file (without path), the second part refers to the internal dictionary data stream inside an OXT container. In combination, the ID defines a unique identifier for a particular sub-language.

Note:

Do not confuse this value with ID.


LangID

LangID

LangID | Previous topic | Next topic
LangID | Previous topic | Next topic

property LangID: Word

Read-only.

LangID returns numeric value of the dictionary language. It may include a sub-language such as "English (U.K.)".


LanguageName

LanguageName

LanguageName | Previous topic | Next topic
LanguageName | Previous topic | Next topic

property LanguageName: UnicodeString

Read-only.

LanguageName returns the Windows name of the dictionary language including the sub-language (e.g. "English (U.S.)".


Publisher

Publisher

Publisher | Previous topic | Next topic
Publisher | Previous topic | Next topic

property Publisher: UnicodeString

Read-only.

Publisher returns the publisher (copyright) the dictionary.

This value is assigned to the OXT package file. If the package file contains more than one dictionary (e.g. English US/UK/Australia), TNHunspell will treat the sub-languages as separate dictionaries, but they all share the same value.


Version

Version

Version | Previous topic | Next topic
Version | Previous topic | Next topic

property Version: UnicodeString

Read-only.

Version returns the internal version of the dictionary.

This value is assigned to the OXT package file. If the package file contains more than one dictionary (e.g. English US/UK/Australia), TNHunspell will treat the sub-languages as separate dictionaries, but they all share the same value.


TNHHyphenDictionary

TNHHyphenDictionary

TNHHyphenDictionary | Previous topic | Next topic
TNHHyphenDictionary | Previous topic | Next topic

Geben Sie hier den Text ein.


Hyphenate

Hyphenate

Hyphenate | Previous topic | Next topic
Hyphenate | Previous topic | Next topic

function Hyphenate(const Word: UnicodeString): UnicodeString

Returns the given word in hyphenated form.

Parameters:

Name | Type | Description
Word | Unicodestring | The word to hyphenate

Return value

The word in hyphenated form, hyphenation points are indicated by equal signs ("=").