The lucerne Reference Manual

Table of Contents

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

The lucerne Reference Manual

This is the lucerne Reference Manual, version 0.3, generated automatically by Declt version 2.3 "Robert April" on Wed Mar 14 04:16:21 2018 GMT+0.


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

1 Introduction

Lucerne: a web framework

Build Status Coverage Status Quicklisp

Read the docs.

Usage

(defapp app)

@route app "/"
(defview index ()
  (respond "<h1>Welcome to Lucerne</h1>"))

@route app "/greet/:name"
(defview greet (name)
  (respond (format nil "Hello, ~A!" name)))

(start app)

License

Copyright (c) 2014-2015 Fernando Borretti (eudoxiahp@gmail.com)

Licensed under the MIT License.


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 lucerne

Maintainer

Fernando Borretti <eudoxiahp@gmail.com>

Author

Fernando Borretti <eudoxiahp@gmail.com>

Home Page

https://github.com/eudoxia0/lucerne

Source Control

(:git "git@github.com:eudoxia0/lucerne.git")

Bug Tracker

https://github.com/eudoxia0/lucerne/issues

License

MIT

Description

A Clack-based microframework.

Long Description

# Lucerne: a web framework

[![Build Status](https://travis-ci.org/eudoxia0/lucerne.svg?branch=master)](https://travis-ci.org/eudoxia0/lucerne)
[![Coverage Status](https://coveralls.io/repos/eudoxia0/lucerne/badge.svg?branch=master)](https://coveralls.io/r/eudoxia0/lucerne?branch=master) [![Quicklisp](http://quickdocs.org/badge/lucerne.svg)](http://quickdocs.org/lucerne/)

Read the [docs](http://eudoxia.me/lucerne/docs/overview.html).

## Usage

“‘lisp
(defapp app)

@route app "/"
(defview index ()
(respond "<h1>Welcome to Lucerne</h1>"))

@route app "/greet/:name"
(defview greet (name)
(respond (format nil "Hello, ~A!" name)))

(start app)
“‘

# License

Copyright (c) 2014-2015 Fernando Borretti (eudoxiahp@gmail.com)

Licensed under the MIT License.

Version

0.3

Dependencies
Source

lucerne.asd (file)

Component

src (module)


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

3 Modules

Modules are listed depth-first from the system components tree.


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

3.1 lucerne/src

Parent

lucerne (system)

Location

src/

Components

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

4 Files

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


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

4.1 Lisp


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

4.1.1 lucerne.asd

Location

lucerne.asd

Systems

lucerne (system)


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

4.1.2 lucerne/src/app.lisp

Parent

src (module)

Location

src/app.lisp

Packages

lucerne.app

Exported Definitions
Internal Definitions

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

4.1.3 lucerne/src/http.lisp

Parent

src (module)

Location

src/http.lisp

Packages

lucerne.http

Exported Definitions

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

4.1.4 lucerne/src/views.lisp

Parent

src (module)

Location

src/views.lisp

Packages

lucerne.views

Exported Definitions
Internal Definitions

strip-app-prefix-and-query-string (function)


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

4.1.5 lucerne/src/control.lisp

Parent

src (module)

Location

src/control.lisp

Packages

lucerne.ctl

Exported Definitions

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

4.1.6 lucerne/src/lucerne.lisp

Parent

src (module)

Location

src/lucerne.lisp

Packages

lucerne


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

4.1.7 lucerne/src/skeleton.lisp

Parent

src (module)

Location

src/skeleton.lisp

Packages

lucerne.skeleton

Exported Definitions

make-project (function)

Internal Definitions

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

5 Packages

Packages are listed by definition order.


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

5.1 lucerne.app

Here we define the class foundations of Lucerne. There are
applications, which have routes, middleware and sub-applications.

Routes map a particular URL pattern and HTTP method to a function that takes a request and returns a response to the client.

Middleware is what we all know and love: An item of Clack middleware is a class that wraps a request to perform some preprocessing, or regular processing. For example, serving files, guarding against CSRF attacks, etc.

Sub applications give us the ability to compose different applications. For example, you can have an ‘admin‘ application which implements an administration panel, and has its own middleware (For serving the CSS and JS used by the panel). You can integrate this application into your own simply by adding it as a sub-application under a mount point (Most typically ’/admin/’). The ability to painlessly compose applications is extremely valuable, as it allows you to easily modularize an application, and even separate some functionality into a completely separate library.

Lucerne applications are not strictly the same as Clack applications: Rather than applying middleware and mounting sub-applications when an app is defined, those things are kept in slots. When an application is started, Lucerne recursively tranverses the tree of nested applications and sub-applications, mounts them all together, and ensures all their middleware is applied.

Source

app.lisp (file)

Use List
Exported Definitions
Internal Definitions

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

5.2 lucerne.http

Source

http.lisp (file)

Use List

common-lisp

Used By List

lucerne

Exported Definitions

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

5.3 lucerne.views

Source

views.lisp (file)

Use List
Exported Definitions
Internal Definitions

strip-app-prefix-and-query-string (function)


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

5.4 lucerne.ctl

Lucerne keeps a database of running applications and their
port numbers. This is useful when loading a system that starts a Lucerne application, but either does not shut it down or fails to do so because of an error – This is particularly common in testing. By using this system, we don’t leak ports and prevent ’address in use’ errors.

Source

control.lisp (file)

Use List

common-lisp

Used By List

lucerne

Exported Definitions

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

5.5 lucerne

Source

lucerne.lisp (file)

Use List

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

5.6 lucerne.skeleton

Lucerne project skeleton generator.

Source

skeleton.lisp (file)

Use List

common-lisp

Exported Definitions

make-project (function)

Internal Definitions

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

6 Definitions

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


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

6.1 Exported definitions


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

6.1.1 Special variables

Special Variable: *request*

The current request. This will be bound in the body of a view through a lexical let.

Package

lucerne.http

Source

http.lisp (file)


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

6.1.2 Macros

Macro: defapp NAME &key MIDDLEWARES SUB-APPS CLASS

Define an application.

Package

lucerne.app

Source

app.lisp (file)

Macro: defview NAME (&rest ARGS) &body BODY

Define a view. The body of the view implicitly has access to the global request object @c(*request*).

Package

lucerne.views

Source

views.lisp (file)

Macro: render-template (TEMPLATE) &rest ARGS

Render a Djula template @cl:param(template-name) passing arguments @cl:param(args).

Package

lucerne.http

Source

http.lisp (file)

Macro: route APP CONFIG BODY
Package

lucerne.views

Source

views.lisp (file)

Macro: session ()

Extract the session hash table from the request object.

Package

lucerne.http

Source

http.lisp (file)

Macro: with-params PARAMS &body BODY

Extract the parameters in @cl:param(param) from the @c(*request*), and bind them for use in @cl:param(body).

Package

lucerne.http

Source

http.lisp (file)


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

6.1.3 Functions

Function: make-project ()

Generate a project by interactively asking questions.

Package

lucerne.skeleton

Source

skeleton.lisp (file)

Function: redirect URL &key STATUS

Redirect a user to @cl:param(url), optionally specifying a status code @cl:param(status) (302 by default).

Package

lucerne.http

Source

http.lisp (file)

Function: respond BODY &key TYPE STATUS

Construct a response from a @cl:param(body), content @cl:param(type) and @cl:param(status) code.

Package

lucerne.http

Source

http.lisp (file)


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

6.1.4 Generic functions

Generic Function: build-app APP
Package

lucerne.app

Methods
Method: build-app (APP base-app)

Take a Lucerne application, and recursively mount sub-applications and apply middleware.

Source

app.lisp (file)

Generic Function: define-route APP URL METHOD FN
Package

lucerne.views

Methods
Method: define-route (APP base-app) URL METHOD FN

Map @cl:param(method) calls to @cl:param(url) in @cl:param(app) to the function @cl:param(fn).

Source

views.lisp (file)

Generic Function: handler OBJECT
Generic Function: (setf handler) NEW-VALUE OBJECT
Package

lucerne.app

Methods
Method: handler (BASE-APP base-app)
Method: (setf handler) NEW-VALUE (BASE-APP base-app)

The server handler.

Source

app.lisp (file)

Generic Function: middlewares OBJECT
Generic Function: (setf middlewares) NEW-VALUE OBJECT
Package

lucerne.app

Methods
Method: middlewares (BASE-APP base-app)
Method: (setf middlewares) NEW-VALUE (BASE-APP base-app)

List of middlewares the application will run.

Source

app.lisp (file)

Generic Function: not-found APP
Package

lucerne.views

Methods
Method: not-found (APP base-app)

The basic not found screen: Returns HTTP 404 and the text ’Not found’.

Source

views.lisp (file)

Generic Function: prefix OBJECT
Package

lucerne.app

Methods
Method: prefix (PREFIX-MOUNT prefix-mount)

automatically generated reader method

Source

app.lisp (file)

Generic Function: register APP PREFIX SUB-APP
Package

lucerne.app

Methods
Method: register (APP base-app) PREFIX (SUB-APP base-app)

Mount ‘sub-app‘ to ‘app‘ on the prefix ‘prefix‘.

Source

app.lisp (file)

Generic Function: routes OBJECT
Generic Function: (setf routes) NEW-VALUE OBJECT
Package

lucerne.app

Methods
Method: routes (BASE-APP base-app)
Method: (setf routes) NEW-VALUE (BASE-APP base-app)

The application’s routes.

Source

app.lisp (file)

Generic Function: start APP &key PORT SERVER DEBUG SILENT
Package

lucerne.ctl

Methods
Method: start (APP base-app) &key PORT SERVER DEBUG SILENT

Bring up @cl:param(app), by default on @cl:param(port) 8000. If the server was not running, it returns @c(T). If the server was running, it restarts it and returns @c(NIL).

Source

control.lisp (file)

Generic Function: stop APP
Package

lucerne.ctl

Methods
Method: stop (APP base-app)

If @cl:param(app) is running, stop it and return @c(T). Otherwise, do nothing and return @c(NIL).

Source

control.lisp (file)

Generic Function: sub-apps OBJECT
Generic Function: (setf sub-apps) NEW-VALUE OBJECT
Package

lucerne.app

Methods
Method: sub-apps (BASE-APP base-app)
Method: (setf sub-apps) NEW-VALUE (BASE-APP base-app)

A list of sub-application mount points.

Source

app.lisp (file)

Generic Function: use APP MIDDLEWARE
Package

lucerne.app

Methods
Method: use (APP base-app) MIDDLEWARE

Make ‘app‘ use the middleware instance ‘middleware‘.

Source

app.lisp (file)


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

6.1.5 Classes

Class: base-app ()

The base class for all Lucerne applications.

Package

lucerne.app

Source

app.lisp (file)

Direct superclasses

<component> (class)

Direct methods
Direct slots
Slot: routes

The application’s routes.

Type

myway.mapper:mapper

Initform

(myway.mapper:make-mapper)

Readers

routes (generic function)

Writers

(setf routes) (generic function)

Slot: middlewares

List of middlewares the application will run.

Type

list

Initargs

:middlewares

Readers

middlewares (generic function)

Writers

(setf middlewares) (generic function)

Slot: sub-apps

A list of sub-application mount points.

Type

(trivial-types:proper-list lucerne.app::mount-point)

Initargs

:sub-apps

Readers

sub-apps (generic function)

Writers

(setf sub-apps) (generic function)

Slot: handler

The server handler.

Readers

handler (generic function)

Writers

(setf handler) (generic function)

Class: prefix-mount ()

Maps a prefix to a sub-application.

Package

lucerne.app

Source

app.lisp (file)

Direct superclasses

standard-object (class)

Direct methods
Direct slots
Slot: prefix
Type

string

Initargs

:prefix

Readers

prefix (generic function)

Slot: app
Type

lucerne.app:base-app

Initargs

:app

Readers

app (generic function)


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

6.2 Internal definitions


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

6.2.1 Special variables

Special Variable: +skeleton-directory+
Package

lucerne.skeleton

Source

skeleton.lisp (file)


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

6.2.2 Functions

Function: apply-middlewares-list APP MIDDLEWARE-LIST

Apply the middlewares in ‘middleware-list‘ to ‘app‘, returning a new app.

Package

lucerne.app

Source

app.lisp (file)

Function: apply-mounts APP

Recursively go through an app, mounting sub-applications to their prefix URLs and returning the resulting mounted app.

Package

lucerne.app

Source

app.lisp (file)

Function: parse-systems-list SYSTEMS-LIST
Package

lucerne.skeleton

Source

skeleton.lisp (file)

Function: skeleton-to-file SKELETON-FILE TARGET-FILE DIRECTORY PLIST-DATA
Package

lucerne.skeleton

Source

skeleton.lisp (file)

Function: strip-app-prefix-and-query-string URL APP-PREFIX
Package

lucerne.views

Source

views.lisp (file)

Function: strip-whitespace STRING
Package

lucerne.skeleton

Source

skeleton.lisp (file)


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

6.2.3 Generic functions

Generic Function: app OBJECT
Package

lucerne.app

Methods
Method: app (PREFIX-MOUNT prefix-mount)

automatically generated reader method

Source

app.lisp (file)


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

6.2.4 Classes

Class: mount-point ()
Package

lucerne.app

Source

app.lisp (file)

Direct superclasses

standard-object (class)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   F   L   M  
Index Entry  Section

F
File, Lisp, lucerne.asd: The lucerne<dot>asd file
File, Lisp, lucerne/src/app.lisp: The lucerne/src/app<dot>lisp file
File, Lisp, lucerne/src/control.lisp: The lucerne/src/control<dot>lisp file
File, Lisp, lucerne/src/http.lisp: The lucerne/src/http<dot>lisp file
File, Lisp, lucerne/src/lucerne.lisp: The lucerne/src/lucerne<dot>lisp file
File, Lisp, lucerne/src/skeleton.lisp: The lucerne/src/skeleton<dot>lisp file
File, Lisp, lucerne/src/views.lisp: The lucerne/src/views<dot>lisp file

L
Lisp File, lucerne.asd: The lucerne<dot>asd file
Lisp File, lucerne/src/app.lisp: The lucerne/src/app<dot>lisp file
Lisp File, lucerne/src/control.lisp: The lucerne/src/control<dot>lisp file
Lisp File, lucerne/src/http.lisp: The lucerne/src/http<dot>lisp file
Lisp File, lucerne/src/lucerne.lisp: The lucerne/src/lucerne<dot>lisp file
Lisp File, lucerne/src/skeleton.lisp: The lucerne/src/skeleton<dot>lisp file
Lisp File, lucerne/src/views.lisp: The lucerne/src/views<dot>lisp file
lucerne.asd: The lucerne<dot>asd file
lucerne/src: The lucerne/src module
lucerne/src/app.lisp: The lucerne/src/app<dot>lisp file
lucerne/src/control.lisp: The lucerne/src/control<dot>lisp file
lucerne/src/http.lisp: The lucerne/src/http<dot>lisp file
lucerne/src/lucerne.lisp: The lucerne/src/lucerne<dot>lisp file
lucerne/src/skeleton.lisp: The lucerne/src/skeleton<dot>lisp file
lucerne/src/views.lisp: The lucerne/src/views<dot>lisp file

M
Module, lucerne/src: The lucerne/src module

Jump to:   F   L   M  

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

A.2 Functions

Jump to:   (  
A   B   D   F   G   H   M   N   P   R   S   U   W  
Index Entry  Section

(
(setf handler): Exported generic functions
(setf handler): Exported generic functions
(setf middlewares): Exported generic functions
(setf middlewares): Exported generic functions
(setf routes): Exported generic functions
(setf routes): Exported generic functions
(setf sub-apps): Exported generic functions
(setf sub-apps): Exported generic functions

A
app: Internal generic functions
app: Internal generic functions
apply-middlewares-list: Internal functions
apply-mounts: Internal functions

B
build-app: Exported generic functions
build-app: Exported generic functions

D
defapp: Exported macros
define-route: Exported generic functions
define-route: Exported generic functions
defview: Exported macros

F
Function, apply-middlewares-list: Internal functions
Function, apply-mounts: Internal functions
Function, make-project: Exported functions
Function, parse-systems-list: Internal functions
Function, redirect: Exported functions
Function, respond: Exported functions
Function, skeleton-to-file: Internal functions
Function, strip-app-prefix-and-query-string: Internal functions
Function, strip-whitespace: Internal functions

G
Generic Function, (setf handler): Exported generic functions
Generic Function, (setf middlewares): Exported generic functions
Generic Function, (setf routes): Exported generic functions
Generic Function, (setf sub-apps): Exported generic functions
Generic Function, app: Internal generic functions
Generic Function, build-app: Exported generic functions
Generic Function, define-route: Exported generic functions
Generic Function, handler: Exported generic functions
Generic Function, middlewares: Exported generic functions
Generic Function, not-found: Exported generic functions
Generic Function, prefix: Exported generic functions
Generic Function, register: Exported generic functions
Generic Function, routes: Exported generic functions
Generic Function, start: Exported generic functions
Generic Function, stop: Exported generic functions
Generic Function, sub-apps: Exported generic functions
Generic Function, use: Exported generic functions

H
handler: Exported generic functions
handler: Exported generic functions

M
Macro, defapp: Exported macros
Macro, defview: Exported macros
Macro, render-template: Exported macros
Macro, route: Exported macros
Macro, session: Exported macros
Macro, with-params: Exported macros
make-project: Exported functions
Method, (setf handler): Exported generic functions
Method, (setf middlewares): Exported generic functions
Method, (setf routes): Exported generic functions
Method, (setf sub-apps): Exported generic functions
Method, app: Internal generic functions
Method, build-app: Exported generic functions
Method, define-route: Exported generic functions
Method, handler: Exported generic functions
Method, middlewares: Exported generic functions
Method, not-found: Exported generic functions
Method, prefix: Exported generic functions
Method, register: Exported generic functions
Method, routes: Exported generic functions
Method, start: Exported generic functions
Method, stop: Exported generic functions
Method, sub-apps: Exported generic functions
Method, use: Exported generic functions
middlewares: Exported generic functions
middlewares: Exported generic functions

N
not-found: Exported generic functions
not-found: Exported generic functions

P
parse-systems-list: Internal functions
prefix: Exported generic functions
prefix: Exported generic functions

R
redirect: Exported functions
register: Exported generic functions
register: Exported generic functions
render-template: Exported macros
respond: Exported functions
route: Exported macros
routes: Exported generic functions
routes: Exported generic functions

S
session: Exported macros
skeleton-to-file: Internal functions
start: Exported generic functions
start: Exported generic functions
stop: Exported generic functions
stop: Exported generic functions
strip-app-prefix-and-query-string: Internal functions
strip-whitespace: Internal functions
sub-apps: Exported generic functions
sub-apps: Exported generic functions

U
use: Exported generic functions
use: Exported generic functions

W
with-params: Exported macros

Jump to:   (  
A   B   D   F   G   H   M   N   P   R   S   U   W  

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

A.3 Variables

Jump to:   *   +  
A   H   M   P   R   S  
Index Entry  Section

*
*request*: Exported special variables

+
+skeleton-directory+: Internal special variables

A
app: Exported classes

H
handler: Exported classes

M
middlewares: Exported classes

P
prefix: Exported classes

R
routes: Exported classes

S
Slot, app: Exported classes
Slot, handler: Exported classes
Slot, middlewares: Exported classes
Slot, prefix: Exported classes
Slot, routes: Exported classes
Slot, sub-apps: Exported classes
Special Variable, *request*: Exported special variables
Special Variable, +skeleton-directory+: Internal special variables
sub-apps: Exported classes

Jump to:   *   +  
A   H   M   P   R   S  

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

A.4 Data types

Jump to:   B   C   L   M   P   S  
Index Entry  Section

B
base-app: Exported classes

C
Class, base-app: Exported classes
Class, mount-point: Internal classes
Class, prefix-mount: Exported classes

L
lucerne: The lucerne system
lucerne: The lucerne package
lucerne.app: The lucerne<dot>app package
lucerne.ctl: The lucerne<dot>ctl package
lucerne.http: The lucerne<dot>http package
lucerne.skeleton: The lucerne<dot>skeleton package
lucerne.views: The lucerne<dot>views package

M
mount-point: Internal classes

P
Package, lucerne: The lucerne package
Package, lucerne.app: The lucerne<dot>app package
Package, lucerne.ctl: The lucerne<dot>ctl package
Package, lucerne.http: The lucerne<dot>http package
Package, lucerne.skeleton: The lucerne<dot>skeleton package
Package, lucerne.views: The lucerne<dot>views package
prefix-mount: Exported classes

S
System, lucerne: The lucerne system

Jump to:   B   C   L   M   P   S