The ningle Reference Manual

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

The ningle Reference Manual

This is the ningle Reference Manual, version 0.3.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Thu Sep 15 05:44:20 2022 GMT+0.

Table of Contents

Next: , Previous: , Up: The ningle Reference Manual   [Contents][Index]

1 Introduction

ningle

Build Status

"ningle" is a lightweight web application framework for Common Lisp.

Usage

(defvar *app* (make-instance 'ningle:app))

(setf (ningle:route *app* "/")
      "Welcome to ningle!")

(setf (ningle:route *app* "/login" :method :POST)
      #'(lambda (params)
          (if (authorize (cdr (assoc "username" params :test #'string=))
                         (cdr (assoc "password" params :test #'string=)))
              "Authorized!"
              "Failed...Try again.")))

(clack:clackup *app*)

Now you can access to http://localhost:5000/ and then ningle should show you "Welcome to ningle!".

Installation

(ql:quickload :ningle)

Description

ningle is a fork project of Caveman. ningle doesn't require you to generate a project skeleton.

As this is a thin framework, you need to have subtle knowledge about Clack. It is a server interface ningle bases on.

Getting started

Routing

ningle has the Sinatra-like routing system.

;; GET request (default)
(setf (ningle:route *app* "/" :method :GET) ...)

;; POST request
(setf (ningle:route *app* "/" :method :POST) ...)

;; PUT request
(setf (ningle:route *app* "/" :method :PUT) ...)

;; DELETE request
(setf (ningle:route *app* "/" :method :DELETE) ...)

;; OPTIONS request
(setf (ningle:route *app* "/" :method :OPTIONS) ...)

Route pattern may contain "keyword" to put the value into the argument.

(setf (ningle:route *app* "/hello/:name")
      #'(lambda (params)
          (format nil "Hello, ~A" (cdr (assoc :name params)))))

The above controller will be invoked when you access to "/hello/Eitaro" or "/hello/Tomohiro", and then (cdr (assoc :name params)) will be "Eitaro" and "Tomohiro".

Route patterns may also contain "wildcard" parameters. They are accessible by (assoc :splat params).

(setf (ningle:route *app* "/say/*/to/*")
      #'(lambda (params)
          ; matches /say/hello/to/world
          (cdr (assoc :splat params)) ;=> ("hello" "world")
          ))

(setf (ningle:route *app* "/download/*.*")
      #'(lambda (params)
          ; matches /download/path/to/file.xml
          (cdr (assoc :splat params)) ;=> ("path/to/file" "xml")
          ))

Route matching with Regular Expressions:

(setf (ningle:route *app* "/hello/([\\w]+)" :regexp t)
      #'(lambda (params)
          (format nil "Hello, ~A!" (first (cdr (assoc :captures params))))))

Requirements

Routes may include a variety of matching conditions, such as the Accept:

(setf (ningle:route *app* "/" :accept '("text/html" "text/xml"))
      #'(lambda (params)
          (declare (ignore params))
          "<html><body>Hello, World!</body></html>"))

(setf (ningle:route *app* "/" :accept "text/plain")
      #'(lambda (params)
          (declare (ignore params))
          "Hello, World!"))

You can easily define your own conditions:

(setf (ningle:requirement *app* :probability)
      #'(lambda (value)
          (<= (random 100) value)))

(setf (ningle:route *app* "/win_a_car" :probability 10)
      #'(lambda (params)
          (declare (ignore params))
          "You won!"))

(setf (ningle:route *app* "/win_a_car")
      #'(lambda (params)
          (declare (ignore params))
          "Sorry, you lost."))

Request & Response

ningle provides two special variables named *request* and *response*. They will be bound to an instance Lack.Request and Lack.Response for each request.

For example, by using them, you can change the response status code, Content-Type or something like that in each controllers.

(setf (lack.response:response-headers *response*)
      (append (lack.response:response-headers *response*)
              (list :content-type "application/json")))

(setf (lack.response:response-headers *response*)
      (append (lack.response:response-headers *response*)
              (list :access-control-allow-origin "*")))

(setf (lack.response:response-status *response*) 201)

Context

ningle provides a useful function named context. It is an accessor to an internal hash table.

(setf (context :database)
      (dbi:connect :mysql
                   :database-name "test-db"
                   :username "nobody"
                   :password "nobody"))

