The simple-routes Reference Manual

Table of Contents

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

The simple-routes Reference Manual

This is the simple-routes Reference Manual, version 0.3, generated automatically by Declt version 2.3 "Robert April" on Tue Feb 20 09:21:05 2018 GMT+0.


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

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)
  1. Navigate to localhost:8080/ in your web browser.

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 simple-routes

Author

Currell Berry

License

2 clause BSD

Description

Facility for straightforward http routing on top of Hunchentoot.

Version

0.3

Dependencies
Source

simple-routes.asd (file)

Component

simple-routes.lisp (file)


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 simple-routes.asd

Location

simple-routes.asd

Systems

simple-routes (system)

Packages

simpleroutes-asd


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

3.1.2 simple-routes/simple-routes.lisp

Parent

simple-routes (system)

Location

simple-routes.lisp

Packages

simple-routes

Exported Definitions
Internal Definitions

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

4 Packages

Packages are listed by definition order.


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

4.1 simpleroutes-asd

Source

simple-routes.asd

Use List

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

4.2 simple-routes

Source

simple-routes.lisp (file)

Use List
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: *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)


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

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)


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

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

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

5.2 Internal definitions


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

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)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   F   L   S  
Index Entry  Section

F
File, Lisp, simple-routes.asd: The simple-routes<dot>asd file
File, Lisp, simple-routes/simple-routes.lisp: The simple-routes/simple-routes<dot>lisp file

L
Lisp File, simple-routes.asd: The simple-routes<dot>asd file
Lisp File, simple-routes/simple-routes.lisp: The simple-routes/simple-routes<dot>lisp file

S
simple-routes.asd: The simple-routes<dot>asd file
simple-routes/simple-routes.lisp: The simple-routes/simple-routes<dot>lisp file

Jump to:   F   L   S  

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

A.2 Functions

Jump to:   B   C   D   F   I   L   M   R   S  
Index Entry  Section

B
bind-alist-values: Exported macros

C
compile-routes: Exported macros

D
define-simple-handler: Exported macros

F
Function, issymbolstring: Internal functions
Function, lastitem: Internal functions
Function, removelast: Internal functions
Function, routespec-compile: Internal functions
Function, simple-router: Internal functions

I
issymbolstring: Internal functions

L
lastitem: Internal functions

M
Macro, bind-alist-values: Exported macros
Macro, compile-routes: Exported macros
Macro, define-simple-handler: Exported macros

R
removelast: Internal functions
routespec-compile: Internal functions

S
simple-router: Internal functions

Jump to:   B   C   D   F   I   L   M   R   S  

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

A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*routeslist*: Exported special variables

S
Special Variable, *routeslist*: Exported special variables

Jump to:   *  
S  

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

A.4 Data types

Jump to:   C   P   S  
Index Entry  Section

C
Class, simpleroutes-acceptor: Exported classes
Class, simpleroutes-ssl-acceptor: Exported classes

P
Package, simple-routes: The simple-routes package
Package, simpleroutes-asd: The simpleroutes-asd package

S
simple-routes: The simple-routes system
simple-routes: The simple-routes package
simpleroutes-acceptor: Exported classes
simpleroutes-asd: The simpleroutes-asd package
simpleroutes-ssl-acceptor: Exported classes
System, simple-routes: The simple-routes system

Jump to:   C   P   S