curlOptions: Constructor and accessors for CURLOptions objects

In RCurl: General Network (HTTP/FTP/...) Client Interface for R

Constructor and accessors for CURLOptions objects

Description

These functions provide a constructor and accessor methods for the (currently S3) class CURLOptions. This class is a way to group and manage options settings for CURL. These functions manage a named list of options where the names are elements of a fixed. Not all elements need be set, but these functions take care of expanding names to match the fixed set, while allowing callers to use abbreviated/partial names. Names that do not match (via pmatch) will cause an error.

The set of possible names is given by names(getCurlOptionsConstants()) or more directly with listCurlOptions().

mapCurlOptNames handles the partial matching and expansion of the names of the options for all the functions that handle CURL options. Currently this uses pmatch to perform the matching and so rejects words that are ambiguous, i.e. have multiple matches within the set of permissible option names. As a result, "head" will match both "header" and "headerfunction". We may change this behavior in the future, but we encourage using the full names for readability of code if nothing else.

Usage

curlOptions(..., .opts = list())
getCurlOptionsConstants()
## S3 replacement method for class 'CURLOptions'
x[i] <- value
## S3 replacement method for class 'CURLOptions'
x[[i]] <- value
listCurlOptions()
getCurlOptionTypes(opts = getCurlOptionsConstants())

Arguments

...	name-value pairs identifying the settings for the options of interest.
.opts	a named list of options, typically a previously created CURLOptions object. These are merged with the options specified in ....
x	a CURLOptions object
i	the name(s) of the option elements being accessed. These can be partial names matching elements in the set of known options. Other names will cause an error.
value	the values to assign to the options identified via i.
opts	the options whose type description are of interest in the call.

Details

These functions use mapCurlOptNames to match and hence expand the names the callers provide.

Value

curlOptions returns an object of class CURLOptions which is simply a named list.

getCurlConstants returns a named vector identifying the names of the possible options and their associated values. These values are used in the C code and also each integer encodes the type of the argument expected by the C code for that option.

getCurlOptionTypes returns human-readable, heuristic descriptions of the types expected for the different options. These are integer/logical corresponding to "long" in the RCurl documentation; string/object pointer corresponding to "char *" or ; function corresponding to a function/routine pointer; large number corresponding to a curl_off_t.

Author(s)

Duncan Temple Lang

References

Curl homepage https://curl.se/

See Also

curlPerform curlSetOpt

Examples

 tt = basicTextGatherer()
 myOpts = curlOptions(verbose = TRUE, header = TRUE, writefunc = tt[[1]])

  # note that the names are expanded, e.g. writefunc is now writefunction.
 names(myOpts)

 myOpts[["header"]]

 myOpts[["header"]] <- FALSE

# Using the abbreviation "hea" is an error as it matches
# both 
#  myOpts[["hea"]] <- FALSE

 # Remove the option from the list
 myOpts[["header"]] <- NULL

RCurl documentation built on Sept. 11, 2024, 8:36 p.m.