This is an alternative router/dispatcher to Swi-Prolog's http_dispatch module. The main motivation for creating this module was more convenient (less verbose) implementation of RESTful web services.
:- use_module(library(http/thread_httpd)). :- use_module(library(arouter)). :- route_get(hello/Name, handle_hello(Name)). handle_hello(Name):- format('Content-Type: text/plain; charset=UTF-8~n~n'), format('Hello ~w', [Name]). :- http_server(route, [port(8008)]).
Save it to a file, run it, and then visit http://localhost:8008/hello/world.
Normal path terms correspond directly to URL paths with the implicit root (
symbol. For example,
path/to/something corresponds to URL
`http://example.com/path/to/something`. To match the root itself,
must be used. To match an URL path with a slash in the end, an empty atom
has to be used at the end of the path term. For example, to match URL
`http://example.com/path/to/something/`, a path term
must be used.
Using with http_dispatch
Make fallback to
http_dispatch/1 like this:
handle_request(Request):- ( route(Request) -> true ; http_dispatch(Request)).
handle_request/1 as the handler in
Routes can have intermediate goals. The following example is cheking auth information before executing the handler:
:- route_get(api/resource, auth, handle_resource). auth(Next):- ( http_session_data(user(User)), memberchk(role(admin), User) -> call(Next) ; current_request(Request), memberchk(path(Path), Request), current_output(Out), http_reply(forbidden(Path), Out, )). handle_resource:- ...
The before-handler predicate calls its first argument when the request should pass it. Otherwise it should produce the response itself.
A path will match the route when:
- Path and rule are
- Path is an atomic value and the route is same atomic value or a variable.
- Path is
/(P1, P2), route is
/(R1, R2)and R1 matches P1 and R2 matches P2.
Routes are tested in reverse to the adding order. Overlapping routes can be added. Structurally equivalent routes cannot be added. Routes are overlapping when one route has atom in position of route variable in the other. Routes are structurally equivalent when:
- Both routes are
- Both routes are variables.
- Both routes are same atomic values.
- One route is
/(A1, B1), the other is
/(A2, B2)and A1, A2 are structurally equivalent and B1, B2 are structurally equivalent.
Structural equivalence is used for detecting duplicate rules. This plays nice with the
In some cases another matching (overlapping) route might have to be tried. This can be
done by throwing
arouter_next from the current route handler. Example:
:- route_get(something/specific, handle_specific). handle_specific:- ... :- route_get(something/Generic, handle_generic(Generic)). handle_generic(Generic):- ( Generic = specific -> throw(arouter_next) ; ...).
handle_specific will handle the request in this case
arouter_next from the
handle_generic handler (handlers
are tried in reverse order of adding them).
List of predicates
Adding new routes
`route_get(+Route, :Goal)` registers a new GET handler.
`route_put(+Route, :Goal)` registers a new PUT handler.
`route_del(+Route, :Goal)` registers a new DELETE handler.
`route_post(+Route, :Goal)` registers a new POST handler.
`route_get(+Route, :Before, :Goal)` registers a new GET handler with a before action.
`route_put(+Route, :Before, :Goal)` registers a new PUT handler with a before action.
`route_del(+Route, :Before, :Goal)` registers a new DELETE handler with a before action.
`route_post(+Route, :Before, :Goal)` registers a new POST handler with a before action.
`new_route(+Method, +Route, :Goal)` registers a new custom method handler.
`new_route(+Method, +Route, :Before, :Goal)` registers a new custom method handler with a before action.
All predicates above will throw an error when the Route does not contain the suitable term.
Route handler predicates can take variables from the route. Example:
:- http_get(post/show/Slug, post_show(Slug)). post_show(Slug):- ...
However, they do not take the Request argument, unlike the
http_dispatch handlers. To obtain the
current request, use the http_current_request/1
route(+Request) - takes given request and attempts to find suitable handler.
Request must contain terms
handler_failed(Method, Path) when
handler was found but it failed during execution.
Use the `route(?Method, ?Route, ?Before, ?Goal)` predicate.
route_remove(Method, Route) predicate. Both arguments
can be unbound or partially instantiated.
To install as a package:
Tested with Swi-Prolog 7.x but should work with earlier versions too.
Full API documentation
In the package root, insert into swipl:
Or if you cloned the repo:
Enable debugging with:
?- use_module(library(debug)). ?- debug(arouter).
- 2015-11-01 version 1.1.1. Attempt to preserve route order on
- 2015-11-01 version 1.1.0. Non-deterministic routing.
- 2014-05-08 version 1.0.0. Precise route matching semantics.
- 2014-02-01 version 0.0.1
Bug reports/feature requests
Please send bug reports/feature request through the GitHub project page.
The MIT license. See the LICENSE file.
|new_route/3||Registers a new method-specific route handler.|
|new_route/4||Registers a new method-specific route handler.|
|path_to_route/2||Turns path atom like '/path/to/something' into a Prolog term path/to/something.|
|route/1||Routes the request into an handler.|
|route/4||Retrieves currently registered routes.|
|route_del/2||Registers a new DELETE route handler.|
|route_del/3||Registers a new DELETE route handler.|
|route_get/2||Registers a new GET route handler.|
|route_get/3||Registers a new GET route handler.|
|route_post/2||Registers a new POST route handler.|
|route_post/3||Registers a new POST route handler.|
|route_put/2||Registers a new PUT route handler.|
|route_put/3||Registers a new PUT route handler.|
|route_remove/2||Removes the given route.|