This page provides examples of how to use the software library of Nuspell in other software. At the moment, only the usage in C++ on Debian and Ubuntu is described. Feel free to submit more documentation.

First, install the development files. Installing the package libnuspell-dev is the most common way.

Use find_package() for linking in CMake. An example is:

find_package(Nuspell)
add_executable(myprogram main.cpp)
target_link_libraries(myprogram Nuspell::nuspell)

That is all.

If you are using other build system, you can link this library with the help of pkg-config. The build-systems Autotools and Meson directly support this tool. Pkg-config also helps to link to libraries when one is directly invoking the compiler on the command line, like in this example:

g++ example.cxx -std=c++17 $(pkg-config --cflags --libs nuspell)

In your C++ file, add the following lines for including Nuspell:

#include <nuspell/dictionary.hxx>
#include <nuspell/finder.hxx>

Dictionaries installed on your system or on the system of your end-user can be searched and found with the following code:

auto dirs = vector<filesystem::path>();
nuspell::append_default_dir_paths(dirs);
auto dict_path = nuspell::search_dirs_for_one_dict(dirs, "en_US");
if (empty(dict_path))
	return 1; // Return error because we can not find the requested
	          // dictionary.

We strongly recommend that you do not write your own software for searching and finding installed dictionaries. The methods provided by Nuspell support many operating systems and dictionary locations. To get a list of all available dictionaries, use:

auto dict_list = nuspell::search_default_dirs_for_dicts();

From the found paths now a dictionary can be loaded with:

auto dict = nuspell::Dictionary();
try {
	dict.load_aff_dic(dict_path);
}
catch (const nuspell::Dictionary_Loading_Error& e) {
	cerr << e.what() << '\n';
	return 1;
}

Of course, searching, finding and loading dictionaries should be done as little as possible.

The following C++ code will return a boolean of value true the supplied word is spelled correctly:

auto word = string("word");
auto correct = dict.spell(word);

Spell checking is done on a word by word basis and each time the spell checker is agnostic of the context of the word. When you are checking text, you need to split the text to words and call Nuspell functions word by word. The recommended way to get the words of a text is Unicode text segmentation which is already implemented in ICU, QT and Boost::Locale (internally uses ICU).

To get a list of suggestions for a word, use the following:

auto suggestions = vector<string>();
dict.suggest(word, suggestions);

Bellow follows a simple example with simple splitting on white space.

#include <iostream>
#include <nuspell/dictionary.hxx>
#include <nuspell/finder.hxx>

using namespace std;

int main()
{
	auto dirs = vector<filesystem::path>();
	nuspell::append_default_dir_paths(dirs);
	auto dict_path = nuspell::search_dirs_for_one_dict(dirs, "en_US");
	if (empty(dict_path))
		return 1; // Return error because we can not find the requested
		          // dictionary.

	auto dict = nuspell::Dictionary();
	try {
		dict.load_aff_dic(dict_path);
	}
	catch (const nuspell::Dictionary_Loading_Error& e) {
		cerr << e.what() << '\n';
		return 1;
	}
	auto word = string();
	auto sugs = vector<string>();
	while (cin >> word) {
		if (dict.spell(word)) {
			cout << "Word \"" << word << "\" is ok.\n";
			continue;
		}

		cout << "Word \"" << word << "\" is incorrect.\n";
		dict.suggest(word, sugs);
		if (sugs.empty())
			continue;
		cout << "  Suggestions are: ";
		for (auto& sug : sugs)
			cout << sug << ' ';
		cout << '\n';
	}
}

Example of using Unicode segmentation can be found in the file src/tools/main.cxx.

Before shipping your software, make sure the license of Nuspell is respected and proper attribution is done.