Structures

The struct() function lets you define neatly formatted structures with automatic folding and indentation handling.

StructFn = struct(Type, ViewerFn)

Here Type is the type of the structure and ViewerFn is a function that does the actual processing of the structure elements.

The struct() function returns another function, which, when beign executed, does the following: 1) saves current state of the output 2) begins structure definition, that is, prints the structure type, name, comment (if any), starts new folding, prints the "{" sign at the new line, increases indent 3) calls the supplied ViewerFn passing it all the parameters (if any) and remembers all its return values 4) ends structure definition, that is, decreases indent, prints the "}" sign and the next line and ends the current folding 5) restores the previous state of the output. Quite naturally, it uses the StartStruct() and EndStruct() functions internally. The commentary (if any) gets passed to the StartStruct() function and EndStruct() function is called without any parameters.

Of course, it is always a nice idea to remember the fucntion returned by struct() in a variable so that it can be used later.

The StructFn() function expects at least two parameters: the mandatory name of the structure instance and an optional comment. However, if you pass it more parameters, all of them will be passed to the underlying ViewerFn() function that was supplied at the structure definition time. All return values of ViewerFn() will be returned from the StructFn() invocation.

Here is a simple definition of the standard RECT structure, which also demonstrates passing/receiving parameters to/from the underlying function:

-- first of all, we define the function which does the actual processing of the structure elements
function _Rect(Comment, NeedComment)
    -- this is just to demonstrate parameter passing
    if NeedComment then BlockComment(Comment) end
 
    -- actual processing of the structure elements
    LONG "left"
    LONG "top"
    LONG "right"
    LONG "bottom"
 
    -- let's return something
    return "Hello from _Rect()!", 1, 2
end
 
-- next, we define the function that does the full processing of the structure
Rect = struct("RECT", _Rect)
 
-- now we can use our brand new structure function and even pass it some parameters and get its return values
local Ret1, Ret2, Ret3 = Rect("MyRect", "Defined in WINDEF.H", "\rThis will be passed to the _Rect()\r\r", true)
print(Ret1, Ret2, Ret3, "\r\n")