diff --git a/function.lua b/function.lua index 234ee81..c9f1205 100644 --- a/function.lua +++ b/function.lua @@ -1,3 +1,48 @@ +--[=[ The function formatting module for pretty. + +How is one supposed to pretty print functions? Well, there are many different +formats, and no "best" one, only "best for the purpose". Lets first look at how +you could display the most raw data about a function. + +1. The default Lua format: "function: 0x41f71c60" + This is the default, and by far the easiest. Also, very uninformative. We + only get a unique id for the function. +2. Include the arguments: "function (t, str) ... end" + This is slightly more advanced, as it requires using the debug library to + discover the names of the arguments. In addition it adds a pseudo-correct + formatting for the function. Now we know the arguments, and if they possess + descriptive names, we can learn a lot about the function. +3. Include some documentation: "function (x) --[[math.cosh: Returns the hyperbolic cosine of x.]] ... end" + We retain the arguments and pseudo-correct formatting from above, and add + documentation taken from elsewhere (for example the Lua Reference Manual, or + LuaJIT webpage), as comments. This is great for explorative programming, as + we can read about the language from within the language. +4. Short names: "math.min" + Rather than giving an overly descriptive overview of some inbuilt, we assume + that we can find it by its standard name. With this one we gain complete + native representation, assuming the standard enviroment, of course. It won't + work at all with custom functions. +5. Include source code: "function (a, b) return (a + b)/2 end" + Now we find the source code somehow, and use it as the representation. This + is powerful because we can directly inspect the code. It won't work with + builtins, closured functions, or when fucking around with the source files. +6. Include closures: "(function () local i = 5; return function () i = i + 1; return i end end)()" + In cases where a function has a closure, we can use debug.getinfo to get + the names and values of the upvalues. We can then represent the closure, by + creating the closure itself. Iterators like the example above works nicely, + but more complex chains of closures break down. For example: + + local val_a = 1 + local func_a = function () val_a = val_a + 1; return val_a end + local val_a = val_a + local func_c = function () return func_a() + val_a end + + Here we have two functions, both with their own upvalue, both named "val_a", + yet those names refer to two different "slots". Successive calls to + `func_c` should produce the list: 2, 3, 4, 5, 6, 7, ... + To break through this barrier, we need to parse the Lua AST, and that is + beyond this project. +--]=] -- Import @@ -10,7 +55,6 @@ end -- Constants - -------------------------------------------------------------------------------- -- Util