Prepare release

CHANGELOG.md

@@ -10,6 +10,18 @@ adheres to [Semantic Versioning][semver].
 
 ## [Unreleased]
 
+## [v1.0.8] - 2021-12-01
+
+- Add a `checklist` builder.
+- Add the `from-stdin` builder (and a `--stdin` CLI option).
+- Refactor some argument parsing.
+- Fix issues with some builders not supplying alertnate text content.
+- Rename the `draw-progress-bar` and `draw-progress-clock` methods to
+  just `progress-bar` and `progress-clock`.
+- Add a tagging system to make it easier to find useful commands for
+  things like `--stdin` by running `inform-slack --list-functions`.
+- Add a `--version` option.
+
 ## [v1.0.7] - 2021-10-26
 
 - Make progress max default to `0` and only render a progress bar if
@@ -48,7 +60,8 @@ adheres to [Semantic Versioning][semver].
 
 - First actual release.
 
-[Unreleased]: https://github.com/jasonk/inform-slack/compare/v1.0.7...HEAD
+[Unreleased]: https://github.com/jasonk/inform-slack/compare/v1.0.8...HEAD
+[v1.0.8]: https://github.com/jasonk/inform-slack/releases/tag/v1.0.8
 [v1.0.7]: https://github.com/jasonk/inform-slack/releases/tag/v1.0.7
 [v1.0.6]: https://github.com/jasonk/inform-slack/releases/tag/v1.0.6
 [v1.0.5]: https://github.com/jasonk/inform-slack/releases/tag/v1.0.5

bin/inform-slack

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # https://github.com/jasonk/inform-slack
 
-export INFORM_SLACK_VERSION="v1.0.7"
+export INFORM_SLACK_VERSION="v1.0.8"
 
 export INFORM_SLACK_SELF="$(realpath -P "${BASH_SOURCE[0]}")"
 export INFORM_SLACK_DIR="$(cd -P "$(dirname "$INFORM_SLACK_SELF")/.." && pwd)"

builders/checklist

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# https://github.com/jasonk/inform-slack
+
+source inform-slack
+
+txt="${INFORM_SLACK_CHECKLIST_TEXT:-}"
+dir="$INFORM_SLACK_CHECKLIST_DIR"
+title="${INFORM_SLACK_CHECKLIST_TITLE:-}"
+todo_icon=":white_medium_square:"
+done_icon=":heavy_check_mark:"
+fail_icon=":no_entry_sign:"
+
+while (( $# )); do
+  case "$1" in
+    --text)                 txt="$2"            ; shift 2 ;;
+    --text=*)               txt="${1#*=}"       ; shift 1 ;;
+    -T|--title)             title="$2"          ; shift 2 ;;
+    --title=*)              title="${1#*=}"     ; shift 1 ;;
+    -d|--directory|--dir)   dir="$2"            ; shift 2 ;;
+    --directory=*|--dir=*)  dir="${1#*=}"       ; shift 1 ;;
+    --todo-icon)            todo_icon="$2"      ; shift 2 ;;
+    --todo-icon=*)          todo_icon="${1#*=}" ; shift 1 ;;
+    --done-icon)            done_icon="$2"      ; shift 2 ;;
+    --done-icon=*)          done_icon="${1#*=}" ; shift 1 ;;
+    --fail-icon)            fail_icon="$2"      ; shift 2 ;;
+    --fail-icon=*)          fail_icon="${1#*=}" ; shift 1 ;;
+    *) usage "Unknown option '$1'" ;;
+  esac
+done
+
+cd "$dir"
+
+if [ -n "$txt" ]; then
+  text "$txt"
+elif [ -n "$title" ]; then
+  text "$title"
+fi
+
+if [ -n "$title" ]; then block-header "$title"; fi
+
+tasks=()
+
+for I in *.task; do
+  name="${I%.task}"
+  task="$(<"$I")"
+  if [ -f "${name}.done" ]; then
+    task="$done_icon $task"
+  elif [ -f "${name}.fail" ]; then
+    task="$fail_icon $task"
+  else
+    task="$todo_icon $task"
+  fi
+  tasks+=( "$task" )
+done
+
+block-mrkdwn "$(printf '%s\n' "${tasks[@]}")"

builders/checklist.md

