The easy-routes Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The easy-routes Reference Manual

This is the easy-routes Reference Manual, generated automatically by Declt version 3.0 "Montgomery Scott" on Fri Jun 26 10:59:33 2020 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

EASY-ROUTES

EASY-ROUTES is yet another routes handling system on top of Hunchentoot.

It's just glue code for Restas routing subsystem (CL-ROUTES).

It supports:

Usage:

Use routes-acceptor acceptor:

(hunchentoot:start (make-instance 'easy-routes:routes-acceptor))

Note that the routes-acceptor returns with HTTP not found if no route matches and doesn't fallback to easy-handlers, and so it doesn't iterate over Hunchentoot *dispatch-table*. Most of the time, that iteration is a useful thing, so you may want to start the easy-routes:easy-routes-acceptor instead, that inherits from Hunchentoot easy-acceptor and so it iterates the dispatch table if no route matches (useful for being able to use define-easy-handler and also handling static files).

Routes:

Syntax:


(defroute <name> (<path> &rest <route-options>) <route-params> 
   &body body)
   

with:

Example route:

(defroute foo ("/foo/:arg1/:arg2" :method :get
                                  :decorators (@auth @db @html))
   (&get w)
    (format nil "<h1>FOO arg1: ~a arg2: ~a ~a</h1>" arg1 arg2 w))

Decorators:

Decorators are functions that are executed before the route body. They should call the next parameter function to continue executing the decoration chain and the route body finally.

Examples:

(defun @auth (next)
  (let ((*user* (hunchentoot:session-value 'user)))
    (if (not *user*)
	(hunchentoot:redirect "/login")
	(funcall next))))

(defun @html (next)
  (setf (hunchentoot:content-type*) "text/html")
  (funcall next))

(defun @json (next)
  (setf (hunchentoot:content-type*) "application/json")
  (funcall next))

(defun @db (next)
  (postmodern:with-connection *db-spec*
    (funcall next)))

Decorators also support parameters, like in the @check and @check-permission decorators:

(defun @check (predicate http-error next)
  (if (funcall predicate)
      (funcall next)
      (http-error http-error)))

(defun @check-permission (predicate next)
  (if (funcall predicate)
      (funcall next)
      (permission-denied-error)))

Then you can use those decorators passing the needed parameters. predicate and http-error for @check, and predicate for check permission:

(defroute my-protected-route ("/foo" :method :get
                                     :decorators (@check my-permissions-checking-function hunchentoot:+http-forbidden+))
   ...)

Map of routes visualization

CL-ROUTES package implement special SWANK code for routes map visualization. Just inspect *ROUTES-MAP* variable from your lisp listener.

For example:

#<ROUTES:MAPPER {1007630E53}>
--------------------

Tree of routes
--------------------------------------------------

users invoice-engine::admin/users
api/invoices/chart invoice-engine::invoices-chart-data
invoice-engine::dashboard
logout invoice-engine::logout
company/logo invoice-engine::company-logo
search invoice-engine::global-search
preview-invoice invoice-engine::preview-invoice
dt-invoices invoice-engine::datatables-list-invoices
tenants invoice-engine::admin/tenants
admin/
    settings invoice-engine::admin/settings
    invoice-engine::admin/dashboard
    tenants/new/
        invoice-engine::admin/tenants/create
        invoice-engine::admin/tenants/new
    login/
        invoice-engine::admin/signin
        invoice-engine::admin/login
    tenant/$id invoice-engine::admin/tenant
    users/
        new/
            invoice-engine::admin/users/create
            invoice-engine::admin/users/new
        $id/edit/
            invoice-engine::admin/users/update
            invoice-engine::admin/users/edit
customers/
    invoice-engine::web/list-customers
    $id invoice-engine::view-customer
invoices/
    invoice-engine::list-invoices-route
    $id/
        print invoice-engine::web/print-invoice
        printed invoice-engine::web/printed-invoice
        invoice-engine::view-invoice
        send invoice-engine::web/send-invoice-by-email

Less fancy, but useful too, you can also use (describe easy-routes:*routes-mapper*) to visualize the tree of routes.

Djula integration

easy-routes+djula system implements support for generating easy-routes urls using route names and arguments in Djula templates (calls genurl function).

Djula template syntax:

{% genurl route-name &rest args %}

Example:

{% genurl my-route :id 22 :foo template-var.key %}

Reference

Functions

@html

(next)

HTML decoration. Sets reply content type to text/html

find-route

(name)

Find a route by name (symbol)

genurl

(route-symbol &rest args &key &allow-other-keys)

Generate a relative url from a route name and arguments

genurl*

(route-symbol &rest args &key &allow-other-keys)

Generate an absolute url from a route name and arguments

redirect

(route-symbol &rest args)

Redirect to a route url. Pass the route name and the parameters.

Macros

defroute

(name template-and-options params &body body)

Route definition syntax

Classes

easy-routes-acceptor

This acceptor tries to match and handle easy-routes first, but fallbacks to easy-routes dispatcher if there's no matching

routes-acceptor

This acceptors handles routes and only routes. If no route is matched then an HTTP NOT FOUND error is returned. If you want to use Hunchentoot easy-handlers dispatch as a fallback, use EASY-ROUTES-ACCEPTOR


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 easy-routes

Author

Mariano Montone <marianomontone@gmail.com>

License

MIT

Description

Yet another routes handling utility on top of Hunchentoot

Dependencies
Source

easy-routes.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 easy-routes.asd

Location

easy-routes.asd

Systems

easy-routes (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 easy-routes/package.lisp

Parent

easy-routes (system)

Location

package.lisp

Packages

easy-routes


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.3 easy-routes/util.lisp

Dependency

package.lisp (file)

Parent

easy-routes (system)

Location

util.lisp

Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.4 easy-routes/easy-routes.lisp

Dependency

util.lisp (file)

Parent

easy-routes (system)

Location

easy-routes.lisp

Exported Definitions
Internal Definitions

Previous: , Up: Lisp files   [Contents][Index]

3.1.5 easy-routes/routes-map-printer.lisp

Dependency

easy-routes.lisp (file)

Parent

easy-routes (system)

Location

routes-map-printer.lisp

Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 easy-routes

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Special variables

Special Variable: *routes-mapper*

This is the cl-routes map of routes.
cl-routes implements special SWANK inspect code and prints routes mappers as a tree. Just inspect *routes-mapper* from the Lisp listener to see.

Package

easy-routes

Source

easy-routes.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Macros

Macro: defroute NAME TEMPLATE-AND-OPTIONS PARAMS &body BODY

Route definition syntax

Package

easy-routes

Source

easy-routes.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.3 Functions

Function: @check PREDICATE HTTP-ERROR NEXT
Package

easy-routes

Source

easy-routes.lisp (file)

Function: @check-permission PREDICATE NEXT
Package

easy-routes

Source

easy-routes.lisp (file)

Function: @html NEXT

HTML decoration. Sets reply content type to text/html

Package

easy-routes

Source

easy-routes.lisp (file)

Function: @json NEXT

JSON decoration. Sets reply content type to application/json

Package

easy-routes

Source

easy-routes.lisp (file)

Function: find-route NAME

Find a route by name (symbol)

Package

easy-routes

Source

easy-routes.lisp (file)

Function: genurl ROUTE-SYMBOL &rest ARGS &key &allow-other-keys

Generate a relative url from a route name and arguments

Package

easy-routes

Source

easy-routes.lisp (file)

Function: genurl* ROUTE-SYMBOL &rest ARGS &key &allow-other-keys

Generate an absolute url from a route name and arguments

Package

easy-routes

Source

easy-routes.lisp (file)

Function: http-error HTTP-ERROR
Package

easy-routes

Source

easy-routes.lisp (file)

Function: not-found-error ()
Package

easy-routes

Source

easy-routes.lisp (file)

Function: or-http-error VALUE HTTP-ERROR
Package

easy-routes

Source

easy-routes.lisp (file)

Function: or-not-found VALUE
Package

easy-routes

Source

easy-routes.lisp (file)

Function: permission-denied-error ()
Package

easy-routes

Source

easy-routes.lisp (file)

Function: redirect ROUTE-SYMBOL &rest ARGS

Redirect to a route url. Pass the route name and the parameters.

Package

easy-routes

Source

easy-routes.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.4 Classes

Class: easy-routes-acceptor ()

This acceptor tries to match and handle easy-routes first, but fallbacks to easy-routes dispatcher if there’s no matching

Package

easy-routes

Source

easy-routes.lisp (file)

Direct superclasses

easy-acceptor (class)

Direct methods

acceptor-dispatch-request (method)

Class: route ()
Package

easy-routes

Source

easy-routes.lisp (file)

Direct superclasses

route (class)

Direct methods
Direct slots
Slot: symbol
Initargs

:symbol

Readers

route-symbol (generic function)

Slot: variables
Initargs

:variables

Readers

variables (generic function)

Slot: required-method
Initargs

:required-method

Readers

required-method (generic function)

Slot: decorators
Type

list

Initargs

:decorators

Readers

route-decorators (generic function)

Class: routes-acceptor ()

This acceptors handles routes and only routes. If no route is matched then an HTTP NOT FOUND error is returned. If you want to use Hunchentoot easy-handlers dispatch as a fallback, use EASY-ROUTES-ACCEPTOR

Package

easy-routes

Source

easy-routes.lisp (file)

Direct superclasses

acceptor (class)

Direct methods

acceptor-dispatch-request (method)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Special variables

Special Variable: *current-indention*
Package

easy-routes

Source

routes-map-printer.lisp (file)

Special Variable: *indention*
Package

easy-routes

Source

routes-map-printer.lisp (file)

Special Variable: *routes*
Package

easy-routes

Source

easy-routes.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Macros

Macro: assoc-bind LAMBDA-LIST ALIST &body BODY
Package

easy-routes

Source

util.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.3 Functions

Function: apply-format-aux FORMAT ARGS
Package

easy-routes

Source

easy-routes.lisp (file)

Function: call-decorator DECORATOR NEXT
Package

easy-routes

Source

easy-routes.lisp (file)

Function: call-with-decorators DECORATORS FUNCTION
Package

easy-routes

Source

easy-routes.lisp (file)

Function: connect-routes ()
Package

easy-routes

Source

easy-routes.lisp (file)

Function: lambda-list-split TEMPLATE LAM-LIST
Package

easy-routes

Source

util.lisp (file)

Function: route-symbol-template ROUTE-SYMBOL
Package

easy-routes

Source

easy-routes.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.4 Generic functions

Generic Function: make-route-url TMPL ARGS
Package

easy-routes

Methods
Method: make-route-url (ROUTE route) ARGS
Source

easy-routes.lisp (file)

Method: make-route-url (ROUTE symbol) ARGS
Source

easy-routes.lisp (file)

Method: make-route-url (TMPL list) ARGS
Source

easy-routes.lisp (file)

Generic Function: print-route ROUTE STREAM
Package

easy-routes

Source

routes-map-printer.lisp (file)

Methods
Method: print-route (ROUTE concat-template) STREAM
Method: print-route (ROUTE or-template) STREAM
Method: print-route (ROUTE cons) STREAM
Method: print-route (ROUTE wildcard-template) STREAM
Method: print-route (ROUTE variable-template) STREAM
Method: print-route (ROUTE route) STREAM
Method: print-route ROUTE STREAM
Generic Function: process-route ROUTE BINDINGS
Package

easy-routes

Methods
Method: process-route (ROUTE route) BINDINGS
Source

easy-routes.lisp (file)

Generic Function: required-method OBJECT
Package

easy-routes

Methods
Method: required-method (ROUTE route)

automatically generated reader method

Source

easy-routes.lisp (file)

Generic Function: route-decorators OBJECT
Package

easy-routes

Methods
Method: route-decorators (ROUTE route)

automatically generated reader method

Source

easy-routes.lisp (file)

Generic Function: route-symbol OBJECT
Package

easy-routes

Methods
Method: route-symbol (ROUTE route)

automatically generated reader method

Source

easy-routes.lisp (file)

Generic Function: variables OBJECT
Package

easy-routes

Methods
Method: variables (ROUTE route)

automatically generated reader method

Source

easy-routes.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   E   F   L  
Index Entry  Section

E
easy-routes.asd: The easy-routes․asd file
easy-routes/easy-routes.lisp: The easy-routes/easy-routes․lisp file
easy-routes/package.lisp: The easy-routes/package․lisp file
easy-routes/routes-map-printer.lisp: The easy-routes/routes-map-printer․lisp file
easy-routes/util.lisp: The easy-routes/util․lisp file

F
File, Lisp, easy-routes.asd: The easy-routes․asd file
File, Lisp, easy-routes/easy-routes.lisp: The easy-routes/easy-routes․lisp file
File, Lisp, easy-routes/package.lisp: The easy-routes/package․lisp file
File, Lisp, easy-routes/routes-map-printer.lisp: The easy-routes/routes-map-printer․lisp file
File, Lisp, easy-routes/util.lisp: The easy-routes/util․lisp file

L
Lisp File, easy-routes.asd: The easy-routes․asd file
Lisp File, easy-routes/easy-routes.lisp: The easy-routes/easy-routes․lisp file
Lisp File, easy-routes/package.lisp: The easy-routes/package․lisp file
Lisp File, easy-routes/routes-map-printer.lisp: The easy-routes/routes-map-printer․lisp file
Lisp File, easy-routes/util.lisp: The easy-routes/util․lisp file

Jump to:   E   F   L  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   @  
A   C   D   F   G   H   L   M   N   O   P   R   V  
Index Entry  Section

@
@check: Exported functions
@check-permission: Exported functions
@html: Exported functions
@json: Exported functions

A
apply-format-aux: Internal functions
assoc-bind: Internal macros

C
call-decorator: Internal functions
call-with-decorators: Internal functions
connect-routes: Internal functions

D
defroute: Exported macros

F
find-route: Exported functions
Function, @check: Exported functions
Function, @check-permission: Exported functions
Function, @html: Exported functions
Function, @json: Exported functions
Function, apply-format-aux: Internal functions
Function, call-decorator: Internal functions
Function, call-with-decorators: Internal functions
Function, connect-routes: Internal functions
Function, find-route: Exported functions
Function, genurl: Exported functions
Function, genurl*: Exported functions
Function, http-error: Exported functions
Function, lambda-list-split: Internal functions
Function, not-found-error: Exported functions
Function, or-http-error: Exported functions
Function, or-not-found: Exported functions
Function, permission-denied-error: Exported functions
Function, redirect: Exported functions
Function, route-symbol-template: Internal functions

G
Generic Function, make-route-url: Internal generic functions
Generic Function, print-route: Internal generic functions
Generic Function, process-route: Internal generic functions
Generic Function, required-method: Internal generic functions
Generic Function, route-decorators: Internal generic functions
Generic Function, route-symbol: Internal generic functions
Generic Function, variables: Internal generic functions
genurl: Exported functions
genurl*: Exported functions

H
http-error: Exported functions

L
lambda-list-split: Internal functions

M
Macro, assoc-bind: Internal macros
Macro, defroute: Exported macros
make-route-url: Internal generic functions
make-route-url: Internal generic functions
make-route-url: Internal generic functions
make-route-url: Internal generic functions
Method, make-route-url: Internal generic functions
Method, make-route-url: Internal generic functions
Method, make-route-url: Internal generic functions
Method, print-route: Internal generic functions
Method, print-route: Internal generic functions
Method, print-route: Internal generic functions
Method, print-route: Internal generic functions
Method, print-route: Internal generic functions
Method, print-route: Internal generic functions
Method, print-route: Internal generic functions
Method, process-route: Internal generic functions
Method, required-method: Internal generic functions
Method, route-decorators: Internal generic functions
Method, route-symbol: Internal generic functions
Method, variables: Internal generic functions

N
not-found-error: Exported functions

O
or-http-error: Exported functions
or-not-found: Exported functions

P
permission-denied-error: Exported functions
print-route: Internal generic functions
print-route: Internal generic functions
print-route: Internal generic functions
print-route: Internal generic functions
print-route: Internal generic functions
print-route: Internal generic functions
print-route: Internal generic functions
print-route: Internal generic functions
process-route: Internal generic functions
process-route: Internal generic functions

R
redirect: Exported functions
required-method: Internal generic functions
required-method: Internal generic functions
route-decorators: Internal generic functions
route-decorators: Internal generic functions
route-symbol: Internal generic functions
route-symbol: Internal generic functions
route-symbol-template: Internal functions

V
variables: Internal generic functions
variables: Internal generic functions

Jump to:   @  
A   C   D   F   G   H   L   M   N   O   P   R   V  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *  
D   R   S   V  
Index Entry  Section

*
*current-indention*: Internal special variables
*indention*: Internal special variables
*routes*: Internal special variables
*routes-mapper*: Exported special variables

D
decorators: Exported classes

R
required-method: Exported classes

S
Slot, decorators: Exported classes
Slot, required-method: Exported classes
Slot, symbol: Exported classes
Slot, variables: Exported classes
Special Variable, *current-indention*: Internal special variables
Special Variable, *indention*: Internal special variables
Special Variable, *routes*: Internal special variables
Special Variable, *routes-mapper*: Exported special variables
symbol: Exported classes

V
variables: Exported classes

Jump to:   *  
D   R   S   V  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   E   P   R   S  
Index Entry  Section

C
Class, easy-routes-acceptor: Exported classes
Class, route: Exported classes
Class, routes-acceptor: Exported classes

E
easy-routes: The easy-routes system
easy-routes: The easy-routes package
easy-routes-acceptor: Exported classes

P
Package, easy-routes: The easy-routes package

R
route: Exported classes
routes-acceptor: Exported classes

S
System, easy-routes: The easy-routes system

Jump to:   C   E   P   R   S