diff --git a/function.lua b/function.lua index 268ca63..fd51040 100644 --- a/function.lua +++ b/function.lua @@ -1,31 +1,38 @@ --[=[ 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. +formats, and no "best" one, only "best for the purpose". Lets start at the +simplest, and move towards abstraction. 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. + discover the names of the arguments. In addition it comes closer to a Lua + parsable formatting. We can know the argument names, and if these are + descriptive, we can learn some things 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. + We retain the arguments and almost parsable formatting from above, and add + documentation taken from elsewhere - Lua Reference Manual, LuaJIT webpage - + as comments. This is great for explorative programming, as we can read about + the language by just fiddling around with it. 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. + We can assume that an experienced Lua user might already know how any given + library function works, and would thus prefer a shorthand, rather than the + documentation. To that aim, we can use the short name/access path instead. + This is also ideal in places where we don't have a lot of space. + This representation is completely parsable, but won't necessarily work for + custom enviroment and user-defined 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. + is powerful because we can directly inspect the code. But it makes the + function representation a lot more bussy. It won't work with builtins, + closured functions, or when fucking around with the source files. It also + hits limits when functions are nested, as the debug library does not give + enough precision. + This also works nicely with 3. due to being able to read function + documentation from the source file. 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 @@ -42,6 +49,7 @@ you could display the most raw data about a function. `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. + Closures also create extremely bussy output. --]=] -- Import