The R Project SVN R

% File src/library/utils/man/aspell.Rd
% Part of the R package, https://www.R-project.org
% Copyright 1995-2025 R Core Team
% Distributed under GPL 2 or later

\name{aspell}
\alias{aspell}
\alias{aspell_filter_db}
\title{Spell Check Interface}
\description{
  Spell check given files via Aspell, Hunspell or Ispell.
}
\usage{
aspell(files, filter, control = list(), encoding = "unknown",
       program = NULL, dictionaries = character())

aspell_filter_db
}
\arguments{
  \item{files}{a character vector with the names of files to be checked.}
  \item{filter}{an optional filter for processing the files before spell
    checking, given as either a function (with formals \code{ifile} and
    \code{encoding}), or a character string specifying a built-in
    filter, or a list with the name of a built-in filter and additional
    arguments to be passed to it.  See \bold{Details} for available
    filters.  If missing or \code{NULL}, no filtering is performed.}
  \item{control}{a list or character vector of control options for the
    spell checker.}
  \item{encoding}{the encoding of the files.  Recycled as needed.}
  \item{program}{a character string giving the name (if on the system
    path) or full path of the spell check program to be used, or
    \code{NULL} (default).  By default, the system path is searched for
    \command{aspell}, \command{hunspell} and \command{ispell} (in that
    order), and the first one found is used.}
  \item{dictionaries}{a character vector of names or file paths of
    additional R level dictionaries to use.  Elements with no path
    separator specify R system dictionaries (in subdirectory
    \file{share/dictionaries} of the R home directory).  The file
    extension (currently, only \file{.rds}) can be omitted.}
}
\details{
  The spell check programs employed must support the so-called Ispell
  pipe interface activated via command line option \option{-a}.  In
  addition to the programs, suitable dictionaries need to be available.
  See \url{http://aspell.net},
  \url{https://hunspell.github.io/} and
  \url{https://www.cs.hmc.edu/~geoff/ispell.html}, respectively, for
  obtaining the Aspell, Hunspell and (International) Ispell programs and
  dictionaries.

  On Windows, Aspell is available via \abbr{MSYS2}.  One should use a non-\I{Cygwin}
  version, e.g.  package \code{mingw-w64-x86_64-aspell}.  The version built
  against the \I{Cygwin} runtime (package \code{aspell}) requires Unix line
  endings in files and Unix-style paths, which is incompatible with
  \code{aspell()}.

  The currently available built-in filters are \code{"Rd"}
  (corresponding to \code{\link{RdTextFilter}}, with additional argument
  \code{ignore} allowing to give regular expressions for parts of the
  text to be ignored for spell checking), \code{"Sweave"}
  (corresponding to \code{\link{SweaveTeXFilter}}), \code{"R"},
  \code{"pot"}, \code{"dcf"} and \code{"md"}.

  Filter \code{"R"} is for R code and extracts the message string
  constants in calls to \code{\link{message}}, \code{\link{warning}},
  \code{\link{stop}}, \code{\link{packageStartupMessage}},
  \code{\link{gettext}}, \code{\link{gettextf}}, and
  \code{\link{ngettext}} (the unnamed string constants for the first
  five, and \code{fmt} and \code{msg1}/\code{msg2} string constants,
  respectively, for the latter two).
  
  Filter \code{"pot"} is for message string catalog \file{.pot} files.
  Both have an argument \code{ignore} allowing to give regular
  expressions for parts of message strings to be ignored for spell
  checking: e.g., using \code{"[ \t]'[^']*'[ \t[:punct:]]"} ignores all
  text inside single quotes.

  Filter \code{"dcf"} is for files in Debian Control File format.
  The fields to keep can be controlled by argument \code{keep} (a
  character vector with the respective field names).  By default,
  \samp{Title} and \samp{Description} fields are kept.

  Filter \code{"md"} is for files in
  \href{https://en.wikipedia.org/wiki/Markdown}{Markdown} format
  (\file{.md} and \file{.Rmd} files), and needs packages
  \CRANpkg{commonmark} and \CRANpkg{xml2} to be available.

  Filter \code{"LaTeX"} is an experimental LaTeX filter which allows
  customized skipping of mandatory arguments to commands (similar to the
  LaTeX filter provided by Aspell) and skipping environments,
  controllable via arguments \code{cmds} and \code{envs}.
  This filter uses the LaTeX parser provided by
  \code{\link[tools]{parseLatex}()}.
  Argument \code{cmds} should be a character vector with elements of the
  form \code{"\var{NAME} \var{ARGS}"} with \code{\var{NAME}} the name of
  the command and \code{\var{ARGS}} a comma-separated list of either
  \samp{p} or \samp{P}, with \samp{p} indicating the mandatory arguments
  to be skipped.  The user-defined list given via \code{cmds} is
  combined with a built-in list of Aspell LaTeX filter defaults.
  Argument \code{envs} should be a character vector with the names of
  environments to be skipped.
  Argument \code{before} can be used to specify a function to be called
  for pre-processing the LaTeX source before calling the parser.
  All other arguments given to the filter are passed to the parser,
  which can be used in particular to customize the names of the commands
  and environments holding verbatim text.

  \code{aspell_filter_db} is an environment containing all available
  built-in filters.
  
  The print method for the objects returned by \code{aspell} has an
  \code{indent} argument controlling the indentation of the positions of
  possibly misspelled words.  The default is 2; Emacs users may find it
  useful to use an indentation of 0 and visit output in grep-mode.  It
  also has a \code{verbose} argument: when this is true, suggestions for
  replacements are shown as well.

  It is possible to employ additional R level dictionaries.  Currently,
  these are files with extension \file{.rds} obtained by serializing
  character vectors of word lists using \code{\link{saveRDS}}.  If such
  dictionaries are employed, they are combined into a single word list
  file which is then used as the spell checker's personal dictionary
  (option \option{-p}): hence, the default personal dictionary is not
  used in this case.
}
\value{
  A data frame inheriting from \code{aspell} (which has a useful print
  method) with the information about possibly misspelled words.
}
\references{
  \bibshow{R:Hornik+Murdoch:2011}
}
\seealso{
  \link{aspell-utils} for utilities for spell checking packages.

  %% Package \pkg{Aspell} formerly available from Omegahat
  %% (\url{http://www.omegahat.net/Aspell}) for a fine-grained R interface
  %% to the Aspell library.
}
\examples{
\dontrun{
## To check all Rd files in a directory, (additionally) skipping the
## \references sections.
files <- Sys.glob("*.Rd")
aspell(files, filter = list("Rd", drop = "\\\\references"))

## To check all Sweave files
files <- Sys.glob(c("*.Rnw", "*.Snw", "*.rnw", "*.snw"))
aspell(files, filter = "Sweave", control = "-t")

## To check all Texinfo files (Aspell only)
files <- Sys.glob("*.texi")
aspell(files, control = "--mode=texinfo")
}

## List the available R system dictionaries.
Sys.glob(file.path(R.home("share"), "dictionaries", "*.rds"))
}
\keyword{utilities}