# OctOS OctOS is the operating system used by digicomputers. OctOS is made of many Linux-like commands which are documented in `commands.md`, however, there is also an API which can be used when writing programs for OctOS. The API can be used by players to interact with the computer under a safe and secure environment. The documentation is divided into two sections as is the code, main (for general functions), and filesystem (for filesystem access). ## Main This contains a set of functions mainly for the purpose of interacting with the computer's displays. #### `print(string, false)` **Usage:** `print(, ` Prints to the output buffer. If contents is not a string, it will be converted to a string with `dump`. The second parameter, if false, prevents print from inserting a newline before printing the provided contents. #### `set_help(value)` **Usage:** `set_help()` Sets the text to be shown when hovering over the help button. A `nil` value will revert the text to default. #### `get_attr(key)` **Usage:** `get_attr()` Gets a piece of global information from the node meta (storage). Several common attributes are below. **Note:** none of these attributes can be directly set, with the purpose of being read-only. However, there are methods to set several. * `owner`: username of the player who owns the computer. * `input`: input field. * `output`: output buffer. * `name`: computer name. #### `get_output()` **Usage:** `get_output()` Returns the value of the output buffer. Shorthand for `get_attr("output")`. #### `set_output(value)` **Usage:** `set_output()` Set the output buffer to any string. This is the write method for the output attribute. #### `set_output_editable(bool)` **Usage:** `set_output_editable()` Makes the output buffer editable. Useful for programs that would like a larger input field. However, it can be used in any way wanted as `get_output` and `set_output` are still functional. #### `get_input()` **Usage:** `get_input()` Returns the value of the input field. Shorthand for `get_attr("input")`. #### `set_input(value)` **Usage:** `set_input()` Set the input field to any string. This is the write method for the input attribute. #### `get_os(key)` **Usage:** `get_os()` Gets a piece of information from the OS table. See next function for further information on this table. #### `set_os(key, value)` **Usage:** `set_os(, ` Sets a piece of information stored in the OS table. This table stores basic values containing information global to the operating system. However, it is quite limitted, only being capable of storing a few pieces of information as listed below. * `clear`: command to clear the output and input. * `off`: command to turn the computer off. * `reboot`: command to reboot the computer. * `prefix`: prefix printed at the beginning of a new line. #### `get_userdata(key)` **Usage:** `get_userdata()` Gets a piece of information from the userdata table. This table is like RAM, as information will be reset when the computer is turned off. #### `set_userdata(key, value)` **Usage:** `set_userdata(, ` Stores any piece of information in the non-persistant userdata table. (Table is cleared when computer is turned off, therefore non-persistant.) #### `refresh()` **Usage:** `refresh()` Refresh the computer display, typically after making changes to a buffer, field, or other element. If `nil` is returned rather than `true`, you have been somehow disconnected from the computer as being the current user (e.g. somebody manually edited the `current_user` meta field); the problem can be solved by simply closing and reopening the formspec manually. #### `run(code, ...)` **Usage:** `run(, )` Run code under the environment (e.g. run data in the input field whenever it is submitted). Returns two parameters, the first representing success and the second being `nil` unless the operation was not successful, in which case it contains an error message. Any number of additional parameters can be provided after the path, to be accessed by the code being run. #### `set_run(path)` __Usage:__ `set_run()` Set the file that is to be run when text in the input bar is submitted. Defaults to `os/main.lua`. If the `path` parameter is not provided, the run file will be reset to the default. #### `Settings(path)` __Usage:__ `Settings()` Returns a userdata value containing a list of the "settings" defined in a file. Each setting should be on a new line, like variables but without `local` as a prefix. This "object" has several methods that you can use on it (e.g. `:to_table()`), however they are not documented here. Instead, see the methods section in the [documentation for node meta](http://dev.minetest.net/NodeMetaRef#Methods) as `Settings()` and node meta share the same methods. ## Filesystem This API section introduces function to interact with the computer's physical filesystem. #### `exists(path)` __Usage:__ `fs.exists()` Checks to see if a file exists by opening it with `io.open()` and returns `true` if exists, and `nil` if it does not. #### `create(path)` __Usage:__ `fs.create()` Creates a file with and returns `true` unless unsuccessful. If you want to write to the file, use `write` directly, as it will automatically create the file if it doesn't already exist. #### `remove(path)` __Usage:__ `fs.remove(` Removes a file and returns `true` if successful. If the return value is `nil`, the file either does not exist or is a directory. Directories must be removed with `rmdir`. #### `write(path, data, mode)` __Usage:__ `fs.write(, , ` Writes any data to the file specified by `path` and returns `true` if successful. If the file does not exist, it will be created and written to. You can specify if you would like to overwrite or append to a file using the optional `mode` parameter (`w`: overwrite/create, `a`: append). #### `read(path)` __Usage:__ `fs.read()` Attempts to read entire file. If `nil` is returned, the file does not exist, otherwise, the file contents will be returned. #### `list(path)` __Usage:__ `fs.list()` Lists the contents of a directory specified by `path`. Returns a table containing two subtables, `files` and `subdirs`. If there are no file or subdirectories, or if the path point to a file rather than a directory, these two subtables will both be empty. #### `copy(original_path, new_path)` __Usage:__ `fs.copy(, (string)` Reads from one path then creates and writes its contents to the new path. If the function returns `nil`, the file doesn't exist or some other error has occurred. Otherwise, a return value of `true` indicates a success. #### `mkdir(path)` __Usage:__ `fs.mkdir()` Creates a directory. Will return `true` if successful, and `nil` if the directory already exists or another error occurs. #### `rmdir(path)` __Usage:__ `fs.rmdir()` Recursively removes a directory if it exists. Returns `true` if successful. __Note:__ this is destructive and will remove all of the sub-directories and files inside of a directory. #### `cpdir(original_path, new_path)` __Usage:__ `fs.cpdir(, ` Recursively copies a directory and all it's sub-directories and files. Returns `true` if successful. __Note:__ depending on the size of the original directory, this may take some time. #### `run(path, ...)` __Usage:__ `fs.run(, )` Attempts to read the contents of a file, treating it as Lua code to be run under the environment. Returns two parameters, the first representing success and the second being `nil` unless the operation was not successful, in which case it contains an error message. Any number of additional parameters can be provided after the path, to be accessed by the code being run.