lightning-runner/readme.md

# ⚡-runner: the minimal task runner you've been missing in your life
⚡-runner is a language-agnostic task runner in the category of tools such as `make`, `grunt`, `gradle`, `leiningen`, etc. It has a single, widely available dependency: bash.
It's intent is to provide your shell scripts with the syntactic sugar they crave to make them more presentable, and more manageable.

# Why have you done this?
The main reason ⚡-runner was born, was because I'm a huge fan of [go scripts](https://blog.thepete.net/blog/2014/03/28/_-attributes-of-an-amazing-dev-toolchain/). I find myself including one in nearly every repo I make. I've also started finding myself copy-pasting a WHOLE bunch of helper functions across them. These scripts are always in bash to make them easily usable by everyone on a team, regardless of their operating system of choice. I've also found myself using similar patterns for other scripts I have, which do maybe more than a single thing but maybe less than a full application would warrant.

# Usage
Download the runner, chuck it into your repo, and source it from a shell script! Or if you're feeling brave, use the line below... I know I will!
```
source <(cat /tmp/⚡ 2> /dev/null || curl https://apps.ofvlad.xyz/⚡ | tee /tmp/⚡)
```

# Examples
You can see these all working in [the examples script](examples)

## Hello ⚡
As is tradition:
```bash
$ echo '
#!/usr/bin/env bash

⚡hello() {
  _help-line "Say hello!"
  echo Hello, world!
}

source ⚡
' > go && chmod +x go
$ ./go hello
Hello, world!
$ ./go
Usage: ./go [sub-command]

Available subcommands:
	hello                - Say hello!
	help                 - Show this list
```

## Build/run/check/test/clean
Look! It's like a task runner!
```bash
#!/usr/bin/env bash
cd $(dirname $0)

⚡build() {
  echo 'echo hi; echo "$@"' > .generated/potato
  chmod +x .generated/potato
}

⚡run() {
  ⚡build
  .generated/potato "$@"
}

⚡check() {
  ⚡build
  shellcheck .generated/potato
}

⚡test() {
  ⚡build
  [ "$(.generated/potato)" == "hi" ]
}

⚡clean() {
  rm -rf .generated
}

source ⚡
```

## It's just bash!
Do whatever you need, just define a ⚡function or two as the interface
```bash
#!/usr/bin/env bash

cookie_jar_path=$(mktemp)
trap "rm $cookie_jar_path" EXIT
encrypted_password=$(pass routers/tp-link-encrypted)

router-curl() {
  path=$1; shift
  curl -s -b $cookie_jar_path -c $cookie_jar_path -X POST "http://192.168.0.1/cgi-bin/luci/;stok=${STOK:-}/$path" "$@"
}

⚡connected-devices() {
  _help-line "Show devices connected to router"
  STOK=$(router-curl login?form=login --data-raw "operation=login&password=$encrypted_password"| jq -r .data.stok )
  router-curl admin/status?form=all | jq '.data | [.access_devices_wired, .access_devices_wireless_guest, .access_devices_wireless_host] | flatten'
}

source ⚡
```

# More sugar
## Colors
```diff
$ echo '
#!/usr/bin/env bash

⚡good() {
  _good-message + Good Message
}

⚡bad() {
  _bad-message - Bad Message
}

source ⚡
' > go && chmod +x go
$ ./go good
+ Good message
$ ./go bad
- Bad message
```

## Prerequisites
```bash
$ echo '
#!/usr/bin/env bash

_verify-prerequisites() {
  docker ps &> /dev/null || (echo 'Not enough docker'; exit 1)
}

⚡ubuntu() {
  docker run -ti ubuntu
}

source ⚡
' > go && chmod +x go
$ ./go ubuntu
Not enough docker
```

# Wrappers
Tired of your gradlew, terraformw, mavenw, jqw, opensslw, kubectlw, etc literring the root of your repo? Me too! 
```bash
$ echo '
#!/usr/bin/env bash

kubectlw() {
  _wrapper \
    -n kubectl \
    -v v1.19.4 \
    -l https://dl.k8s.io/release/VERSION/bin/linux/amd64/kubectl \
    -d https://dl.k8s.io/release/VERSION/bin/darwin/amd64/kubectl \
    -- \
    "$@"
}

⚡kubectl-version() {
  kubectlw version
}

source ⚡
' > go && chmod +x go
$ ./go kubectl-version
Client Version: version.Info{Major:"1", Minor:"19", GitVersion:"v1.19.4", GitCommit:"d360454c9bcd1634cf4cc52d1867af5491dc9c5f", GitTreeState:"clean", BuildDate:"2020-11-11T13:17:17Z", GoVersion:"go1.15.2", Compiler:"gc", Platform:"darwin/amd64"}
The connection to the server localhost:8080 was refused - did you specify the right host or port?

```

# Appendix
This is where I would put the full list of helpers ⚡-runner provides IF I HAD ONE

# FAQ
## How do I type ⚡?
Below this line are a number of options. Go down the list until you find one that works for you.
- ^⌘Space on macos opens the emoji picker. Search for 'lightning'
- ⊞Win + . on windows opens the emoji picker. Search for 'lightning'
- ctrl + . within gnome opens the emoji picker. Search for 'lightning' (can someone confirm?)
- Super + . within KDE opens the emoji picker. Search for 'lightning' (can someone confirm?)
- Copy and paste this: ⚡
- Use your favorite web search engine to search for 'lightning emoji', copy paste from there.
## Why bash?
Because I like it.
## But really, why bash?
When have you, a developer, used a computer that doesn't have bash installed?
## My operating system of choice is Windows, it doesn't come with bash?
That's not a question. Enable WSL.
## I don't want to enable WSL?
That's still not a question. Also you're wrong.