version: bump to 0.97.3

README.md

@@ -14,6 +14,7 @@ We have some guides and general documentation in the [docs](docs/) directory. Am
 - [Tests](docs/tests.md)
 - [HTTP Router](docs/router.md)
 - [Template engine](docs/template.md)
+- [Script integrations](docs/util.md)
 - [List of security fixes](docs/sec-fixes/)
 
 ## Dependencies

docs/running.md

@@ -9,3 +9,6 @@ The arg parsing is a bit rudimentary atm. Assume only one option supported per i
 - `debug` shows stderr (useful for debugging)
 - `debuggier` shows stderr and calltrace 
 - `shell` drops you into an environment practically equivalent to the runtime
+- `utils` lists all available [utilities](./util.md) (scripts which integrate into the
+  standard HTTP.sh environment, but are strictly for CLI use. Useful for administrative tasks.)
+- `<util> [params]` launches an utility, if it's available

docs/util.md

@@ -0,0 +1,45 @@
+# utils: integrating scripts with http.sh
+
+HTTP.sh provides a number of useful APIs designed to make interfacing with HTTP and browsers easier.
+Some of those (especially notORM) are also useful in a CLI environment, to help with migrations and
+other administrative tasks.
+
+Utils integrate into HTTP.sh through calling the main script, with the utility name as the first
+parameter. So, for `meow.sh` the invocation would be `./http.sh meow`, or `./http.sh meow [params]`
+if the util takes any parameters.
+
+Utils are automagically started within the environment, and otherwise work like normal scripts.
+Of note:
+
+- `$0` is always the `./http.sh` invocation, not your script name
+- script name is instead stored in `$HTTPSH_SCRIPTNAME`
+- `$@` contain parameters to the utility, not a full invocation.
+- at the present, only the `master.sh` config is loaded
+- the environment is equivalent to `./http.sh shell`
+
+A list of utilities can be obtained by calling `./http.sh utils`.
+
+## Built-in utils
+
+The following scripts are generic helpers shipped with HTTP.sh. We hope they'll come in handy.
+
+### notORM
+
+WIP. Currently can only dump a store out to the terminal:
+
+```bash
+$ ./http.sh notORM dump storage/new.dat
+declare -a data=([0]="0" [1]="domi" [2]="http://sdomi.pl/" [3]="" [4]="XOaj44smtzCg1p88fgG7bEnMeTNt361wK8Up4BKEiU747lcNIuMAez60zEiAaALWMwzcQ6" [5]="0" [6]="meow~" [7]="RCszUuBXQI")
+ (…)
+```
+
+### bump
+
+Acknowledges a version after a HTTP.sh update. Takes no parameters.
+
+## Future plans
+
+- List a description for each util on the `./http.sh utils` page. This would require storing more
+  metadata on the utils, TBD.
+- more 1st-party utils!
+- more work on notORM util, ideally it should allow one to do all actions on the DB

http.sh

@@ -59,7 +59,12 @@ fi
 source config/master.sh
 
 if [[ "$HTTPSH_VERSION" != "${cfg[init_version]}" ]]; then
-	echo "WARN: HTTP.sh was updated since this instance was initialized (config v${cfg[init_version]:-(none)}, runtime v$HTTPSH_VERSION). There may be breaking changes. Edit cfg[init_version] in config/master.sh to remove this warning."
+	echo "WARN: HTTP.sh was updated since this instance was initialized (config v${cfg[init_version]:-(none)}, runtime v$HTTPSH_VERSION). There may be breaking changes.
+
+Check for breaking changes (announced on IRC and in `git log`),
+then use this to ACK the message:
+
+./http.sh bump"
 fi	
 
 while read i; do
@@ -102,6 +107,32 @@ if [[ "$1" == 'shell' ]]; then
 	exit 0
 fi
 
+if [[ "$1" == "utils" ]]; then # list all available utils
+	# would be cool to make this more generic
+	ls "${cfg[namespace]}/util/" "src/util"
+	exit 0
+fi
+
+for path in "${cfg[namespace]}/util/" "src/util/"; do
+	HTTPSH_SCRIPTNAME="$(basename "$1")"
+	if [[ -x "$path$HTTPSH_SCRIPTNAME.sh" ]]; then
+		shift
+		shopt -s extglob
+		source src/account.sh
+		source src/mail.sh
+		source src/mime.sh
+		source src/misc.sh
+		source src/notORM.sh
+		source src/template.sh
+		source "${cfg[namespace]}/config.sh"
+		source "$path$HTTPSH_SCRIPTNAME.sh"
+		exit 0
+	elif [[ -f "$path$HTTPSH_SCRIPTNAME.sh" ]]; then
+		echo "[WARN] util '$1' found, but not executable. Ignoring..." >&2
+	fi
+done
+unset path HTTPSH_SCRIPTNAME
+
 cat <<EOF >&2
  _    _ _______ _______ _____  ______ _    _ 
 | |  | |_______|_______|  _  \/  ___/| |  | |

src/util/bump.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+if [[ "$HTTPSH_VERSION" != "${cfg[init_version]}" ]]; then
+	sed -i '/cfg\[init_version\]=/d' config/master.sh
+	echo "cfg[init_version]=$HTTPSH_VERSION" >> "config/master.sh"
+	echo "Version bumped. I hope you checked for breaking changes!"
+else
+	echo "All good! :3"
+fi

src/util/notORM.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+if [[ ! "$1" ]]; then
+	echo "usage: $0 $HTTPSH_SCRIPTNAME <action> [params]
+
+Action can be one of:
+  dump <store> - dump the contents of a notORM store"
+	exit 1
+elif [[ "$1" == dump ]]; then
+	x() { declare -p data; }
+	data_iter "$2" { } x
+fi

src/version.sh

@@ -1,2 +1,2 @@
 #!/usr/bin/env bash
-HTTPSH_VERSION=0.97.2
+HTTPSH_VERSION=0.97.3