This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision | ||
|
api:non-standard-lua-libs [2016/06/20 01:52] payonel [Modules] |
api:non-standard-lua-libs [2020/05/23 17:38] (current) payonel [Operating System Facilities] |
||
|---|---|---|---|
| Line 39: | Line 39: | ||
| * ''package.path'' | * ''package.path'' | ||
| - | **It is recommended that users do not change the default package.path and place their custom libraries in /usr/lib/** | + | **It is recommended that users do not change the default package.path. Rather they should place their custom libraries in /usr/lib/** |
| Defines a list of library search paths that `require` iterates to find libraries. It is a semi-colon delimited list of paths, using '?' as a placeholder for a library name passed to `require`. An example would make this much easier to explain | Defines a list of library search paths that `require` iterates to find libraries. It is a semi-colon delimited list of paths, using '?' as a placeholder for a library name passed to `require`. An example would make this much easier to explain | ||
| 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 65: | Line 65: | ||
| **It is nonstandard to modify `package.loaded`** | **It is nonstandard to modify `package.loaded`** | ||
| - | Contains the source of cached libraries in a table, keyed by the library name (as given to `require`), who value is the cached library itself. | + | 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. |
| - | . | + | |
| String Manipulation | String Manipulation | ||
| ------------------- | ------------------- | ||
| Line 101: | Line 101: | ||
| - **binary mode** | - **binary mode** | ||
| - | Streams given by `io.open(path, "rb")` or `filesystem.open(path)` are in binary mode. `filesystem.open(path, "rb")` also works, but streams returned by `filesystem.open` are **always** in binary mode. `stream:read(1)` in binary mode reads a single byte. Reading a numerical value via `buffered_stream:read("*n")` considers the `string.char()` of each byte (buffered streams are returned from `io.open`, and support interpreting numerical values from a stream) | + | Streams given by `io.open(path, "rb")` or `filesystem.open(path)` are in binary mode. `filesystem.open(path, "rb")` also works, but streams returned by `filesystem.open` are **always** in binary mode. `stream:read(1)` in binary mode reads a single byte. Reading a numerical value via `buffered_stream:read("*n")` reads the data as single-byte characters. (buffered streams are returned from `io.open`, and support interpreting numerical values from a stream) |
| - **text mode** | - **text mode** | ||
| - | Only streams given by `io.open` that specifically do not use "b" in the mode are in text mode. Examples are `io.open(path)` and `io.open(path, "r")`. No type of handle given by `filesystem.open` is a stream in text mode. `stream:read(1)` in text mode reads a single unicode-aware char. This could be a single byte, or even 3 bytes - depending on the text. Reading a numerical value via `buffered_stream:read("*n")` considers the `unicode.char()` of the series of bytes (buffered streams are returned from `io.open`, and support interpreting numerical values from a stream) | + | Only streams given by `io.open` that specifically do not use "b" in the mode are in text mode. Examples are `io.open(path)` and `io.open(path, "r")`. No type of handle given by `filesystem.open` is a stream in text mode. `stream:read(1)` in text mode reads a single unicode-aware char. This could be a single byte, or even 3 bytes - depending on the text. Reading a numerical value via `buffered_stream:read("*n")` reads the data as unicode chars. (buffered streams are returned from `io.open`, and support interpreting numerical values from a stream) |
| * `io.open(path, "r")` is equivalent to `io.open(path)`, which opens a file in text read-only mode. | * `io.open(path, "r")` is equivalent to `io.open(path)`, which opens a file in text read-only mode. | ||
| Line 150: | Line 150: | ||
| One additional function has been added: | One additional function has been added: | ||
| - | - `os.sleep(seconds: number)` which allows pausing a script for the specified amount of time. Note that signals will still be processed by event handlers while the sleep is active, i.e. you cannot pull signals that were accumulated during the sleep after it ended, since no signals will remain in the queue (or at least not all of them). | + | - `os.sleep(seconds: number)` which allows pausing a script for the specified amount of time. `os.sleep` consumes events but registered event handlers and threads are still receiving events during the sleep. Rephrased, signals will still be processed by event handlers while the sleep is active, i.e. you cannot pull signals that were accumulated during the sleep after it ended, since no signals will remain in the queue (or at least not all of them). |
| Some new functions that kind of fall into this category are available in [[api:computer|the computer API]]. | Some new functions that kind of fall into this category are available in [[api:computer|the computer API]]. | ||