% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/hunspell.R
\name{hunspell}
\alias{hunspell}
\alias{hunspell_find}
\alias{en_stats}
\alias{dicpath}
\alias{hunspell_parse}
\alias{hunspell_check}
\alias{hunspell_suggest}
\alias{hunspell_analyze}
\alias{hunspell_stem}
\alias{hunspell_info}
\alias{dictionary}
\alias{list_dictionaries}
\title{Hunspell Spell Checking and Morphological Analysis}
\usage{
hunspell(
  text,
  format = c("text", "man", "latex", "html", "xml"),
  dict = dictionary("en_US"),
  ignore = en_stats
)

hunspell_parse(
  text,
  format = c("text", "man", "latex", "html", "xml"),
  dict = dictionary("en_US")
)

hunspell_check(words, dict = dictionary("en_US"))

hunspell_suggest(words, dict = dictionary("en_US"))

hunspell_analyze(words, dict = dictionary("en_US"))

hunspell_stem(words, dict = dictionary("en_US"))

hunspell_info(dict = dictionary("en_US"))

dictionary(lang = "en_US", affix = NULL, add_words = NULL, cache = TRUE)

list_dictionaries()
}
\arguments{
\item{text}{character vector with arbitrary input text}

\item{format}{input format; supported parsers are \code{text}, \code{latex}, \code{man},
\code{xml} and \code{html}.}

\item{dict}{a dictionary object or string which can be passed to \code{\link{dictionary}}.}

\item{ignore}{character vector with additional approved words added to the dictionary}

\item{words}{character vector with individual words to spell check}

\item{lang}{dictionary file or language, see details}

\item{affix}{file path to corresponding affix file. If \code{NULL} it is
is assumed to be the same path as \code{dict} with extension \code{.aff}.}

\item{add_words}{a character vector of additional words to add to the dictionary}

\item{cache}{speed up loading of dictionaries by caching}
}
\description{
The \code{\link{hunspell}} function is a high-level wrapper for finding spelling
errors within a text document. It takes a character vector with text (\code{plain},
\code{latex}, \code{man}, \code{html} or \code{xml} format), parses out the words
and returns a list with incorrect words for each line. It effectively combines
\code{\link{hunspell_parse}} with \code{\link{hunspell_check}} in a single step.
Other functions in the package operate on individual words, see details.
}
\details{
Hunspell uses a special dictionary format that defines which stems and affixes are
valid in a given language. The \code{\link{hunspell_analyze}} function shows how a
word breaks down into a valid stem plus affix. The \code{\link{hunspell_stem}}
function is similar but only returns valid stems for a given word. Stemming can be
used to summarize text (e.g in a wordcloud). The \code{\link{hunspell_check}} function
takes a vector of individual words and tests each one for correctness. Finally
\code{\link{hunspell_suggest}} is used to suggest correct alternatives for each
(incorrect) input word.

Because spell checking is usually done on a document, the package includes some
parsers to extract words from various common formats. With \code{\link{hunspell_parse}}
we can parse plain-text, latex and man format. R also has a few built-in parsers
such as \code{\link[tools:RdTextFilter]{RdTextFilter}} and
\code{\link[tools:SweaveTeXFilter]{SweaveTeXFilter}}, see also
\code{\link[utils:aspell]{?aspell}}.

The package searches for dictionaries in the working directory as well as in the
standard system locations. \code{\link{list_dictionaries}} provides a list of all
dictionaries it can find. Additional search paths can be specified by setting
the \code{DICPATH} environment variable. A US English dictionary (\code{en_US}) is
included with the package; other dictionaries need to be installed by the system.
Most operating systems already include compatible dictionaries with names such as
\href{https://packages.debian.org/sid/hunspell-en-gb}{hunspell-en-gb} or
\href{https://packages.debian.org/sid/myspell-en-gb}{myspell-en-gb}.

To manually install dictionaries, copy the corresponding \code{.aff} and \code{.dic}
file to \code{~/Library/Spelling} or a custom directory specified in \code{DICPATH}.
Alternatively you can pass the entire path to the \code{.dic} file as the \code{dict}
parameter. Some popular sources of dictionaries are
\href{http://wordlist.aspell.net/dicts/}{SCOWL},
\href{https://www.mirrorservice.org/sites/download.openoffice.org/contrib/dictionaries/}{OpenOffice},
\href{http://archive.ubuntu.com/ubuntu/pool/main/libr/libreoffice-dictionaries/?C=S;O=D}{debian},
\href{https://github.com/titoBouzout/Dictionaries}{github/titoBouzout} or
\href{https://github.com/wooorm/dictionaries}{github/wooorm}.

Note that \code{hunspell} uses \code{\link{iconv}} to convert input text to
the encoding used by the dictionary. This will fail if \code{text} contains characters
which are unsupported by that particular encoding. For this reason UTF-8 dictionaries
are preferable over legacy 8-bit dictionaries.
}
\examples{
# Check individual words
words <- c("beer", "wiskey", "wine")
correct <- hunspell_check(words)
print(correct)

# Find suggestions for incorrect words
hunspell_suggest(words[!correct])

# Extract incorrect from a piece of text
bad <- hunspell("spell checkers are not neccessairy for langauge ninja's")
print(bad[[1]])
hunspell_suggest(bad[[1]])

# Stemming
words <- c("love", "loving", "lovingly", "loved", "lover", "lovely", "love")
hunspell_stem(words)
hunspell_analyze(words)

\donttest{
# Check an entire latex document
tmpfile <- file.path(tempdir(), "1406.4806v1.tar.gz")
download.file("https://arxiv.org/e-print/1406.4806v1", tmpfile,  mode = "wb")
untar(tmpfile, exdir = tempdir())
text <- readLines(file.path(tempdir(), "content.tex"), warn = FALSE)
bad_words <- hunspell(text, format = "latex")
sort(unique(unlist(bad_words)))

# Summarize text by stems (e.g. for wordcloud)
allwords <- hunspell_parse(text, format = "latex")
stems <- unlist(hunspell_stem(unlist(allwords)))
words <- head(sort(table(stems), decreasing = TRUE), 200)
}
}
