#+TITLE: SPELL: spellchecking library for Common Lisp.

* Introduction

  SPELL is a spellchecking library for Common Lisp. The code of this
  library is made available under the BSD license. The file
  file:data/english.txt is made available under the license in
  file:english.LICENSE.

  Loading (possibly after compiling) the ~spell~ system may initially
  take between something like 3 and 60 seconds, depending on the
  machine and CL implementation, as an English dictionary is loaded,
  optimized and compiled into a FASL file. Subsequent load operations
  (without compiling) should finish within well below one second.

  For loading the ~spell~ system, use

  #+begin_src lisp
    (ql:quickload "spell")
  #+end_src

  This document gives only a very brief overview and highlights some
  features. Proper documentation can be found in the
  file:documentation directory.

* Looking up Words

  The exported functions for looking up words are
  ~spell:english-lookup~ which accepts a string, and
  ~spell:english-check-paragraph~ which checks a whole paragraph of
  text and returns a list of conses:

  #+begin_src lisp :exports both
    (spell:english-lookup "horse")
  #+end_src

  #+RESULTS:
  #+begin_example
  (#<EXPLICIT-BASE-VERB "horse" person:ANY number:ANY tense:NIL negative:NIL contraction:NIL strength:WEAK infinitive:SELF {1001089AA3}>
   #<EXPLICIT-BASE-NOUN "horse" number:SINGULAR case:NIL gender:NIL {1001089A73}>)
  #+end_example

  #+begin_src lisp :exports both
    (spell:english-check-paragraph "In Polish, a horse is koń, and in German, it's
    das Pferd.")
  #+end_src

  #+RESULTS:
  #+begin_example
    ((22 . 25) (47 . 50) (51 . 56))
  #+end_example

  Each cons represents a single word in the paragraph which has failed
  dictionary lookup, with the ~car~ and ~cdr~ being offsets in the
  original string outlining the word.

* Obtaining Corrections

  The SPELL library exports a few functions that obtain similar words
  for a given word or corrections for a misspelled word. The most
  convenient function is ~spell:english-corrections~ which returns a
  list of corrections for a (possibly) misspelled English word;

  #+begin_src lisp :exports both :results value verbatim
    (spell:english-corrections "lifp" :threshold 1)
  #+end_src

  #+RESULTS:
  #+begin_example
    ("lift" "life" "lip" "lisp" "limp")
    NIL
  #+end_example

  For more ways to use this function as well as the information about
  the lower-level functions for similar words and corrections, see the
  main documentation.

* Backward Compatibility Notice

  The SPELL library provides the ~spell/simple~ ASDF system. The
  difference between the full and the simple version /used to be/ that
  the simple version answered only "does this word occur in the
  English dictionary?" with a boolean value, while the full version
  returns a list of all word meanings associated with that
  string. However, this difference no longer exists and the
  ~spell/simple~ system is now an alias for the ~spell~ system.

  The ~spell/simple~ system can still be loaded with

  #+begin_src lisp
    (ql:quickload "spell/simple")
  #+end_src

# Local Variables:
# eval: (load-library "ob-lisp")
# End: