# Bashio: variables, strings, files, and JSON

> Bashio helper functions for values, strings, files, JSON with jq, the cache, network ports, and Have I Been Pwned.

Source: https://contributors.home-assistant.io/apps/bashio/helpers/

<!-- Generated by `pnpm bashio` from scripts/bashio/helpers.md. Edit that file, not this one. -->

These helpers do not call the Supervisor. They work on values, files, and JSON, and the other Bashio functions use them too. The function lists on this page are generated from the docblocks in the source of Bashio. The descriptions are the ones in the source, so some still say "addon" where this site says app.

The `bashio::var.*`, `bashio::fs.*`, and `bashio::jq.is*` functions are checks: they print nothing and return exit status `0` for yes, `1` for no. Use them in an `if`.

```bash
#!/command/with-contenv bashio

if ! bashio::fs.directory_exists '/data/db'; then
  mkdir -p /data/db
fi

config=$(bashio::var.json name "$(bashio::app.name)" port "^8080")
bashio::log.debug "${config}"

bashio::net.wait_for 3306 localhost 30
```

`bashio::var.json` builds a JSON object from key and value pairs. Values are strings, unless you start them with `^`: then they go in as they are, for numbers, booleans, and nested JSON.

## Variables

Check values, and turn shell values into JSON. Source: [`lib/var.sh`](https://github.com/hassio-addons/bashio/blob/main/lib/var.sh).

- `bashio::var.true`: Checks if a given value is true.
  - `$1`: value
- `bashio::var.false`: Checks if a given value is false.
  - `$1`: value
- `bashio::var.defined`: Checks if a global variable is defined.
  - `$1`: Name of the variable
- `bashio::var.has_value`: Checks if a value has actual value.
  - `$1`: Value
- `bashio::var.is_empty`: Checks if a value is empty.
  - `$1`: Value
- `bashio::var.equals`: Checks if a value equals.
  - `$1`: Value
  - `$2`: Equals value
- `bashio::var.json`: Creates JSON based on function arguments.
  - `$@`: Bash array of key/value pairs, prefix integer or boolean values with ^
- `bashio::var.json_string`: Escapes a string for use in a JSON object.
  - `$1`: String to escape
- `bashio::var.json_array`: Converts a bash array to a JSON array.
  - `$@`: Bash array

## Strings

Change and measure strings. Source: [`lib/string.sh`](https://github.com/hassio-addons/bashio/blob/main/lib/string.sh).

- `bashio::string.lower`: Converts a string to lower case.
  - `$1`: String to convert
- `bashio::string.upper`: Converts a string to upper case.
  - `$1`: String to convert
- `bashio::string.replace`: Replaces parts of the string with another string.
  - `$1`: String to make replacements in
  - `$2`: String part to replace
  - `$3`: String replacement
- `bashio::string.length`: Returns the length of a string.
  - `$1`: String to determine the length of
- `bashio::string.substring`: Returns a substring of a string.
  - `$1`: String to return a substring of
  - `$2`: Position to start
  - `$3`: Length of the substring (optional)

The docblock of `bashio::string.substring` has this example:

```bash
stringZ=abcABC123ABCabc
bashio::string.substring "${stringZ}" 0      # abcABC123ABCabc
bashio::string.substring "${stringZ}" 1      # bcABC123ABCabc
bashio::string.substring "${stringZ}" 7      # 23ABCabc
bashio::string.substring "${stringZ}" 7 3    # 23A
```

## Files

Check whether files, folders, devices, and sockets exist. Source: [`lib/fs.sh`](https://github.com/hassio-addons/bashio/blob/main/lib/fs.sh).

- `bashio::fs.directory_exists`: Check whether or not a directory exists.
  - `$1`: Path to directory
- `bashio::fs.file_exists`: Check whether or not a file exists.
  - `$1`: Path to file
- `bashio::fs.file_non_empty`: Check whether or not a file exists and is non-empty (size > 0 bytes).
  - `$1`: Path to file
- `bashio::fs.device_exists`: Check whether or not a device exists.
  - `$1`: Path to device
- `bashio::fs.socket_exists`: Check whether or not a socket exists.
  - `$1`: Path to socket

## JSON

Query JSON with jq, and check the type of the result. Source: [`lib/jq.sh`](https://github.com/hassio-addons/bashio/blob/main/lib/jq.sh).

- `bashio::jq`: Execute a JSON query.
  - `$1`: JSON string or path to a JSON file
  - `$2`: jq filter (optional)
  - `$@`: Extra jq arguments, for example --arg/--argjson to pass values safely (optional)
- `bashio::jq.exists`: Checks if variable exists (optionally after filtering).
  - `$1`: JSON string or path to a JSON file
  - `$2`: jq filter (optional)
- `bashio::jq.has_value`: Checks if data exists (optionally after filtering).
  - `$1`: JSON string or path to a JSON file
  - `$2`: jq filter (optional)
- `bashio::jq.is`: Checks if resulting data is of a specific type.
  - `$1`: JSON string or path to a JSON file
  - `$2`: jq filter
  - `$3`: type (boolean, string, number, array, object, null)
- `bashio::jq.is_boolean`: Checks if resulting data is a boolean.
  - `$1`: JSON string or path to a JSON file
  - `$2`: jq filter (optional)
- `bashio::jq.is_string`: Checks if resulting data is a string.
  - `$1`: JSON string or path to a JSON file
  - `$2`: jq filter (optional)
- `bashio::jq.is_object`: Checks if resulting data is an object.
  - `$1`: JSON string or path to a JSON file
  - `$2`: jq filter (optional)
- `bashio::jq.is_number`: Checks if resulting data is a number.
  - `$1`: JSON string or path to a JSON file
  - `$2`: jq filter (optional)
- `bashio::jq.is_array`: Checks if resulting data is an array.
  - `$1`: JSON string or path to a JSON file
  - `$2`: jq filter (optional)

## Cache

The file cache that the Supervisor API functions use, in `/tmp/.bashio` unless you set `CACHE_DIR`. Source: [`lib/cache.sh`](https://github.com/hassio-addons/bashio/blob/main/lib/cache.sh).

- `bashio::cache.exists`: Check if a cache key exists in the cache
  - `$1`: Cache key
- `bashio::cache.get`: Returns the cached value based on a key
  - `$1`: Cache key
- `bashio::cache.set`: Cache a value identified by a given key
  - `$1`: Cache key
  - `$2`: Cache value
- `bashio::cache.flush`: Remove a specific item from the cache based on the caching key
  - `$1`: Cache key
- `bashio::cache.flush_all`: Flush all cached data

## Network

Wait for a TCP port to accept connections. The function returns after the timeout either way, so check the port again if your script depends on it. Source: [`lib/net.sh`](https://github.com/hassio-addons/bashio/blob/main/lib/net.sh).

- `bashio::net.wait_for`: Wait for a TCP port to be available.
  - `$1`: Port to wait for
  - `$2`: Interface/host the port should bind to (optional, default: localhost)
  - `$3`: Timeout in seconds (optional, default: 60)

## Have I Been Pwned

Check a password against the Have I Been Pwned database. Only the first five characters of the SHA-1 hash of the password leave the container. Source: [`lib/pwned.sh`](https://github.com/hassio-addons/bashio/blob/main/lib/pwned.sh).

- `bashio::pwned.is_safe_password`: Checks if a given password is safe to use.
  - `$1`: The password to check
- `bashio::pwned.occurrences`: Gets the number of occurrences of the password in the list.
  - `$1`: The password to check
- `bashio::pwned.occurances`: Deprecated alias for `bashio::pwned.occurrences.`
- `bashio::pwned`: Makes a call to the Have I Been Pwned password database
  - `$1`: The password to check