|Did you know ...||Search Documentation:|
|The HTTP client libraries|
This package provides two client libraries for accessing HTTP
servers. The first,
library(http/http_open) is a library
for opening a HTTP URL address as a Prolog stream. The general skeleton
for using this library is given below, where process/1 processes the
data from the HTTP server.1One may
opt to use cleanup/2
intead of setup_call_cleanup/3
to allow for aborting while http_open/3
is waiting for the connection.
setup_call_cleanup( http_open(URL, In, ), process(In), close(In)).
library(http/http_client) provides http_get/3
both of which process the reply using plugins to convert the data based
Content-Type of the reply. This library supports a
plugin infrastructure that can register hooks for converting additional
This library defines http_open/3, which opens a URL as a Prolog stream. The functionality of the library can be extended by loading two additional modules that act as plugins:
httpsis requested using a default SSL context. See the plugin for additional information regarding security.
gziptransfer encoding. This plugin is lazily loaded if a connection is opened that claims this transfer encoding.
Here is a simple example to fetch a web-page:
?- http_open('http://www.google.com/search?q=prolog', In, ), copy_stream_data(In, user_output), close(In). <!doctype html><head><title>prolog - Google Search</title><script> ...
The example below fetches the modification time of a web-page. Note that Modified is” (the empty atom) if the web-server does not provide a time-stamp for the resource. See also parse_time/2.
modified(URL, Stamp) :- http_open(URL, In, [ method(head), header(last_modified, Modified) ]), close(In), Modified \== '', parse_time(Modified, Stamp).
Then next example uses Google search. It exploits
to manage URIs,
library(sgml) to load an HTML document and
to navigate the parsed HTML. Note that you may need to adjust the XPath
queries if the data returned by Google changes.
:- use_module(library(http/http_open)). :- use_module(library(xpath)). :- use_module(library(sgml)). :- use_module(library(uri)). google(For, Title, HREF) :- uri_encoded(query_value, For, Encoded), atom_concat('http://www.google.com/search?q=', Encoded, URL), http_open(URL, In, ), call_cleanup( load_html(In, DOM, ), close(In)), xpath(DOM, //h3(@class=r), Result), xpath(Result, //a(@href=HREF0, text), Title), uri_components(HREF0, Components), uri_data(search, Components, Query), uri_query_components(Query, Parts), memberchk(q=HREF, Parts).
An example query is below:
?- google(prolog, Title, HREF). Title = 'SWI-Prolog', HREF = 'http://www.swi-prolog.org/' ; Title = 'Prolog - Wikipedia', HREF = 'https://nl.wikipedia.org/wiki/Prolog' ; Title = 'Prolog - Wikipedia, the free encyclopedia', HREF = 'https://en.wikipedia.org/wiki/Prolog' ; Title = 'Pro-Log is logistiek dienstverlener m.b.t. vervoer over water.', HREF = 'http://www.pro-log.nl/' ; Title = 'Learn Prolog Now!', HREF = 'http://www.learnprolognow.org/' ; Title = 'Free Online Version - Learn Prolog ...
true), do not try to automatically authenticate the client if a 401 (Unauthorized) status code is received.
library(http/http_digest)is also loaded.
Connectionheader. Default is
close. The alternative is
Keep-alive. This maintains a pool of available connections as determined by keep_connection/1. The
Keep-alive, Upgrade. Keep-alive connections can be closed explicitly using http_close_keep_alive/1. Keep-alive connections may significantly improve repetitive requests on the same server, especially if the IP route is long, HTTPS is used or the connection uses a proxy.
headmessage can be used in combination with the
header(Name, Value)option to access information on the resource without actually fetching the resource itself. The returned stream must be closed immediately.
post(Data) is provided, the default is
Content-Lengthin the reply header.
Major-Minor, where Major and Minor are integers representing the HTTP version in the reply header.
end. HTTP 1.1 only supports Unit =
bytes. E.g., to ask for bytes 1000-1999, use the option
true), do not automatically redirect if a 3XX code is received. Must be combined with
status_code(Code)and one of the header options to read the redirect reply. In particular, without
status_code(Code)a redirect is mapped to an exception.
POSTrequest on the HTTP server. Data is handed to http_post_data/3.
true, bypass proxy hooks. Default is
infinite. The default value is
User-Agentfield of the HTTP header. Default is
The hook http:open_options/2
can be used to provide default options based on the broken-down URL.
status_code(-Code) is particularly useful to query REST
interfaces that commonly return status codes other than
that need to be be processed by the client code.
|URL||is either an atom or string (url) or a
list of parts.
When provided, this list may contain the fields
http_open([ host('www.example.com'), path('/my/path'), search([ q='Hello world', lang=en ]) ])
error(existence_error(url, Id),Context)is raised if the HTTP result code is not in the range 200..299. Context has the shape
context(Message, status(Code, TextCode)), where Code is the numeric HTTP code and TextCode is the textual description thereof provided by the server. Message may provide additional details or may be unbound.
METHODkeywords. Default are the official HTTP methods as defined by the various RFCs.
Transfer-encodingencoding for specific values of ContentType. This predicate is multifile and can thus be extended by the user.
-, possibly defined authorization is cleared. For example:
?- http_set_authorization('http://www.example.com/private/', basic('John', 'Secret'))
Mode == read.
http_close_keep_alive(_)closes all currently known keep-alive connections.
:- multifile http:open_options/2. http:open_options(Parts, Options) :- option(host(Host), Parts), Host \== localhost, Options = [proxy('proxy.local', 3128)].
This hook may return multiple solutions. The returned options are combined using merge_options/3 where earlier solutions overrule later solutions.
Cookie:header for the current connection. Out is an open stream to the HTTP server, Parts is the broken-down request (see uri_components/2) and Options is the list of options passed to http_open. The predicate is called as if using ignore/1.
library(http/http_cookie)implements cookie handling on top of these hooks.
Set-Cookiefield, Parts is the broken-down request (see uri_components/2) and Options is the list of options passed to http_open.
library(http/http_cookies)implements cookie handling on top of these hooks.
This library provides the four basic HTTP client actions:
addition, it provides http_read_data/3,
which is used by
library(http/http_parameters) to decode
data in server applications.
This library is based on http_open/3, which opens a URL as a Prolog stream. The reply is processed by http_read_data/3. The following content-types are supported. Options passed to http_get/3 and friends are passed to http_read_data/3, which in turn passes them to the conversion predicates. Support for additional content types can be added by extending the multifile predicate http_client:http_convert_data/4.
library(http/http_multipart_plugin)is loaded. This format should be used to handle web forms that upload a file.
library(http/http_sgml_plugin)is loaded. See load_html/3 for details and load_xml/3 for details. The output is often processed using xpath/3.
library(http/http_json)is loaded. The option
json_object(As)can be used to return a term
term) or a dict (As is
Content-Typeheader and plugins. This predicate is the common implementation of the HTTP client operations. The predicates http_delete/3, http_post/4 and http_put/4 call this predicate with an appropriate
method(+Method)option and ---for http_post/4 and http_put/4--- a
headers(Fields)from http_open/3. Provided for backward compatibility. Note that
http_version(Major-Minor)is missing in the new version.
DELETEmethod on the server. Arguments are the same as for http_get/3. Typically one should pass the option
status_code(-Code)to assess and evaluate the returned status code. Without, codes other than 200 are interpreted as an error.
POSTrequest. Data is posted using http_post_data/3. The HTTP server reply is returned in Reply, using the same rules as for http_get/3.
PUTrequest. Arguments are the same as for http_post/4.
PATCHrequest. Arguments are the same as for http_post/4.
to(Format)option or based on the
Content-typein the Request. The following options are supported:
stream(+WriteStream)) Append the content of the message to Stream
library(http/http_multipart_plugin)and apply to processing
Without plugins, this predicate handles
|Request||is a parsed HTTP request as returned
available from the HTTP server's request dispatcher. Request
must contain a term |
library(http/http_json)), HTML/XML (
all, closing all connections.
post(Data)option of http_open/3. The default implementation supports
prolog(Term), sending a Prolog term as