Portable Spell Checker Interface Library

Kevin Atkinson kevina at users sourceforge net

Version 0.12.2

Contents

1 Introduction 2 1.1 Goal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

2 Getting Started 3 2.1 Obtaining . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.2 Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.3 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2.3.1 Generic Install Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.3.2 General Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 2.3.3 Problems with Libltdl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 2.3.4 Upgrading from Pspell .11.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

2.4 Helping Out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

3 Keeping in Touch 6

4 Library Interface 7 4.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 4.2 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 4.3 Class Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 4.4 Available Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 4.5 Format of the PWLI Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 4.6 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 4.7 Rational . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

4.7.1 store_repl method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

5 Status 13 5.1 Current . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 5.2 Future . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

6 Feedback 14

7 Changelog 15

8 Copyright 17 8.1 LGPL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Chapter 1

Introduction

1.1 Goal

The goal of the library is to provide a generic interface to Spell checker libraries installed on the system.

Chapter 2

Getting Started

2.1 Obtaining

The latest version of pspell can always be found at the pspell home page at http://pspell.

sourceforge.net/

2.2 Support

Support for Pspell can be found on the Pspell mailing lists. Instructions for joining the various mailing lists (and an archive of them) can be found off the Pspell home page at http://pspell.

sourceforge.net.

2.3 Installation

2.3.1 Generic Install Instructions

To install the library simply type

     ./configure
     make
     make install

Then install at least one pspell module. You can find more information about available modules from the Pspell home page. This is all that should be required for Pspell to function properly.

If you run into problems you can try disabling the building of shared libraries with --disable-shared and/or the ltdl library which is used for dynamically loading pspell modules with --disable-ltdl. If you do so you will then need to manually link in the necessary modules by doing the following:

     cd modules
     ./add-modules
     cd ..
     make
     make install

However this has not been known to work properly on most platforms. If you are just installing Pspell so that you can compile and use the Aspell utility then you should be okay as Aspell does not need any of Pspell modules linked in. However, if you are trying to use Pspell with an application that actually used the Pspell library such as PHP, AbiWord or the like then you will likely run into problems.

By default a static library is also created you can turn this of by passing the parameter --disable-static to configure. You can control what C and C++ compiler is used by setting the environmental variable CC and CXX respectfully before running configure and you can control what flags are passed to the C and C++ compile via the environmental variable CFLAGS and CXXFLAGS respectfully.

2.3.2 General Problems

Aspell does not use a released version of GNU Libtool. In previous versions of aspell this will often create problems if you inadvertently modify a file which causes Libtool to be called. However, as of Pspell .12.2 this so no longer be a problem and automake, autoconf, or libtool should not be called unless you specifically call them or if you configure Aspell with --enable-maintainer-mode. If you do notice any of these programs being called (and you did not configure with --enable-maintainer-mode) please let me know about it. If you have a need to modify configure.in or any of the Makefile.am’s you should install the multi-language-branch of the CVS version of libtool.

2.3.3 Problems with Libltdl

Pspell also requires libltdl, Libtool’s portable “dlopen” wrapper library, in order to function properly. If configure does not find libltdl installed on your system it will generally compile it and install it with the rest of Pspell. However, this can create problems if the compile environment is different than the environment that Pspell runs under. For example if configure was able to find libltdl at compile time but libltdl is no longer visible at runtime you will run into problems. The easiest thing to do here is copy the libltdl library found when compiling Pspell into the library directly Pspell was installed in. Another potently source of problems is the fact that the version of Libltdl found in the Pspell distribution is not the same as the one found in the released version of Libtool. In fact the two, while being source code compatible, are not binary compatible. This should normally not be a problem because if configure finds libltdl already installed on your system it will use that one. However, this might cause problems if the compile environment is different than the environment that Pspell runs under.

2.3.4 Upgrading from Pspell .11.2

Pspell .12 breaks binary and source code compatibility with Pspell .11. Many of the PspellManager functions now also have a length parameter specifying the length of the word. A length of -1 means that the string is null terminated. This unfortunately breaks source code compatibility. To upgrade to Pspell .12 either define the variable USE_ORIGINAL_MANAGER_FUNCS before pspell.h in included or simply add a length of -1 after each word passed in. Please see manager.h for the exact phototype of the functions. Defining the variable USE_ORIGINAL_MANAGER_FUNCS will allow your code to work with both Pspell .11 and .12.

2.4 Helping Out

