This module provides an abstract specification of HTTP server
locations that is inspired on absolute_file_name/3.
The specification is done by adding rules to the dynamic multifile
predicate http:location/3.
The specification is very similar to user:file_search_path/2,
but takes an additional argument with options. Currently only one option
is defined:
- priority(+Integer)
- If two rules match, take the one with highest priority. Using priorities
is needed because we want to be able to overrule paths, but we do not
want to become dependent on clause ordering.
The default priority is 0. Note however that notably libraries may
decide to provide a fall-back using a negative priority. We suggest -100
for such cases.
This library predefines a single location at priority -100:
- root
- The root of the server. Default is /, but this may be overruled using
the setting (see setting/2)
http:prefix
To serve additional resource files such as CSS, JavaScript and icons,
see library(http/http_server_files).
Here is an example that binds /login to login/1.
The user can reuse this application while moving all locations using a
new rule for the admin location with the option [priority(10)].
:- multifile http:location/3.
:- dynamic http:location/3.
http:location(admin, /, []).
:- http_handler(admin(login), login, []).
login(Request) :-
...
- [nondet,multifile]http:location(+Alias,
-Expansion, -Options)
- Multifile hook used to specify new HTTP locations. Alias is
the name of the abstract path. Expansion is either a term
Alias2(Relative), telling http_absolute_location/3
to translate
Alias by first translating Alias2 and then applying the
relative path Relative or, Expansion is an absolute location,
i.e., one that starts with a
/. Options
currently only supports the priority of the path. If http:location/3
returns multiple solutions the one with the highest priority is
selected. The default priority is 0.
This library provides a default for the abstract location
root. This defaults to the setting http:prefix or, when not
available to the path /. It is advised to define all
locations (ultimately) relative to root. For example, use
root('home.html') rather than '/home.html'.
- [det]http_absolute_uri(+Spec,
-URI)
- URI is the absolute (i.e., starting with
http://) URI
for the abstract specification Spec. Use http_absolute_location/3
to create references to locations on the same server.
- [det]http_absolute_location(+Spec,
-Path, +Options)
- Path is the HTTP location for the abstract specification Spec.
Options:
- relative_to(Base)
- Path is made relative to Base. Default is to
generate absolute URLs.
- See also
- http_absolute_uri/2 to
create a reference that can be used on another server.
- http_clean_location_cache
- HTTP locations resolved through http_absolute_location/3
are cached. This predicate wipes the cache. The cache is automatically
wiped by make/0 and if the setting
http:prefix is changed.
