v3.0.0 "The Great Overhaul"

=====================================================================

Notice the major version change which comes with breaking changes to
2.x! Reconstructs "library" functions for both python and zsh scwrypts,
with changes to virtualenv naming conventions (you'll need to refresh
all virtualenv with the appropriate scwrypt).

--- Changes ------------------------------

- changed a naming convention across zsh scripts, particularly
  removing underscores where there is no need to avoid naming clash
  (e.g. 'zsh/lib/utils/io.zsh' renames '__STATUS' to 'STATUS')

- moved clients reliant on py.lib.http to the py.lib.http module

- python scripts now rely on py.lib.scwrypts.execute

- updated package.json in zx scripts to include `type = module`

- 'scwrypts --list' commandline argument now includes additional
  relevant data for each scwrypt

- environment variables no longer add themselves to be staged in the
  '.env.template'

--- New Features -------------------------

- new 'use' syntax for disjoint import within zsh scripts; took me
  a very long time to convince myself this would be necessary

- introduced scwrypt "groups" to allow portable module creation;
  (i.e. ability add your own scripts from another repo!)

- py.lib.scwrypts.io provides a combined IO stream for quick, hybrid
  use of input/output files and stdin/stdout

- py.lib.fzf provides a wrapper to provide similar functionality to
  zsh/utils/io.zsh including fzf_(head|tail)

- improved efficiency of various scwrypts; notably reducing runtime
  of scwrypts/environment sync

- improved scwrypts CLI by adding new options for exact scwrypt
  matching, better filtering, and prettier/more-detailed interfaces

--- New Scripts --------------------------

- py/twilio )
    basic SMS integration with twilio
     - send-sms

- py/directus )
    interactive directus GET query
     - get-items

- py/discord )
    post message to discord channel or webhook
     - post-message

zsh/system/config/settings

@@ -0,0 +1,9 @@
+#!/bin/zsh
+DEPENDENCIES+=()
+REQUIRED_ENV+=()
+
+use system/config
+
+CHECK_ENVIRONMENT
+#####################################################################
+EDIT "$CONFIG__USER_SETTINGS"

zsh/system/config/symlinks

@@ -0,0 +1,39 @@
+#!/bin/zsh
+DEPENDENCIES+=()
+REQUIRED_ENV+=()
+
+use system/config
+
+CHECK_ENVIRONMENT
+#####################################################################
+
+SETUP_SYMLINKS() {
+	while read SYMLINK
+	do
+		SETUP_SYMLINK $(echo $SYMLINK | awk '{print $1;}') $(echo $SYMLINK | awk '{print $2}')
+	done < <(echo $SYMLINKS | sed -n '/^[^#]/p')
+}
+
+SETUP_SYMLINK() {
+	[ ! $2 ] && FAIL 1 'must provide SOURCE_CONFIG and TARGET_CONFIG'
+
+	local SOURCE_CONFIG="$1"
+	[ ! -f "$SOURCE_CONFIG" ] && [ ! -d "$SOURCE_CONFIG" ] && FAIL 2 "no such file or directory '$SOURCE_CONFIG'"
+
+	local TARGET_CONFIG="$HOME/.config/$2"
+
+	[ ! -d $(dirname "$TARGET_CONFIG") ] && mkdir -p $(dirname "$TARGET_CONFIG")
+
+	[[ $SAFE_SYMLINKS -eq 1 ]] \
+		&& mv "$TARGET_CONFIG" "$TARGET_CONFIG.bak" >/dev/null 2>&1
+
+	rm "$TARGET_CONFIG" >/dev/null 2>&1
+
+	ln -s "$SOURCE_CONFIG" "$TARGET_CONFIG" \
+		&& SUCCESS "successfully linked '$(basename $(dirname $TARGET_CONFIG))/$(basename $TARGET_CONFIG)'" \
+		|| FAIL 3 "failed to create link '$TARGET_CONFIG'" \
+		;
+}
+
+#####################################################################
+SETUP_SYMLINKS $@

zsh/system/config/terminfo