Right now the area I need the most help in is better shared library support and on the ispell module. If you are interested in helping out please contact me at kevina@users.sourceforge.net.

If you wish to work on Pspell you will need the multi-language-branch of the CVS version of libtool. You will also need autoconf and automake. The released version of autoconf has a small bug in it CHAPTER 2. GETTING STARTED 5 which will cause it to think “.C” is the extension of executables. To fix this you need to apply the patch “autoconf-exeext.patch” which can be found in the pspell distribution.

Keeping in Touch

Even though you the LGPL license gives you the right to use Pspell in your application without ever notifying me, Kevin Atkinson, the sole author of Pspell—please don’t. If you are using, or planning on using, Pspell in your project please at very least send me an email at kevina at users sourceforge net. It doesn’t have to me anything fancy. A simple “I am planning on using Pspell in my project X. For more information please see Y.” will suffice. I will greatly appreciate it. I put a lot of unpaid time into Pspell and Aspell and would appreciate simply knowing where it is being used.

Library Interface

4.1 Overview

The Pspell library contains two main classes and several helper classes. The two main classes are PspellConfig and PspellMaster. The PspellConfig class is used to set initial defaults and to change spell checker specific options. The PspellManager class does most of the real work. It is responsible for managing the dictionaries, checking if a word is in the dictionary, and coming up with suggestions among other things. There are many helper classes the important ones are PspellWordList, PspellMutableWordList, Pspell*Emulation. The PspellWordList classes is used for accessing the suggestion list, as well as the personal and suggestion word list currently in use. The PspellMutableWordList is used to manage the personal, and perhaps other, word lists. The Pspell*Emulation classes are used for iterating through a list.

A C and C++ Interface is provided. I recommend using the C interface, even if your program is in C++, to avoid some of the nasty issues associated with C++ linkage. In general one can only use C++ linkage if both the library and the program were created with the same compiler. I may eventually provide C++ wrapper classes, including a few STL like one, for the C library and remove the existing C++ interface all together.

The mapping between the C and C++ interface is pretty straightforward and from C++ to C goes as follows:

<class name in lowercase with underscores>_<method name>([const] <Class> *, <other parameters if any>)

For example “PspellManager::lang_name() const” would become “pspell_manager_lang_name(const PspellManager *)”.

Methods that return a bool will instead return an int in the C interface.

4.2 Usage

To use pspell your application should include “pspell/pspell.h”. In order to insure that all the necessary libraries are linked in libtool should be used to perform the linking. When using libtool simply linking with “-lpspell” should be all that is necessary. When using shared libraries you might be able to simply link “-lpspell”, but this is not recommended. This version of Pspell uses the CVS version of libtool (multi-language-branch) however released versions of libtool should also work.

When your application first starts you should get a new configuration class with the command:

     PspellConfig * spell_config = new_pspell_config();

which will create a new PspellConfig class. It is allocated with new and it is your responsibility to delete it with delete_pspell_config. The standard C++ delete can be used if the compiler is compatible with the one used to create the Pspell library. Once you have the config class you should set some variables. The most important one is the language variable. To do so use the command:

     pspell_config_replace(spell_config, "language-tag", "en_US");

which will set the default language to use to American English. The language is expected to be the standard two letter ISO 639 language code, with an optional two letter ISO 3166 country code after an underscore. You can set the preferred spelling via the “spelling” option, any extra info via the “jargon” option, and the encoding via the “encoding” option. Other things you might want to set is the preferred spell checker to use, the search path for dictionary’s, and the like see section 4.4 for the available options.

When ever a new document is created a new PspellManager class should also be created. There should be one manager class per document. To create a new manager class use the new_pspell_manager and then cast it up using to_pspell_manager like so.

     PspellCanHaveError * possible_err = new_pspell_manager(spell_config);
     PspellManager * spell_checker = 0;
     if (pspell_error_number(possible_err) != 0)
       puts(pspell_error_message(possible_err));
     else
       spell_checker = to_pspell_manager(possible_err);

which will create a new PspellManager class using the defaults found in spell_config. If C++ is being used AND the compiler is compatible with the one used to create the Pspell library a normal cast can be used instead of to_pspell_manager.

If for some reason you want to use different defaults simply clone spell_config and change the setting like so:

     PspellConfig * spell_config2 = pspell_config_clone(spell_config);
     pspell_config_replace(spell_config2, "language-tag","nl");
     possible_err = new_pspell_manager(spell_config2);
     delete_pspell_config(spell_config2);

