filter: lua: cosmetics

Author: arl

filter/lua.go

@@ -5,6 +5,7 @@ import (
 	"runtime"
 
 	"github.com/AdRoll/baker"
+
 	lua "github.com/yuin/gopher-lua"
 )
 
@@ -16,11 +17,13 @@ var LUADesc = baker.FilterDesc{
 	Help:   `Run a baker filter defined in a lua script`,
 }
 
+// LUAConfig holds the configuration for the LUA filter.
 type LUAConfig struct {
 	Script     string `help:"Path to the lua script where the baker filter is defined" required:"true"`
 	FilterName string `help:"Name of the lua function to run as baker filter" required:"true"`
 }
 
+// LUA allows to run a baker filter from an external script written in lua.
 type LUA struct {
 	l       *lua.LState    // lua state used during all the baker filter lifetime
 	ud      *lua.LUserData // pre-allocated (reused) userdata for the processed record
@@ -29,6 +32,7 @@ type LUA struct {
 	next    func(baker.Record)
 }
 
+// NewLUA returns a new LUA filter.
 func NewLUA(cfg baker.FilterParams) (baker.Filter, error) {
 	dcfg := cfg.DecodedConfig.(*LUAConfig)
 
@@ -69,9 +73,20 @@ func NewLUA(cfg baker.FilterParams) (baker.Filter, error) {
 	return f, nil
 }
 
+// registerLUATypes registers, in the given lua state, some lua types
+// and utility functions useful to run a baker filter:
+//  - the record type
+//  - createRecord function (creates and returns a new record)
+//  - validateRecord function (takes a record and returns a boolean and a
+//    number), see baker.ComponentParams.ValidateRecord
+//  - fieldByName function (returns a field index given its name, or nil
+//    if the given field name doesn't exist)
+//  - fieldNames, an lua table where field names are indexed by their field
+//    field indexes
 func registerLUATypes(l *lua.LState, comp baker.ComponentParams) {
 	registerLUARecordType(l)
 
+	// Registers the 'createRecord' lua function.
 	l.SetGlobal("createRecord", l.NewFunction(func(L *lua.LState) int {
 		rec := comp.CreateRecord()
 		ud := recordToLua(l, rec)
@@ -106,8 +121,14 @@ func registerLUATypes(l *lua.LState, comp baker.ComponentParams) {
 	l.SetGlobal("fieldNames", fields)
 }
 
+// TODO: at the moment LUA filter doesn't publish stats.
+// There are multiple ways to do it, either require the filter to update
+// the numbers of processed and filtered records, or deduce them automatically
+// by hooking into next and Process functions (if that proves too costly
+// this could be disabled in configuration.
 func (t *LUA) Stats() baker.FilterStats { return baker.FilterStats{} }
 
+// Process forwards records to the lua-written filter.
 func (t *LUA) Process(rec baker.Record, next func(baker.Record)) {
 	// Modify the record inside the pre-allocated user value
 	t.ud.Value = &luaRecord{r: rec}
@@ -122,6 +143,8 @@ func (t *LUA) Process(rec baker.Record, next func(baker.Record)) {
 		Protect: true,
 	}, t.ud, t.luaNext)
 
+	// TODO: should not panic here and instead increment a filter-specific
+	// metric that tracks the number of lua runtime errors.
 	if err != nil {
 		panic(err)
 	}
@@ -131,19 +154,25 @@ func (t *LUA) Process(rec baker.Record, next func(baker.Record)) {
 
 const luaRecordTypeName = "record"
 
+// registers the 'record' type into the given lua state.
 func registerLUARecordType(L *lua.LState) {
 	mt := L.NewTypeMetatable(luaRecordTypeName)
 	L.SetGlobal(luaRecordTypeName, mt)
 	L.SetField(mt, "__index", L.SetFuncs(L.NewTable(), luaRecordMethods))
 }
 
+// converts a baker.Record to lua user data, suitable to be pushed onto
+// an lua stack.
 func recordToLua(L *lua.LState, r baker.Record) *lua.LUserData {
 	ud := L.NewUserData()
 	ud.Value = &luaRecord{r: r}
 	L.SetMetatable(ud, L.GetTypeMetatable(luaRecordTypeName))
 	return ud
 }
 
+// checks that the element at current stack index n is an lua
+// user data, holding an luaRecord, and returns it. Raises an lua
+// runtime error if the element is not a record.
 func checkLuaRecord(L *lua.LState, n int) *luaRecord {
 	ud := L.CheckUserData(n)
 	if v, ok := ud.Value.(*luaRecord); ok {
@@ -153,17 +182,21 @@ func checkLuaRecord(L *lua.LState, n int) *luaRecord {
 	return nil
 }
 
+// faster version of checkLuaRecord that panics if the stack element
+// is not a record, rather than raising an lua runtime error.
 func fastcheckLuaRecord(L *lua.LState, n int) *luaRecord {
 	return L.Get(n).(*lua.LUserData).Value.(*luaRecord)
 }
 
+// holds the lua-bound methods of baker.Record.
 var luaRecordMethods = map[string]lua.LGFunction{
 	"get":   luaRecordGet,
 	"set":   luaRecordSet,
 	"copy":  luaRecordCopy,
 	"clear": luaRecordClear,
 }
 
+// lua wrapper over a baker Record.
 type luaRecord struct {
 	r baker.Record
 }

filter/lua_test.go

@@ -25,7 +25,7 @@ end
 	if err != nil {
 		b.Fatal(err)
 	}
-	// fname := filepath.Join(b.TempDir(), "filters.lua")
+
 	fname := filepath.Join(dir, "filters.lua")
 	if err := ioutil.WriteFile(fname, []byte(script), os.ModePerm); err != nil {
 		b.Fatalf("can't write lua script: %v", err)

filter/testdata/lua_test.lua

@@ -1,7 +1,7 @@
+-- use record:get and record:set to swap 2 fields
 function swapFields(rec, next)
-    local f1, f2
-    f1 = rec:get(1)
-    rec:set(1, rec:get(2))
+    local f1, f2 = rec:get(1), rec:get(2)
+    rec:set(1, f2)
     rec:set(2, f1)
     next(rec)
 end