@@ -0,0 +1,27 @@
+#!/bin/zsh
+DEPENDENCIES+=(tic)
+REQUIRED_ENV+=()
+
+use system/config
+
+CHECK_ENVIRONMENT
+#####################################################################
+
+SETUP_TERMINFO() {
+	[ ! $TERMINFO_PATH ] && return 0
+	[ ! -d $TERMINFO_PATH ] && FAIL 1 "TERMINFO_PATH='$TERMINFO_PATH' does not exist"
+
+	local ERRORS=0
+	for TERMINFO in $(find $TERMINFO_PATH -type f)
+	do
+		tic -x $TERMINFO >/dev/null 2>&1 \
+			&& SUCCESS "added '$(basename $TERMINFO)'" \
+			|| ERROR "failed to add '$(basename $TERMINFO)'" \
+			;
+	done
+
+	CHECK_ERRORS
+}
+
+#####################################################################
+SETUP_TERMINFO $@

zsh/system/config/update

@@ -0,0 +1,13 @@
+#!/bin/zsh
+DEPENDENCIES+=()
+REQUIRED_ENV+=()
+
+use scwrypts/meta
+
+CHECK_ENVIRONMENT
+#####################################################################
+
+STATUS 'updating all config files and links'
+SCWRYPTS__RUN --name system/config/symlinks --group scwrypts --type zsh || exit 1
+SCWRYPTS__RUN --name system/config/terminfo --group scwrypts --type zsh || exit 2
+SUCCESS 'finished updating config files and links'

zsh/system/i3/create-local-font-override

@@ -0,0 +1,102 @@
+#!/bin/zsh
+DEPENDENCIES+=(
+	diff
+)
+REQUIRED_ENV+=(
+	I3__MODEL_CONFIG
+)
+
+CHECK_ENVIRONMENT
+#####################################################################
+
+REGEX_FONT='^\(font [^0-9]*\)\(.*\)'
+REGEX_DMENU="^\\(.*dmenu_run .*-fn '[^0-9]*\\)\\([0-9]*\\)'"
+REGEX_BORDER='^\(for_window.*border pixel \)\(.*\)'
+
+INSTALL() {
+	local USAGE="
+		usage: [...options...]
+
+		options
+		  -f, --force             force replacement of existing i3config
+		  -n, --no-link           if output config and template are the same, don't create link
+
+		  -h, --help              print this message and exit
+
+		environment
+		  I3__MODEL_CONFIG        fully-qualified path to sourced i3config
+		  I3__GLOBAL_FONT_SIZE    global font size
+		  I3__DMENU_FONT_SIZE     (optional) font size for 'dmenu' command
+		  I3__BORDER_PIXEL_SIZE   (optional) pixel-width of window borders
+
+		I3 provides no way to include dynamic variables in your config.
+		The main difference I want between my i3 configurations is font-size
+		to match the current monitor. Since i3-msg provides no way to change
+		font size, I run this command to update those variables on a local
+		copy of my sourced config
+	"
+	local FORCE=0
+	local AUTOLINK=1
+	while [[ $# -gt 0 ]]
+	do
+		case $1 in 
+			-f | --force ) FORCE=1 ;;
+			-n | --no-link ) AUTOLINK=0 ;;
+			-h | --help ) USAGE; exit 0 ;;
+		esac
+		shift 1
+	done
+
+	STATUS 'reading local i3config'
+	[[ ^$I3__MODEL_CONFIG$ =~ ^$HOME/.config/i3/config$ ]] && {
+		STATUS "model configuration is default configuration"
+		I3__MODEL_CONFIG="$I3__MODEL_CONFIG.template"
+		[ ! -f "$I3__MODEL_CONFIG" ] && {
+			STATUS "creating template"
+			cp "$HOME/.config/i3/config" "$I3__MODEL_CONFIG.template"
+		}
+		STATUS "referring to '$I3__MODEL_CONFIG'"
+	}
+	local CONFIG=$(cat "$I3__MODEL_CONFIG")
+	[ ! $CONFIG ] && FAIL 1 "failed to read config at '$I3__MODEL_CONFIG'"
+
+	local CONFIG_FILE="$HOME/.config/i3/config"
+	[ ! -d $(dirname "$CONFIG_FILE") ] && mkdir -p "$(dirname "$CONFIG_FILE")"
+
+	[ -f "$CONFIG_FILE" ] && mv "$CONFIG_FILE" "$CONFIG_FILE.bak"
+
+	[ $I3__GLOBAL_FONT_SIZE ] && {
+		STATUS "setting global font size to '$I3__GLOBAL_FONT_SIZE'"
+		CONFIG=$(echo $CONFIG | sed "s/$REGEX_FONT/\\1$I3__GLOBAL_FONT_SIZE/")
+	}
+
+	[ $I3__DMENU_FONT_SIZE ] && {
+		STATUS "setting dmenu font size to '$I3__DMENU_FONT_SIZE'"
+		CONFIG=$(echo $CONFIG | sed "s/$REGEX_DMENU/\\1$I3__DMENU_FONT_SIZE'/")
+	}
+
+	[ $I3__BORDER_PIXEL_SIZE ] && {
+		STATUS "setting border pixel size to '$I3__BORDER_PIXEL_SIZE'"
+		CONFIG=$(echo $CONFIG | sed "s/$REGEX_BORDER/\\1$I3__BORDER_PIXEL_SIZE/")
+	}
+
+	echo $CONFIG > "$CONFIG_FILE"
+	[ -f "$CONFIG_FILE.bak" ] \
+		&& diff "$CONFIG_FILE" "$CONFIG_FILE.bak" -q >/dev/null \
+		&& mv "$CONFIG_FILE.bak" "$CONFIG_FILE" \
+		&& INFO "no changes were made" \
+		;
+
+	[[ $AUTOLINK -eq 1 ]] \
+		&& diff "$CONFIG_FILE" "$I3__MODEL_CONFIG" -q >/dev/null \
+		&& rm "$CONFIG_FILE" \
+		&& ln -s "$I3__MODEL_CONFIG" "$CONFIG_FILE" \
+		&& INFO "output is the same as model, i3config has been linked to model" \
+		;
+
+	[[ $FORCE -eq 1 ]] && rm "$CONFIG.bak" >/dev/null 2>&1
+	return 0
+}
+
+#####################################################################
+INSTALL $@

