Spell v2.0 (Preview)

Summary
Spell v2.0 (Preview)
IntroductionThe Spell library is a wrapper for the Hunspell API with additional functions to support custom libraries.
CompatibilityThis library was designed to run on most versions of Windows (Windows XP+) and on all versions of AutoHotkey including AutoHotkey Basic (ANSI) and AutoHotkey v1.1+ (ANSI and Unicode, 32-bit and 64-bit).
Credit:Credit and thanks to majkinetor for developing the original Spell library.
Functions:
Spell_AddAdd a word or list or words to the dictionary which is/are valid until the spell object is destroyed.
Spell_AddCustomAdd a word to a custom dictionary file.
Spell_ANSI2UnicodeMaps a character string (ANSI) to a UTF-16 (wide character) string.
Spell_InitInitialize Hunspell.
Spell_InitCustomAdd words from a custom dictionary file to the active dictionary.
Spell_SpellCheck the spelling of the specified word.
Spell_SuggestSuggest words for a misspelled word.
Spell_Unicode2ANSIMaps a UTF-16 (wide character) string to a character string (ANSI).
Spell_UninitFrees the spell object and the memory allocated to the dynamic link library (DLL).

Introduction

The Spell library is a wrapper for the Hunspell API with additional functions to support custom libraries.

Compatibility

This library was designed to run on most versions of Windows (Windows XP+) and on all versions of AutoHotkey including AutoHotkey Basic (ANSI) and AutoHotkey v1.1+ (ANSI and Unicode, 32-bit and 64-bit).

Credit:

Credit and thanks to majkinetor for developing the original Spell library.  Thanks to Prodigy (AutoIt forum) for the idea to use the NHunspell API for version 2.0 of this library and for guidance to the syntax of some of API functions.  Thanks to ProgAndy (AutoIt German forum) for providing a copy of the NHunspell DLL files.

Functions:

Spell_Add

Spell_Add(ByRef hSpell,  
 p_Word,  
 p_AddCase = "")

Description

Add a word or list or words to the dictionary which is/are valid until the spell object is destroyed.

Parameters

hSpellVariable that contains the current dictionary information.
p_WordWord or list of words (delimited by a LF (line feed) or CR+LF (carriage return and line feed)) to add to the dictionary.
p_AddCase[Optional] See the Add Case section for more information.

Add Case

Preface: For the most part, the affix file (Ex: en_US.aff) contains the rules that determine how words in a dictionary are treated.  What may be true for words in one dictionary (Ex: en_US) may not be true for words in other dictionaries (Ex: en_GB).  The p_AddCase parameter was added to deal with possible shortcomings in all dictionaries but it has only been tested using the en_US dictionary files.  Be sure to test thoroughly.

Mixed case words (Ex: “Kevin” or “KevinWasHere”) added to the dictionary may be treated as case sensitive.  Under most circumstances this is the desired behavior.  However, there are certain words or group of words that are commonly (and validly) used in other forms.  One example is a list of commands and/or key words for a programming language.  For many programming languages, the commands and/or key words are not case sensitive, so adding different variations of the command/key word to the dictionary might reduce the number of “word not found” errors when running a spell check on the source code.

The p_AddCase parameter will add up to 3 additional words to the dictionary for every word found in the p_Word parameter.  The following options are available.

UAdd an all uppercase version of the word(s) to the dictionary.  Ex: “KEVIN”.  Note: Most dictionaries automatically recognize an all uppercase version of every word so this option is usually superfluous.  Be sure to test your dictionary to be sure.
LAdd an all lowercase version of the word(s) to the dictionary.  Ex: “kevin”.  Observation: For the English (US) dictionary, this option provides the most value out of all the options.  I suspect this may be true for other dictionaries.
TAdd a title case (first letter is uppercase, all others are lowercase) version of the word(s) to the dictionary.  Ex: “Kevin”.  Note: Most dictionaries automatically recognize a title case version of a word if a lowercase version of the word exists so this option may be unnecessary if the word is already all lowercase or if the “L” option is specified.  Be sure to test your dictionary to be sure.
AAdd an all uppercase, an all lowercase, and a title case version of the word(s) to the dictionary.  This option is the same as “ULT”.

