The simple-routes Reference Manual

Table of Contents

The simple-routes Reference Manual

This is the simple-routes Reference Manual, version 0.3, generated automatically by Declt version 3.0 "Montgomery Scott" on Tue Dec 22 15:02:46 2020 GMT+0.

1 Introduction

simple-routes

A simple Common Lisp RESTful routing facility on top of Hunchentoot.

This library provides a method for simple, centralized http routing on top of Hunchentoot. When you use this library with hunchentoot it takes priority over the default hunchentoot routing system but does not replace it. If simple-routes does not match a handler to a given request, it will fall back to hunchentoot's other url routing methods (easy-handler, then the default static file service).

I wrote this library because the current routing methods I found were either too complicated for my needs (Restas) or too unstructured for a RESTful api (Hunchentoot easy-handler).

Sample syntax

simple-routes searches through *routeslist* for every incoming request to try to find a matching handler for the incoming url.

(setf simple-routes:*routeslist*
      (compile-routes 
       ;;html content uris
       (:GET    ""                                      'home-handler)
       (:GET    "/people"                               'people-handler)
       (:GET    "/people/:first/:last"                  'get-person-handler)
       (:PUT    "/people/:first/:last/:description"     'put-person-handler)
              ))

This will register the listed relative urls with whatever functions are defined with names matching those specified in the rightmost column. It will automatically forward the url segments which are keywords (start with a ":") as arguments to the handlers. Here are corresponding function signatures for the url-handler functions.

(defun home-handler () ())
(defun people-handler () ())
(defun get-person-handler (first last) ())
(defun put-person-handler (first last description) ())

Demo

See simpleroutes-demo for a self-contained example web app using simple-routes! To run the demo:

1. Navigate to the directory containing simpleroutes-demo.lisp
2. open up a Lisp REPL
3. Run these commands

* (load "simpleroutes-build.asd")
* (asdf:operate 'asdf:load-op 'simpleroutes-demo)

4. Navigate to localhost:8080/ in your web browser.

2 Systems

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

2.1 simple-routes

Author

Currell Berry

License

2 clause BSD

Description

Facility for straightforward http routing on top of Hunchentoot.

Version

0.3

Dependencies

• hunchentoot
• cl-ppcre

Source

simple-routes.asd (file)

Component

simple-routes.lisp (file)

3 Files

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

3.1 Lisp

3.1.1 simple-routes.asd

Location

simple-routes.asd

Systems

simple-routes (system)

Packages

simpleroutes-asd

3.1.2 simple-routes/simple-routes.lisp

Parent

simple-routes (system)

Location

simple-routes.lisp

Packages

simple-routes

Exported Definitions

• *routeslist* (special variable)
• bind-alist-values (macro)
• compile-routes (macro)
• define-simple-handler (macro)
• simpleroutes-acceptor (class)
• simpleroutes-ssl-acceptor (class)

Internal Definitions

• issymbolstring (function)
• lastitem (function)
• removelast (function)
• routespec-compile (function)
• simple-router (function)

4 Packages

Packages are listed by definition order.

4.1 simpleroutes-asd

Source

simple-routes.asd

Use List

• asdf/interface
• common-lisp

4.2 simple-routes

Source

simple-routes.lisp (file)

Use List

• hunchentoot
• cl-ppcre
• common-lisp

Exported Definitions

• *routeslist* (special variable)
• bind-alist-values (macro)
• compile-routes (macro)
• define-simple-handler (macro)
• simpleroutes-acceptor (class)
• simpleroutes-ssl-acceptor (class)

Internal Definitions

• issymbolstring (function)
• lastitem (function)
• removelast (function)
• routespec-compile (function)
• simple-router (function)

5 Definitions

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

5.1 Exported definitions

5.1.1 Special variables

Special Variable: *routeslist*

should contain routes compiled with routespec-compile or manually entered in compiled form incoming requests are matched up against each item in *routeslist* successively, until (and if) a matching routespec is found.

Package

simple-routes

Source

simple-routes.lisp (file)

5.1.2 Macros

Macro: bind-alist-values LAMBDA-LIST ALIST-EXPRESSION &rest BODY

this is intended to be used to access get and post parameters. example usage (bind-alist-values (first second) (hunchentoot:get-parameters*)
(list first second))

Package

simple-routes

Source

simple-routes.lisp (file)

Macro: compile-routes &rest ROUTESPECS

Package

simple-routes

Source

simple-routes.lisp (file)

Macro: define-simple-handler NAME ARGUMENT-SPEC &body BODY

Package

simple-routes

Source

simple-routes.lisp (file)

5.1.3 Classes

Class: simpleroutes-acceptor ()

This first tries to route requests using simple-router, then falls back to hunchentoot’s default easy-acceptor.

Package

simple-routes

Source

simple-routes.lisp (file)

Direct superclasses

easy-acceptor (class)

Direct subclasses

simpleroutes-ssl-acceptor (class)

Direct methods

acceptor-dispatch-request (method)

Class: simpleroutes-ssl-acceptor ()

This is an acceptor that mixes the simpleroutes acceptor with SSL connections.

Package

simple-routes

Source

simple-routes.lisp (file)

Direct superclasses

• ssl-acceptor (class)
• simpleroutes-acceptor (class)

5.2 Internal definitions

5.2.1 Functions

Function: issymbolstring STR

Package

simple-routes

Source

simple-routes.lisp (file)

Function: lastitem SEQ

Package

simple-routes

Source

simple-routes.lisp (file)

Function: removelast SEQUENCE

removes the last item in sequence IF THE SEQUENCE HAS A LAST ITEM

Package

simple-routes

Source

simple-routes.lisp (file)

Function: routespec-compile HTTPMETHOD URLDEF FNTOCALL

httpmethod can be one of :GET :HEAD :POST :PUT :DELETE or :ALL
urldef is a url definition string sharing *basic* syntax with Ruby on Rails
fntocall is the function to call in case the this is found to be a match for the request

this macro returns a list which is meant to be processed by cl-simple routehandler example call:
=>(rtreg :GET “/home/next/:number” #’nxthandler) returns
(:GET "^/home/next/([^/]*)$" (NUMBER)
#<CLOSURE (LAMBDA # :IN MACRO-FUNCTION) {1000F213DB}>)
the output of this macro can in turn be processed by simple-processor

Package

simple-routes

Source

simple-routes.lisp (file)

Function: simple-router REQUEST-URI REQUEST-TYPE

takes in a request uri and type (:GET, :POST, etc...) and loops through all compiled routes in *routeslist*. If it finds a route that matches
,it returns the associated handler and returns true. otherwise returns false

Package

simple-routes

Source

simple-routes.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types