@@ -0,0 +1,55 @@
+# checklist #
+
+This builder allows you to easily create a checklist-style updating
+message for a multi-step process.
+
+## Usage ##
+
+The most common way to use this is to just set the appropriate
+environment variables and then run `inform-slack --update`.  The
+status directory you provide will be scanned looking for files with
+the extension `.task`.  You should create a file for each item you
+want to appear in the checklist, and it's content should be a single
+line of text with the label you want to appear in the checklist.  The
+files will be sorted by their filenames, so you should use names that
+result in the order you want.
+
+For each `<name>.task` file found, it will also check for files named
+`<name>.done` or `<name>.fail`.  If these are found the status of the
+checklist item will be updated appropriately.
+
+```sh
+mkdir -p ./checklist
+cd ./checklist
+
+echo "Step 1: Create cool Slack notifier checklist" > step1.task
+echo "Step 2: ???" > step2.task
+echo "Step 3: Profit!" > step3.task
+export INFORM_SLACK_CHECKLIST_DIR="$(pwd)"
+export INFORM_SLACK_BUILDER=checklist
+inform-slack --update
+touch "$INFORM_SLACK_CHECKLIST_DIR/step1.done"
+touch "$INFORM_SLACK_CHECKLIST_DIR/step1.fail"
+inform-slack --update
+```
+
+## Environment Variables ##
+
+ * `INFORM_SLACK_CHECKLIST_DIR` - The directory to use to store the
+   status files.
+ * `INFORM_SLACK_CHECKLIST_TITLE` - A header message to include above
+   the checklist.  If this is not set but `INFORM_SLACK_TITLE` is then
+   that will get used.
+ * `INFORM_SLACK_CHECKLIST_TEXT` - If set will be used to provide the
+   alternate text content for the message.  If not used, the text will
+   be the same as the title.
+
+## Options ##
+
+ * `--text <text>` - Specify the alternate text content for the message.
+ * `--title <title>` - Specify a title for the checklist message.
+ * `--directory <dir>` or `--dir <dir>` or `-d <dir>` - Specify the
+   status directory.
+ * `--todo-icon <name>` - Specify the icon to use for `todo` items.
+ * `--done-icon <name>` - Specify the icon to use for `done` items.
+ * `--fail-icon <name>` - Specify the icon to use for `fail` items.

builders/from-stdin

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+# https://github.com/jasonk/inform-slack
+
+source inform-slack
+
+eval "$(
+  for BUILDER in $(list-builders); do
+    echo "${BUILDER}() { run-builder $BUILDER \"\$@\"; }"
+  done
+)"
+eval "$(cat)"

builders/from-stdin.md

@@ -0,0 +1,53 @@
+# from-stdin #
+
+This builder is different than most, rather than formatting a message,
+it allows you to construct multiple messsages by providing
+commands on stdin.
+
+You can use this to make very complex collections of messages without
+having to write a custom builder.
+
+## Usage ##
+
+To use it, just call `inform-slack --stdin` and then provide a series
+of commands on standard input.  The input you provide will be
+evaluated as a script and run with all of the internal `inform-slack`
+functions available, as well as functions that mirror all of the
+available builder names.  This means you can basically use builders as
+commands.
+
+## Examples ##
+
+```sh
+inform-slack --dry-run --stdin <<'END'
+message 'foo bar baz'
+command-output echo hello world
+block-context thing1 thing2 thing3
+END
+```
+
+## Functions ##
+
+Some internal functions are tagged to indicate that they could be
+useful in a context like this.  You can get a list of all of these
+tagged functions by running `inform-slack --list-functions`.
+
+Here are the ones that are currently defined:
+
+* `block-context`
+* `block-header`
+* `block-image`
+* `block-list`
+* `block-divider`
+* `block-file`
+* `block-progress`
+* `block-section`
+* `block-fields`
+* `block-mrkdwn`
+* `section-fields`
+* `element-image`
+* `text-mrkdwn`
+* `text-plain`
+* `progress-bar`
+* `progress-clock`
+* `text`

builders/message

@@ -3,9 +3,22 @@
 
 source inform-slack
 
+did_text=false
+do-text() {
+  if $did_text; then return; fi
+  if [ -n "${1:-}" ]; then
+    text "$1"
+    did_text=true
+  fi
+}
+
 if (( $# )); then
-  for I in "$@"; do block-mrkdwn "$I"; done
+  for I in "$@"; do
+    do-text "$I"
+    block-mrkdwn "$I"
+  done
 fi
 if [ -n "${INFORM_SLACK_MESSAGE:-}" ]; then
+  do-text "$INFORM_SLACK_MESSAGE";
   block-mrkdwn "$INFORM_SLACK_MESSAGE";
 fi

builders/tests-summary

@@ -12,6 +12,8 @@ errored=""
 skipped=""
 warned=""
 
+txt=""
+
 order="tests pass fail error warn skip"
 
 test_label="Tests: "
@@ -32,6 +34,8 @@ while (( $# )); do
   case "$1" in
     --order)             order="$2"            ; shift 2 ;;
     --order=*)           order="${1#*=}"       ; shift 1 ;;
+    --text)              text="$2"             ; shift 2 ;;
+    --text=*)            text="${1#*=}"        ; shift 1 ;;
     -T|--title)          title="$2"            ; shift 2 ;;
     --title=*)           title="${1#*=}"       ; shift 1 ;;
     -i|--icon)           icon="$2"             ; shift 2 ;;
@@ -97,4 +101,5 @@ for I in $order; do
   if [ -n "$value" ]; then fields+=( "$value" ); fi
 done
 
+if [ -n "$txt" ]; then text "$txt"; fi
 block-section "$title" "$(section-fields "${fields[@]}")"

builders/thread-progress

@@ -30,7 +30,7 @@ done
 text "${txt:-$title${status:+ - $status}}"
 
 if [ -n "$clock" ]; then
-  block-header "$(draw-progress-clock) $title"
+  block-header "$(progress-clock) $title"
 else
   block-header "$title"
   block-progress "$pos" "$max"