zsh/system/i3/launch-or-show

@@ -0,0 +1,118 @@
+#!/bin/zsh
+DEPENDENCIES+=(
+	i3-msg
+	xdotool
+	xrandr
+)
+REQUIRED_ENV+=()
+
+use system/desktop/notify
+
+CHECK_ENVIRONMENT
+#####################################################################
+
+LAUNCH_OR_SHOW() {
+	INFO $@
+	local USAGE="
+		usage: <path-executable> [client-class] [...options...]
+
+		options
+		  -c, --client <string>   if different from the executable name, xprop CLIENT_CLASS
+
+		  -s, --scale <value>     (default: 0.8 or 0.5 if screen width >3000px)
+		  -x, --x-offset <value>  (default: 0.0)
+		  -y, --y-offset <value>  (default: 0.0)
+
+		  -a, --always-launch     invoke executable even if client-class exists
+		  -n, --no-resize         don't resize the window (ignores -sxy flags)
+
+		  -h, --help              print this message and exit
+
+		Makes it easy to bind appications to key shortcuts without having to
+		spin up redundant instances or cycle through the scratchpad queue.
+
+		Performs a variety of tasks based on states:
+		  1) starts and application
+		  2) adds all instances of the specified application to the scratchpad
+		  3) (toggle) hides all visible instances
+		  4) (toggle) shows all scratchpad-hidden instances
+	"
+	local APPLICATION CLIENT_CLASS
+
+	local XFFSET=0.0
+	local YFFSET=0.0
+	local SCALE=0.8
+	[[ $(xrandr | grep primary | awk '{print $4;}' | sed 's/x.*//') -gt 3000 ]] \
+		&& SCALE=0.5
+
+	local ALWAYS_LAUNCH=0
+	local RESIZE=1
+
+	while [[ $# -gt 0 ]]
+	do
+		case $1 in 
+			-c | --client   ) CLIENT_CLASS="$2"; shift 1 ;;
+			-x | --x-offset ) XFFSET=$2; shift 1 ;;
+			-y | --y-offset ) YFFSET=$2; shift 1 ;;
+			-s | --scale    ) SCALE=$2;  shift 1 ;;
+
+			-a | --always-launch ) ALWAYS_LAUNCH=1 ;;
+			-n | --no-resize     ) RESIZE=0 ;;
+
+			-h | --help ) USAGE; exit 0 ;;
+
+			* )
+				[ ! $APPLICATION  ] && APPLICATION="$1" \
+					|| ERROR "extra positional argument '$1'"
+		esac
+		shift 1
+	done
+
+	[ ! $APPLICATION  ] && ERROR 'path-executable required'
+	[ ! $CLIENT_CLASS ] && CLIENT_CLASS=$APPLICATION
+
+	[ $APPLICATION ] && {
+		__CHECK_DEPENDENCY $APPLICATION || {
+			ERROR "$APPLICATION is not installed"
+			NOTIFY "ERROR: $APPLICATION not found"
+		}
+	}
+
+	ERROR_CHECK
+
+	local LAUNCH_APP=$ALWAYS_LAUNCH
+	STATUS "looking for window process ids"
+	xdotool search --class $CLIENT_CLASS || LAUNCH_APP=1
+
+	[[ $LAUNCH_APP -eq 1 ]] && {
+		STATUS 'launching application'
+		i3-msg "exec --no-startup-id $APPLICATION;"
+		sleep .5
+	}
+
+	STATUS 'getting target window size'
+	WINDOW_SIZE=$(\
+		xrandr \
+			| grep 'connected primary' \
+			| sed 's/.*connected primary \([^x]*\)x\([^+]*\).*/\1 \2/' \
+			| awk -v f=$SCALE -v x=$XFFSET -v y=$YFFSET \
+				'{print int($1*f+x)," ",int($2*f+y);}'\
+	)
+	INFO "window size: $WINDOW_SIZE"
+
+	STATUS 'moving window to scratchpad'
+	i3-msg "[class=$CLIENT_CLASS] move scratchpad"
+
+	[[ $RESIZE -eq 1 ]] \
+		&& STATUS 'resizing window' \
+		&& i3-msg "[class=$CLIENT_CLASS] resize set $WINDOW_SIZE"
+
+	STATUS 'pulling window from scratchpad to foreground'
+	i3-msg "[class=$CLIENT_CLASS] scratchpad show"
+
+	STATUS 'moving window to center of current screen'
+	i3-msg "[class=$CLIENT_CLASS] move position center"
+}
+
+#####################################################################
+LAUNCH_OR_SHOW $@

