Penlight Documentation

## Technical Choices

### Modularity and Granularity

In an ideal world, a program should only load the libraries it needs. Penlight is intended to work in situations where an extra 100Kb of bytecode could be a problem. It is straightforward but tedious to load exactly what you need:

    local data = require 'pl.data'
    local List = require 'pl.List'
    local array2d = require 'pl.array2d'
    local seq = require 'pl.seq'
    local utils = require 'pl.utils'

This is the style that I follow in Penlight itself, so that modules don't mess with the global environment; also, `stringx.import()` is not used because it will update the global string table.

But `require 'pl'` is more convenient in scripts; the question is how to ensure that one doesn't load the whole kitchen sink as the price of convenience. The strategy is to only load modules when they are referenced. In 'init.lua' (which is loaded by `require 'pl'`) a metatable is attached to the global table with an `__index` metamethod. Any unknown name is looked up in the list of modules, and if found, we require it and make that module globally available. So when tablex.deepcompare is encountered, looking up tablex causes 'pl.tablex' to be required. .

Modifying the behaviour of the global table has consequences. For instance, there is the famous module strict which comes with Lua itself (perhaps the only standard Lua module written in Lua itself) which also does this modification so that global variiables must be defined before use. So the implementation in 'init.lua' allows for a 'not found' hook, which 'pl.strict.lua' uses. Other libraries may install their own metatables for `_G`, but Penlight will now forward any unknown name to the `__index` defined by the original metatable.

But the strategy is worth the effort: the old 'kitchen sink' 'init.lua' would pull in about 260K of bytecode, whereas now typical programs use about 100K less, and short scripts even better - for instance, if they were only needing functionality in utils.

There are some functions which mark their output table with a special metatable, when it seems particularly appropriate. For instance, tablex.makeset creates a Set, and seq.copy creates a List. But this does not automatically result in the loading of pl.Set and pl.List; only if you try to access any of these methods. In 'utils.lua', there is an exported table called `stdmt`:

    stdmt = { List = {}, Map = {}, Set = {}, MultiMap = {} }

If you go through 'init.lua', then these plain little 'identity' tables get an `__index` metamethod which forces the loading of the full functionality. Here is the code from 'list.lua' which starts the ball rolling for lists:

    List = utils.stdmt.List
    List.__index = List
    List._name = "List"
    List._class = List

The 'load-on-demand' strategy helps to modularize the library. Especially for more casual use, `require 'pl'` is a good compromise between convenience and modularity.

In this current version, I have generally reduced the amount of trickery involved. Previously, Map was defined in pl.class; now it is sensibly defined in pl.Map; pl.class only contains the basic class mechanism (and returns that function.) For consistency, List is returned directly by `require 'pl.List'` (note the uppercase 'L'), Also, the amount of module dependencies in the non-core libraries like pl.config have been reduced.

### Defining what is Callable

'utils.lua' exports `function_arg` which is used extensively throughout Penlight. It defines what is meant by 'callable'. Obviously true functions are immediately passed back. But what about strings? The first option is that it represents an operator in 'operator.lua', so that '<' is just an alias for operator.lt.

We then check whether there is a function factory defined for the metatable of the value.

(It is true that strings can be made callable, but in practice this turns out to be a cute but dubious idea, since all strings share the same metatable. A common programming error is to pass the wrong kind of object to a function, and it's better to get a nice clean 'attempting to call a string' message rather than some obscure trace from the bowels of your library.)

The other module that registers a function factory is pl.func. Placeholder expressions cannot be directly calleable, and so need to be instantiated and cached in as efficient way as possible.

(An inconsistency is that `utils.is_callable` does not do this thorough check.)

generated by LDoc 1.4.6