Once again in C++ delete_pspell_config can be replaced with a simple C++ delete. Once the manager class is created you can use the check method to see if a word in the document is correct like so:

     int correct = pspell_manager_check(spell_checker, <word>, <size>);

<word> can is expected to a const char * character string. If the encoding is set to be “machine unsigned 16” or “machine unsigned 32”. <word> is expected to be a cast from either const u16int * or const u32int* respectfully. U16int and u32int are generally unsigned short and unsigned int respectfully. <size> is the length of the string or -1 if the sting is null terminated. If the string is a cast from const u16int * or const u32int * then size is the amount of space in bytes the string takes up after being casted to const char * and not the true size of the string. Pspell_manager_check will return 0 is it is not found and non-zero otherwise.

If the word is not correct than the suggest method can be used to come up with likely replacements.

     PspellWordList * suggestions = pspell_manager_suggest(spell_checker,
                                                           <word>, <size>);
     PspellStringEmulation * elements = pspell_word_list_elements(suggestions);
     const char * word;
     while ( (word = pspell_string_emulation_next(pspell_elements) != NULL ) {
       // add to suggestion list
     }
     delete_pspell_string_emulation(elements);

Notice how elements is deleted but suggestions is not. The value returned by suggestions is only valid to the next call to suggest. Once a replacement is made the store_repl method should be used to communicate the replacement pair back to the spell checker (see section 4.7.1 for why). It usage is as follows:

     pspell_manager_store_repl(spell_checker,
                               <misspelled word>, <size>,
                               <correctly spelled word>, <size>);

If the user decided to add the word to the session or personal dictionary the the word can be be added using the add_to_session or add_to_personal methods respectfully like so:

     pspell_manager_add_to_session|personal(spell_checker, <word>, <size>);

It is better to let the spell checker manage these words rather than doing it your self so that the words have a change of appearing in the suggestion list.

Finally, when the document is closed the PspellManager class should be deleted like so.

     delete_pspell_manager(spell_checker);

The standard C++ delete should NOT be used here because it will not unload any shared libraries pulled in my when the manager class is created.

4.3 Class Reference

Methods that return a bool generally return false on error and true other wise. To find out what went wrong use the error_number and error_message methods. Unless otherwise stated methods that return a const char * will return null on error. The charter string returned is only valid until the next method which returns a const char * is called.

All methods are virtual and abstract, thus these classes are really abstract base classes. Therefore you cannot simply store the object directly. In order to make copies of the objects use the clone and assign methods if they are provided.

For the details of the various classes please see the header files. In the future I will generate class references using some automated tool.

4.4 Available Options

The following options are available to control which word list Pspell selects.

language-tag <string> the language code which consists of the two letter ISO 639 language code and an optional two letter ISO 3166 country code after a dash or underscore. spelling <string> the requested spelling for languages with more than one spelling such as En-

glish. Known values are “american”, “britsh”, and “canadian”. This information is normally inferred from the language-tag option. For example the language tag “en_GB” will set spelling to “british”.

jargon <string> an extra information to distinguish two different words lists that have the same language-tag and spelling.

word-list-path <list> search path for word list information files

module-search-order <list> list of available modules, modules that come first on this list have a higher priority

The following options control the behavior of the selected module. Not all modules support all options.

encoding <string> encoding that words are expected to be in. Valid values are “utf-8”, “iso8859- *”, “koi8-r”, “viscii”, “cp1252”, “machine unsigned 16”, “machine unsigned 32”.

ignore <int> ignore all words which are not at least as long as the value for this setting

personal <file> file name of the personal word list to use. Start it with “./” to look for the file in the current directory rather than the home directory.

repl <file> file name of the replacement word list to use. Start it with “./” to look for the file in the current directory rather than the home directory.

save-repl <boolean> save the replacement word list on calls to save_all_word_lists.

ignore-repl <boolean> ignore calls to Manager::store_replacement.

sug-mode <string> the suggestion mode, known values are fast, normal, and bad-spellers

run-together <boolean> consider run-together words as legal compounds.

The following options may be examined to tell exactly what word list or module was selected

master the full path of the word list selected

master-flags any special flags that were passed on to the module

module the module selected

The options, spelling and jargon can also be examined.

<string> options may be set to anything, including in some cases an empty string. <int> options must be set to a valid integer string. <boolean> options must be set to “true” or “false”. <list> options can not be set directly, you must use the option add-<option> to add an item to the list, rem-<option> to remove an item, or rem-all-<option> to remove all the items. In the case of rem-all-<option> the value should be an empty string. Although the standard retrieve method will work for a string, it should not be used as the format of the string is implementation dependent. Use the retrieve_list method instead.

4.5 Format of the PWLI Files

In order for Pspell to know which word lists to use each word list must have at least one PWLI file in the pspell data directory which is normally /usr/local/share/pspell/, use “pspell-config pkgdatadir” to find out what it is on your system.

Each PWLI has the the following name:

<language>[-[<spelling>][-<jargon>]]-<module>.pwli

Where <language> is the two letter language code, <spelling> is the particular spelling your interested in if the languages has multiple spelling in different parts of the world such as English, <jargon> is any extra informations to distinguish the word list from other ones with the same language and spelling, and <module> is the pspell module the main word list is for.

For example:

en-aspell.pwli

en-american-aspell.pwli

en-american-medical-ispell.pwli en-american-xlg-ispell.pwli de--medical-ispell.pwli

Notice how if the spelling is left out but the jargon is not there needs to be two dashes between the language and the jargon.

Each PWLI file then contains exactly one line which contains the full path of the main word list, white space, then any additional options to pass onto the module.

4.6 Examples

Two simple examples are included in the examples directory. Pspell must be installed before they will compile and at least one pspell module must be installed before they will run. To build the C example type “make example-c” and to build the C++ examples type “make example-cxx”.

4.7 Rational

4.7.1 store_repl method

This method is needed because Aspell (http://aspell.sourceforge.net/) is able to learn from users misspellings. For example on the first pass a user misspells beginning as beging so aspell suggests:

begging, begin, being, Beijing, bagging, ....

However the user then tries "begning" and aspell suggests

beginning, beaning, begging, ...

so the user selects beginning. However than, latter on in the document the user misspelles it as begng (NOT beging). Normally aspell will suggest.

CHAPTER 4. LIBRARY INTERFACE 12

began, begging, begin, begun, .... However becuase it knows the user mispelled beginning as beging it will instead suggest:

beginning, began, begging, begin, begun ... I myself often misspelled beginning (and still do) as something close to begging and two many times wind up writing sentences such as "begging with ....".

Status

5.1 Current

This version of Pspell is still incomplete.

The PspellMutableWordList and STL like helper classes are nonexistent and building of the shared libraries does not work nearly as well as it should.

5.2 Future

Future version of this library will of course be more complete.

Future versions of the interface will provide better support for multi-lingual documents as well as methods for spell checking whole regions of text. Letting the spell checker check whole region of text will allow the spell checker to skip over formating commands, URLs, and the like.

I also plan on coming up with a Pspell utility that will, among other things, function as a drop in replacement for “ispell -a” so that Pspell can be used in place of Ispell.

Chapter 6

Feedback

As always feedback is most appreciated. I can be contacted at kevina@users.sourceforge.net.

Changelog

Changes from .12.1 to .12.2 (May 29, 2001)

• Portibility fixes to allow Pspell to compile with older compilers.

• Added a hack to deal with Libtool’s interdependencies problem. See bug #416981 for more info.

• Added the configure option AM_MAINTAINER_MODE to avoid enableing rules which often causes generated build files to be rebuild with the wrong version of libtool by default. I don’t know why I didn’t think to do this a long time ago.

Changes from .12 to .12.1 (April 5, 2001)

• Added a hack to that Pspell will properly compile as a shared library under Solaris.

• Fixed a problem on Win32 which involves path names which begin with <Drive Letter>:.

• Removed excuse semicolon (;) after “#endif” in one of the header files.

Changes from .11.2 to .12 (January 28, 2001)

• Added a length parameter to many Pspell functions which should cut down on unnecessary copying of words with some programs that use Pspell. Unfortunately this also breaks sourcecode compatibility. But it is easy to fix, see section 2.3.4 for what to do.

• Added support for mapping the county code to a spelling for the English language. For example the language tag “en_GB” will now get the British dictionary if it is available.

• Rewrote the “Usage” section of the manual to use the C interface instead of the C++ one as I recommend using the C interface even in C++ code to avoid some of the nasty issues associated with C++ linkage.

• Libltdl is now enabled by default.

• Switched to the multi-language branch of libtool.

• Added support for iso-8859-13 and 14.

• Fixed a memory leak in PspellStringMap which fixes a bug #126245 reported for Aspell.

• Bug fixes.

CHAPTER 7. CHANGELOG 16

Changes from .11.1 to .11.2 (August 19, 2000)

• Changed my email from kevinatk@home.com to kevina@users.sourceforge.net please make a note of the new email address.

• Added the “repl”, “save-repl”, “ignore-repl” options.

Changes from .11.0.2 to .11.1 (August 3, 2000)

• Compile fixes for better C++ compliance and less warning when compiled with -Wall.

• Fixed some bug in the configuration classes which caused aspell’s dont-strip-accents not to work when specified on the command line.

• Added “personal” option to change the personal word list.

Changes from .11.0.1 to .11.0.2 (June 18, 2000)

• Compile fixes so pspell will compile with the very latest gcc version (CVS Version)

• Included libltdl so it will compile with --enable-ltdl

Changes from .11 to .11.0.1 (June 11, 2000)

• Fixed a bug in PspellConfigImpl::merge that caused the Aspell module to core dump.

Changes from .10 to .11 (June 11, 2000)

• Added support for searching for the word list to use based on the language, and other information. This included support for other modules other than Aspell.

• Added support for linking modules in a compile time so that Pspell will also work with static libraries and on system where libltdl does not work.

• Temporary disabled using the libltdl library as it will only work well with C++ libraries on Linux. This means that all modules must be linked in at compile time using the “./addmodules” script. If you want to enable it use “--enable-ltdl” when running configure.

• Added support for non “iso-8859-1” encodings. The “machine unsigned 16” and “machine unsigned 32” encoding are still untested however.

• Switched to the HEAD branch of libtool as the multi-language branch was causing too many problems.

• Fixed it so that the manual will install in the correct location.

• Bug Fixes.

Changes to .10 (April 2, 2000)

• Initial release.

Copyright

Copyrighted 2001 by Kevin Atkinson under the LGPL. Certain parts of the library, as indicated at the top of the source file, may be under a weaker license. Individual modules are under there own independent license.

8.1 LGPL

GNU LIBRARY GENERAL PUBLIC LICENSE Version 2, June 1991

Copyright (C) 1991 Free Software Foundation, Inc.

59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

[This is the first released version of the library GPL. It is numbered 2 because it goes with version 2 of the ordinary GPL.]

Preamble

The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public Licenses are intended to guarantee your freedom to share and change free software — to make sure the software is free for all its users.

This license, the Library General Public License, applies to some specially designated Free Software Foundation software, and to any other libraries whose authors decide to use it. You can use it for your libraries, too.

When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.

To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the library, or if you modify it.

For example, if you distribute copies of the library, whether gratis or for a fee, you must give the recipients all the rights that we gave you. You must make sure that they, too, receive or can get the source code. If you link a program with the library, you must provide complete object files to the recipients so that they can relink them with the library, after making changes to the library and recompiling it. And you must show them these terms so they know their rights.

Our method of protecting your rights has two steps: (1) copyright the library, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the library.

Also, for each distributor’s protection, we want to make certain that everyone understands that there is no warranty for this free library. If the library is modified by someone else and passed on, we want its recipients to know that what they have is not the original version, so that any problems introduced by others will not reflect on the original authors’ reputations.

Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that companies distributing free software will individually obtain patent licenses, thus in effect transforming the program into proprietary software. To prevent this, we have made it clear that any patent must be licensed for everyone’s free use or not licensed at all.

Most GNU software, including some libraries, is covered by the ordinary GNU General Public License, which was designed for utility programs. This license, the GNU Library General Public License, applies to certain designated libraries. This license is quite different from the ordinary one; be sure to read it in full, and don’t assume that anything in it is the same as in the ordinary license.

The reason we have a separate public license for some libraries is that they blur the distinction we usually make between modifying or adding to a program and simply using it. Linking a program with a library, without changing the library, is in some sense simply using the library, and is analogous to running a utility program or application program. However, in a textual and legal sense, the linked executable is a combined work, a derivative of the original library, and the ordinary General Public License treats it as such.

Because of this blurred distinction, using the ordinary General Public License for libraries did not effectively promote software sharing, because most developers did not use the libraries. We concluded that weaker conditions might promote sharing better.

However, unrestricted linking of non-free programs would deprive the users of those programs of all benefit from the free status of the libraries themselves. This Library General Public License is intended to permit developers of non-free programs to use free libraries, while preserving your freedom as a user of such programs to change the free libraries that are incorporated in them. (We have not seen how to achieve this as regards changes in header files, but we have achieved it as regards changes in the actual functions of the Library.) The hope is that this will lead to faster development of free libraries.

The precise terms and conditions for copying, distribution and modification follow. Pay close attention to the difference between a "work based on the library" and a "work that uses the library". The former contains code derived from the library, while the latter only works together with the library.

Note that it is possible for a library to be covered by the ordinary General Public License rather than by this special one.

GNU LIBRARY GENERAL PUBLIC LICENSE TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

0. This License Agreement applies to any software library which contains a notice placed by the copyright holder or other authorized party saying it may be distributed under the terms of this Library General Public License (also called "this License"). Each licensee is addressed as "you".

A "library" means a collection of software functions and/or data prepared so as to be conveniently linked with application programs (which use some of those functions and data) to form executables.

The "Library", below, refers to any such software library or work which has been distributed under these terms. A "work based on the Library" means either the Library or any derivative work under copyright law: that is to say, a work containing the Library or a portion of it, either verbatim or with modifications and/or translated straightforwardly into another language. (Hereinafter, translation is included without limitation in the term "modification".)

"Source code" for a work means the preferred form of the work for making modifications to it. For a library, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the library.

Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running a program using the Library is not restricted, and output from such a program is covered only if its contents constitute a work based on the Library (independent of the use of the Library in a tool for writing it). Whether that is true depends on what the Library does and what the program that uses the Library does. 1. You may copy and distribute verbatim copies of the Library’s complete source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and distribute a copy of this License along with the Library.

You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.

2. You may modify your copy or copies of the Library or any portion of it, thus forming a work based on the Library, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:

a) The modified work must itself be a software library.

b) You must cause the files modified to carry prominent notices stating that you changed the files and the date of any change.

