| 1 |
\name{curlOptions} |
| 2 |
\alias{curlOptions} |
| 3 |
\alias{getCurlOptionsConstants} |
| 4 |
\alias{getCurlOptionTypes} |
| 5 |
\alias{listCurlOptions} |
| 6 |
\alias{mapCurlOptNames} |
| 7 |
\alias{[<-.CURLOptions} |
| 8 |
\alias{[[<-.CURLOptions} |
| 9 |
\title{Constructor and accessors for CURLOptions objects} |
| 10 |
\description{ |
| 11 |
These functions provide a constructor |
| 12 |
and accessor methods |
| 13 |
for the (currently S3) class \code{CURLOptions}. |
| 14 |
This class is a way to group and manage options settings |
| 15 |
for CURL. |
| 16 |
These functions manage a named list of options |
| 17 |
where the names are elements of a fixed. |
| 18 |
Not all elements need be set, but |
| 19 |
these functions take care of expanding names |
| 20 |
to match the fixed set, while allowing callers |
| 21 |
to use abbreviated/partial names. |
| 22 |
Names that do not match (via \code{\link[base]{pmatch}}) |
| 23 |
will cause an error. |
| 24 |
|
| 25 |
The set of possible names is given by |
| 26 |
\code{names(getCurlOptionsConstants())} |
| 27 |
or more directly with \code{listCurlOptions()}. |
| 28 |
|
| 29 |
\code{mapCurlOptNames} handles the partial matching and |
| 30 |
expansion of the names of the options for all the functions |
| 31 |
that handle CURL options. |
| 32 |
Currently this uses \code{\link[base]{pmatch}} to |
| 33 |
perform the matching and so rejects words |
| 34 |
that are ambiguous, i.e. have multiple matches |
| 35 |
within the set of permissible option names. |
| 36 |
As a result, "head" will match both |
| 37 |
"header" and "headerfunction". |
| 38 |
We may change this behavior in the future, but |
| 39 |
we encourage using the full names for readability of code if nothing |
| 40 |
else. |
| 41 |
|
| 42 |
|
| 43 |
} |
| 44 |
\usage{ |
| 45 |
curlOptions(..., .opts = list()) |
| 46 |
getCurlOptionsConstants() |
| 47 |
\method{[}{CURLOptions}(x, i) <- value |
| 48 |
\method{[[}{CURLOptions}(x, i) <- value |
| 49 |
listCurlOptions() |
| 50 |
getCurlOptionTypes(opts = getCurlOptionsConstants()) |
| 51 |
} |
| 52 |
%"[<-.CURLOptions"(x, i, value) |
| 53 |
\arguments{ |
| 54 |
\item{\dots}{name-value pairs identifying the settings for the options |
| 55 |
of interest.} |
| 56 |
\item{.opts}{a named list of options, typically a previously created |
| 57 |
\code{CURLOptions} object. These are merged with the options |
| 58 |
specified in \code{\dots}.} |
| 59 |
\item{x}{a \code{CURLOptions} object} |
| 60 |
\item{i}{the name(s) of the option elements being accessed. |
| 61 |
These can be partial names matching elements in the set |
| 62 |
of known options. Other names will cause an error.} |
| 63 |
\item{value}{the values to assign to the options identified via \code{i}.} |
| 64 |
\item{opts}{the options whose type description are of interest in the call.} |
| 65 |
} |
| 66 |
\details{ |
| 67 |
These functions use \code{mapCurlOptNames} |
| 68 |
to match and hence expand the names the callers |
| 69 |
provide. |
| 70 |
} |
| 71 |
\value{ |
| 72 |
\code{curlOptions} returns an object |
| 73 |
of class \code{CURLOptions} which is simply |
| 74 |
a named list. |
| 75 |
|
| 76 |
\code{getCurlConstants} returns a named vector identifying |
| 77 |
the names of the possible options and their associated |
| 78 |
values. These values are used in the C code and also each integer |
| 79 |
encodes the type of the argument expected by the C code |
| 80 |
for that option. |
| 81 |
|
| 82 |
\code{getCurlOptionTypes} returns human-readable, |
| 83 |
heuristic descriptions of the types expected for the different options. |
| 84 |
These are integer/logical corresponding to "long" in the RCurl documentation; |
| 85 |
string/object pointer corresponding to "char *" or ; |
| 86 |
function corresponding to a function/routine pointer; |
| 87 |
large number corresponding to a \code{curl_off_t}. |
| 88 |
} |
| 89 |
|
| 90 |
\references{Curl homepage \url{https://curl.se/}} |
| 91 |
\author{Duncan Temple Lang} |
| 92 |
|
| 93 |
\seealso{ |
| 94 |
\code{\link{curlPerform}} |
| 95 |
\code{\link{curlSetOpt}} |
| 96 |
} |
| 97 |
\examples{ |
| 98 |
|
| 99 |
tt = basicTextGatherer() |
| 100 |
myOpts = curlOptions(verbose = TRUE, header = TRUE, writefunc = tt[[1]]) |
| 101 |
|
| 102 |
# note that the names are expanded, e.g. writefunc is now writefunction. |
| 103 |
names(myOpts) |
| 104 |
|
| 105 |
myOpts[["header"]] |
| 106 |
|
| 107 |
myOpts[["header"]] <- FALSE |
| 108 |
|
| 109 |
# Using the abbreviation "hea" is an error as it matches |
| 110 |
# both |
| 111 |
# myOpts[["hea"]] <- FALSE |
| 112 |
|
| 113 |
# Remove the option from the list |
| 114 |
myOpts[["header"]] <- NULL |
| 115 |
} |
| 116 |
\keyword{IO} |
| 117 |
|