📖 Bump version, add to changelog

Added simple tests for database and cache locations.

Moved test PATH setup to new file-level function which should slightly
speed up testing and makes more sense conceptually to set the bemoji
executable to be in the path once for all tests.

.gitmodules

@@ -0,0 +1,9 @@
+[submodule "test/bats"]
+	path = test/bats
+	url = https://github.com/bats-core/bats-core.git
+[submodule "test/test_helper/bats-support"]
+	path = test/test_helper/bats-support
+	url = https://github.com/bats-core/bats-support.git
+[submodule "test/test_helper/bats-assert"]
+	path = test/test_helper/bats-assert
+	url = https://github.com/bats-core/bats-assert.git

CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+<!-- ### Added -->
+
+<!-- ### Changed -->
+
+<!-- ### Deprecated -->
+
+<!-- ### Removed -->
+
+<!-- ### Fixed -->
+
+<!-- ### Security -->
+
+## [0.2.0] - 2022-06-29
+
+### Added
+
+- Display of configuration options on `-v` toggle
+- AUR installation instructions
+
+### Changed
+
+- Simplified grep invocation to adhere more closely to POSIX
+
+### Fixed
+
+- Custom picker, clipper, and typer command invocation quoting

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2021 Marty Oehme
+Copyright (c) 2022 Marty Oehme
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,4 +1,4 @@
-# bemoji ❤ - Quickly ⛏ your 🌟
+# bemoji ❤️ - Quickly ⛏️ your 🌟
 
 ![bemoji picker interface on bemenu](assets/bemenu.png)
 
@@ -8,8 +8,20 @@ Will remember your favorite emojis and give you quick access.
 
 ## 📁 Installation
 
+### Dependencies
+
+* One of `bemenu`, `wofi`, `rofi`, `dmenu`, or supplying your own picker.
+* One of `wl-copy`, `xclip`, `xsel` or supplying your own clipboard tool.
+* One of `wtype`, `xdotool` or supplying your own typing tool.
+* `sed`, `grep`, `cut`, `sort`, `uniq`, `tr`, `curl` if using the download functionality.
+
+To see how to substitute the default choices with your own tools,
+see Options below.
+
 ![rofi picker interface](assets/rofi.png)
 
+### Manual
+
 Option 1. Clone the repository and put the executable somewhere in your path:
 
 ```bash
@@ -27,16 +39,13 @@ chmod +x bemoji/bemoji
 ln -s bemoji/bemoji /usr/local/bin/bemoji
 ```
 
-Dependencies:
+### Arch Linux
 