c) You must cause the whole of the work to be licensed at no charge to all third parties under the terms of this License.

d) If a facility in the modified Library refers to a function or a table of data to be supplied by an application program that uses the facility, other than as an argument passed when the facility is invoked, then you must make a good faith effort to ensure that, in the event an application does not supply such function or table, the facility still operates, and performs whatever part of its purpose remains meaningful.

(For example, a function in a library to compute square roots has a purpose that is entirely welldefined independent of the application. Therefore, Subsection 2d requires that any applicationsupplied function or table used by this function must be optional: if the application does not supply it, the square root function must still compute square roots.)

These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Library, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Library, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.

Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Library.

In addition, mere aggregation of another work not based on the Library with the Library (or with a work based on the Library) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.

3. You may opt to apply the terms of the ordinary GNU General Public License instead of this License to a given copy of the Library. To do this, you must alter all the notices that refer to this License, so that they refer to the ordinary GNU General Public License, version 2, instead of to this License. (If a newer version than version 2 of the ordinary GNU General Public License has appeared, then you can specify that version instead if you wish.) Do not make any other change in these notices.

Once this change is made in a given copy, it is irreversible for that copy, so the ordinary GNU General Public License applies to all subsequent copies and derivative works made from that copy.

This option is useful when you wish to copy part of the code of the Library into a program that is not a library.

