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
speficiation is very similar to file_search_path/2, but takes an
additional argument with options. Currently only one option is defined:
- 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:
- The root of the server. Default is /, but this may be overruled
using the setting (see setting/2)
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
:- multifile http:location/3.
:- dynamic http:location/3.
http:location(admin, /, ).
:- http_handler(admin(login), login, ).
- http:location(+Alias, -Expansion, -Options) is nondet[multifile]
- 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 adviced to define all
locations (ultimately) relative to
root. For example, use
root('home.html') rather than
- http_absolute_uri(+Spec, -URI) is det
- 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.
- http_absolute_location(+Spec, -Path, +Options) is det
- Path is the HTTP location for the abstract specification Spec.
- Path is made relative to Base. Default is to generate
- See also
- - http_absolute_uri/2 to create a reference that can be
used on another server.
- http_location_path(+Alias, -Expansion) is det[private]
- Expansion is the expanded HTTP location for Alias. As we have no
condition search, we demand a single expansion for an alias. An
ambiguous alias results in a printed warning. A lacking alias
results in an exception.
- http_location_path(+Alias, -Path, -Priority) is nondet[private]
- To be done
prefix(Path) is discouraged; use
- relative_to(+Base, +Path, -AbsPath) is det[private]
- AbsPath is an absolute URL location created from Base and Path.
The result is cleaned
- clean_segments(+SegmentsIn, -SegmentsOut) is det[private]
- Clean a path represented as a segment list, removing empty
segments and resolving .. based on syntax.
- path_list(+Spec, -List) is det[private]
- Translate seg1/seg2/... into [seg1,seg2,...].
- - instantiation_error
- 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