This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision Next revision Both sides next revision | ||
api:non-standard-lua-libs [2016/06/20 20:38] payonel [Input and Output Facilities] |
api:non-standard-lua-libs [2019/07/03 12:57] forecaster [Modules] |
||
---|---|---|---|
Line 49: | Line 49: | ||
if the user tries to load "foobar" | if the user tries to load "foobar" | ||
- | `local foobar = require(*foobar")` | + | `local foobar = require("foobar")` |
Following is the order of files `require` looks for to resolve require("foobar"). To make it interesting, we are assuming the current working directory is /tmp/ | Following is the order of files `require` looks for to resolve require("foobar"). To make it interesting, we are assuming the current working directory is /tmp/ | ||
Line 66: | Line 66: | ||
Contains the source of cached libraries in a table, keyed by the library name (as given to `require`), and whose value is the cached library itself. Setting a value to `nil` in this table essentially removes the library from the cache. Some libraries are assumed to remain loaded for the proper execution of the operating system. | Contains the source of cached libraries in a table, keyed by the library name (as given to `require`), and whose value is the cached library itself. Setting a value to `nil` in this table essentially removes the library from the cache. Some libraries are assumed to remain loaded for the proper execution of the operating system. | ||
- | |||
- | * ''delayloaded-start'', ''delayloaded-end'' | ||
- | |||
- | This is an advanced library loading feature built for memory optimizations in OpenOS. We don't expect users to ever need to use this feature, nor should there be a need to understand it. But it is here because it deserves some documentation. | ||
- | |||
- | This specially formatted comment, called a delayload annotation, guides the `package` loader to only partially store a library in memory along with sufficient metadata about which functions have not been loaded. The returned library table uses metatable redirection to lazy-load these not-yet-loaded methods, giving the user the experience that all methods are available form the start. This unusual optimization was done to reduce memory costs on boot of OpenOS. To include a method for delay loading 3 things are required: proper delayload annotation syntax, proper environment boxing, and marking `package.delayed[libname]` to true for the library before loading (i.e. before `require`). | ||
- | |||
- | - delayload annotation syntax | ||
- | |||
- | This exact text, `--[[@delayloaded-start@]]`, must come after `function` and before the function name. The method must be at least one generation below the library table, e.g. `lib.methodName` or `lib.a.b.methodName`, but not just `methodName`. | ||
- | |||
- | `end` must be on a new line, with no text before it, followed by this exact text `--[[@delayloaded-end@]]` followed by a newline. | ||
- | |||
- | - delayloaded method environments | ||
- | |||
- | Delay loaded methods may expect closure around local identifiers. In order to pass the local environment (and because the oc sandbox does not give sufficient debug hooks), you must return a second table from the library lua file that holds locals needed. For example, if your delay loaded method is using a local function `foobar`, you'll return a env table at the end of your library file, as a second return, of at least `{foobar=foobar}` | ||
- | |||
- | - ''package.delayed'' | ||
- | |||
- | `package.delayed` is a table whose keys are the library names and values of `true` to indicate to the package loader to attempt to delay load the methods. Note that failed delay load parsing falls back to a normal load of the library. | ||
- | |||
- | ```lua | ||
- | function --[[@delayloaded-start@]] lib.name(...) | ||
- | body(1,2,3) | ||
- | end --[[@delayloaded-end@]] | ||
- | |||
- | return lib, {body=body} | ||
- | ``` | ||
- | |||
- | ```lua | ||
- | package.delayed["foobar"] = true | ||
- | local foobar = require("foobar") | ||
- | ``` | ||
- | |||
String Manipulation | String Manipulation |