Debian Codegraph @

man/curlOptions.Rd

raw
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