zsh/system/packages/build

@@ -0,0 +1,9 @@
+#!/bin/zsh
+DEPENDENCIES+=()
+REQUIRED_ENV+=()
+
+use scwrypts/meta
+
+CHECK_ENVIRONMENT
+#####################################################################
+SCWRYPTS__RUN --name system/packages/install --group scwrypts --type zsh -- --only-build $@

zsh/system/packages/download

@@ -0,0 +1,9 @@
+#!/bin/zsh
+DEPENDENCIES+=()
+REQUIRED_ENV+=()
+
+use scwrypts/meta
+
+CHECK_ENVIRONMENT
+#####################################################################
+SCWRYPTS__RUN --name system/packages/install --group scwrypts --type zsh -- --only-pull $@

zsh/system/packages/install

@@ -0,0 +1,91 @@
+#!/bin/zsh
+DEPENDENCIES+=()
+REQUIRED_ENV+=()
+
+use system/packages/git
+
+CHECK_ENVIRONMENT
+#####################################################################
+
+INSTALL() {
+	local USAGE="
+		usage: [...options...]
+
+		options
+		  -t, --target-url <string>   target URL; required for first-time download
+		  -n, --local-name <string>   local name for package (optional)
+
+		  -u, --update                if package exists, update without prompt
+		  -b, --only-build            if package exists, skip update step and only build
+		  -p, --only-pull             skip the automated build step
+		  -c, --clean                 for make, run make clean before build
+
+		  -h, --help                  print this message and exit
+	"
+	local NAME
+	local TARGET
+
+	local SKIP_BUILD=0
+	local SKIP_PULL=0
+	local UPDATE=0
+	local CLEAN=0
+
+	while [[ $# -gt 0 ]]
+	do
+		case $1 in
+			-t | --target-url ) TARGET="$2"; shift 1 ;;
+			-n | --local-name ) NAME="$2"; shift 1 ;;
+
+			-u | --update     ) UPDATE=1 ;;
+			-b | --only-build ) SKIP_PULL=1 ;;
+			-p | --only-pull  ) SKIP_BUILD=1 ;;
+			-c | --clean      ) CLEAN=1 ;;
+
+			-h | --help ) USAGE; exit 0 ;;
+
+			-* ) ERROR "unknown argument '$1'" ;;
+
+			* ) [ ! $TARGET ] && TARGET="$1" \
+					|| ERROR "extra positional argument '$1'" \
+					;
+				;;
+		esac
+		shift 1
+	done
+
+	[[ $SKIP_PULL -eq 1 ]] && [[ $SKIP_BUILD -eq 1 ]] && ERROR 'only one of [-b | -p] can be specified'
+
+	[ ! $TARGET ] && [ ! $NAME ] && {
+		[[ $SKIP_BUILD -eq 1 ]] && {
+			ERROR 'cannot skip build without specifying package local-name'
+		} || {
+			UPDATE=1
+			NAME=$(ls "$PACKAGE_INSTALL_DIR" | FZF 'select a package to update')
+			[ ! $NAME ] && ERROR 'target-url required'
+		}
+	}
+
+	ERROR_CHECK
+
+	####################################################
+
+	[ ! $NAME ] && {
+		NAME=$(echo $TARGET | sed 's/.*\///; s/\.git$//')
+		INFO "using default name '$NAME'"
+	}
+
+	[ -d "$PACKAGE_INSTALL_DIR/$NAME" ] && [[ $SKIP_PULL -eq 0 ]] && {
+		[[ $UPDATE -eq 0 ]] && Yn "package '$NAME' already exists; update now?" && UPDATE=1
+		[[ $UPDATE -eq 1 ]] && PULL || return 1
+	}
+
+	[ ! -d "$PACKAGE_INSTALL_DIR/$NAME" ] && {
+		CLONE || return 2
+	}
+
+	[[ $SKIP_BUILD -eq 1 ]] && return 0
+	BUILD
+}
+
+#####################################################################
+INSTALL $@