4. You may copy and distribute the Library (or a portion or derivative of it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange.

If distribution of object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place satisfies the requirement to distribute the source code, even though third parties are not compelled to copy the source along with the object code.

5. A program that contains no derivative of any portion of the Library, but is designed to work with the Library by being compiled or linked with it, is called a "work that uses the Library". Such a work, in isolation, is not a derivative work of the Library, and therefore falls outside the scope of this License.

However, linking a "work that uses the Library" with the Library creates an executable that is a derivative of the Library (because it contains portions of the Library), rather than a "work that uses the library". The executable is therefore covered by this License. Section 6 states terms for distribution of such executables.

When a "work that uses the Library" uses material from a header file that is part of the Library, the object code for the work may be a derivative work of the Library even though the source code is not. Whether this is true is especially significant if the work can be linked without the Library, or if the work is itself a library. The threshold for this to be true is not precisely defined by law.

If such an object file uses only numerical parameters, data structure layouts and accessors, and small macros and small inline functions (ten lines or less in length), then the use of the object file is unrestricted, regardless of whether it is legally a derivative work. (Executables containing this object code plus portions of the Library will still fall under Section 6.)

Otherwise, if the work is a derivative of the Library, you may distribute the object code for the work under the terms of Section 6. Any executables containing that work also fall under Section 6, whether or not they are linked directly with the Library itself.

6. As an exception to the Sections above, you may also compile or link a "work that uses the Library" with the Library to produce a work containing portions of the Library, and distribute that work under terms of your choice, provided that the terms permit modification of the work for the customer’s own use and reverse engineering for debugging such modifications.

You must give prominent notice with each copy of the work that the Library is used in it and that the Library and its use are covered by this License. You must supply a copy of this License. If the work during execution displays copyright notices, you must include the copyright notice for the Library among them, as well as a reference directing the user to the copy of this License. Also, you must do one of these things:

a) Accompany the work with the complete corresponding machine-readable source code for the Library including whatever changes were used in the work (which must be distributed under Sections 1 and 2 above); and, if the work is an executable linked with the Library, with the complete machine-readable "work that uses the Library", as object code and/or source code, so that the user can modify the Library and then relink to produce a modified executable containing the modified Library. (It is understood that the user who changes the contents of definitions files in the Library will not necessarily be able to recompile the application to use the modified definitions.)

