# API Documentation
API documentation for autosway.
The global namespace is `autosway`, `as` exists as an alias,
the examples in this documentation will use `as` for brevity.
## OS Module
The OS module provides functions for manipulating processes and environment
variables.
The namespace is `autosway.os`
### `exec(name: string, args: string[]) -> string|boolean`
Searches for `name` in the PATH environment variable, if found executes the
program with `args` as arguments and returns output.
On failure it returns `false`.
Example:
```lua
as.os.exec("ls", {"-alh"})
```
### `get_pid() -> integer`
Returns current process ID.
### `get_env(name: string) -> string|nil`
Gets environment variable `name` and returns its value or `nil` if not found.
### `set_env(name: string, value: string) -> nil`
Sets environment variable `name` to `value`.
### `current_exe() -> string|nil`
Gets the full filesystem path of the current executable or returns `nil` on
failure.
### `get_cwd() -> string|nil`
Gets the current working directory or returns `nil` on failure.
### `set_cwd(path: string) -> nil`
Sets the current working directory to `path`.
## FS Module
The **F**ile**S**ystem module provides functions for manipulating the
filesystem.
The namespace is `autosway.fs`
### `create(path: string) -> File|error`
Creates or opens a file in writing mode.
### `open(path: string) -> File|error`
Opens a file in reading mode.
### `File:write(data: string) -> nil|error`
Writes `data` to file.
### `File:read_line() -> string|error`
Reads a line from file.
### `File:read_all() -> string|error`
Reads entire file.
### `File:flush() -> nil`
Flushes file output stream.
### `File:is_file() -> boolean|error`
Returns whether this file is a regular file.
### `File:is_symlink() -> boolean|error`
Returns whether this file is a symbolic link.
## Utility Module
This module provides utility functions.
The namespace is `autosway.util`.
### `parse_json(json: string) -> any|error`
Parses JSON string `json` into a Lua value.
### `join_path(path: string, right: string) -> string`
Joins 2 paths together.
### `string_split(str: string, delim: string) -> string[]`
Splits `str` into an array of strings separated by `delim`.
### `string_trim(str: string) -> string`
Trims `str`, removing trailing spaces.
### `string_index(str: string, index: integer) -> string`
Returns character in `str` at `index`.
### `get_knife_path(knife: string) -> string|nil`
Returns the path of `knife` or returns `nil` if not found.
## Desktop Module
This module provides desktop manipulation functions.
The namespace is `autosway.desktop`.
### `notify(summary: string, body: string, icon: string|nil) -> nil|error`
Sends a desktop notification.
If `icon` isn't `nil` then the icon of application `icon` will be used.
Example:
```lua
local str = string.format("Rise an shine, %s!", as.os.get_env("USER"))
as.desktop.notify("Good morning!", str, "firefox")
```
## Multimedia Module
This module provides multimedia functions.
The namespace is `autosway.multimedia`.
### `play_sound(path: string) -> nil|error`
Plays a sound at `path` or throws an error on failure.
## i3 Module
This module provides functions for manipulating the [i3](https://i3wm.org) and
[sway](swaywm.org) window managers.
It only works on platforms supported by i3.
The namespace is `autosway.i3`
### Constants
- `EVENT_WORKSPACE`: Workspace event
- `EVENT_OUTPUT`: Output event
- `EVENT_MODE`: Mode event
- `EVENT_WINDOW`: Window event
- `EVENT_BARCONFIG_UPDATE`: Bar configuration update event
- `EVENT_BINDING`: Keybinding event
- `EVENT_SHUTDOWN`: Shutdown event
- `EVENT_TICK`: Tick event
- `EVENT_BARSTATE_UPDATE`: Bar state update event
- `EVENT_INPUT`: Input event
All the above constants are of type `EventType`
### `run_command(command: string) -> boolean`
Runs the i3 command `command`. Returns true on success, false on failure.
### `get_workspaces() -> string[]`
Returns active workspaces.
### `get_outputs() -> string[]`
Returns outputs.
### `get_inputs() -> string[]`
Returns inputs.
### `get_seats() -> string[]`
Returns seats.
### `get_tree() -> string|nil`
Returns the tree or nil on failure.
### `subscribe_event(type: EventType, callback: function(json: string|nil)) -> nil|boolean`
This function subscribes to an event of `type`, calling `callback` with either
the event JSON or nil on failure to parse the JSON.
This function returns nil on success and false on failure.
Example:
```lua
as.i3.subscribe_event(as.i3.EVENT_WORKSPACE, function (json_string)
if not json_string then return end
local event = as.util.parse_json(json_string)["Workspace"]
as.desktop.notify("Switched to new workspace", event["current"]["name"])
end)
```