Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the caveman Reference Manual, version 12.8.0, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 10:52:09 2018 GMT+0.
| • Introduction: | What caveman is all about | |
| • Systems: | The systems documentation | |
| • Modules: | The modules documentation | |
| • Files: | The files documentation | |
| • Packages: | The packages documentation | |
| • Definitions: | The symbols documentation | |
| • Indexes: | Concepts, functions, variables and data types |
(defparameter *web* (make-instance '<app>))
@route GET "/"
(defun index ()
(render #P"index.tmpl"))
@route GET "/hello"
(defun say-hello (&key (|name| "Guest"))
(format nil "Hello, ~A" |name|))
All of them. Caveman2 was written from scratch.
These are noticeable points.
One of the most frequently asked questions was "Which should I use ningle or Caveman? What are the differences?" I think it was because the roles of them were too similar. Both of them are saying "micro" and no database support.
Caveman2 is no more "micro" web application framework. It supports CL-DBI and has database connection management by default. Caveman has started growing up.
Caveman is intended to be a collection of common parts of web applications. Caveman has 3 rules to make decisions.
You came here because you're interested in living like a caveman, right? There's no Disneyland, but it's good place to start. Let's get into a cave.
Caveman2 is now available on Quicklisp.
(ql:quickload :caveman2)
(caveman2:make-project #P"/path/to/myapp/"
:author "<Your full name>")
;-> writing /path/to/myapp/.gitignore
; writing /path/to/myapp/README.markdown
; writing /path/to/myapp/app.lisp
; writing /path/to/myapp/db/schema.sql
; writing /path/to/myapp/shlyfile.lisp
; writing /path/to/myapp/myapp-test.asd
; writing /path/to/myapp/myapp.asd
; writing /path/to/myapp/src/config.lisp
; writing /path/to/myapp/src/db.lisp
; writing /path/to/myapp/src/main.lisp
; writing /path/to/myapp/src/view.lisp
; writing /path/to/myapp/src/web.lisp
; writing /path/to/myapp/static/css/main.css
; writing /path/to/myapp/t/myapp.lisp
; writing /path/to/myapp/templates/_errors/404.html
; writing /path/to/myapp/templates/index.tmpl
; writing /path/to/myapp/templates/layout/default.tmpl
Caveman2 provides 2 ways to define a route -- @route and defroute. You can choose which to use.
@route is an annotation macro defined by using cl-annot. It takes a method, an URL-string and a function.
@route GET "/"
(defun index ()
...)
;; A route with no name.
@route GET "/welcome"
(lambda (&key (|name| "Guest"))
(format nil "Welcome, ~A" |name|))
This is similar to Caveman1's @url except its argument list. You don't have to specify an argument when you don't need it.
defroute is just a macro. It provides same feature to @route.
(defroute index "/" ()
...)
;; A route with no name.
(defroute "/welcome" (&key (|name| "Guest"))
(format nil "Welcome, ~A" |name|))
Since Caveman bases on ningle, Caveman also has the Sinatra-like routing system.
;; GET request (default)
@route GET "/" (lambda () ...)
(defroute ("/" :method :GET) () ...)
;; POST request
@route POST "/" (lambda () ...)
(defroute ("/" :method :POST) () ...)
;; PUT request
@route PUT "/" (lambda () ...)
(defroute ("/" :method :PUT) () ...)
;; DELETE request
@route DELETE "/" (lambda () ...)
(defroute ("/" :method :DELETE) () ...)
;; OPTIONS request
@route OPTIONS "/" (lambda () ...)
(defroute ("/" :method :OPTIONS) () ...)
;; For all methods
@route ANY "/" (lambda () ...)
(defroute ("/" :method :ANY) () ...)
Route pattern may contain "keyword" to put the value into the argument.
(defroute "/hello/:name" (&key name)
(format nil "Hello, ~A" name))
The above controller will be invoked when you access to "/hello/Eitaro" or "/hello/Tomohiro", and then name will be "Eitaro" and "Tomohiro".
(&key name) is almost same as a lambda list of Common Lisp, excepts it always allows other keys.
(defroute "/hello/:name" (&rest params &key name)
;; ...
)
Route patterns may also contain "wildcard" parameters. They are accessible by splat.
(defroute "/say/*/to/*" (&key splat)
; matches /say/hello/to/world
splat ;=> ("hello" "world")
))
(defroute "/download/*.*" (&key splat)
; matches /download/path/to/file.xml
splat ;=> ("path/to/file" "xml")
))
If you'd like to write a regular expression for URL rule, :regexp t should work for it.
(defroute ("/hello/([\\w]+)" :regexp t) (&key captures)
(format nil "Hello, ~A!" (first captures)))
Normally, routes are matched in the order they are defined. Only the first route matched is invoked and rest of them just will be ignored. But, a route can punt processing to the next matching route using next-route.
(defroute "/guess/:who" (&key who)
(if (string= who "Eitaro")
"You got me!"
(next-route)))
(defroute "/guess/*" ()
"You missed!")
You can return following formats as the result of defroute.
Parameter keys contain square brackets ("[" & "]") will be parsed as structured parameters. You can access the parsed parameters as _parsed in routers.
<form action="/edit">
<input type="name" name="person[name]" />
<input type="name" name="person[email]" />
<input type="name" name="person[birth][year]" />
<input type="name" name="person[birth][month]" />
<input type="name" name="person[birth][day]" />
</form>
(defroute "/edit" (&key _parsed)
(format nil "~S" (cdr (assoc "person" _parsed :test #'string=))))
;=> "((\"name\" . \"Eitaro\") (\"email\" . \"e.arrows@gmail.com\") (\"birth\" . ((\"year\" . 2000) (\"month\" . 1) (\"day\" . 1))))"
Blank keys mean they have multiple values.
<form action="/add">
<input type="text" name="items[][name]" />
<input type="text" name="items[][price]" />
<input type="text" name="items[][name]" />
<input type="text" name="items[][price]" />
<input type="submit" value="Add" />
</form>
(defroute "/add" (&key _parsed)
(format nil "~S" (assoc "items" _parsed :test #'string=)))
;=> "(((\"name\" . \"WiiU\") (\"price\" . \"30000\")) ((\"name\" . \"PS4\") (\"price\" . \"69000\")))"
Caveman adopts Djula for the default templating engine.
{% extends "layouts/default.html" %}
{% block title %}Users | MyApp{% endblock %}
{% block content %}
<div id="main">
<ul>
{% for user in users %}
<li><a href="{{ user.url }}">{{ user.name }}</a></li>
{% endfor %}
</ul>
</div>
{% endblock %}
(import 'myapp.view:render)
(render #P"users.html"
'(:users ((:url "/id/1"
:name "nitro_idiot")
(:url "/id/2"
:name "meymao"))
:has-next-page T))
If you want to get something from a database or execute any function using Djula you have to explicity call list when passing the arguments to render so that the code executes.
(import 'myapp.view:render)
(render #P"users.html"
(list :users (get-users-from-db)))
This is an example of a JSON API.
(defroute "/user.json" (&key |id|)
(let ((person (find-person-from-db |id|)))
;; person => (:|name| "Eitaro Fukamachi" :|email| "e.arrows@gmail.com")
(render-json person)))
;=> {"name":"Eitaro Fukamachi","email":"e.arrows@gmail.com"}
render-json is a part of a skeleton project. You can find its code in "src/view.lisp".
Images, CSS, JS, favicon.ico and robot.txt in "static/" directory will be served by default.
/images/logo.png => {PROJECT_ROOT}/static/images/logo.png
/css/main.css => {PROJECT_ROOT}/static/css/main.css
/js/app/index.js => {PROJECT_ROOT}/static/js/app/index.js
/robot.txt => {PROJECT_ROOT}/static/robot.txt
/favicon.ico => {PROJECT_ROOT}/static/favicon.ico
You can change these rules by rewriting "PROJECT_ROOT/app.lisp". See Clack.Middleware.Static for detail.
Caveman adopts Envy as a configuration switcher. It allows to define multiple configurations and to switch them by an environment variable.
This is a typical example.
(defpackage :myapp.config
(:use :cl
:envy))
(in-package :myapp.config)
(setf (config-env-var) "APP_ENV")
(defconfig :common
`(:application-root ,(asdf:component-pathname (asdf:find-system :myapp))))
(defconfig |development|
'(:debug T
:databases
((:maindb :sqlite3 :database-name ,(merge-pathnames #P"test.db"
*application-root*)))))
(defconfig |production|
'(:databases
((:maindb :mysql :database-name "myapp" :username "whoami" :password "1234")
(:workerdb :mysql :database-name "jobs" :username "whoami" :password "1234"))))
(defconfig |staging|
`(:debug T
,@|production|))
Every configuration is a property list. You can choose the configuration which to use by setting APP_ENV.
To get a value from the current configuration, call myapp.config:config with a key you want.
(import 'myapp.config:config)
(setf (osicat:environment-variable "APP_ENV") "development")
(config :debug)
;=> T
When you add :databases to the configuration, Caveman enables database support. :databases is an association list of database settings.
(defconfig |production|
'(:databases
((:maindb :mysql :database-name "myapp" :username "whoami" :password "1234")
(:workerdb :mysql :database-name "jobs" :username "whoami" :password "1234"))))
db in a package myapp.db is a function for connecting to each databases configured the above. Here is an example.
(use-package '(:myapp.db :sxql :datafly))
(defun search-adults ()
(with-connection (db)
(retrieve-all
(select :*
(from :person)
(where (:>= :age 20))))))
The connection is alive during the Lisp session and will be reused in each HTTP requests.
retrieve-all and the query language came from datafly and SxQL. See those documentations for more informations.
There are several special variables available during a HTTP request. *request* and *response* represents a request and a response. If you are familiar with Clack, these are instances of subclasses of Clack.Request and Clack.Response.
(use-package :caveman2)
;; Get a value of Referer header.
(http-referer *request*)
;; Set Content-Type header.
(setf (getf (response-headers *response* :content-type) "application/json")
;; Set HTTP status.
(setf (status *response*) 304)
If you would like to set Content-Type "application/json" for all "*.json" requests, next-route will help you.
(defroute "/*.json" ()
(setf (getf (response-headers *response*) :content-type) "application/json")
(next-route))
(defroute "/user.json" () ...)
(defroute "/search.json" () ...)
(defroute ("/new.json" :method :POST) () ...)
Session data is for memorizing user-specific data. *session* is a hash table represents session data.
This example increments :counter in the session and displays it for each visitors.
(defroute "/counter" ()
(format nil "You came here ~A times."
(incf (gethash :counter *session* 0))))
Caveman2 stores the session data in-memory by default. To change it, specify :store to :session in "PROJECT_ROOT/app.lisp".
This example uses RDBMS to store it.
'(:backtrace
:output (getf (config) :error-log))
nil)
- :session
+ (:session
+ :store (make-dbi-store :connector (lambda ()
+ (apply #'dbi:connect
+ (myapp.db:connection-settings)))))
(if (productionp)
nil
(lambda (app)
NOTE: Don't forget to add :lack-session-store-dbi as :depends-on of your app. It is not a part of Clack/Lack.
See the source code of Lack.Session.Store.DBi for more informations.
(import 'caveman2:throw-code)
(defroute ("/auth" :method :POST) (&key |name| |password|)
(unless (authorize |name| |password|)
(throw-code 403)))
To specify error pages for 404, 500 or so, define a method on-exception of your app.
(defmethod on-exception ((app <web>) (code (eql 404)))
(declare (ignore app code))
(merge-pathnames #P"_errors/404.html"
*template-directory*))
Your application has functions named start and stop to start/stop your web application. This is a example assuming that the name of your application is "myapp".
(myapp:start :port 8080)
As Caveman bases on Clack/Lack, you can choose which server to run on -- Hunchentoot, mod_lisp or FastCGI.
(myapp:start :server :hunchentoot :port 8080)
(myapp:start :server :fcgi :port 8080)
I recommend you to use Hunchentoot in local machine and use FastCGI/Woo for production environment.
You can also start your application by using clackup command.
$ ros install clack
$ which clackup
/Users/nitro_idiot/.roswell/bin/clackup
$ APP_ENV=development clackup --server :fcgi --port 8080 app.lisp
Though Caveman doesn't have a feature for hot deployment, Server::Starter -- a Perl module -- makes it easy.
$ APP_ENV=production start_server --port 8080 -- clackup --server :fcgi app.lisp
NOTE: Server::Starter requires the server to support binding on a specific fd, which means only :fcgi and :woo are the ones work with start_server command.
To restart the server, send HUP signal (kill -HUP <pid>) to the start_server process.
Caveman outputs error backtraces to a file which is specified at :error-log in your configuration.
(defconfig |default|
`(:error-log #P"/var/log/apps/myapp_error.log"
:databases
((:maindb :sqlite3 :database-name ,(merge-pathnames #P"myapp.db"
*application-root*)))))
(import 'cl-who:with-html-output-to-string)
(defroute "/" ()
(with-html-output-to-string (output nil :prologue t)
(:html
(:head (:title "Welcome to Caveman!"))
(:body "Blah blah blah."))))
;=> "<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Strict//EN\" \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd\">
; <html><head><title>Welcome to Caveman!</title></head><body>Blah blah blah.</body></html>"
(import 'cl-markup:xhtml)
(defroute "/" ()
(xhtml
(:head (:title "Welcome to Caveman!"))
(:body "Blah blah blah.")))
;=> "<?xml version=\"1.0\" encoding=\"UTF-8\"?><!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\" \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\"><html><head><title>Welcome to Caveman!</title></head><body>Blah blah blah.</body></html>"
{namespace myapp.view}
{template renderIndex}
<!DOCTYPE html>
<html>
<head>
<title>"Welcome to Caveman!</title>
</head>
<body>
Blah blah blah.
</body>
</html>
{/template}
(import 'myapp.config:*template-directory*)
(closure-template:compile-cl-templates (merge-pathnames #P"index.tmpl"
*template-directory*))
(defroute "/" ()
(myapp.view:render-index))
Licensed under the LLGPL License.
Next: Modules, Previous: Introduction, Up: Top [Contents][Index]
The main system appears first, followed by any subsystem dependency.
| • The caveman system: |
Eitaro Fukamachi
LLGPL
Web Application Framework for Common Lisp
# Caveman2 - Lightweight web application framework
[](https://travis-ci.org/fukamachi/caveman)
## Usage
“‘common-lisp
(defparameter *web* (make-instance ’<app>))
@route GET "/"
(defun index ()
(render #P"index.tmpl"))
@route GET "/hello"
(defun say-hello (&key (|name| "Guest"))
(format nil "Hello, ~A" |name|))
“‘
## About Caveman2
### What’s the difference from Caveman "1"?
All of them. Caveman2 was written from scratch.
These are noticeable points.
* Bases on [ningle](http://8arrow.org/ningle/)
* Database integration
* New separated configuration system ([Envy](https://github.com/fukamachi/envy))
* New routing macro
### The reason I wrote it from scratch
One of the most frequently asked questions was "Which should I use ningle or Caveman? What are the differences?" I think it was because the roles of them were too similar. Both of them are saying "micro" and no database support.
Caveman2 is no more "micro" web application framework. It supports CL-DBI and has database connection management by default. Caveman has started growing up.
## Design Goal
Caveman is intended to be a collection of common parts of web applications. Caveman has 3 rules to make decisions.
* Be extensible.
* Be practical.
* Don’t force anything.
## Quickstart
You came here because you’re interested in living like a caveman, right? There’s no Disneyland, but it’s good place to start. Let’s get into a cave.
### Installation
Caveman2 is now available on [Quicklisp](https://www.quicklisp.org/beta/).
“‘common-lisp
(ql:quickload :caveman2)
“‘
### Generating a project skeleton
“‘common-lisp
(caveman2:make-project #P"/path/to/myapp/"
:author "<Your full name>")
;-> writing /path/to/myapp/.gitignore
; writing /path/to/myapp/README.markdown
; writing /path/to/myapp/app.lisp
; writing /path/to/myapp/db/schema.sql
; writing /path/to/myapp/shlyfile.lisp
; writing /path/to/myapp/myapp-test.asd
; writing /path/to/myapp/myapp.asd
; writing /path/to/myapp/src/config.lisp
; writing /path/to/myapp/src/db.lisp
; writing /path/to/myapp/src/main.lisp
; writing /path/to/myapp/src/view.lisp
; writing /path/to/myapp/src/web.lisp
; writing /path/to/myapp/static/css/main.css
; writing /path/to/myapp/t/myapp.lisp
; writing /path/to/myapp/templates/_errors/404.html
; writing /path/to/myapp/templates/index.tmpl
; writing /path/to/myapp/templates/layout/default.tmpl
“‘
### Routing
Caveman2 provides 2 ways to define a route – ‘@route‘ and ‘defroute‘. You can choose which to use.
‘@route‘ is an annotation macro defined by using [cl-annot](https://github.com/arielnetworks/cl-annot). It takes a method, an URL-string and a function.
“‘common-lisp
@route GET "/"
(defun index ()
...)
;; A route with no name.
@route GET "/welcome"
(lambda (&key (|name| "Guest"))
(format nil "Welcome, ~A" |name|))
“‘
This is similar to Caveman1’s ‘@url‘ except its argument list. You don’t have to specify an argument when you don’t need it.
‘defroute‘ is just a macro. It provides same feature to ‘@route‘.
“‘common-lisp
(defroute index "/" ()
...)
;; A route with no name.
(defroute "/welcome" (&key (|name| "Guest"))
(format nil "Welcome, ~A" |name|))
“‘
Since Caveman bases on ningle, Caveman also has the [Sinatra](http://www.sinatrarb.com/)-like routing system.
“‘common-lisp
;; GET request (default)
@route GET "/" (lambda () ...)
(defroute ("/" :method :GET) () ...)
;; POST request
@route POST "/" (lambda () ...)
(defroute ("/" :method :POST) () ...)
;; PUT request
@route PUT "/" (lambda () ...)
(defroute ("/" :method :PUT) () ...)
;; DELETE request
@route DELETE "/" (lambda () ...)
(defroute ("/" :method :DELETE) () ...)
;; OPTIONS request
@route OPTIONS "/" (lambda () ...)
(defroute ("/" :method :OPTIONS) () ...)
;; For all methods
@route ANY "/" (lambda () ...)
(defroute ("/" :method :ANY) () ...)
“‘
Route pattern may contain "keyword" to put the value into the argument.
“‘common-lisp
(defroute "/hello/:name" (&key name)
(format nil "Hello, ~A" name))
“‘
The above controller will be invoked when you access to "/hello/Eitaro" or "/hello/Tomohiro", and then ‘name‘ will be "Eitaro" and "Tomohiro".
‘(&key name)‘ is almost same as a lambda list of Common Lisp, excepts it always allows other keys.
“‘common-lisp
(defroute "/hello/:name" (&rest params &key name)
;; ...
)
“‘
Route patterns may also contain "wildcard" parameters. They are accessible by ‘splat‘.
“‘common-lisp
(defroute "/say/*/to/*" (&key splat)
; matches /say/hello/to/world
splat ;=> ("hello" "world")
))
(defroute "/download/*.*" (&key splat)
; matches /download/path/to/file.xml
splat ;=> ("path/to/file" "xml")
))
“‘
If you’d like to write a regular expression for URL rule, ‘:regexp t‘ should work for it.
“‘common-lisp
(defroute ("/hello/([\\w]+)" :regexp t) (&key captures)
(format nil "Hello, ~A!" (first captures)))
“‘
Normally, routes are matched in the order they are defined. Only the first route matched is invoked and rest of them just will be ignored. But, a route can punt processing to the next matching route using ‘next-route‘.
“‘common-lisp
(defroute "/guess/:who" (&key who)
(if (string= who "Eitaro")
"You got me!"
(next-route)))
(defroute "/guess/*" ()
"You missed!")
“‘
You can return following formats as the result of ‘defroute‘.
* String
* Pathname
* Clack’s response list (containing Status, Headers and Body)
### Structured query/post parameters
Parameter keys contain square brackets ("[" & "]") will be parsed as structured parameters. You can access the parsed parameters as ‘_parsed‘ in routers.
“‘html
<form action="/edit">
<input type="name" name="person[name]" />
<input type="name" name="person[email]" />
<input type="name" name="person[birth][year]" />
<input type="name" name="person[birth][month]" />
<input type="name" name="person[birth][day]" />
</form>
“‘
“‘common-lisp
(defroute "/edit" (&key _parsed)
(format nil "~S" (cdr (assoc "person" _parsed :test #’string=))))
;=> "((\"name\" . \"Eitaro\") (\"email\" . \"e.arrows@gmail.com\") (\"birth\" . ((\"year\" . 2000) (\"month\" . 1) (\"day\" . 1))))"
“‘
Blank keys mean they have multiple values.
“‘html
<form action="/add">
<input type="text" name="items[][name]" />
<input type="text" name="items[][price]" />
<input type="text" name="items[][name]" />
<input type="text" name="items[][price]" />
<input type="submit" value="Add" />
</form>
“‘
“‘common-lisp
(defroute "/add" (&key _parsed)
(format nil "~S" (assoc "items" _parsed :test #’string=)))
;=> "(((\"name\" . \"WiiU\") (\"price\" . \"30000\")) ((\"name\" . \"PS4\") (\"price\" . \"69000\")))"
“‘
### Templates
Caveman adopts [Djula](http://mmontone.github.io/djula/) for the default templating engine.
“‘html
{% extends "layouts/default.html" %}
{% block title %}Users | MyApp{% endblock %}
{% block content %}
<div id="main">
<ul>
{% for user in users %}
<li><a href="{{ user.url }}">{{ user.name }}</a></li>
{% endfor %}
</ul>
</div>
{% endblock %}
“‘
“‘common-lisp
(import ’myapp.view:render)
(render #P"users.html"
’(:users ((:url "/id/1"
:name "nitro_idiot")
(:url "/id/2"
:name "meymao"))
:has-next-page T))
“‘
If you want to get something from a database or execute any function using [Djula](http://mmontone.github.io/djula/) you have to explicity call ‘list‘ when passing the arguments to render so that the code executes.
“‘common-lisp
(import ’myapp.view:render)
(render #P"users.html"
(list :users (get-users-from-db)))
“‘
### JSON API
This is an example of a JSON API.
“‘common-lisp
(defroute "/user.json" (&key |id|)
(let ((person (find-person-from-db |id|)))
;; person => (:|name| "Eitaro Fukamachi" :|email| "e.arrows@gmail.com")
(render-json person)))
;=> {"name":"Eitaro Fukamachi","email":"e.arrows@gmail.com"}
“‘
‘render-json‘ is a part of a skeleton project. You can find its code in "src/view.lisp".
### Static file
Images, CSS, JS, favicon.ico and robot.txt in "static/" directory will be served by default.
“‘
/images/logo.png => {PROJECT_ROOT}/static/images/logo.png
/css/main.css => {PROJECT_ROOT}/static/css/main.css
/js/app/index.js => {PROJECT_ROOT}/static/js/app/index.js
/robot.txt => {PROJECT_ROOT}/static/robot.txt
/favicon.ico => {PROJECT_ROOT}/static/favicon.ico
“‘
You can change these rules by rewriting "PROJECT_ROOT/app.lisp". See [Clack.Middleware.Static](http://quickdocs.org/clack/api#package-CLACK.MIDDLEWARE.STATIC) for detail.
### Configuration
Caveman adopts [Envy](https://github.com/fukamachi/envy) as a configuration switcher. It allows to define multiple configurations and to switch them by an environment variable.
This is a typical example.
“‘common-lisp
(defpackage :myapp.config
(:use :cl
:envy))
(in-package :myapp.config)
(setf (config-env-var) "APP_ENV")
(defconfig :common
‘(:application-root ,(asdf:component-pathname (asdf:find-system :myapp))))
(defconfig |development|
’(:debug T
:databases
((:maindb :sqlite3 :database-name ,(merge-pathnames #P"test.db"
*application-root*)))))
(defconfig |production|
’(:databases
((:maindb :mysql :database-name "myapp" :username "whoami" :password "1234")
(:workerdb :mysql :database-name "jobs" :username "whoami" :password "1234"))))
(defconfig |staging|
‘(:debug T
,@|production|))
“‘
Every configuration is a property list. You can choose the configuration which to use by setting ‘APP_ENV‘.
To get a value from the current configuration, call ‘myapp.config:config‘ with a key you want.
“‘common-lisp
(import ’myapp.config:config)
(setf (osicat:environment-variable "APP_ENV") "development")
(config :debug)
;=> T
“‘
### Database
When you add ‘:databases‘ to the configuration, Caveman enables database support. ‘:databases‘ is an association list of database settings.
“‘common-lisp
(defconfig |production|
’(:databases
((:maindb :mysql :database-name "myapp" :username "whoami" :password "1234")
(:workerdb :mysql :database-name "jobs" :username "whoami" :password "1234"))))
“‘
‘db‘ in a package ‘myapp.db‘ is a function for connecting to each databases configured the above. Here is an example.
“‘common-lisp
(use-package ’(:myapp.db :sxql :datafly))
(defun search-adults ()
(with-connection (db)
(retrieve-all
(select :*
(from :person)
(where (:>= :age 20))))))
“‘
The connection is alive during the Lisp session and will be reused in each HTTP requests.
‘retrieve-all‘ and the query language came from [datafly](https://github.com/fukamachi/datafly) and [SxQL](https://github.com/fukamachi/sxql). See those documentations for more informations.
### Set HTTP headers or HTTP status
There are several special variables available during a HTTP request. ‘*request*‘ and ‘*response*‘ represents a request and a response. If you are familiar with [Clack](http://clacklisp.org/), these are instances of subclasses of [Clack.Request](http://quickdocs.org/clack/api#package-CLACK.REQUEST) and [Clack.Response](http://quickdocs.org/clack/api#package-CLACK.RESPONSE).
“‘common-lisp
(use-package :caveman2)
;; Get a value of Referer header.
(http-referer *request*)
;; Set Content-Type header.
(setf (getf (response-headers *response* :content-type) "application/json")
;; Set HTTP status.
(setf (status *response*) 304)
“‘
If you would like to set Content-Type "application/json" for all "*.json" requests, ‘next-route‘ will help you.
“‘common-lisp
(defroute "/*.json" ()
(setf (getf (response-headers *response*) :content-type) "application/json")
(next-route))
(defroute "/user.json" () ...)
(defroute "/search.json" () ...)
(defroute ("/new.json" :method :POST) () ...)
“‘
### Using session
Session data is for memorizing user-specific data. ‘*session*‘ is a hash table represents session data.
This example increments ‘:counter‘ in the session and displays it for each visitors.
“‘common-lisp
(defroute "/counter" ()
(format nil "You came here ~A times."
(incf (gethash :counter *session* 0))))
“‘
Caveman2 stores the session data in-memory by default. To change it, specify ‘:store‘ to ‘:session‘ in "PROJECT_ROOT/app.lisp".
This example uses RDBMS to store it.
“‘diff
’(:backtrace
:output (getf (config) :error-log))
nil)
- :session
+ (:session
+ :store (make-dbi-store :connector (lambda ()
+ (apply #’dbi:connect
+ (myapp.db:connection-settings)))))
(if (productionp)
nil
(lambda (app)
“‘
NOTE: Don’t forget to add ‘:lack-session-store-dbi‘ as ‘:depends-on‘ of your app. It is not a part of Clack/Lack.
See the source code of Lack.Session.Store.DBi for more informations.
- [Lack.Session.Store.Dbi](https://github.com/fukamachi/lack/blob/master/src/middleware/session/store/dbi.lisp)
### Throw an HTTP status code
“‘common-lisp
(import ’caveman2:throw-code)
(defroute ("/auth" :method :POST) (&key |name| |password|)
(unless (authorize |name| |password|)
(throw-code 403)))
“‘
### Specify error pages
To specify error pages for 404, 500 or so, define a method ‘on-exception‘ of your app.
“‘common-lisp
(defmethod on-exception ((app <web>) (code (eql 404)))
(declare (ignore app code))
(merge-pathnames #P"_errors/404.html"
*template-directory*))
“‘
### Start a server
Your application has functions named ‘start‘ and ‘stop‘ to start/stop your web application. This is a example assuming that the name of your application is "myapp".
“‘common-lisp
(myapp:start :port 8080)
“‘
As Caveman bases on Clack/Lack, you can choose which server to run on – Hunchentoot, mod_lisp or FastCGI.
“‘common-lisp
(myapp:start :server :hunchentoot :port 8080)
(myapp:start :server :fcgi :port 8080)
“‘
I recommend you to use Hunchentoot in local machine and use FastCGI/Woo for production environment.
You can also start your application by using [clackup command](https://github.com/fukamachi/clack/blob/master/roswell/clackup.ros).
$ ros install clack
$ which clackup
/Users/nitro_idiot/.roswell/bin/clackup
$ APP_ENV=development clackup –server :fcgi –port 8080 app.lisp
### Hot Deployment
Though Caveman doesn’t have a feature for hot deployment, [Server::Starter](http://search.cpan.org/~kazuho/Server-Starter-0.15/lib/Server/Starter.pm) – a Perl module – makes it easy.
$ APP_ENV=production start_server –port 8080 – clackup –server :fcgi app.lisp
NOTE: Server::Starter requires the server to support binding on a specific fd, which means only ‘:fcgi‘ and ‘:woo‘ are the ones work with ‘start_server‘ command.
To restart the server, send HUP signal (‘kill -HUP <pid>‘) to the ‘start_server‘ process.
### Error Log
Caveman outputs error backtraces to a file which is specified at ‘:error-log‘ in your configuration.
“‘common-lisp
(defconfig |default|
‘(:error-log #P"/var/log/apps/myapp_error.log"
:databases
((:maindb :sqlite3 :database-name ,(merge-pathnames #P"myapp.db"
*application-root*)))))
“‘
## Use another templating library
### CL-WHO
“‘common-lisp
(import ’cl-who:with-html-output-to-string)
(defroute "/" ()
(with-html-output-to-string (output nil :prologue t)
(:html
(:head (:title "Welcome to Caveman!"))
(:body "Blah blah blah."))))
;=> "<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Strict//EN\" \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd\">
; <html><head><title>Welcome to Caveman!</title></head><body>Blah blah blah.</body></html>"
“‘
* [CL-WHO Website](http://weitz.de/cl-who/)
### CL-Markup
“‘common-lisp
(import ’cl-markup:xhtml)
(defroute "/" ()
(xhtml
(:head (:title "Welcome to Caveman!"))
(:body "Blah blah blah.")))
;=> "<?xml version=\"1.0\" encoding=\"UTF-8\"?><!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\" \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\"><html><head><title>Welcome to Caveman!</title></head><body>Blah blah blah.</body></html>"
“‘
* [CL-Markup repository](https://github.com/arielnetworks/cl-markup)
### cl-closure-template
“‘html
{namespace myapp.view}
{template renderIndex}
<!DOCTYPE html>
<html>
<head>
<title>"Welcome to Caveman!</title>
</head>
<body>
Blah blah blah.
</body>
</html>
{/template}
“‘
“‘common-lisp
(import ’myapp.config:*template-directory*)
(closure-template:compile-cl-templates (merge-pathnames #P"index.tmpl"
*template-directory*))
(defroute "/" ()
(myapp.view:render-index))
“‘
* [cl-closure-template](http://quickdocs.org/cl-closure-template/)
* [Closure Templates Documentation](https://developers.google.com/closure/templates/docs/overview)
<!– Commenting out because these are old.
## Use another database library
### CLSQL
You can use Lack.Middleware.Clsql to use CLSQL in Clack compliant application.
In Caveman, add the middleware to ‘builder‘ in "PROJECT_ROOT/app.lisp".
“‘common-lisp
(ql:quickload :clack-middleware-clsql)
(import ’clack.middleware.clsql:<clack-middleware-clsql>)
(builder
(<clack-middleware-clsql>
:database-type :mysql
:connection-spec ’("localhost" "db" "fukamachi" "password"))
*web*)
“‘
* [Clack.Middleware.Clsql](http://quickdocs.org/clack/api#system-clack-middleware-clsql)
* [CLSQL: Common Lisp SQL Interface](http://clsql.b9.com/)
### Postmodern
You can use Clack.Middleware.Postmodern to use Postmodern in Clack compliant application.
In Caveman, add the middleware to ‘builder‘ in "PROJECT_ROOT/app.lisp".
“‘common-lisp
(ql:quickload :clack-middleware-postmodern)
(import ’clack.middleware.postmodern:<clack-middleware-postmodern>)
(builder
(<clack-middleware-postmodern>
:database "database-name"
:user "database-user"
:password "database-password"
:host "remote-address")
*web*)
“‘
* [Clack.Middleware.Postmodern](http://quickdocs.org/clack/api#system-clack-middleware-postmodern)
* [Postmodern](http://marijnhaverbeke.nl/postmodern/)
–>
## See Also
* [Clack](http://clacklisp.org/) - Web application environment.
* [Lack](https://github.com/fukamachi/lack) - The core of Clack.
* [ningle](http://8arrow.org/ningle/) - Super micro web application framework Caveman bases on.
* [Djula](http://mmontone.github.io/djula/) - HTML Templating engine.
* [CL-DBI](http://8arrow.org/cl-dbi/) - Database independent interface library.
* [SxQL](http://8arrow.org/sxql/) - SQL builder library.
* [Envy](https://github.com/fukamachi/envy) - Configuration switcher.
* [Roswell](https://github.com/snmsts/roswell) - Common Lisp implementation manager.
## Author
* Eitaro Fukamachi (e.arrows@gmail.com)
# License
Licensed under the LLGPL License.
12.8.0
caveman.asd (file)
v1/src (module)
Modules are listed depth-first from the system components tree.
| • The caveman/v1/src module: | ||
| • The caveman/v1/src/core module: | ||
| • The caveman/v1/src/lib module: | ||
| • The caveman/v1/src/lib/widget module: | ||
| • The caveman/v1/src/lib/view module: |
Next: The caveman/v1/src/core module, Previous: Modules, Up: Modules [Contents][Index]
Next: The caveman/v1/src/lib module, Previous: The caveman/v1/src module, Up: Modules [Contents][Index]
v1/src (module)
v1/src/core/
Next: The caveman/v1/src/lib/widget module, Previous: The caveman/v1/src/core module, Up: Modules [Contents][Index]
Next: The caveman/v1/src/lib/view module, Previous: The caveman/v1/src/lib module, Up: Modules [Contents][Index]
Previous: The caveman/v1/src/lib/widget module, Up: Modules [Contents][Index]
lib (module)
v1/src/lib/view/
Files are sorted by type and then listed depth-first from the systems components trees.
| • Lisp files: |
Next: The caveman/v1/src/core/caveman<dot>lisp file, Previous: Lisp files, Up: Lisp files [Contents][Index]
caveman.asd
caveman (system)
Next: The caveman/v1/src/core/app<dot>lisp file, Previous: The caveman<dot>asd file, Up: Lisp files [Contents][Index]
core (module)
v1/src/core/caveman.lisp
Next: The caveman/v1/src/core/project<dot>lisp file, Previous: The caveman/v1/src/core/caveman<dot>lisp file, Up: Lisp files [Contents][Index]
core (module)
v1/src/core/app.lisp
Next: The caveman/v1/src/core/request<dot>lisp file, Previous: The caveman/v1/src/core/app<dot>lisp file, Up: Lisp files [Contents][Index]
core (module)
v1/src/core/project.lisp
Next: The caveman/v1/src/core/response<dot>lisp file, Previous: The caveman/v1/src/core/project<dot>lisp file, Up: Lisp files [Contents][Index]
core (module)
v1/src/core/request.lisp
Next: The caveman/v1/src/core/context<dot>lisp file, Previous: The caveman/v1/src/core/request<dot>lisp file, Up: Lisp files [Contents][Index]
core (module)
v1/src/core/response.lisp
<response> (class)
Next: The caveman/v1/src/core/middleware/context<dot>lisp file, Previous: The caveman/v1/src/core/response<dot>lisp file, Up: Lisp files [Contents][Index]
core (module)
v1/src/core/context.lisp
Next: The caveman/v1/src/core/skeleton<dot>lisp file, Previous: The caveman/v1/src/core/context<dot>lisp file, Up: Lisp files [Contents][Index]
context.lisp (file)
core (module)
v1/src/core/middleware/context.lisp
<caveman-middleware-context> (class)
Next: The caveman/v1/src/core/route<dot>lisp file, Previous: The caveman/v1/src/core/middleware/context<dot>lisp file, Up: Lisp files [Contents][Index]
core (module)
v1/src/core/skeleton.lisp
generate (function)
*skeleton-directory* (special variable)
Next: The caveman/v1/src/core/widget<dot>lisp file, Previous: The caveman/v1/src/core/skeleton<dot>lisp file, Up: Lisp files [Contents][Index]
app.lisp (file)
core (module)
v1/src/core/route.lisp
add-query-parameters (function)
Next: The caveman/v1/src/lib/widget/form<dot>lisp file, Previous: The caveman/v1/src/core/route<dot>lisp file, Up: Lisp files [Contents][Index]
core (module)
v1/src/core/widget.lisp
Next: The caveman/v1/src/lib/view/function<dot>lisp file, Previous: The caveman/v1/src/core/widget<dot>lisp file, Up: Lisp files [Contents][Index]
widget (module)
v1/src/lib/widget/form.lisp
Next: The caveman/v1/src/lib/view/emb<dot>lisp file, Previous: The caveman/v1/src/lib/widget/form<dot>lisp file, Up: Lisp files [Contents][Index]
view (module)
v1/src/lib/view/function.lisp
render (function)
Previous: The caveman/v1/src/lib/view/function<dot>lisp file, Up: Lisp files [Contents][Index]
function.lisp (file)
view (module)
v1/src/lib/view/emb.lisp
render (function)
Next: Definitions, Previous: Files, Up: Top [Contents][Index]
Packages are listed by definition order.
Next: The caveman package, Previous: Packages, Up: Packages [Contents][Index]
caveman.asd
Next: The caveman<dot>app package, Previous: The caveman-asd package, Up: Packages [Contents][Index]
caveman.lisp (file)
common-lisp
Next: The caveman<dot>project package, Previous: The caveman package, Up: Packages [Contents][Index]
app.lisp (file)
Next: The caveman<dot>request package, Previous: The caveman<dot>app package, Up: Packages [Contents][Index]
project.lisp (file)
Next: The caveman<dot>response package, Previous: The caveman<dot>project package, Up: Packages [Contents][Index]
request.lisp (file)
Next: The caveman<dot>context package, Previous: The caveman<dot>request package, Up: Packages [Contents][Index]
response.lisp (file)
<response> (class)
Next: The caveman<dot>middleware<dot>context package, Previous: The caveman<dot>response package, Up: Packages [Contents][Index]
context.lisp (file)
Next: The caveman<dot>skeleton package, Previous: The caveman<dot>context package, Up: Packages [Contents][Index]
middleware/context.lisp (file)
<caveman-middleware-context> (class)
Next: The caveman<dot>route package, Previous: The caveman<dot>middleware<dot>context package, Up: Packages [Contents][Index]
skeleton.lisp (file)
common-lisp
generate (function)
*skeleton-directory* (special variable)
Next: The caveman<dot>widget package, Previous: The caveman<dot>skeleton package, Up: Packages [Contents][Index]
route.lisp (file)
add-query-parameters (function)
Next: The caveman<dot>widget<dot>form package, Previous: The caveman<dot>route package, Up: Packages [Contents][Index]
widget.lisp (file)
Next: The caveman<dot>view<dot>function package, Previous: The caveman<dot>widget package, Up: Packages [Contents][Index]
form.lisp (file)
Next: The caveman<dot>view<dot>emb package, Previous: The caveman<dot>widget<dot>form package, Up: Packages [Contents][Index]
function.lisp (file)
common-lisp
render (function)
Previous: The caveman<dot>view<dot>function package, Up: Packages [Contents][Index]
Definitions are sorted by export status, category, package, and then by lexicographic order.
| • Exported definitions: | ||
| • Internal definitions: |
Next: Internal definitions, Previous: Definitions, Up: Definitions [Contents][Index]
| • Exported special variables: | ||
| • Exported macros: | ||
| • Exported functions: | ||
| • Exported generic functions: | ||
| • Exported classes: |
Next: Exported macros, Previous: Exported definitions, Up: Exported definitions [Contents][Index]
Special variable to store Caveman Context, a hash table.
Don’t set to this variable directly. This is designed to be bound in lexical let.
context.lisp (file)
Special variable to store current Caveman application.
Don’t set to this variable directly. This is designed to be bound in lexical let.
context.lisp (file)
Special variable to store Caveman Request, a instance of ‘<request>’ in Caveman.Request package. Don’t set to this variable directly. This is designed to be bound in lexical let.
context.lisp (file)
Special variable to store Caveman Response, a instance of ‘<response>’ in Caveman.Response package. Don’t set to this variable directly. This is designed to be bound in lexical let.
context.lisp (file)
Special variable to store session.
Don’t set to this variable directly. This is designed to be bound in lexical let.
context.lisp (file)
Next: Exported functions, Previous: Exported special variables, Up: Exported definitions [Contents][Index]
Recreation of @URL annotation in S-expression form
route.lisp (file)
Useful annotation to define actions.
Example:
;; for Function
@url GET "/login"
(defun login (req)
;; response
)
;; for Clack Component
@url GET "/member/:id"
(defclass <member-profile> (<component>) ())
(defmethod call ((this <member-profile>) req)
;; response
)
route.lisp (file)
Convert action form into a routing rule, a list.
Example:
((member-profile #<url-rule> #’member-profile)
(login-form #<url-rule> #’login-form))
route.lisp (file)
context.lisp (file)
Next: Exported generic functions, Previous: Exported macros, Up: Exported definitions [Contents][Index]
caveman.lisp (file)
caveman.lisp (file)
Access to current context. If key is specified, return the value in current context.
If not, just return a current context.
Example:
(context)
;=> #<HASH-TABLE :TEST EQL size 0/60 #x3020025FF5FD>
(context :request)
;=> #<CAVEMAN.REQUEST:<REQUEST> #x3020024FCCFD>
context.lisp (file)
(setf context) (function)
context.lisp (file)
context (function)
caveman.lisp (file)
caveman.lisp (file)
caveman.lisp (file)
Generate a skeleton of Caveman Application.
‘name’ must be a symbol or a keyword. ‘path’ must be a pathname. If ‘path’ isn’t specified, generate a skeleton to current directory.
skeleton.lisp (file)
Create a new Context.
context.lisp (file)
A synonim for ‘(make-instance ’<caveman-widget-form> ...)‘.
form.lisp (file)
Construct a request instance.
request.lisp (file)
app.lisp (file)
An action when no routing rules are found.
app.lisp (file)
caveman.lisp (file)
Render function for Functions.
function.lisp (file)
Render function for CL-EMB templates.
emb.lisp (file)
Make an URL for the action with PARAMS.
Example:
@url GET "/animals/:type"
(defun animals (params))
(url-for ’animals :type "cat")
;; => "/animals/cat"
route.lisp (file)
Next: Exported classes, Previous: Exported functions, Up: Exported definitions [Contents][Index]
Add another widget to this form. That will be rendered in ’form’ tag.
form.lisp (file)
Add a routing rule to the Application.
app.lisp (file)
Build up an application for this project and return it. This method must be implemented in subclasses.
project.lisp (file)
automatically generated reader method
project.lisp (file)
automatically generated writer method
project.lisp (file)
automatically generated reader method
project.lisp (file)
automatically generated writer method
project.lisp (file)
project.lisp (file)
Lookup a routing rule with SYMBOL from the application.
app.lisp (file)
automatically generated reader method
project.lisp (file)
automatically generated writer method
project.lisp (file)
widget.lisp (file)
project.lisp (file)
project.lisp (file)
Stop a server.
project.lisp (file)
form.lisp (file)
automatically generated reader method
widget.lisp (file)
automatically generated writer method
widget.lisp (file)
Previous: Exported generic functions, Up: Exported definitions [Contents][Index]
Base class for Caveman Application. All Caveman Application must inherit this class.
app.lisp (file)
<component> (class)
caveman.app::routing-rules
routing-rules (generic function)
(setf routing-rules) (generic function)
Clack Middleware to set context for each request.
middleware/context.lisp (file)
<middleware> (class)
call (method)
form.lisp (file)
<caveman-widget> (class)
string
:action
""
form-action (generic function)
(setf form-action) (generic function)
keyword
:method
:post
form-method (generic function)
(setf form-method) (generic function)
list
:components
form-components (generic function)
(setf form-components) (generic function)
Base class of view widget.
widget.lisp (file)
standard-object (class)
<caveman-widget-form> (class)
(or null function clack.component:<component>)
:view
view (generic function)
(setf view) (generic function)
project.lisp (file)
<component> (class)
:config
config (generic function)
(setf config) (generic function)
acceptor (generic function)
(setf acceptor) (generic function)
boolean
:debug-mode-p
t
debug-mode-p (generic function)
(setf debug-mode-p) (generic function)
keyword
:mode
project-mode (generic function)
(setf project-mode) (generic function)
Class for Caveman Request.
request.lisp (file)
<request> (class)
Class for Caveman Response.
response.lisp (file)
<response> (class)
Previous: Exported definitions, Up: Definitions [Contents][Index]
| • Internal special variables: | ||
| • Internal functions: | ||
| • Internal generic functions: |
Next: Internal functions, Previous: Internal definitions, Up: Internal definitions [Contents][Index]
A function called when ‘next-route’ is invoked. This will be overwritten in ‘dispatch-with-rules’.
app.lisp (file)
skeleton.lisp (file)
Next: Internal generic functions, Previous: Internal special variables, Up: Internal definitions [Contents][Index]
Add a query parameters string of PARAMS to BASE-URL.
route.lisp (file)
app.lisp (file)
app.lisp (file)
Read a specified file and return the content as a sequence.
project.lisp (file)
Previous: Internal functions, Up: Internal definitions [Contents][Index]
automatically generated reader method
project.lisp (file)
automatically generated writer method
project.lisp (file)
Previous: Definitions, Up: Top [Contents][Index]
| • Concept index: | ||
| • Function index: | ||
| • Variable index: | ||
| • Data type index: |
Next: Function index, Previous: Indexes, Up: Indexes [Contents][Index]
| Jump to: | C F L M |
|---|
| Jump to: | C F L M |
|---|
Next: Variable index, Previous: Concept index, Up: Indexes [Contents][Index]
| Jump to: | (
A B C D F G L M N P R S U V W |
|---|
| Jump to: | (
A B C D F G L M N P R S U V W |
|---|
Next: Data type index, Previous: Function index, Up: Indexes [Contents][Index]
| Jump to: | *
A C D M R S V |
|---|
| Jump to: | *
A C D M R S V |
|---|
Previous: Variable index, Up: Indexes [Contents][Index]
| Jump to: | <
C P S |
|---|
| Jump to: | <
C P S |
|---|