b) Accompany the work with a written offer, valid for at least three years, to give the same user the materials specified in Subsection 6a, above, for a charge no more than the cost of performing this distribution.

c) If distribution of the work is made by offering access to copy from a designated place, offer equivalent access to copy the above specified materials from the same place.

d) Verify that the user has already received a copy of these materials or that you have already sent this user a copy.

For an executable, the required form of the "work that uses the Library" must include any data and utility programs needed for reproducing the executable from it. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.

It may happen that this requirement contradicts the license restrictions of other proprietary libraries that do not normally accompany the operating system. Such a contradiction means you cannot use both them and the Library together in an executable that you distribute.

7. You may place library facilities that are a work based on the Library side-by-side in a single library together with other library facilities not covered by this License, and distribute such a combined library, provided that the separate distribution of the work based on the Library and of the other library facilities is otherwise permitted, and provided that you do these two things:

a) Accompany the combined library with a copy of the same work based on the Library, uncombined with any other library facilities. This must be distributed under the terms of the Sections above.

b) Give prominent notice with the combined library of the fact that part of it is a work based on the Library, and explaining where to find the accompanying uncombined form of the same work.

8. You may not copy, modify, sublicense, link with, or distribute the Library except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, link with, or distribute the Library is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

9. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Library or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Library (or any work based on the Library), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Library or works based on it.

