# Autosway API Documentation
API documentation for autosway 0.5.0.
The module namespace is `autosway`, acess it and it's children via `require()`.
For example `require("autosway")` will give you the Core Module and
`require("autosway.os")` will give you the OS Module
Functions that can return an error can be noted as they return something like
`T|error`, these errors can be handled inside the `pcall` function.
## Core Module
This module provides functions that return information about autosway.
The namespace is `autosway`
### `version() -> string,string,string`
This function returns 3 strings that represent the current autosway version in
Semver. It returns major.minor.patch as the 3 strings.
### `config_dir() -> string|nil`
This function returns the autosway configuration directory.
### `local_dir() -> string|nil`
This function returns the local autosway configuration directory.
### `knife_dir() -> string|nil`
This function returns the autosway knife directory.
## OS Module
The OS module provides functions for manipulating processes and environment
variables.
The namespace is `autosway.os`
### `exec(name: string, args: string[]) -> string|error`
Searches for `name` in the PATH environment variable, if found executes the
program with `args` as arguments and returns output.
Example:
```lua
require("autosway.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|error`
Gets the full filesystem path of the current executable or returns an error 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 at `path` in writing mode.
### `open(path: string) -> File|error`
Opens a file at `path` in reading mode.
### `exists(path: string) -> boolean|error`
Returns whether a file or directory at `path` exists.
### `rename(from: string, to: string) -> nil|error`
Renames file `from` to `to`.
### `copy(from: string, to: string) -> integer|error`
Copies file `from` to `to` and returns bytes written
### `remove(path: string, recursive: boolean|nil) -> nil|error`
Removes a file or directory at `path`, `recursive` is `false` by default.
If `recursive` is true and `path` is a directory the directory is recursively
removed.
### `mkdir(path: string) -> nil|error`
Recursively creates directory at `path` and all of its parents if they are
missing.
### `set_mode(path: string, mode: integer) -> nil|error`
Sets UNIX file permissions for `path` to `mode`.
### `symlink(from: string, to: string) -> nil|error`
Creates a symbolic link from `from` to `to`.
### `canonicalize(path: string) -> string|error`
Returns the absolute form of `path` with all intermediate components normalized
and symbolic links resolved.
### `follow_link(path: string) -> string|error`
Returns the path symbolic link `path` points to.
### `read_dir(path: string) -> Directory|error`
Opens a directory at `path` for reading.
### `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:metadata() -> Metadata|error`
Returns file metadata.
### `Directory:next() -> DirectoryEntry|nil|error`
Returns the next directory entry or `nil` when finished.
### `DirectoryEntry:path() -> string`
Returns the full path of this directory entry.
### `DirectoryEntry:metadata() -> string`
Returns metadata of directory entry.
### `Metadata:is_file() -> boolean|error`
Returns whether this file is a regular file.
### `Metadata:is_symlink() -> boolean|error`
Returns whether this file is a symbolic link.
### `Metadata:is_dir() -> boolean|error`
Returns whether this file is a directory.
## 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, returns an error on failure.
### `serialize_json(value: sany) -> string|error`
Parses Lua value into serialized JSON string, returns an error on failure.
### `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?, urgent: bool?) -> nil|error`
Sends a desktop notification.
If `body` isn't `nil` then the notification will have a body.
If `icon` isn't `nil` then the icon of application `icon` will be used.
If `urgent` is `true` the notification will be sent with high urgency.
Example:
```lua
local str = string.format("Rise an shine, %s!", require("autosway.os").get_env("USER"))
require("autosway.desktop").notify("Good morning!", str, "some_application")
```
### `get_clipboard() -> Clipboard|error`
Returns a `Clipboard` or an error on failure.
### `Clipboard:clear() -> nil|error`
Clears the clipboard.
### `Clipboard:get_text() -> string|error`
Gets the text on the clipboard.
### `Clipboard:set_text(text: string) -> nil|error`
Sets the text on the clipboard to `text`.
### `Clipboard:set_html(html: string, alt: string|nil) -> nil|error`
Sets the text on the clipboard to HTML encoded text `html` with the alt text of `alt`.
## 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.
## Net Module
This module provides networking functions.
The namespace is `autosway.net`.
### `http.get(url: string) -> Request|error`
Constructs a `Request` structure with `url` for GET requests and the response.
### `http.head(url: string) -> nil|error`
Sends an HEAD request to `url`.
### `http.post(url: string, body: string) -> Request|error`
Constructs a `Request` structure with `url` and `body` for POST requests and the response.
There are also the `put`, `patch`, `delete` functions that send their respective
HTTP requests, they take the same arguments and return the same value as `post`.
### `Request:text() -> string|error`
Sends the request and returns the response text.
### `Request:json() -> string|error`
Sends the request and returns the response JSON.
### `Request:status() -> string|error`
Sends the request and returns the response status.
### `Request:headers() -> string[]|error`
Sends the request and returns the response headers.
## i3 Module
This module provides functions for manipulating the [i3](https://i3wm.org) and
[sway](https://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
local i3 = require("autosway.i3")
i3.subscribe_event(i3.EVENT_WORKSPACE, function (json_string)
if not json_string then return end
local event = require("autosway.util").parse_json(json_string)["Workspace"]
require("autosway.desktop").notify("Switched to new workspace", event["current"]["name"])
end)
```
## Extra module
This module provides extra functions implemented in Lua instead of Rust.
The namespace is `autosway.extra`
### `hello() -> string`
Returns `"World"`
### `parse_json_ensure_table() -> table|error`
Parses JSON value and ensures a table (object or array).