% This LaTeX document was generated using the LaTeX backend of PlDoc,
% The SWI-Prolog documentation system



\subsection{library(http/http_path): Abstract specification of HTTP server locations}

\label{sec:httppath}

This module provides an abstract specification of HTTP server locations
that is inspired on \predref{absolute_file_name}{3}. The specification is done by
adding rules to the dynamic multifile predicate \qpredref{http}{location}{3}. The
speficiation is very similar to \qpredref{user}{file_search_path}{2}, but takes an
additional argument with options. Currently only one option is defined:

\begin{description}
    \termitem{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.
\end{description}

This library predefines a single location at priority -100:

\begin{description}
    \termitem{root}{}
The root of the server. Default is /, but this may be overruled
using the setting (see \predref{setting}{2}) \verb$http:prefix$
\end{description}

To serve additional resource files such as CSS, JavaScript and icons,
see \verb$library(http/http_server_files)$.

Here is an example that binds \verb$/login$ to \predref{login}{1}. The user can reuse
this application while moving all locations using a new rule for the
admin location with the option \verb$[priority(10)]$.

\begin{code}
:- multifile http:location/3.
:- dynamic   http:location/3.

http:location(admin, /, []).

:- http_handler(admin(login), login, []).

login(Request) :-
        ...
\end{code}

\vspace{0.7cm}

\begin{description}
\qpredicate[nondet,multifile]{http}{location}{3}{+Alias, -Expansion, -Options}Multifile hook used to specify new HTTP locations. \arg{Alias} is the
name of the abstract path. \arg{Expansion} is either a term
Alias2(Relative), telling \predref{http_absolute_location}{3} to translate
\arg{Alias} by first translating Alias2 and then applying the relative
path Relative or, \arg{Expansion} is an absolute location, i.e., one
that starts with a \verb$/$. \arg{Options} currently only supports the
priority of the path. If \qpredref{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
\const{root}. This defaults to the setting http:prefix or, when not
available to the path \verb$/$. It is adviced to define all
locations (ultimately) relative to \const{root}. For example, use
\verb$root('home.html')$ rather than \verb$'/home.html'$.

    \predicate[det]{http_absolute_uri}{2}{+Spec, -URI}
\arg{URI} is the absolute (i.e., starting with \verb$http://$) \arg{URI} for
the abstract specification \arg{Spec}. Use \predref{http_absolute_location}{3} to
create references to locations on the same server.

    \predicate[det]{http_absolute_location}{3}{+Spec, -Path, +Options}
\arg{Path} is the HTTP location for the abstract specification \arg{Spec}.
\arg{Options}:

\begin{description}
    \termitem{relative_to}{Base}
\arg{Path} is made relative to \arg{Base}. Default is to generate
absolute URLs.
\end{description}

\begin{tags}
    \tag{See also}
\predref{http_absolute_uri}{2} to create a reference that can be
used on another server.
\end{tags}

    \predicate{http_clean_location_cache}{0}{}
HTTP locations resolved through \predref{http_absolute_location}{3} are
cached. This predicate wipes the cache. The cache is
automatically wiped by \predref{make}{0} and if the setting http:prefix is
changed.
\end{description}