# ZSH Utilities

A shell-scripting utilities module made for ZSH.
This module is definitely a major component of Scwrypts, but is also standalone and can be sourced by any ZSH script to utilize (almost) all of the features.

## Usage
Import `utils.module.zsh` to activate all of the features.
Doing so will *also* check for path dependencies and required environment variables (see [Dependencies](#dependencies) and [Environment](#environment) below).


```shell
#!/bin/zsh
source ./path/to/utils.plugin.zsh
__SUCCESS 'ZSH utilities online!'
```

Checkout [io](./io.zsh) and [os](./os.zsh) for available simple functions.

### Dependencies
Ensures dependent programs are available for execution.
Specify a simple name to check the current `PATH`, or give a fully-qualified path for arbitrary dependency inclusion.

Include a dependency by adding to the `_DEPENDENCIES` array.
*Always using `+=` makes your dependencies extensible to other scripts :)*

If any dependencies are missing, `source utils.module.zsh` will return an error code and count the number of missing dependencies in the variable `DEP_ERROR_COUNT`.

```shell
#!/bin/zsh
_DEPENDENCIES+=(
	path-executable-1
	path-executable-2
	/path/to/arbitrary/program
)
source ./path/to/utils.plugin.zsh
echo "missing $DEP_ERROR required dependencies"
```

### Environment
Similar to [Dependencies](#dependencies), `environment.zsh` ensures a list of environment variables are *set to non-empty values*.

Include an environment variable by adding to the `_REQUIRED_ENV` array.
*Something something use `+=` here too ;)*

If any environment variables are missing, `source utils.module.zsh` will return an error code and count the number of missing variables in `ENV_ERROR_COUNT`.

Missing environment variables will be added to the environment template (*exclusive to Scwrypts*).

```shell
#!/bin/zsh
_REQUIRED_ENV+=(
	AWS_PROFILE
	AWS_REGION
)
source ./path/to/utils.plugin.zsh
echo "missing $ENV_ERROR_COUNT required environment variables"
```

io.zsh
os.zsh

## Basic Utilities

One of my biggest pet-peeves with scripting is when every line of a *(insert-language-here)* program is escaped to shell.
This kind of program, which doesn't use language features, should be a shell script.
While there are definitely unavoidable limitations to shell scripting, we can minimize a variety of problems with a modern shell and shared utilities library.

Loaded by `common.zsh`, the [`utils/` library](./utils) provides:
- common function wrappers to unify flags and context
- lazy dependency and environment variable validation
- consistent (and pretty) user input / output