To use more than one option, just add it next to the previous option.  For example, “UL”.

The additional word will not be added if the original word is already in that case.  For example, if the original word is already all lowercase (Ex: “kevin”), then the all lowercase version of the word is not added.

Important: This function uses the AutoHotkey StringUpper and StringLower commands to convert the word(s) to uppercase, lowercase, and title case.  The rules and limitations of these commands could affect the results for some words.

Returns

The number of words added to the dictionary.

Calls To Other Functions

Remarks

The performance of this function is excellent under almost all circumstances.  However, when adding a very large number of words (>2000?), performance can be improved by setting SetBatchLines to a higher value before calling this function.  For example:

SetBatchLines 100ms
Spell_Add(hSpell,...)
SetBatchLines 10ms  ;-- This is the system default

Spell_AddCustom

Spell_AddCustom(p_CustomDic,  
p_Word,  
p_EOL = "`r`n")

Description

Add a word to a custom dictionary file.

Parameters

p_CustomDicPath to a custom dictionary file.
p_WordWord or list of words (delimited by a LF (line feed) or CR+LF (carriage return and line feed)) to add.
p_EOLEnd-Of-Line (EOL) characters.  [Optional] The default is CR+LF.

Returns

The number of words loaded to the custom dictionary file if successful (can be 0) or -1 if there was an error (custom dictionary file not found or error writing to the custom dictionary file).

Remarks

  • This function does not update the active dictionary.  If needed, call Spell_Add to add the word(s) to the active dictionary.
  • The custom dictionary file must already exist, even if it’s empty.  The file must be in a Unix (EOL=LF) or DOS/Windows (EOL=CR+LF) format.  This function will add a word followed by the characters in p_EOL parameter (default=CR+LR) to the end of the file.  If editing the custom dictionary file manually, make sure there is a LF or CR+LF after the last word.
  • This function (via the FileAppend command) uses the default file encoding which is the system default ANSI code page.  For AutoHotkey v1.1+, this default can be changed by calling the FileEncoding command any time before calling this function.

Spell_ANSI2Unicode

Spell_ANSI2Unicode( lpMultiByteStr,
ByRef WideCharStr)

Description

Maps a character string (ANSI) to a UTF-16 (wide character) string.

Type

Internal function.  Subject to change.  Do not use.

Parameters

lpMultiByteStrAddress to a character string (ANSI).
WideCharStrVariable to store the UTF-16 (wide character) string.

Spell_Init

Spell_Init(ByRef hSpell,  
 p_Aff,  
 p_Dic,  
 DLLPath = "")

Description

Initialize Hunspell.

Parameters

hSpellVariable that will contain the current dictionary information.
p_AffPath to affix file.
p_DicPath to dictionary file.
DLLPathPath to the folder of the Hunspell DLL files (Ex: “lib\”) or the full path and file name of the Hunspell DLL file (Ex: “lib\Hunspellx86.dll”) . [Optional] If null or not specified, the Hunspell DLL files must be located in the local folder or in the path.

Returns

TRUE if initialization was successful, otherwise FALSE.

Calls To Other Functions

Remarks

hSpell map :

Offset  Description
------  -----------

   0    Handle to the spell object
   8    Handle to the Hunspell DLL library module
  16    Address to the HunspellAdd function
  24    Address to the HunspellAddWithAffix function
  32    Address to the HunspellAnalyze function
  40    Address to the HunspellFree function
  48    Address to the HunspellGenerate function
  56    Address to the HunspellInit function
  64    Address to the HunspellSpell function
  72    Address to the HunspellStem function
  80    Address to the HunspellSuggest function
  88    Address to the HyphenFree function
  96    Address to the HyphenHyphenate function
 104    Address to the HyphenInit function
 112    Address to the MyThesFree function
 120    Address to the MyThesInit function
 128    Address to the MyThesLookup function
 ---
 136    Total bytes

