Add auth method to simplify (o)authorization
Change-Id: I318e27375dfece96d0d80f35cd2c2b5bb3b167df
diff --git a/man/KorAPConnection-class.Rd b/man/KorAPConnection-class.Rd
index 9230a42..363f97b 100644
--- a/man/KorAPConnection-class.Rd
+++ b/man/KorAPConnection-class.Rd
@@ -5,10 +5,6 @@
\alias{KorAPConnection-class}
\alias{KorAPConnection}
\alias{initialize,KorAPConnection-method}
-\alias{persistAccessToken,KorAPConnection-method}
-\alias{persistAccessToken}
-\alias{clearAccessToken,KorAPConnection-method}
-\alias{clearAccessToken}
\alias{apiCall,KorAPConnection-method}
\alias{apiCall}
\alias{clearCache,KorAPConnection-method}
@@ -28,10 +24,6 @@
cache = TRUE
)
-\S4method{persistAccessToken}{KorAPConnection}(kco, accessToken = kco@accessToken)
-
-\S4method{clearAccessToken}{KorAPConnection}(kco)
-
\S4method{apiCall}{KorAPConnection}(
kco,
url,
@@ -57,7 +49,9 @@
\item{accessToken}{OAuth2 access token. For queries on corpus parts with restricted
access (e.g. textual queries on IPR protected data), you need to authorize
your application with an access token.
-How to obtain an access token for the DeReKo KorAP instance is explained in the
+You can obtain an access token using the \code{\link[=auth]{auth()}} method.
+
+More details are explained in the
\href{https://github.com/KorAP/RKorAPClient#authorization}{authorization section}
of the RKorAPClient Readme on GitHub.
@@ -152,16 +146,4 @@
kq@collectedMatches$snippet
}
-\dontrun{
-
-kco <- new("KorAPConnection", accessToken="e739u6eOzkwADQPdVChxFg")
-persistAccessToken(kco)
-}
-
-\dontrun{
-
-kco <- new("KorAPConnection")
-clearAccessToken(kco)
-}
-
}
diff --git a/man/auth-KorAPConnection-method.Rd b/man/auth-KorAPConnection-method.Rd
new file mode 100644
index 0000000..8a1ab5d
--- /dev/null
+++ b/man/auth-KorAPConnection-method.Rd
@@ -0,0 +1,34 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/KorAPConnection.R
+\name{auth,KorAPConnection-method}
+\alias{auth,KorAPConnection-method}
+\alias{auth}
+\title{Authorize RKorAPClient}
+\usage{
+\S4method{auth}{KorAPConnection}(kco, app_id = generic_kor_app_id, scope = "search match_info")
+}
+\arguments{
+\item{kco}{KorAPConnection object}
+
+\item{app_id}{OAuth2 application id. Defaults to the generic KorAP client application id.}
+
+\item{scope}{OAuth2 scope. Defaults to "search match_info".}
+}
+\value{
+KorAPConnection object with access token set in \verb{@accessToken}.
+}
+\description{
+\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}}
+
+Authorize RKorAPClient to make KorAP queries and download results on behalf of the user.
+}
+\examples{
+\dontrun{
+kco <- new("KorAPConnection", verbose = TRUE) \%>\% auth()
+df <- collocationAnalysis(kco, "focus([marmot/p=ADJA] {Ameisenplage})", leftContextSize=1, rightContextSize=0)
+}
+
+}
+\seealso{
+\code{\link[=persistAccessToken]{persistAccessToken()}}, \code{\link[=clearAccessToken]{clearAccessToken()}}
+}
diff --git a/man/clearAccessToken-KorAPConnection-method.Rd b/man/clearAccessToken-KorAPConnection-method.Rd
new file mode 100644
index 0000000..2dfa4b5
--- /dev/null
+++ b/man/clearAccessToken-KorAPConnection-method.Rd
@@ -0,0 +1,29 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/KorAPConnection.R
+\name{clearAccessToken,KorAPConnection-method}
+\alias{clearAccessToken,KorAPConnection-method}
+\alias{clearAccessToken}
+\title{Clear access token from keyring and KorAPConnection object}
+\usage{
+\S4method{clearAccessToken}{KorAPConnection}(kco)
+}
+\arguments{
+\item{kco}{KorAPConnection object}
+}
+\value{
+KorAPConnection object with access token set to \code{NULL}.
+}
+\description{
+Clear access token from keyring and KorAPConnection object
+}
+\examples{
+
+\dontrun{
+kco <- new("KorAPConnection")
+kco <- clearAccessToken(kco)
+}
+
+}
+\seealso{
+\code{\link[=persistAccessToken]{persistAccessToken()}}
+}
diff --git a/man/persistAccessToken-KorAPConnection-method.Rd b/man/persistAccessToken-KorAPConnection-method.Rd
new file mode 100644
index 0000000..b66457e
--- /dev/null
+++ b/man/persistAccessToken-KorAPConnection-method.Rd
@@ -0,0 +1,32 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/KorAPConnection.R
+\name{persistAccessToken,KorAPConnection-method}
+\alias{persistAccessToken,KorAPConnection-method}
+\alias{persistAccessToken}
+\title{Persist current access token in keyring}
+\usage{
+\S4method{persistAccessToken}{KorAPConnection}(kco, accessToken = kco@accessToken)
+}
+\arguments{
+\item{kco}{KorAPConnection object}
+
+\item{accessToken}{access token to be persisted. If not supplied, the current access token of the KorAPConnection object will be used.}
+}
+\value{
+KorAPConnection object.
+}
+\description{
+Persist current access token in keyring
+}
+\examples{
+\dontrun{
+kco <- new("KorAPConnection", accessToken="e739u6eOzkwADQPdVChxFg")
+persistAccessToken(kco)
+
+kco <- new("KorAPConnection") \%>\% auth(app_id="<my application id>") \%>\% persistAccessToken()
+}
+
+}
+\seealso{
+\code{\link[=clearAccessToken]{clearAccessToken()}}, \code{\link[=auth]{auth()}}
+}