(context :database)
;;=> #<DBD.MYSQL:<DBD-MYSQL-CONNECTION> #x3020013D1C6D>

Using Session

ningle doesn't provide Session system in the core, but recommends to use Lack.Middleware.Session with Lack.Builder.

(import 'lack.builder:builder)

(clack:clackup
  (builder
    :session
    *app*))

Of course, you can use other Lack Middlewares with ningle.

See Also

Author

Copyright

Copyright (c) 2012-2014 Eitaro Fukamachi (e.arrows@gmail.com)

License

Licensed under the LLGPL License.

Next: , Previous: , Up: The ningle Reference Manual   [Contents][Index]

2 Systems

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

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

2.1 ningle

Super micro framework for Common Lisp.

Author

Eitaro Fukamachi

License

LLGPL

Version

0.3.0

Dependencies
Source

ningle.asd.

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

2.2 ningle/main

Author

Eitaro Fukamachi

License

LLGPL

Dependencies
Source

ningle.asd.

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

2.3 ningle/app

Author

Eitaro Fukamachi

License

LLGPL

Dependencies
  • ningle/context (system).
  • ningle/route (system).
  • lack-request (system).
  • lack-response (system).
  • lack-component (system).
  • myway (system).
  • alexandria (system).
Source

ningle.asd.

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

2.4 ningle/context

Author

Eitaro Fukamachi

License

LLGPL

Source

ningle.asd.

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

2.5 ningle/route

Author

Eitaro Fukamachi

License

LLGPL

Dependency

myway (system).

Source

ningle.asd.

Next: , Previous: , Up: The ningle Reference Manual   [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   [Contents][Index]

3.1.1 ningle/ningle.asd

Source

ningle.asd.

Parent Component

ningle (system).

ASDF Systems

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

3.1.2 ningle/main/file-type.lisp

Source

ningle.asd.

Parent Component

ningle/main (system).

Packages

ningle.

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

3.1.3 ningle/app/file-type.lisp

Source

ningle.asd.

Parent Component

ningle/app (system).

Packages

ningle/app.

Public Interface
Internals

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

3.1.4 ningle/context/file-type.lisp

Source

ningle.asd.

Parent Component

ningle/context (system).

Packages

ningle/context.

Public Interface

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

3.1.5 ningle/route/file-type.lisp

Source

ningle.asd.

Parent Component

ningle/route (system).

Packages

ningle/route.

Public Interface
Internals

Next: , Previous: , Up: The ningle Reference Manual   [Contents][Index]

4 Packages

Packages are listed by definition order.

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

4.1 ningle/route

Source

file-type.lisp.

Nickname

ningle.route

Use List

common-lisp.

Public Interface
Internals

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

4.2 ningle

Source

file-type.lisp.

Nickname

ningle/main

Use List

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

4.3 ningle/context

Source

file-type.lisp.

Nickname

ningle.context

Use List

common-lisp.

Used By List

ningle.

Public Interface

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

4.4 ningle/app

Source

file-type.lisp.

Nickname

ningle.app

Use List

common-lisp.

Used By List

ningle.

Public Interface
Internals

Next: , Previous: , Up: The ningle Reference Manual   [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 Public Interface

Next: , Previous: , Up: Public Interface   [Contents][Index]

5.1.1 Special variables

Special Variable: *context*

Special variable to store Ningle Context, a hash table.
Don’t set to this variable directly. This is designed to be bound in lexical let.

Package

ningle/context.

Source

file-type.lisp.

Special Variable: *request*

Special variable to store Ningle Request, a instance of ‘<request>’ in Ningle.Request package. Don’t set to this variable directly. This is designed to be bound in lexical let.

Package

ningle/context.

Source

file-type.lisp.

Special Variable: *response*

Special variable to store Ningle Response, a instance of ‘<response>’ in Ningle.Response package. Don’t set to this variable directly. This is designed to be bound in lexical let.

Package

ningle/context.

Source

file-type.lisp.

Special Variable: *session*

Special variable to store session.
Don’t set to this variable directly. This is designed to be bound in lexical let.

Package

ningle/context.

Source

file-type.lisp.

Next: , Previous: , Up: Public Interface   [Contents][Index]

5.1.2 Macros

Macro: with-context-variables ((&rest vars) &body body)
Package

ningle/context.

Source

file-type.lisp.

Next: , Previous: , Up: Public Interface   [Contents][Index]

5.1.3 Ordinary functions

Function: clear-routing-rules (app)
Package

ningle/app.

Source

file-type.lisp.

Function: context (&optional key)

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>

Package

ningle/context.

Source

file-type.lisp.

Function: (setf context) (key)
Package

ningle/context.

Source

file-type.lisp.

Function: make-context (app env)

Create a new Context.

Package

ningle/context.

Source

file-type.lisp.

Function: requirement (app name)
Package

ningle/app.

Source

file-type.lisp.

Function: (setf requirement) (app name)
Package

ningle/app.

Source

file-type.lisp.

Next: , Previous: , Up: Public Interface   [Contents][Index]

5.1.4 Generic functions

Generic Function: make-request (app env)

Make a request object. See ningle.app for the default behavior.

Package

ningle/context.

Source

file-type.lisp.

Methods
Method: make-request ((app app) env)

Make a request object. A class of the request object can be changed by overwriting this.

Source

file-type.lisp.

Generic Function: make-response (app &optional status headers body)

Make a response object. See ningle.app for the default behavior.

Package

ningle/context.

Source

file-type.lisp.

Methods
Method: make-response ((app app) &optional status headers body)

Make a response object. A class of the response object can be changed by overwriting this.

Source

file-type.lisp.

Generic Function: not-found (app)

An action when no routing rules are found.

Package

ningle/app.

Source

file-type.lisp.

Methods
Method: not-found ((this app))
Generic Function: process-response (app result)
Package

ningle/app.

Methods
Method: process-response ((app app) result)
Source

file-type.lisp.

Generic Function: route (app string-url-rule &rest args &key method identifier regexp &allow-other-keys)
Package

ningle/app.

Source

file-type.lisp.

Methods
Method: route ((this app) string-url-rule &rest args &key method identifier regexp &allow-other-keys)
Generic Function: (setf route) (app string-url-rule &rest args &key method identifier regexp &allow-other-keys)
Package

ningle/app.

Source

file-type.lisp.

Methods
Method: (setf route) ((this app) string-url-rule &rest args &key method identifier regexp &allow-other-keys)
Generic Reader: route-controller (object)
Package

ningle/route.

Methods
Reader Method: route-controller ((ningle-route ningle-route))

automatically generated reader method

Source

file-type.lisp.

Target Slot

controller.

Generic Writer: (setf route-controller) (object)
Package

ningle/route.

Methods
Writer Method: (setf route-controller) ((ningle-route ningle-route))

automatically generated writer method

Source

file-type.lisp.

Target Slot

controller.

Next: , Previous: , Up: Public Interface   [Contents][Index]

5.1.5 Standalone methods

Method: call ((this app) env)

Overriding method. This method will be called for each request.

Package

lack.component.

Source

file-type.lisp.

Method: call :around ((this app) env)
Package

lack.component.

Source

file-type.lisp.

Method: equal-route ((route1 ningle-route) (route2 ningle-route))
Package

myway.route.

Source

file-type.lisp.

Method: initialize-instance :after ((route ningle-route) &rest initargs &key requirements-map requirements &allow-other-keys)
Source

file-type.lisp.

Method: match-route ((route ningle-route) method url-string &key allow-head)
Package

myway.route.

Source

file-type.lisp.

Previous: , Up: Public Interface   [Contents][Index]

5.1.6 Classes

Class: <app>

Base class for Ningle Application. All Ningle Application must inherit this class.

Package

ningle/app.

Source

file-type.lisp.

Direct superclasses

lack-component.

Direct methods
Direct slots
Slot: mapper
Initform

(myway.mapper:make-mapper)

Readers

mapper.

Writers

(setf mapper).

Slot: requirements
Type

hash-table

Initform

(ningle/app::default-requirements-map)

Readers

app-requirements.

Writers

(setf app-requirements).

Class: app

Base class for Ningle Application. All Ningle Application must inherit this class.

Package

ningle/app.

Source

file-type.lisp.

Direct superclasses

lack-component.

Direct methods
Direct slots
Slot: mapper
Initform

(myway.mapper:make-mapper)

Readers

mapper.

Writers

(setf mapper).

Slot: requirements
Type

hash-table

Initform

(ningle/app::default-requirements-map)

Readers

app-requirements.

Writers

(setf app-requirements).

Class: ningle-route
Package

ningle/route.

Source

file-type.lisp.

Direct superclasses

route.

Direct methods
Direct slots
Slot: requirements
Initform

(quote nil)

Initargs

:requirements

Readers

route-requirements.

Writers

(setf route-requirements).

Slot: compiled-requirements
Initargs

:compiled-requirements

Readers

route-compiled-requirements.

Writers

(setf route-compiled-requirements).

Slot: controller
Initargs

:controller

Readers

route-controller.

Writers

(setf route-controller).

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

5.2 Internals

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

5.2.1 Macros

Macro: with-context ((context) &body body)
Package

ningle/app.

Source

file-type.lisp.

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

5.2.2 Ordinary functions

Function: compile-requirements (map requirements)
Package

ningle/route.

Source

file-type.lisp.

Function: default-requirements-map ()
Package

ningle/app.

Source

file-type.lisp.

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

5.2.3 Generic functions

Generic Reader: app-requirements (object)
Package

ningle/app.

Methods
Reader Method: app-requirements ((app app))

automatically generated reader method

Source

file-type.lisp.

Target Slot

requirements.

Generic Writer: (setf app-requirements) (object)
Package

ningle/app.

Methods
Writer Method: (setf app-requirements) ((app app))

automatically generated writer method

Source

file-type.lisp.

Target Slot

requirements.

Generic Reader: mapper (object)
Package

ningle/app.

Methods
Reader Method: mapper ((app app))

automatically generated reader method

Source

file-type.lisp.

Target Slot

mapper.

Generic Writer: (setf mapper) (object)
Package

ningle/app.

Methods
Writer Method: (setf mapper) ((app app))

automatically generated writer method

Source

file-type.lisp.

Target Slot

mapper.

Generic Reader: route-compiled-requirements (object)
Package

ningle/route.

Methods
Reader Method: route-compiled-requirements ((ningle-route ningle-route))

automatically generated reader method

Source

file-type.lisp.

Target Slot

compiled-requirements.

Generic Writer: (setf route-compiled-requirements) (object)
Package

ningle/route.

Methods
Writer Method: (setf route-compiled-requirements) ((ningle-route ningle-route))

automatically generated writer method

Source

file-type.lisp.

Target Slot

compiled-requirements.

Generic Reader: route-requirements (object)
Package

ningle/route.

Methods
Reader Method: route-requirements ((ningle-route ningle-route))

automatically generated reader method

Source

file-type.lisp.

Target Slot

requirements.

Generic Writer: (setf route-requirements) (object)
Package

ningle/route.

Methods
Writer Method: (setf route-requirements) ((ningle-route ningle-route))

automatically generated writer method

Source

file-type.lisp.

Target Slot

requirements.

Previous: , Up: The ningle Reference Manual   [Contents][Index]

Appendix A Indexes

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

A.1 Concepts

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

A.2 Functions

Jump to:   (  
A   C   D   E   F   G   I   M   N   P   R   W  
Index Entry  Section
(
(setf app-requirements): Private generic functions
(setf app-requirements): Private generic functions
(setf context): Public ordinary functions
(setf mapper): Private generic functions
(setf mapper): Private generic functions
(setf requirement): Public ordinary functions
(setf route): Public generic functions
(setf route): Public generic functions
(setf route-compiled-requirements): Private generic functions
(setf route-compiled-requirements): Private generic functions
(setf route-controller): Public generic functions
(setf route-controller): Public generic functions
(setf route-requirements): Private generic functions
(setf route-requirements): Private generic functions
A
app-requirements: Private generic functions
app-requirements: Private generic functions
C
call: Public standalone methods
call: Public standalone methods
clear-routing-rules: Public ordinary functions
compile-requirements: Private ordinary functions
context: Public ordinary functions
D
default-requirements-map: Private ordinary functions
E
equal-route: Public standalone methods
F
Function, (setf context): Public ordinary functions
Function, (setf requirement): Public ordinary functions
Function, clear-routing-rules: Public ordinary functions
Function, compile-requirements: Private ordinary functions
Function, context: Public ordinary functions
Function, default-requirements-map: Private ordinary functions
Function, make-context: Public ordinary functions
Function, requirement: Public ordinary functions
G
Generic Function, (setf app-requirements): Private generic functions
Generic Function, (setf mapper): Private generic functions
Generic Function, (setf route): Public generic functions
Generic Function, (setf route-compiled-requirements): Private generic functions
Generic Function, (setf route-controller): Public generic functions
Generic Function, (setf route-requirements): Private generic functions
Generic Function, app-requirements: Private generic functions
Generic Function, make-request: Public generic functions
Generic Function, make-response: Public generic functions
Generic Function, mapper: Private generic functions
Generic Function, not-found: Public generic functions
Generic Function, process-response: Public generic functions
Generic Function, route: Public generic functions
Generic Function, route-compiled-requirements: Private generic functions
Generic Function, route-controller: Public generic functions
Generic Function, route-requirements: Private generic functions
I
initialize-instance: Public standalone methods
M
Macro, with-context: Private macros
Macro, with-context-variables: Public macros
make-context: Public ordinary functions
make-request: Public generic functions
make-request: Public generic functions
make-response: Public generic functions
make-response: Public generic functions
mapper: Private generic functions
mapper: Private generic functions
match-route: Public standalone methods
Method, (setf app-requirements): Private generic functions
Method, (setf mapper): Private generic functions
Method, (setf route): Public generic functions
Method, (setf route-compiled-requirements): Private generic functions
Method, (setf route-controller): Public generic functions
Method, (setf route-requirements): Private generic functions
Method, app-requirements: Private generic functions
Method, call: Public standalone methods
Method, call: Public standalone methods
Method, equal-route: Public standalone methods
Method, initialize-instance: Public standalone methods
Method, make-request: Public generic functions
Method, make-response: Public generic functions
Method, mapper: Private generic functions
Method, match-route: Public standalone methods
Method, not-found: Public generic functions
Method, process-response: Public generic functions
Method, route: Public generic functions
Method, route-compiled-requirements: Private generic functions
Method, route-controller: Public generic functions
Method, route-requirements: Private generic functions
N
not-found: Public generic functions
not-found: Public generic functions
P
process-response: Public generic functions
process-response: Public generic functions
R
requirement: Public ordinary functions
route: Public generic functions
route: Public generic functions
route-compiled-requirements: Private generic functions
route-compiled-requirements: Private generic functions
route-controller: Public generic functions
route-controller: Public generic functions
route-requirements: Private generic functions
route-requirements: Private generic functions
W
with-context: Private macros
with-context-variables: Public macros
Jump to:   (  
A   C   D   E   F   G   I   M   N   P   R   W  

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

A.4 Data types

Jump to:   <  
A   C   F   N   P   S  
Index Entry  Section
<
<app>: Public classes
A
app: Public classes
C
Class, <app>: Public classes
Class, app: Public classes
Class, ningle-route: Public classes
F
File, file-type.lisp: The ningle/main/file-type․lisp file
File, file-type.lisp: The ningle/app/file-type․lisp file
File, file-type.lisp: The ningle/context/file-type․lisp file
File, file-type.lisp: The ningle/route/file-type․lisp file
File, ningle.asd: The ningle/ningle․asd file
file-type.lisp: The ningle/main/file-type․lisp file
file-type.lisp: The ningle/app/file-type․lisp file
file-type.lisp: The ningle/context/file-type․lisp file
file-type.lisp: The ningle/route/file-type․lisp file
N
ningle: The ningle system
ningle: The ningle package
ningle-route: Public classes
ningle.asd: The ningle/ningle․asd file
ningle/app: The ningle/app system
ningle/app: The ningle/app package
ningle/context: The ningle/context system
ningle/context: The ningle/context package
ningle/main: The ningle/main system
ningle/route: The ningle/route system
ningle/route: The ningle/route package
P
Package, ningle: The ningle package
Package, ningle/app: The ningle/app package
Package, ningle/context: The ningle/context package
Package, ningle/route: The ningle/route package
S
System, ningle: The ningle system
System, ningle/app: The ningle/app system
System, ningle/context: The ningle/context system
System, ningle/main: The ningle/main system
System, ningle/route: The ningle/route system
Jump to:   <  
A   C   F   N   P   S