curl/[1,2,3]

Module: curl

curl/1 — Access to the internet via the curl package with URL, Options, Target in one list
curl/2 — Access to the internet via the curl package with separate URL arg, combined Options, Target in one list
curl/3 — Access to the internet via the curl package with separate URL, Options, Target args
http/3 — REST-inspired user-level interface for curl

FORMS

curl(Options)

curl(URL, Target)

curl(URL, Options, Target)

http(RESTVerb, URL, Options)

DESCRIPTION

curl is an open source software command line tool and library (libcurl) “for transferring data with URLs”. The ALS Prolog interface to curl is built using the so-called “Easy interface” of the curl library. In this approach, everything about any of the calls curl/[1,2,3] or http/3 is converted into a single list of Easy-oriented curl option equations, and that list is then passed to a C program built over the curl Easy interface API. The predicates curl/[1,2,3] provide three variations on the theme of a rather direct interface to curl, while http/3 provides slightly higher-level REST-inspired transfer services.

For all equations on the Options list passed to the C program, the left side of every equation, which must be an atom, is first converted to uppercase. Then, with the exception of the special equation tags

'DATA', 'DATAFILE', 'EOL', 'EOLCODE', 'FIELDS', 'FIELDSFILE', 'RESULT', 'RESULTFILE', 'URL', 'POST',

(see below), the left side L of every equation L=R passed to the C plumbing over curl is prefixed with either 'CURLOPT_' or 'CURLINFO_'. The result of this prefixing must be either an easy option or an info option.

Several simple transformations are applied to the elements of the list:

i) Unary prolog expressions <F>(A) are allowed on the Options list. These are converted to equations FF = A, where FF is the uppercase version of <F>.

ii) Equations E = A are converted to EE = A where EE is the uppercase version of E.

Options must be list of terms of the form Tag = Value. Tag must be an atom, and when converted to all upper case, must either be one of the following

'DATA', 'DATAFILE', 'EOL', 'EOLCODE', 'FIELDS', 'FIELDSFILE', 'RESULT', 'RESULTFILE', 'URL', 'POST',

or must be a CURLOPT expression, or must be a CURLINFO expression. Those prefixed with CURLOPT request specific services or pass information into curl. Those prefixed with CURLINFO request various information to be returned from curl.

The acceptable expressions for Value will depend on Tag (see below).

Among curl/[1,2,3], curl/1 is basic:

curl/1:
curl(Options)
Cleans up option capitalization and invokes the low-level interface to curl.

The other two are defined in terms of cur/1:

curl/2:
Effectively:
curl(URL, Target)
    :-
    curl(URL, [], Target).

curl/3:
Effectively:
curl(URL, Options, Target)
    :-
    XOptions = [url=URL, result=Target | Options],
    curl(XOptions).

In curl/1, the one Tag which absolutely must be set is 'URL'=<URL> (effectively 'CURLOPT_URL'=<URL>), since this specifies where the file transfer will take place (to or from). <URL> must be an atom (typically a UIA) which describes a proper url.

Common options:

Further CURLOPT_ options are described below in connection with http/3.

Appropriate CURLINFO options can be used with any of curl/[1,2,3] or http/3. For example, including response_code(RC) on Options will bind RC to the HTTP response code returned by the server (e.g., 200, 404, etc.), and including total_time(TTT) will bind TTT to the number of seconds expended in the transaction.

For transferring information outbound, data for POSTing can be supplied in one of two forms: 1) structured data such as is uploaded from Web forms (e.g., ‘name=admin&shoesize=12’) and 2) free-form text data (e.g., ‘lorem ipsum doler’). Either type of data can be supplied either directly in an equation on the Options list, or in a file specified on the Options list:

Inspired by the REST approach to internet file transfer,

http/3
http(RESTVerb, URL, Options)

provides REST-inspired transfer services. At present, the following RESTVerbs are implemented:

get, post put, delete, head, options, patch.

The available Options overall are the same as for curl/[1,2,3], but in individual calls, depend on the RESTVerb. The special equations and special equation tags are the also the same as for curl/[1,2,3].

EXAMPLES

These three calls provide the same service and response, except that curl/2 cannot provide the response_code:

?- curl('http://example.com', [response_code(RC)], RR).
?- curl('http://example.com', RR).
?- curl([url='http://example.com', response_code=RC, result=RR]).
RC=200 
RR='<!doctype html>\n<html>\n<head>\n    <title>Example Domain</title>......</html>\n' 

yes.

http(get, 'http://example.com', [response_code(RC), result=RR]).

RC=200 
RR='<!doctype html>\n<html>\n<head>\n    <title>Example Domain</title>......</html>\n'

yes.

?- http(post, 'https://postman-echo.com/post', [fields='name=admin&shoesize=12', result=RR]).

RR='{"args":{},"data":"","files":{},"form":{"name":"admin","shoesize":"12"},"headers":{"x-forwarded-proto":"https","host":"postman-echo.com","content-length":"22","accept":"*/*","content-type":"application/x-www-form-urlencoded","x-forwarded-port":"443"},"json":{"name":"admin","shoesize":"12"},"url":"https://postman-echo.com/post"}' 

yes.

ERRORS

curl(Options) curl(URL, Target) curl(URL, Options, Target) http(RESTVerb, URL, Options)

Options is a variable

– – – – > instantiation_error

Options is neither a variable nor a list

– – – – > type_error(list, Option)

Options is a list an element of which is a variable

– – – – > instantiation_error

Options is a list containing an element E which is neither a curl equation nor a unary prolog expression

– – – – > domain_error(type_error('equation (_=_)', E)

URL is a variable

– – – – > instantiation_error

URL is not an atom

– – – – > domain_error(atom,URL)

URL does not indicate an internet host

– – – – > curl_error: 'curl_easy_perform() failed: Couldn\'t resolve host name\n'

Target is a variable

– – – – > instantiation_error

RESTVerb is not one of the listed REST verbs

– – – – > domain_error(http_rest_verb,RESTVerb)

NOTES

Access to curl is also provided by ALS Prolog streams. See the discussion under URLs: Internet Streams in Section 10.2.2 SourceSink Terms, in the User Guide (Prolog I/O).

SEE ALSO