Migrate to S4 Classes
Change-Id: I27e9452e9d59f6b414898390074908ec0e91e2a9
diff --git a/man/KorAPConnection-class.Rd b/man/KorAPConnection-class.Rd
new file mode 100644
index 0000000..2c4c60e
--- /dev/null
+++ b/man/KorAPConnection-class.Rd
@@ -0,0 +1,43 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/KorAPConnection.R
+\docType{class}
+\name{KorAPConnection-class}
+\alias{KorAPConnection-class}
+\alias{KorAPConnection}
+\alias{initialize,KorAPConnection-method}
+\alias{show,KorAPConnection-method}
+\title{Class KorAPConnection}
+\usage{
+\S4method{initialize}{KorAPConnection}(.Object,
+ KorAPUrl = "https://korap.ids-mannheim.de/", apiVersion = "v1.0",
+ apiUrl)
+
+\S4method{show}{KorAPConnection}(object)
+}
+\arguments{
+\item{.Object}{KorAPConnection object}
+
+\item{KorAPUrl}{the URL of the KorAP server instance you want to access.}
+
+\item{apiVersion}{which version of KorAP's API you want to connect to.}
+
+\item{apiUrl}{URL of the KorAP web service.}
+
+\item{object}{KorAPConnection object}
+}
+\value{
+\code{\link{KorAPConnection}} object that can be used e.g. with \code{\link{corpusQuery}}
+}
+\description{
+\code{KorAPConnection} objetcs represent the connection to a KorAP server.
+New \code{KorAPConnection} objects can be created by \code{KorAPConnection()}
+}
+\note{
+Currently it is not possible to authenticate the client
+}
+\examples{
+kcon <- new("KorAPConnection")
+kq <- corpusQuery(kcon, "Ameisenplage")
+kq <- fetchAll(kq, verbose=TRUE)
+
+}
diff --git a/man/KorAPConnection.Rd b/man/KorAPConnection.Rd
deleted file mode 100644
index 1fb436f..0000000
--- a/man/KorAPConnection.Rd
+++ /dev/null
@@ -1,25 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/KorAPConnection.R
-\name{KorAPConnection}
-\alias{KorAPConnection}
-\title{Connect to a KorAP server.}
-\usage{
-KorAPConnection(KorAPUrl = defaultKorAPUrl, apiVersion = "v1.0",
- apiUrl)
-}
-\arguments{
-\item{KorAPUrl}{instead of providing the query and vc string parameters, you can also simply copy a KorAP query URL from your browser and use it here (and in \code{KorAPConnection}) to provide all necessary information for the query.}
-
-\item{apiVersion}{which version of KorAP's API you want to connect to}
-
-\item{apiUrl}{url of the KorAP web service}
-}
-\value{
-object that contains all connection information and can be used with \code{\link{KorAPQuery}}
-}
-\description{
-Connect to a KorAP server.
-}
-\note{
-Currently it is not possible to authenticate the client
-}
diff --git a/man/KorAPCorpusStats-class.Rd b/man/KorAPCorpusStats-class.Rd
new file mode 100644
index 0000000..4b8b98a
--- /dev/null
+++ b/man/KorAPCorpusStats-class.Rd
@@ -0,0 +1,31 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/KorAPCorpusStats.R
+\docType{class}
+\name{KorAPCorpusStats-class}
+\alias{KorAPCorpusStats-class}
+\alias{show,KorAPCorpusStats-method}
+\title{Class KorAPCorpusStats}
+\usage{
+\S4method{show}{KorAPCorpusStats}(object)
+}
+\arguments{
+\item{object}{KorAPCorpusStats object}
+}
+\description{
+\code{KorAPCorpusStats} objetcs can hold information about a corpus or virtual corpus.
+\code{KorAPCorpusStats} objects can be obtained by the \code{\link{corpusStats}()} method.
+}
+\section{Slots}{
+
+\describe{
+\item{\code{vc}}{definition of the virtual corpus}
+
+\item{\code{tokens}}{number of tokens}
+
+\item{\code{documents}}{number of documents}
+
+\item{\code{sentences}}{number of sentences}
+
+\item{\code{paragraphs}}{number of paragraphs}
+}}
+
diff --git a/man/KorAPCorpusStats.Rd b/man/KorAPCorpusStats.Rd
deleted file mode 100644
index 71066b2..0000000
--- a/man/KorAPCorpusStats.Rd
+++ /dev/null
@@ -1,21 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/KorAPCorpusStats.R
-\name{KorAPCorpusStats}
-\alias{KorAPCorpusStats}
-\title{Fetch information about a (virtual) corpus}
-\usage{
-KorAPCorpusStats(con, vc, query)
-}
-\arguments{
-\item{con}{object obtained from \code{\link{KorAPConnection}}}
-
-\item{vc}{string describing the virtual corpus. An empty string (default) means the whole corpus, as far as it is license-wise accessible.}
-
-\item{query}{object returned from \code{\link{KorAPQuery}}}
-}
-\value{
-object with the fields \code{$documents}, \code{$tokens}, \code{$sentences}, \code{$paragraphs}
-}
-\description{
-Fetch information about a (virtual) corpus
-}
diff --git a/man/KorAPFetchAll.Rd b/man/KorAPFetchAll.Rd
deleted file mode 100644
index 21b7036..0000000
--- a/man/KorAPFetchAll.Rd
+++ /dev/null
@@ -1,30 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/KorAPQuery.R
-\name{KorAPFetchAll}
-\alias{KorAPFetchAll}
-\title{Fetch all results of a KorAP query.}
-\usage{
-KorAPFetchAll(queryObject, verbose = FALSE)
-}
-\arguments{
-\item{queryObject}{object obtained from \code{\link{KorAPQuery}}}
-
-\item{verbose}{print progress information if true}
-}
-\value{
-The \code{queryObject} input parameter with updated fields \code{$collectedMatches}, \code{$matches} (latest bunch only), \code{$nextStartIndex}, \code{$hasMoreMatches}
-}
-\description{
-Fetch all results of a KorAP query.
-}
-\examples{
-q <- KorAPFetchAll(KorAPQuery(KorAPConnection(), "Ameisenplage"))
-q$collectedMatches
-
-}
-\references{
-\url{https://ids-pub.bsz-bw.de/frontdoor/index/index/docId/9026}
-}
-\seealso{
-\code{\link{KorAPFetchRest}}, \code{\link{KorAPFetchNext}}
-}
diff --git a/man/KorAPFetchNext.Rd b/man/KorAPFetchNext.Rd
deleted file mode 100644
index 66f8aa9..0000000
--- a/man/KorAPFetchNext.Rd
+++ /dev/null
@@ -1,34 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/KorAPQuery.R
-\name{KorAPFetchNext}
-\alias{KorAPFetchNext}
-\title{Fetch the next bunch of results of a KorAP query.}
-\usage{
-KorAPFetchNext(queryObject, offset = queryObject$nextStartIndex,
- maxFetch = maxResultsPerPage, verbose = FALSE)
-}
-\arguments{
-\item{queryObject}{object obtained from \code{\link{KorAPQuery}}}
-
-\item{offset}{start offset for query results to fetch}
-
-\item{maxFetch}{maximum number of query results to fetch}
-
-\item{verbose}{print progress information if true}
-}
-\value{
-The \code{queryObject} input parameter with updated fields \code{$collectedMatches}, \code{$matches} (latest bunch only), \code{$nextStartIndex}, , \code{$hasMoreMatches}
-}
-\description{
-Fetch the next bunch of results of a KorAP query.
-}
-\examples{
-q <- KorAPFetchNext(KorAPQuery(KorAPConnection(), "Ameisenplage"))
-
-}
-\references{
-\url{https://ids-pub.bsz-bw.de/frontdoor/index/index/docId/9026}
-}
-\seealso{
-\code{\link{KorAPFetchRest}}, \code{\link{KorAPFetchAll}}
-}
diff --git a/man/KorAPFetchRest.Rd b/man/KorAPFetchRest.Rd
deleted file mode 100644
index a9d4f03..0000000
--- a/man/KorAPFetchRest.Rd
+++ /dev/null
@@ -1,30 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/KorAPQuery.R
-\name{KorAPFetchRest}
-\alias{KorAPFetchRest}
-\title{Fetches all remaining results of a KorAP query.}
-\usage{
-KorAPFetchRest(queryObject, verbose = FALSE)
-}
-\arguments{
-\item{queryObject}{object obtained from \code{\link{KorAPQuery}}}
-
-\item{verbose}{print progress information if true}
-}
-\value{
-The \code{queryObject} input parameter with updated fields \code{$collectedMatches}, \code{$matches} (latest bunch only), \code{$nextStartIndex}, \code{$hasMoreMatches}
-}
-\description{
-Fetches all remaining results of a KorAP query.
-}
-\examples{
-q <- KorAPFetchRest(KorAPFetchNext(KorAPQuery(KorAPConnection(), "Ameisenplage")))
-q$collectedMatches
-
-}
-\references{
-\url{https://ids-pub.bsz-bw.de/frontdoor/index/index/docId/9026}
-}
-\seealso{
-\code{\link{KorAPFetchAll}}, \code{\link{KorAPFetchNext}}
-}
diff --git a/man/KorAPQuery-class.Rd b/man/KorAPQuery-class.Rd
new file mode 100644
index 0000000..68d8907
--- /dev/null
+++ b/man/KorAPQuery-class.Rd
@@ -0,0 +1,90 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/KorAPQuery.R
+\docType{class}
+\name{KorAPQuery-class}
+\alias{KorAPQuery-class}
+\alias{KorAPQuery}
+\alias{initialize,KorAPQuery-method}
+\alias{fetchNext,KorAPQuery-method}
+\alias{fetchNext}
+\alias{fetchAll,KorAPQuery-method}
+\alias{fetchAll}
+\alias{fetchRest,KorAPQuery-method}
+\alias{fetchRest}
+\alias{format.KorAPQuery}
+\alias{show,KorAPQuery-method}
+\title{Class KorAPQuery}
+\usage{
+\S4method{initialize}{KorAPQuery}(.Object, request = NULL, vc = "",
+ totalResults = 0, nextStartIndex = 0, fields = c("corpusSigle",
+ "textSigle", "pubDate", "pubPlace", "availability", "textClass",
+ "snippet"), requestUrl = "", webUIRequestUrl = "",
+ apiResponse = NULL, hasMoreMatches = FALSE,
+ collectedMatches = NULL)
+
+\S4method{fetchNext}{KorAPQuery}(kqo, offset = kqo@nextStartIndex,
+ maxFetch = maxResultsPerPage, verbose = FALSE)
+
+\S4method{fetchAll}{KorAPQuery}(kqo, verbose = FALSE)
+
+\S4method{fetchRest}{KorAPQuery}(kqo, verbose = FALSE)
+
+\method{format}{KorAPQuery}(x, ...)
+
+\S4method{show}{KorAPQuery}(object)
+}
+\arguments{
+\item{.Object}{…}
+
+\item{request}{query part of the request URL}
+
+\item{vc}{definition of a virtual corpus}
+
+\item{totalResults}{number of hits the query has yielded}
+
+\item{nextStartIndex}{at what index to start the next fetch of query results}
+
+\item{fields}{what data / metadata fields should be collected}
+
+\item{requestUrl}{complete URL of the API request}
+
+\item{webUIRequestUrl}{URL of a web frontend request corresponding to the API request}
+
+\item{apiResponse}{data-frame representation of the JSON response of the API request}
+
+\item{hasMoreMatches}{boolean that signals if more query results can be fetched}
+
+\item{collectedMatches}{matches already fetched from the KorAP-API-server}
+
+\item{kqo}{object obtained from \code{\link{corpusQuery}}}
+
+\item{offset}{start offset for query results to fetch}
+
+\item{maxFetch}{maximum number of query results to fetch}
+
+\item{verbose}{print progress information if true}
+
+\item{x}{KorAPQuery object}
+
+\item{...}{further arguments passed to or from other methods}
+
+\item{object}{KorAPQuery object}
+}
+\value{
+The \code{kqo} input object with updated slots \code{collectedMatches}, \code{apiResponse}, \code{nextStartIndex}, \code{hasMoreMatches}
+}
+\description{
+\code{KorAPQuery} objetcs represent the current state of a query to a KorAP server.
+New \code{KorAPQuery} objects are typically created by the \code{\link{corpusQuery}} method.
+}
+\examples{
+q <- fetchAll(corpusQuery(new("KorAPConnection"), "Ameisenplage"))
+q@collectedMatches
+
+q <- fetchRest(fetchNext(corpusQuery(new("KorAPConnection"), "Ameisenplage")))
+q@collectedMatches
+
+}
+\references{
+\url{https://ids-pub.bsz-bw.de/frontdoor/index/index/docId/9026}
+}
diff --git a/man/KorAPQuery.Rd b/man/KorAPQuery.Rd
deleted file mode 100644
index 1f50a83..0000000
--- a/man/KorAPQuery.Rd
+++ /dev/null
@@ -1,62 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/KorAPQuery.R
-\name{KorAPQuery}
-\alias{KorAPQuery}
-\title{Send a query to a KorAP connection.}
-\usage{
-KorAPQuery(con, query, vc = "", KorAPUrl, metadataOnly = TRUE,
- ql = "poliqarp", fields = defaultFields, accessRewriteFatal = TRUE,
- verbose = FALSE)
-}
-\arguments{
-\item{con}{object obtained from \code{\link{KorAPConnection}}, that contains all necessary connection information}
-
-\item{query}{string that contains the corpus query. The query langauge depends on the \code{ql} parameter. Either \code{query} must be provided or \code{KorAPUrl}}
-
-\item{vc}{string describing the virtual corpus in which the query should be performed. An empty string (default) means the whole corpus, as far as it is license-wise accessible.}
-
-\item{KorAPUrl}{instead of providing the query and vc string parameters, you can also simply copy a KorAP query URL from your browser and use it here (and in \code{KorAPConnection}) to provide all necessary information for the query.}
-
-\item{metadataOnly}{boolean that determines whether queries should return only metadata without any snippets. This can also be useful to prevent access rewrites. Note that the default value is TRUE, unless the connection is authorized (currently not possible).}
-
-\item{ql}{string to choose the query language (see \href{https://github.com/KorAP/Kustvakt/wiki/Service:-Search-GET#user-content-parameters}{section on Query Parameters} in the Kustvakt-Wiki for possible values.}
-
-\item{fields}{(meta)data fields that will be fetched for every match}
-
-\item{accessRewriteFatal}{abort if query or given vc had to be rewritten due to insufficent rights (not yet implemented)}
-
-\item{verbose}{print some info}
-}
-\value{
-A KorAP query object that, among other information, contains the total number of results in \code{$meta$totalResults}. The resulting object can be used to fetch all query results (with \code{\link{KorAPFetchAll}}) or the next page of results (with \code{\link{KorAPFetchNext}}).
-A correspunding URL to be used within a web browser is contained in \code{$webUIRequestUrl}
-Please make sure to check \code{$collection$rewrites} to see if any unforseen access rewrites of the query's virtual corpus had to be performed.
-}
-\description{
-Send a query to a KorAP connection.
-}
-\examples{
-con <- KorAPConnection()
-q <- KorAPQuery(con, "Ameisenplage")
-q <- KorAPFetchAll(q)
-summary(q$collectedMatches)
-
-q <- KorAPQuery(con,
- KorAPUrl = "https://korap.ids-mannheim.de/?q=Ameise&cq=pubDate+since+2017&ql=poliqarp")
-q$meta$totalResults
-
-q <- KorAPQuery(con, "Ameisenplage")
-q <- KorAPFetchAll(q, verbose=TRUE)
-tokensPerYear <- function(year) { return(KorAPCorpusStats(con, paste("pubDate in", year))$tokens) }
-df <- as.data.frame(table(as.numeric(format(q$collectedMatches$pubDate,"\%Y")), dnn="year"),
- stringsAsFactors = FALSE)
-df$ipm <- 1000000 * df$Freq / tokensPerYear(df$year)
-plot(df$year, df$ipm, type="l")
-
-}
-\references{
-\url{https://ids-pub.bsz-bw.de/frontdoor/index/index/docId/9026}
-}
-\seealso{
-\code{\link{KorAPConnection}}, \code{\link{KorAPFetchNext}}, \code{\link{KorAPFetchRest}}, \code{\link{KorAPFetchAll}}, \code{\link{KorAPCorpusStats}}
-}
diff --git a/man/corpusQuery-KorAPConnection-method.Rd b/man/corpusQuery-KorAPConnection-method.Rd
new file mode 100644
index 0000000..04abc71
--- /dev/null
+++ b/man/corpusQuery-KorAPConnection-method.Rd
@@ -0,0 +1,64 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/KorAPQuery.R
+\docType{methods}
+\name{corpusQuery,KorAPConnection-method}
+\alias{corpusQuery,KorAPConnection-method}
+\alias{corpusQuery}
+\title{Method corpusQuery}
+\usage{
+\S4method{corpusQuery}{KorAPConnection}(kco, query, vc = "", KorAPUrl,
+ metadataOnly = TRUE, ql = "poliqarp", fields = defaultFields,
+ accessRewriteFatal = TRUE, verbose = FALSE)
+}
+\arguments{
+\item{kco}{\code{\link{KorAPConnection}} object (obtained e.g. from \code{new("KorAPConnection")}}
+
+\item{query}{string that contains the corpus query. The query langauge depends on the \code{ql} parameter. Either \code{query} must be provided or \code{KorAPUrl}}
+
+\item{vc}{string describing the virtual corpus in which the query should be performed. An empty string (default) means the whole corpus, as far as it is license-wise accessible.}
+
+\item{KorAPUrl}{instead of providing the query and vc string parameters, you can also simply copy a KorAP query URL from your browser and use it here (and in \code{KorAPConnection}) to provide all necessary information for the query.}
+
+\item{metadataOnly}{boolean that determines whether queries should return only metadata without any snippets. This can also be useful to prevent access rewrites. Note that the default value is TRUE, unless the connection is authorized (currently not possible).}
+
+\item{ql}{string to choose the query language (see \href{https://github.com/KorAP/Kustvakt/wiki/Service:-Search-GET#user-content-parameters}{section on Query Parameters} in the Kustvakt-Wiki for possible values.}
+
+\item{fields}{(meta)data fields that will be fetched for every match}
+
+\item{accessRewriteFatal}{abort if query or given vc had to be rewritten due to insufficent rights (not yet implemented)}
+
+\item{verbose}{print some info}
+}
+\value{
+A \code{\link{KorAPQuery}} object that, among other information, contains the total number of results in \code{@totalResults}. The resulting object can be used to fetch all query results (with \code{\link{fetchAll}}) or the next page of results (with \code{\link{fetchNext}}).
+A corresponding URL to be used within a web browser is contained in \code{@webUIRequestUrl}
+Please make sure to check \code{$collection$rewrites} to see if any unforseen access rewrites of the query's virtual corpus had to be performed.
+}
+\description{
+Perform a corpus query via a connection to a KorAP-API-server.
+}
+\examples{
+kco <- new("KorAPConnection")
+kqo <- corpusQuery(kco, "Ameisenplage")
+kqo <- fetchAll(kqo)
+kqo
+
+kqo <- corpusQuery(kco,
+ KorAPUrl = "https://korap.ids-mannheim.de/?q=Ameise&cq=pubDate+since+2017&ql=poliqarp")
+kqo
+
+q <- corpusQuery(kco, "Ameisenplage")
+q <- fetchAll(q, verbose=TRUE)
+tokensPerYear <- function(year) { return(corpusStats(kco, paste("pubDate in", year))@tokens) }
+df <- as.data.frame(table(as.numeric(format(q@collectedMatches$pubDate,"\%Y")), dnn="year"),
+ stringsAsFactors = FALSE)
+df$ipm <- 1000000 * df$Freq / tokensPerYear(df$year)
+plot(df$year, df$ipm, type="l")
+
+}
+\references{
+\url{https://ids-pub.bsz-bw.de/frontdoor/index/index/docId/9026}
+}
+\seealso{
+\code{\link{KorAPConnection}}, \code{\link{fetchNext}}, \code{\link{fetchRest}}, \code{\link{fetchAll}}, \code{\link{corpusStats}}
+}
diff --git a/man/corpusStats-KorAPConnection-method.Rd b/man/corpusStats-KorAPConnection-method.Rd
new file mode 100644
index 0000000..6a4ccc2
--- /dev/null
+++ b/man/corpusStats-KorAPConnection-method.Rd
@@ -0,0 +1,28 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/KorAPCorpusStats.R
+\docType{methods}
+\name{corpusStats,KorAPConnection-method}
+\alias{corpusStats,KorAPConnection-method}
+\alias{corpusStats}
+\title{Fetch information about a (virtual) corpus}
+\usage{
+\S4method{corpusStats}{KorAPConnection}(kco, vc = "")
+}
+\arguments{
+\item{kco}{\code{\link{KorAPConnection}} object (obtained e.g. from \code{new("KorAPConnection")}}
+
+\item{vc}{string describing the virtual corpus. An empty string (default) means the whole corpus, as far as it is license-wise accessible.}
+}
+\value{
+\code{KorAPCorpusStats} object with the slots \code{documents}, \code{tokens}, \code{sentences}, \code{paragraphs}
+}
+\description{
+Fetch information about a (virtual) corpus
+}
+\examples{
+corpusStats(new("KorAPConnection"))
+
+kco <- new("KorAPConnection")
+corpusStats(kco, "pubDate in 2017 & articleType=/Zeitung.*/")
+
+}