Correction on obiformat of bug leading to partial parsing and add godocs

Former-commit-id: b27105355f1a330eedf6eaa72c8ac94f06806c28

pkg/obilua/lua.go

@@ -13,6 +13,10 @@ import (
 	"github.com/yuin/gopher-lua/parse"
 )
 
+// NewInterpreter creates a new Lua interpreter and registers the Obilib and ObiContext modules.
+//
+// No parameters.
+// Returns a pointer to a Lua state.
 func NewInterpreter() *lua.LState {
 	lua := lua.NewState()
 
@@ -22,6 +26,10 @@ func NewInterpreter() *lua.LState {
 	return lua
 }
 
+// Compile compiles a Lua program into a Lua function proto.
+//
+// It takes a byte slice containing the Lua program and a string representing the name of the program.
+// It returns a pointer to a Lua function proto and an error if any.
 func Compile(program []byte, name string) (*lua.FunctionProto, error) {
 
 	reader := bytes.NewReader(program)
@@ -37,6 +45,12 @@ func Compile(program []byte, name string) (*lua.FunctionProto, error) {
 	return proto, nil
 }
 
+// CompileScript compiles a Lua script from a file.
+//
+// It takes a file path as input and returns a pointer to a Lua function proto and an error if any.
+// The function reads the contents of the file specified by the file path and compiles it into a Lua function proto using the Compile function.
+// If there is an error reading the file, the function returns nil and the error.
+// Otherwise, it returns the compiled Lua function proto and nil error.
 func CompileScript(filePath string) (*lua.FunctionProto, error) {
 	program, err := os.ReadFile(filePath)
 
@@ -47,6 +61,25 @@ func CompileScript(filePath string) (*lua.FunctionProto, error) {
 	return Compile(program, filePath)
 }
 
+// LuaWorker creates a Go function that executes a Lua script and returns a SeqWorker.
+//
+// The function takes a Lua function prototype as input and creates a new interpreter.
+// It then creates a new Lua function from the prototype and pushes it onto the interpreter's stack.
+// The interpreter calls the Lua function and checks for any errors.
+// It retrieves the global variable "worker" from the interpreter and checks if it is a Lua function.
+// If it is a Lua function, it defines a Go function that takes a BioSequence as input.
+// Inside the Go function, it calls the Lua function with the BioSequence as an argument.
+// It retrieves the result from the interpreter and checks its type.
+// If the result is a BioSequence or a BioSequenceSlice, it returns it along with any error.
+// If the result is not of the expected type, it returns an error.
+// If the global variable "worker" is not a Lua function, it logs a fatal error.
+// The Go function is returned as a SeqWorker.
+//
+// Parameters:
+// - proto: The Lua function prototype.
+//
+// Return type:
+// - obiseq.SeqWorker: The Go function that executes the Lua script and returns a SeqWorker.
 func LuaWorker(proto *lua.FunctionProto) obiseq.SeqWorker {
 	interpreter := NewInterpreter()
 	lfunc := interpreter.NewFunctionFromProto(proto)
@@ -94,30 +127,20 @@ func LuaWorker(proto *lua.FunctionProto) obiseq.SeqWorker {
 		return f
 	}
 
-	log.Fatalf("THe worker object is not a function")
+	log.Fatalf("The worker object is not a function")
 	return nil
-	// f := func(sequence *obiseq.BioSequence) (obiseq.BioSequenceSlice, error) {
-	// 	interpreter.SetGlobal("sequence", obiseq2Lua(interpreter, sequence))
-	// 	interpreter.Push(lfunc)
-	// 	err := interpreter.PCall(0, lua.MultRet, nil)
-	// 	result := interpreter.GetGlobal("result")
-
-	// 	if result != lua.LNil {
-	// 		log.Info("youpi ", result)
-	// 	}
-
-	// 	rep := interpreter.GetGlobal("sequence")
-
-	// 	if rep.Type() == lua.LTUserData {
-	// 		ud := rep.(*lua.LUserData)
-	// 		sequence = ud.Value.(*obiseq.BioSequence)
-	// 	}
-
-	// 	return obiseq.BioSequenceSlice{sequence}, err
-	// }
-
 }
 
+// LuaProcessor processes a Lua script on a sequence iterator and returns a new iterator.
+//
+// Parameters:
+// - iterator: The IBioSequence iterator to process.
+// - name: The name of the Lua script.
+// - program: The Lua script program as a string.
+// - breakOnError: A boolean indicating whether to stop processing if an error occurs.
+// - nworkers: An integer representing the number of workers to use for processing.
+// Returns:
+// - obiiter.IBioSequence: The new IBioSequence iterator after processing the Lua script.
 func LuaProcessor(iterator obiiter.IBioSequence, name, program string, breakOnError bool, nworkers int) obiiter.IBioSequence {
 	newIter := obiiter.MakeIBioSequence()
 
@@ -223,6 +246,15 @@ func LuaProcessor(iterator obiiter.IBioSequence, name, program string, breakOnEr
 
 }
 
+// LuaPipe creates a pipeable function that applies a Lua script to an input sequence.
+//
+// Parameters:
+// - name: The name of the Lua script.
+// - program: The Lua script program as a string.
+// - breakOnError: A boolean indicating whether to stop processing if an error occurs.
+// - nworkers: An integer representing the number of workers to use for processing.
+// Returns:
+// - obiiter.Pipeable: A pipeable function that applies the Lua script to the input sequence.
 func LuaPipe(name, program string, breakOnError bool, nworkers int) obiiter.Pipeable {
 
 	f := func(input obiiter.IBioSequence) obiiter.IBioSequence {
@@ -232,6 +264,14 @@ func LuaPipe(name, program string, breakOnError bool, nworkers int) obiiter.Pipe
 	return f
 }
 
+// LuaScriptPipe creates a pipeable function that applies a Lua script to an input sequence.
+//
+// Parameters:
+// - filename: The name of the Lua script file.
+// - breakOnError: A boolean indicating whether to stop processing if an error occurs.
+// - nworkers: An integer representing the number of workers to use for processing.
+// Returns:
+// - obiiter.Pipeable: A pipeable function that applies the Lua script to the input sequence.
 func LuaScriptPipe(filename string, breakOnError bool, nworkers int) obiiter.Pipeable {
 	program, err := os.ReadFile(filename)