-* One of `bemenu`, `wofi`, `rofi`, `dmenu`, or supplying your own picker.
+On Arch Linux, bemoji has been packaged for the [AUR](https://aur.archlinux.org/packages/bemoji-git) so it can be installed manually from here or easily with your preferred AUR helper, e.g.:
-* One of `wl-copy`, `xclip`, `xsel` or supplying your own clipboard tool.
-* One of `wtype`, `xdotool` or supplying your own typing tool.
-* `sed`, `grep`, `cut`, `sort`, `uniq`, `tr`, `curl` if using the download functionality.
-
-To see how to substitute the default choices with your own tools, 
-see Options below.
 
+```bash
+paru -S bemoji-git
+```
 
 ## 💿 Usage
 
@@ -50,7 +59,7 @@ When the emoji list is open you can always press `Alt+1` to send the selected em
 regardless of what the default action is set to.
 (Currently works in bemenu and rofi.)
 
-You can also map the picker to a key combination for quick access, e.g. 
+You can also map the picker to a key combination for quick access, e.g.
 
 In `swaywm`, put the following in `~/.config/sway/config`:
 
@@ -88,7 +97,7 @@ bemoji comes with a couple of options to specify actions, emoji libraries and di
 ### Adding your own emoji
 
 Simply put your own emoji list into the bemoji data directory.
-By default, the directory will be at your `$XDG_DATA_HOME/bemoji` location - 
+By default, the directory will be at your `$XDG_DATA_HOME/bemoji` location -
 most likely this is `~/.local/share/bemoji`.
 
 Add any number of `.txt` files containing additional emoji to this directory:
@@ -118,7 +127,7 @@ You can also stop bemoji from adding any emoji to your history in the first plac
 bemoji -p
 ```
 
-This will not add any of the emoji you pick to your recent emojis. 
+This will not add any of the emoji you pick to your recent emojis.
 Put both together to completely ignore the recent emoji feature of the program:
 
 ```bash
@@ -128,12 +137,12 @@ bemoji -Pp
 Like this, you'll be hiding any recent personal emoji and no one will know that you always type 👄🍆💦.
 
 The recent list will also contain emoji that are *not* usually on your lists,
-so kept in single-use lists for example. 
+so kept in single-use lists for example.
 If you don't wish those to show up, make use of these options.
 
 ### Setting custom directories
 
-By default bemoji stores your recent history in `$XDG_CACHE_HOME/bemoji-history.txt`, 
+By default bemoji stores your recent history in `$XDG_CACHE_HOME/bemoji-history.txt`,
 so most often in `~/.cache/bemoji-history.txt`
 
 You can overwrite the directories bemoji uses for its emoji lists and history files with the following two environment variables:
@@ -153,8 +162,8 @@ A custom emoji list can be supplied as commandline argument `-f` or `BEMOJI_CUST
 bemoji -f path/to/my/list.txt
 ```
 
-The list will override the normally presented emoji, 
+The list will override the normally presented emoji,
-so that only the custom list and recent emoji will be displayed. 
+so that only the custom list and recent emoji will be displayed.
 To display *only* the emoji list passed in, pass an extra `-P` flag to bemoji.
 
 The path can also be a weblink which bemoji will download and use:
@@ -173,10 +182,10 @@ To change this setting, execute bemoji like the following:
 bemoji -D all
 ```
 
-This will download *all* default sets bemoji knows - which is currently the default emoji list and a long list of math symbols. 
+This will download *all* default sets bemoji knows - which is currently the default emoji list and a long list of math symbols.
 Other valid options for this setting are `emoji`, `math`, `none`.
 
-If set to `none` and no files are in the emoji directory, 
+If set to `none` and no files are in the emoji directory,
 bemoji will simply complain and not show anything.
 
 ### Using a custom tool for picking, clipping, typing
@@ -204,12 +213,12 @@ bemoji -e | cat <(echo -n "https://emojipedia.org/") - | xargs xdg-open
 
 This snippet will open a wiki page for the picked emoji in your browser.
 
-Of course, there are many more possibilities. 
+Of course, there are many more possibilities.
 This is just an example to show how the echo mode works.
 
 ### A list of all environment variables
 
-What follows is a list of all environment variables bemoji understands, 
+What follows is a list of all environment variables bemoji understands,
 with their default settings
 
 ```bash
@@ -232,3 +241,12 @@ Thanks for checking this program out! ❤
 If there are any problems, don't hesitate to open an issue.
 
 If you have an idea or improvement, don't hesitate to open a merge request!
+
+### Running tests
+
+This project makes use of [bash-bats](https://github.com/bats-core/bats-core) (community fork) to test some of its functionality.
+
+To run the tests locally, simply execute `./test/bats/bin/bats test`.
+
+I would suggest running the test suite in docker instead, just to minimize the possibility of something going awry and borking up your local file system.
+To run the tests in a docker suite, execute `docker run --rm -it -v "$PWD:/code" bats/bats:latest /code/test`

bemoji

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 
-bm_version=0.1
+bm_version=0.2.0
 # Emoji default database location
 bm_db_location=${BEMOJI_DB_LOCATION:-"${XDG_DATA_HOME:-$HOME/.local/share}/bemoji"}
 # Setting custom emoji list file location:
@@ -33,12 +33,14 @@ usage() {
     echo "   -e             Only echo out the picked emoji."
     echo "   -D <choice>    Choose specific default lists to download if none found locally."
     echo "                  Valid choices: all|none|emoji|math."
+    echo "   -v             Display current program version and directory configuration."
+    echo "   -h             Show this help."
     echo
     exit "$1"
 }
 
 version() {
-    echo "v${bm_version}"
+    printf "v%s\ndatabase=%s\nhistory=%s\n" "$bm_version" "$bm_db_location" "$bm_history_file"
     exit
 }
 
@@ -135,7 +137,8 @@ add_to_recent() {
 # Set default clipboard util
 _clipper() {
     if [ -n "$BEMOJI_CLIP_CMD" ]; then
-        "${BEMOJI_CLIP_CMD[@]}"
+        # shellcheck disable=SC2068
+        ${BEMOJI_CLIP_CMD[@]}
     elif [ -n "$WAYLAND_DISPLAY" ] && command -v wl-copy >/dev/null 2>&1; then
         wl-copy
     elif [ -n "$DISPLAY" ] && command -v xclip >/dev/null 2>&1; then
@@ -152,7 +155,8 @@ _clipper() {
 _typer() {
     totype=$(cat -)
     if [ -n "$BEMOJI_TYPE_CMD" ]; then
-        "${BEMOJI_TYPE_CMD[@]}"
+        # shellcheck disable=SC2068
+        ${BEMOJI_TYPE_CMD[@]}
     elif [ -n "$WAYLAND_DISPLAY" ] && command -v wtype >/dev/null 2>&1; then
         wtype -s 30 "$totype"
     elif [ -n "$DISPLAY" ] && command -v xdotool >/dev/null 2>&1; then
@@ -166,7 +170,8 @@ _typer() {
 # Set default picker util
 _picker() {
     if [ -n "$BEMOJI_PICKER_CMD" ]; then
-        "${BEMOJI_PICKER_CMD[@]}"
+        # shellcheck disable=SC2068
+        ${BEMOJI_PICKER_CMD[@]}
     elif command -v bemenu >/dev/null 2>&1; then
         bemenu -p 🔍 -i -l 20
     elif command -v wofi >/dev/null 2>&1; then
@@ -194,7 +199,7 @@ _clipResult() {
 result=$(gather_emojis | _picker)
 exit_value="$?"
 [ "$bm_private_mode" = true ] || add_to_recent "$result"
-result=$(echo "$result" | grep -oP '^[^\s]+' | tr -d '\n')
+result=$(echo "$result" | grep -o '^\S\+' | tr -d '\n')
 
 case "$exit_value" in
 1)

test/bats

@@ -0,0 +1 @@
+Subproject commit 26c9b18983c3ce4cf24c6f6ee942abd8b1c3ee18

test/bemoji.bats

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+
+setup_file() {
+    # make bemoji executable from anywhere relative to current testfile
+    TEST_DIR="$( cd "$( dirname "$BATS_TEST_FILENAME" )" >/dev/null 2>&1 && pwd )"
+    PATH="$TEST_DIR/..:$PATH"
+}
+
+setup() {
+    load 'test_helper/bats-support/load'
+    load 'test_helper/bats-assert/load'
+
+    # mock out interactive picker for static emoji return
+    export BEMOJI_PICKER_CMD="echo ❤️"
+
+    # set up small default set of test emoji for each test
+    export BEMOJI_DB_LOCATION="$BATS_TEST_TMPDIR/database"
+    export BEMOJI_CACHE_LOCATION="$BATS_TEST_TMPDIR/cache"
+    mkdir -p "$BEMOJI_DB_LOCATION" "$BEMOJI_CACHE_LOCATION"
+    cat "$BATS_TEST_DIRNAME/resources/test_emoji.txt" > "$BEMOJI_DB_LOCATION/emoji.txt"
+}
+
+@test "can run script" {
+    export BEMOJI_CLIP_CMD="echo clip test only"
+    # closing FD3 manually to prevent hangs, see
+    # https://bats-core.readthedocs.io/en/stable/writing-tests.html#file-descriptor-3-read-this-if-bats-hangs
+    run bemoji 3>&-
+    assert_success
+}
+
+@test "can receive custom picker mock output" {
+    run bemoji -e 3>&-
+    assert_output "❤️"
+}
+
+@test "-v prints correct version number" {
+    the_version=$(grep 'bm_version=' $(which bemoji))
+
+    run bemoji -v
+    assert_output --partial "v${the_version#bm_version=}"
+}
+
+@test "sets XDG directory for db by default" {
+    unset BEMOJI_DB_LOCATION
+    export XDG_DATA_HOME="$BATS_TEST_TMPDIR/xdb-db"
+    run bemoji -v
+    assert_output --regexp "
+database=$BATS_TEST_TMPDIR/xdb-db/bemoji
+"
+}
+
+@test "sets XDG directory for history by default" {
+    unset BEMOJI_CACHE_LOCATION
+    export XDG_CACHE_HOME="$BATS_TEST_TMPDIR/xdb-cache"
+    run bemoji -v
+    assert_output --regexp "
+history=$BATS_TEST_TMPDIR/xdb-cache/bemoji-history.txt$"
+}
+
+@test "falls back to default db directory if no XDG found" {
+    unset BEMOJI_DB_LOCATION
+    run bemoji -v
+    assert_output --regexp "
+database=$HOME/.local/share/bemoji
+"
+}
+
+@test "falls back to default history location if no XDG found" {
+    unset BEMOJI_CACHE_LOCATION
+    run bemoji -v
+    assert_output --regexp "
+history=$HOME/.cache/bemoji-history.txt$"
+}
+
+@test "BEMOJI_DB_LOCATION sets correct db directory" {
+    run bemoji -v
+    assert_output --regexp "
+database=$BATS_TEST_TMPDIR/database
+"
+}
+
+@test "BEMOJI_CACHE_LOCATION sets correct cache directory" {
+    run bemoji -v
+    assert_output --regexp "
+history=$BATS_TEST_TMPDIR/cache/bemoji-history.txt$"
+}

test/resources/test_emoji.txt

@@ -0,0 +1,4 @@
+❤️ red heart
+😀 grinning face
+😃 grinning face with big eyes
+😄 grinning face with smiling eyes

test/test_helper/bats-assert

@@ -0,0 +1 @@
+Subproject commit ffe84ea5dd43b568851549b3e241db150c12929c

test/test_helper/bats-support

@@ -0,0 +1 @@
+Subproject commit 3c8fadc5097c9acfc96d836dced2bb598e48b009