This map is the same for all versions of AutoHotkey.  Addresses and handles are 4 bytes for the 32-bit versions of AutoHotkey and 8 bytes for the 64-bit version.  All of the API functions are mapped but only key spell functions are used by the Spell library.

As the name implies, this function should be called first.  If key dictionary or library files are not found, this function will display a strong error message and will return FALSE.  If this function returns FALSE, do not call any other library function.  Calling other library functions when Hunspell has not been initialized may (read: will) cause AutoHotkey to crash.

Spell_InitCustom

Spell_InitCustom(ByRef hSpell,  
 p_CustomDic,  
 p_AddCase = "")

Description

Add words from a custom dictionary file to the active dictionary.  Words are valid until spell object is destroyed.

Parameters

hSpellVariable that contains the current dictionary information.
p_CustomDicPath to a custom dictionary file.
p_AddCaseSee Spell_Add for the syntax/rules of this parameter.  [Optional]

Returns

The number of words loaded to the spell object if successful (can be 0) or -1 if there was an error reading the custom dictionary file.

Calls To Other Functions

Remarks

  • This function must be called after Spell_Init.
  • The custom dictionary file must be in Unix (EOL=LF) or DOS/Windows (EOL=CR+LF) format.

Spell_Spell

Spell_Spell(ByRef hSpell,
 p_Word)

Description

Check the spelling of the specified word.

Returns

TRUE if the word was found in the active dictionary, otherwise FALSE.

Calls To Other Functions

Spell_Suggest

Spell_Suggest(ByRef hSpell,
 p_Word,
ByRef r_SuggestList)

Description

Suggest words for a misspelled word.

Parameters

hSpellVariable that contains the current dictionary information.
p_WordWord for which to look up for suggestions.
r_SuggestList[Output] Variable that is loaded with a newline (“`n”) delimited list of suggest words.

Returns

Number of words in r_SuggestList.

Calls To Other Functions

Spell_Unicode2ANSI

Spell_Unicode2ANSI( lpWideCharStr,
ByRef MultiByteStr)

Description

Maps a UTF-16 (wide character) string to a character string (ANSI).

Type

Internal function.  Subject to change.  Do not use.

Parameters

lpWideCharStrAddress to a UTF-16 (wide character) string.
MultiByteStrVariable to store character string (ANSI).

Spell_Uninit

Spell_Uninit(ByRef hSpell)

Description

Frees the spell object and the memory allocated to the dynamic link library (DLL).

Spell_Add(ByRef hSpell,  
 p_Word,  
 p_AddCase = "")
Add a word or list or words to the dictionary which is/are valid until the spell object is destroyed.
Spell_AddCustom(p_CustomDic,  
p_Word,  
p_EOL = "`r`n")
Add a word to a custom dictionary file.
Spell_ANSI2Unicode( lpMultiByteStr,
ByRef WideCharStr)
Maps a character string (ANSI) to a UTF-16 (wide character) string.
Spell_Init(ByRef hSpell,  
 p_Aff,  
 p_Dic,  
 DLLPath = "")
Initialize Hunspell.
Spell_InitCustom(ByRef hSpell,  
 p_CustomDic,  
 p_AddCase = "")
Add words from a custom dictionary file to the active dictionary.
Spell_Spell(ByRef hSpell,
 p_Word)
Check the spelling of the specified word.
Spell_Suggest(ByRef hSpell,
 p_Word,
ByRef r_SuggestList)
Suggest words for a misspelled word.
Spell_Unicode2ANSI( lpWideCharStr,
ByRef MultiByteStr)
Maps a UTF-16 (wide character) string to a character string (ANSI).
Spell_Uninit(ByRef hSpell)
Frees the spell object and the memory allocated to the dynamic link library (DLL).
Close