10. Each time you redistribute the Library (or any work based on the Library), the recipient automatically receives a license from the original licensor to copy, distribute, link with or modify the Library subject to these terms and conditions. You may not impose any further restrictions on the recipients’ exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License.

11. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Library at all. For example, if a patent license would not permit royalty-free redistribution of the Library by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Library.

If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply, and the section as a whole is intended to apply in other circumstances.

It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.

This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.

12. If the distribution and/or use of the Library is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Library under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.

13. The Free Software Foundation may publish revised and/or new versions of the Library General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.

Each version is given a distinguishing version number. If the Library specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Library does not specify a license version number, you may choose any version ever published by the Free Software Foundation.

14. If you wish to incorporate parts of the Library into other free programs whose distribution conditions are incompatible with these, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.

NO WARRANTY

15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY KIND, EI-THER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRIT-ING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUEN-TIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE LIBRARY (IN-CLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INAC-CURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

END OF TERMS AND CONDITIONS

How to Apply These Terms to Your New Libraries

If you develop a new library, and you want it to be of the greatest possible use to the public, we recommend making it free software that everyone can redistribute and change. You can do so by permitting redistribution under these terms (or, alternatively, under the terms of the ordinary General Public License).

To apply these terms, attach the following notices to the library. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found.

<one line to give the library’s name and a brief idea of what it does.> Copyright (C) <year> <name of author>

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WAR-RANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details.

You should have received a copy of the GNU Library General Public License along with this library; if not, write to the Free Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

Also add information on how to contact you by electronic and paper mail.

You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the library, if necessary. Here is a sample; alter the names:

Yoyodyne, Inc., hereby disclaims all copyright interest in the library ‘Frob’ (a library for tweaking knobs) written by James Random Hacker.

<signature of Ty Coon>, 1 April 1990 Ty Coon, President of Vice

That’s all there is to it!