Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/APItools/router.lua
A barebones router for Lua. It matches urls and executes lua functions.
https://github.com/APItools/router.lua
Last synced: 7 days ago
JSON representation
A barebones router for Lua. It matches urls and executes lua functions.
- Host: GitHub
- URL: https://github.com/APItools/router.lua
- Owner: APItools
- License: mit
- Archived: true
- Created: 2013-06-18T17:10:03.000Z (over 11 years ago)
- Default Branch: master
- Last Pushed: 2020-07-14T22:22:31.000Z (over 4 years ago)
- Last Synced: 2024-04-16T18:20:11.116Z (7 months ago)
- Language: Lua
- Size: 67.4 KB
- Stars: 196
- Watchers: 14
- Forks: 48
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: MIT-LICENSE.md
Awesome Lists containing this project
- awesome-resty - router.lua
README
router.lua
==========
[](https://travis-ci.org/APItools/router.lua)
A very basic router for lua.
Features:
* Allows binding a method and a path to a function
* Parses parameters like `/app/services/:service_id`
* It's platform-agnostic. It has been tested with openresty.
Usage
=====
A router is created with `router.new`:
``` lua
local router = require 'router'
local r = router.new()
```
You can define a route with `r:match`:
``` lua
local router = require 'router'
local r = router.new()
r:match('GET', '/hello', function(params)
print('someone said hello')
end)
```
You can use `r:get(...)` instead of `r:match('GET', ...)`. There are similar shortcuts for the usual http verbs (`r:post`, `r:put`, `r:delete` ...).
If you have a route which can handle multiple methods, you can use `r:any(...)`, which will match any http verb. This also passes the verb as a second parameter to the function:
``` lua
local router = require 'router'
local r = router.new()
r:any('/hello', function(params, method)
print('someone said hello using ' .. method)
end)
```
In addition to that, `router.lua` supports router parameters (like `/users/:id/comment`) and extra parameters (which come from outside the route).
``` lua
local router = require 'router'
local r = router.new()
r:get('/hello', function(params)
print('someone said hello')
end)
-- route parameters
r:get('/hello/:name', function(params)
print('hello, ' .. params.name)
end)
-- extra parameters (i.e. from a query or form)
r:post('/app/:id/comments', function(params)
print('comment ' .. params.comment .. ' created on app ' .. params.id)
end)
```
Once the routes are defined, you can trigger their actions by using `r:execute`.
Given the 3 routes above, execute will work like this:
``` lua
r:execute('GET', '/hello')
-- prints "someone said hello"
r:execute('GET', '/hello/peter')
-- prints "hello peter"
r:execute('POST', '/app/4/comments', { comment = 'fascinating'})
-- prints "comment fascinating created on app 4"
```
`r:execute` returns either `nil` followed by an error message if no routes where found, or `true` and
whatever the matched action returned.
If you are defining lots of routes in one go, there is an extra-compact syntax to do so using a table.
The following code is equivalent to the previous one:
``` lua
local router = require 'router'
local r = router.new()
r:match({
GET = {
['/hello'] = function(params) print('someone said hello') end,
['/hello/:name'] = function(params) print('hello, ' .. params.name) end
},
POST = {
['/app/:id/comments'] = function(params)
print('comment ' .. params.comment .. ' created on app ' .. params.id)
end
}
})
r:execute('GET', '/hello')
r:execute('GET', '/hello/peter')
r:execute('POST', '/app/4/comments', { comment = 'fascinating'})
```
Usage with openresty
====================
`router.lua` is platform-agnostic, but you can use it with openresty like this:
``` conf
# nginx.conf
http {
server {
listen 80;
location / {
content_by_lua '
local router = require 'router'
local r = router.new()
r:match({
GET = {
["/hello"] = function(params) ngx.print("someone said hello") end,
["/hello/:name"] = function(params) ngx.print("hello, " .. params.name) end
},
POST = {
["/app/:id/comments"] = function(params)
ngx.print("comment " .. params.comment .. " created on app " .. params.id)
end
}
})
local ok, errmsg = r:execute(
ngx.var.request_method,
ngx.var.request_uri,
ngx.req.get_uri_args(), -- all these parameters
ngx.req.get_post_args(), -- will be merged in order
{other_arg = 1}) -- into a single "params" table
if ok then
ngx.status = 200
else
ngx.status = 404
ngx.print("Not found!")
ngx.log(ngx.ERROR, errmsg)
end
}
}
```
Read more about it in https://docs.apitools.com/blog/2014/04/24/a-small-router-for-openresty.html
Testing
=======
Install dependencies:
```shell
luarocks install luacheck
luarocks install busted
luarocks install luacov
luarocks install luacov-coveralls
```
And run tests:
```shell
luacheck --std max+busted *.lua spec
busted --verbose --coverage --lpath=./?.lua
```
License
=======
MIT license
Specs
=====
This library uses [busted](http://olivinelabs.com/busted) for its specs. In order to run the specs, install `busted` and then do
cd path/to/the/folder/where/the/spec/folder/is
busted