Documentation
This commit is contained in:
parent
677f05d69c
commit
665616f1e3
20
Makefile
20
Makefile
|
@ -9,6 +9,7 @@ CD=cd
|
|||
AWK=awk
|
||||
GREP=grep
|
||||
SORT=sort
|
||||
TEST=test
|
||||
|
||||
# Config
|
||||
worker_chroot = $(smr_var)/kore_worker
|
||||
|
@ -104,13 +105,13 @@ install: $(app_root) $(kmgr_chroot) $(parent_chroot) $(initscript) $(config) smr
|
|||
|
||||
$(config) : conf/smr.conf
|
||||
$(Q)$(MKDIR) $(conf_path)
|
||||
$(Q)$(COPY) $< $@
|
||||
$(Q)$(TEST) ! -e $@ && $(COPY) $< $@
|
||||
|
||||
$(initscript) : packaging/systemd/smr.service
|
||||
$(Q)$(COPY) $< $@
|
||||
|
||||
cloc: ## calculate source lines of code in smr
|
||||
cloc --force-lang="html",etlua --force-lang="lua",luasrc assets Makefile
|
||||
cloc --force-lang="html",etlua --force-lang="lua",lua src assets Makefile
|
||||
|
||||
$(app_root):
|
||||
$(Q)$(MKDIR) $(app_root)
|
||||
|
@ -153,7 +154,7 @@ $(built_sql): $(app_root)/sql/%.sql : src/sql/%.sql
|
|||
$(Q)$(ECHO) "[copy] $@"
|
||||
$(Q)$(COPY) $^ $@
|
||||
|
||||
$(built_tests) : $(app_root)/spec/% : spec/% $(app_root)/spec
|
||||
$(built_tests): $(app_root)/spec/% : spec/% $(app_root)/spec
|
||||
$(Q)$(ECHO) "[copy] $@"
|
||||
$(Q)$(COPY) $< $@
|
||||
|
||||
|
@ -161,15 +162,22 @@ $(app_root)/spec: $(app_root)
|
|||
$(Q)$(MKDIR) $@
|
||||
$(Q)$(MKDIR) $@/parser_tests
|
||||
|
||||
smr.so : $(src_files) conf/build.conf $(asset_files)
|
||||
smr.so: $(src_files) conf/build.conf $(asset_files)
|
||||
$(Q)$(ECHO) "[build] $@"
|
||||
$(Q)$(KODEV) build
|
||||
|
||||
test : $(built) ## run the unit tests
|
||||
test: $(built) ## run the unit tests
|
||||
$(Q)$(CD) $(app_root) && busted -v --no-keep-going --exclude-tags "slow,todo,working"
|
||||
|
||||
cov : $(built) ## code coverage (based on unit tests)
|
||||
cov: $(built) ## code coverage (based on unit tests)
|
||||
$(Q)$(RM) $(kore_chroot)/luacov.stats.out
|
||||
$(Q)$(CD) $(kore_chroot) && busted -v -c --no-keep-going --exclude-tags slow
|
||||
$(Q)$(CD) $(kore_chroot) && luacov endpoints/
|
||||
$(Q)$(ECHO) "open kore_chroot/luacov.report.out to view coverage results."
|
||||
|
||||
doc:
|
||||
rm -rf .trblcache
|
||||
~/Programs/trbldoc/trbldoc.sh src
|
||||
cd .trblcache/built && python3 -m http.server
|
||||
|
||||
.PHONY: doc
|
||||
|
|
|
@ -6,3 +6,4 @@ All other values are considered truethy.
|
|||
In addition, tables may have a metatable that has a `__toboolean` function
|
||||
to implement their own truethyness or falseyness. `false` should be used in
|
||||
places where a boolean is expected, and `nil` should be used otherwise.
|
||||
|
||||
|
|
|
@ -12,3 +12,9 @@ create_user(details :: table) :: boolean
|
|||
```
|
||||
Called when a user creates a user account on the site.
|
||||
|
||||
```
|
||||
authenticate(data :: table) :: number | nil, string
|
||||
```
|
||||
Called when a user attempts to log in. Return a number, userid if the login is successful, or nil and an error message if the login is not successful. By default, smr puts "user" and "passfile" fields into the data table.
|
||||
|
||||
|
||||
|
|
|
@ -1,6 +1,12 @@
|
|||
--[[ md
|
||||
@name lua/addon
|
||||
|
||||
## Addon
|
||||
|
||||
Addons allow you to modify the behavior of smr without modifying the smr
|
||||
source code. This is intended to make updates easier, and to modularize parts
|
||||
of smr that are not minimally required.
|
||||
|
||||
Addon loader - Addons are either:
|
||||
* A folder with at least two files:
|
||||
- meta.lua - contains addon information
|
||||
|
@ -9,8 +15,10 @@ Addon loader - Addons are either:
|
|||
* A sqlite3 database with a table "files" that has at least the columns
|
||||
* name :: TEXT - The filename
|
||||
* data :: BINARY - The file data
|
||||
And there are at least 2 rows with filenames `meta.lua` and `init.lua`
|
||||
as described above. Addons should be placed in $SMR_ADDONS, defined in config.lua
|
||||
|
||||
And there are at least 2 rows with filenames `meta.lua` and `init.lua`
|
||||
as described above. Addons should be placed in {{config/addons_folder},
|
||||
defined in `config.lua`
|
||||
|
||||
The `meta.lua` file is run at worker init time (i.e. it will be run once for
|
||||
each worker), and should return a table with at least the following information
|
||||
|
|
|
@ -1,13 +1,47 @@
|
|||
--[[
|
||||
--[[ md
|
||||
@name lua/hooks
|
||||
|
||||
Global functions that smr exposes that can be detoured by addons
|
||||
|
||||
]]
|
||||
|
||||
--[[ md
|
||||
@name doc/detouring
|
||||
|
||||
# Detouring
|
||||
|
||||
In Lua, functions are given a name, but more generally, they values on a table
|
||||
, perhaps the global table `_G`, and their names are the keys on the table.
|
||||
When you want to modify a function that exists either in smr or in other addons
|
||||
you can **detour** the function by saving a reference to the original function,
|
||||
and then creating a new function that calls the original, maybe after doing
|
||||
other work, or modifying the arguments. For example:
|
||||
|
||||
local pages = require("pages")
|
||||
|
||||
-- Get notified when the index page is rendered to the user
|
||||
local oldindex = pages.index
|
||||
function pages.index(...)
|
||||
print("Index page is getting rendered!")
|
||||
oldindex(...)
|
||||
end
|
||||
]]
|
||||
|
||||
local api = {}
|
||||
|
||||
-- Called before any request processing. Returning true "traps" the request, and
|
||||
-- does not continue calling smr logic. Well-behaved addons should check for
|
||||
-- "true" from the detoured function, and return true immediately if the check
|
||||
-- succeeds.
|
||||
--[[ md
|
||||
@name lua/hooks
|
||||
|
||||
## pre_request
|
||||
|
||||
Called before any request processing. Returning true "traps" the request, and
|
||||
does not continue calling smr logic. Well-behaved addons should check for
|
||||
"true" from the detoured function, and return true immediately if the check
|
||||
succeeds.
|
||||
|
||||
@param req {{http_request}} - The request about to be processed
|
||||
@returns boolean - If true, further processing is not done on this request.
|
||||
]]
|
||||
api.pre_request = function(req) end
|
||||
|
||||
-- Called after smr request processing. Returning true "traps" the request.
|
||||
|
|
|
@ -4,6 +4,36 @@ It registers a bunch of global functions that get called from kore when users
|
|||
visit particular pages. See src/smr.c for the names of the public functions.
|
||||
See conf/smr.conf for the data that can be access in each function
|
||||
]]
|
||||
|
||||
--[[ md
|
||||
@name lua
|
||||
|
||||
# Lua namespace
|
||||
|
||||
By default, smr will run init.lua defined by smr, and then addons in order,
|
||||
see {{lua/addon}} for information on how smr loads addons. You can use any
|
||||
of the modules that ship with smr by including them, and then calling the
|
||||
functions defined in that module.
|
||||
|
||||
For example, the module {{lua/db}} holdes a reference to the sqlite3 database
|
||||
that smr uses for data storage. If you addon needs to set up a table and
|
||||
prepare sql statements for an api endpoint, you might set it up like this:
|
||||
|
||||
local db = require("db")
|
||||
|
||||
local oldconfigure = configure -- Hold a refrence to configure()
|
||||
function configure(...) -- Detour the configure function
|
||||
db.sqlassert(db.conn:exec([=[
|
||||
CREATE TABLE IF NOT EXISTS foo (
|
||||
id INTEGER AUTOINCREMENT PRIMARY KEY
|
||||
value TEXT
|
||||
);
|
||||
]=]))
|
||||
oldconfigure(...)
|
||||
end
|
||||
|
||||
Be sure to always {{doc/appendix/detourin}}
|
||||
]]
|
||||
print("Really fast print from init.lua")
|
||||
|
||||
--Luarocks libraries
|
||||
|
|
Loading…
Reference in New Issue