zsh/system/packages/update

@@ -0,0 +1,9 @@
+#!/bin/zsh
+DEPENDENCIES+=()
+REQUIRED_ENV+=()
+
+use scwrypts/meta
+
+CHECK_ENVIRONMENT
+#####################################################################
+SCWRYPTS__RUN --name system/packages/install --group scwrypts --type zsh -- --update $@

zsh/system/vim/vundle/edit-build-actions

@@ -0,0 +1,9 @@
+#!/bin/zsh
+DEPENDENCIES+=()
+REQUIRED_ENV+=()
+
+use system/vim/vundle
+
+CHECK_ENVIRONMENT
+#####################################################################
+EDIT "$VUNDLE__BUILD_DEFINITIONS"

zsh/system/vim/vundle/install

@@ -0,0 +1,16 @@
+#!/bin/zsh
+DEPENDENCIES+=()
+REQUIRED_ENV+=()
+
+use system/vim/vundle
+
+CHECK_ENVIRONMENT
+#####################################################################
+
+PLUGIN_INSTALL() {
+	VUNDLE__PLUGIN_INSTALL || return 1
+	VUNDLE__REBUILD_PLUGINS || return 2
+}
+
+#####################################################################
+PLUGIN_INSTALL $@

zsh/system/vim/vundle/rebuild

@@ -0,0 +1,9 @@
+#!/bin/zsh
+DEPENDENCIES+=()
+REQUIRED_ENV+=()
+
+use system/vim/vundle
+
+CHECK_ENVIRONMENT
+#####################################################################
+VUNDLE__REBUILD_PLUGINS $@