curlOptions {RCurl} | R Documentation

## 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 method for class 'CURLOptions':
    x[i] <- value
    ## S3 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 <duncan@wald.ucdavis.edu>

### References

Curl homepage http://curl.haxx.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

[Package RCurl version 0.98-1 Index]