📖 Add example for setting manual picker to README

Bumping the year again. I am honestly not entirely sure what the best or
correct way to display this is - so I am simply copying what the `curl`
project is doing and stating the whole period of me working on it.

Perhaps one day (should we get more contributors or much more popular)
it may also make sense to copy its `THANKS` file to keep a stable copy
of my contributing helpers.

.gitmodules

@@ -7,3 +7,6 @@
 [submodule "test/test_helper/bats-assert"]
 	path = test/test_helper/bats-assert
 	url = https://github.com/bats-core/bats-assert.git
+[submodule "test/test_helper/mocks"]
+	path = test/test_helper/mocks
+	url = https://github.com/jasonkarns/bats-mock.git

.woodpecker.yml

@@ -1,5 +1,80 @@
-pipeline:
+steps:
   test:
     image: bats/bats
     commands:
       - /opt/bats/bin/bats test
+
+  release-prep:
+    # prepare changelog and version information for release candidate
+    when:
+      event: tag
+      ref: refs/tags/v*
+    image: alpine
+    commands:
+      - sed -ne 's/bm_version=\(.*\)/\1/p' bemoji > NEWEST_VERSION.txt
+      - awk '/^## \[\d/{p++} p==2{print; exit} p>=1' CHANGELOG.md | head -n -1 | tail -n+3 > NEWEST_CHANGES.txt
+
+  versioncompare:
+    # ensure we correctly bumped versions
+    when:
+      event: tag
+      ref: refs/tags/v*
+    image: alpine
+    secrets: [ github_release_token, github_repo ]
+    commands:
+      - apk add jq curl
+      - "lastversion=$(curl -X GET -H \"Accept: application/vnd.github.v3+json\" -H \"Authorization: Bearer $GITHUB_RELEASE_TOKEN\" https://api.github.com/repos/$GITHUB_REPO/releases/latest | jq -r '.name')"
+      - "programversion=$(cat NEWEST_VERSION.txt)"
+      - changelogversion=$(sed -ne 's/^## \[\([0-9].*\)\].*$/\1/p' CHANGELOG.md | head -n1)
+      - echo "Last version - $lastversion"
+      - echo "New version - $programversion"
+      - echo "Changelog version - $changelogversion"
+      - "if [ \"$changelogversion\" != \"$programversion\" ]; then { echo \"VERSION MISMATCH: Changelog - $changelogversion, Program - $programversion\" && exit 1; }; fi"
+      - "if [ \"$lastversion\" = \"$programversion\" ]; then { echo \"RELEASE DUPLICATE: Last release already had version - $programversion\" && exit 1; }; fi"
+
+  build:
+    when:
+      event: tag
+      ref: refs/tags/v*
+    image: savant/md2man
+    commands:
+      - apk update && apk add zip
+      - BM_VERSION=$(cat NEWEST_VERSION.txt)
+      - mkdir -p build/doc dist
+      - cp bemoji build
+      - md2man -in README.md -out bemoji.1 && gzip bemoji.1
+      - cp LICENSE README.md bemoji.1.gz build/doc
+      - cd build || exit 1
+      - tar -czvf bemoji-$BM_VERSION.tar.gz *
+      - zip -r bemoji-$BM_VERSION.zip *
+      - mv bemoji-$BM_VERSION.tar.gz bemoji-$BM_VERSION.zip ../dist
+
+  release-gitea:
+    when:
+      event: tag
+      ref: refs/tags/v*
+    image: plugins/gitea-release
+    settings:
+      api_key:
+        from_secret: gitea_release_token
+      base_url: https://git.martyoeh.me
+      files: dist/*
+      title: NEWEST_VERSION.txt
+      note: NEWEST_CHANGES.txt
+
+  release-github:
+    when:
+      event: tag
+      ref: refs/tags/v*
+    image: alpine
+    secrets: [ github_release_token, github_repo ]
+    commands:
+      - apk add file jq curl
+      - BM_VERSION=$(cat NEWEST_VERSION.txt)
+      - BM_CHANGED=$(sed -e 's|#||g' -e 's|^.*$|\0 <br />|' NEWEST_CHANGES.txt) # display newlines workaround
+      - echo "{\"tag_name\":\"v${BM_VERSION}\",\"target_commitish\":\"main\",\"name\":\"v${BM_VERSION}\",\"body\":\"$BM_CHANGED\",\"draft\":false,\"prerelease\":false,\"generate_release_notes\":false}" > data.json
+      - "response=$(curl -X POST -H \"Accept:\\ application/vnd.github+json\" -H \"Authorization:\\ Bearer $GITHUB_RELEASE_TOKEN\" https://api.github.com/repos/$GITHUB_REPO/releases -d \"@data.json\")"
+      - "uploadurl=$(echo $response | jq -r '.upload_url' | cut -d'{' -f1)"
+      - "[ $uploadurl = null ] && { echo $response; exit 1; }"
+      - "curl -X POST -H \"Accept:\\ application/vnd.github.v3+json\" -H \"Authorization:\\ Bearer $GITHUB_RELEASE_TOKEN\" -H \"Content-Type:\\ $(file -b --mime-type dist/bemoji-$BM_VERSION.zip)\" -H \"Content-Length:\\ $(wc -c <dist/bemoji-$BM_VERSION.zip | xargs)\" -T dist/bemoji-$BM_VERSION.zip \"$uploadurl?name=bemoji-$BM_VERSION.zip\""
+      - "curl -X POST -H \"Accept:\\ application/vnd.github.v3+json\" -H \"Authorization:\\ Bearer $GITHUB_RELEASE_TOKEN\" -H \"Content-Type:\\ $(file -b --mime-type dist/bemoji-$BM_VERSION.tar.gz)\" -H \"Content-Length:\\ $(wc -c <dist/bemoji-$BM_VERSION.tar.gz | xargs)\" -T dist/bemoji-$BM_VERSION.tar.gz \"$uploadurl?name=bemoji-$BM_VERSION.tar.gz\""

CHANGELOG.md

@@ -7,6 +7,51 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+<!-- ### Added -->
+
+<!-- ### Changed -->
+
+<!-- ### Deprecated -->
+
+<!-- ### Removed -->
+
+<!-- ### Fixed -->
+
+<!-- ### Security -->
+
+## [0.4.0] - 2024-02-22
+
+### Added
+
+- Add default support for `fuzzel` wayland-native picker tool
+- Add default support for `ilia` gtk-based picker tool, used by default in Regolith Linux
+- Pass through return code 1 from selection tool
+- (!) Number of displayed recent emoji can be set with `-P` option:
+  This replaces previous `-P` history flag toggle. Use number to set amount of recent
+  entries to display, `-P3`. To completely hide history use `-P0`.
+- Add nerdfont emoji set download with `-D nerd`
+- Add parsing for long-form options (`--private` instead of `-p` and so on):
+  Options requiring a value can be given both in space-separated (`--hist-limit 2`)
+  and equals-separated (`--hist-limit=2`) versions. POSIX option concatenation still
+  works (`-ne` to echo without newline).
+
+### Changed
+
+- (!) History uses `XDG_STATE_HOME` directory by default:
+  This constitutes a break in behavior if you relied a lot on your pick history in the default
+  location. To retain your old history file, simply move it from the old cache directory
+  (`~/.cache/bemoji-history.txt` by default) to the new one (`~/.local/state/bemoji-history.txt`
+  by default).
+- (!) `XDG_CACHE_LOCATION` renamed to `XDG_HISTORY_LOCATION` to better signify its purpose
+
+### Fixed
+
+- Always download from newest emoji list url
+- Pass selection to custom typing tools through stdin
+- Pass info messages to stderr to avoid passing to picker tools
+
+## [0.3.0] - 2022-11-10
+
 ### Added
 
 - Add new option `-n` which suppresses printing the final newline character in output
@@ -14,18 +59,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 
 - Multiple command options can be combined
-
+- Allow downloading emoji sets at any time after initial run with `-D <choice>`
-<!-- ### Deprecated -->
-
-<!-- ### Removed -->
 
 ### Fixed
 
 - Custom default command is only executed when no command option given
 - Results are matched case insensitively when using rofi picker to match other pickers
 
-<!-- ### Security -->
-
 ## [0.2.0] - 2022-06-29
 
 ### Added

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022 Marty Oehme
+Copyright (c) 2021 - 2024 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

@@ -12,7 +12,7 @@ Will remember your favorite emojis and give you quick access.
 
 ### Dependencies
 
-* One of `bemenu`, `wofi`, `rofi`, `dmenu`, or supplying your own picker.
+* One of `bemenu`, `wofi`, `rofi`, `dmenu`, `ilia`, `fuzzel` 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.
@@ -43,10 +43,10 @@ ln -s bemoji/bemoji /usr/local/bin/bemoji
 
 ### Arch Linux
 
-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.:
+On Arch Linux, bemoji has been packaged for the [AUR](https://aur.archlinux.org/packages?K=bemoji) so it can be installed manually from here or easily with your preferred AUR helper, e.g.:
 
 ```bash
-paru -S bemoji-git
+paru -S bemoji # or bemoji-git
 ```
 
 ## 💿 Usage
@@ -78,7 +78,7 @@ bindsym Mod4+Shift+e exec bemoji -t
 For `riverwm`, put the following in `~/.config/river/init`:
 
 ```
-riverctl map normal $mod+Shift E spawn "bemoji -t"
+riverctl map normal Mod4+Shift E spawn "bemoji -t"
 ```
 
 In `sxhkd`, put the following into `~/.config/sxhkd/sxhkdrc`:
@@ -118,40 +118,51 @@ By default, bemoji will sort the list it displays by your most frequently and mo
 To disable this behavior, execute bemoji like the following:
 
 ```bash
-bemoji -P
+bemoji --hist-limit 0
 ```
 
-This will stop bemoji from re-ordering your emoji lists before displaying them.
+This will stop bemoji from adding recently used emoji before displaying the list.
 
 You can also stop bemoji from adding any emoji to your history in the first place:
 
 ```bash
-bemoji -p
+bemoji --private
 ```
 
 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:
+Put both together to completely ignore the recent emoji feature of the program
+(these are the equivalent short versions of the options above):
 
 ```bash
-bemoji -Pp
+bemoji -p -P0
 ```
 
 Like this, you'll be hiding any recent personal emoji and no one will know that you always type 👄🍆💦.
 
+To limit the number of your recently used emoji that are shown without hiding them completely simply increase the number to however many you wish to display. 
+For example, to display only the top 4 recently used emoji:
+
+```bash
+bemoji --hist-limit 4
+```
+
 The recent list will also contain emoji that are *not* usually on your lists,
 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
+### Setting custom directories and editing history
 
-By default bemoji stores your recent history in `$XDG_CACHE_HOME/bemoji-history.txt`,
+By default bemoji stores your recent history in `$XDG_STATE_HOME/bemoji-history.txt`,
-so most often in `~/.cache/bemoji-history.txt`
+so most often in `~/.local/state/bemoji-history.txt`
+
+You can edit this file in any text editor to change your recent history,
+removing, adding or changing the emoji appearing there.
 
 You can overwrite the directories bemoji uses for its emoji lists and history files with the following two environment variables:
 
 ```
 BEMOJI_DB_LOCATION=/path/to/my/emoji/directory
-BEMOJI_CACHE_LOCATION=/path/to/my/cache/directory
+BEMOJI_HISTORY_LOCATION=/path/to/my/state/directory
 ```
 
 There are no equivalent commandline arguments to overwrite these two settings.
@@ -161,7 +172,7 @@ There are no equivalent commandline arguments to overwrite these two settings.
 A custom emoji list can be supplied as commandline argument `-f` or `BEMOJI_CUSTOM_LIST` environment variable.
 
 ```bash
-bemoji -f path/to/my/list.txt
+bemoji --file path/to/my/list.txt
 ```
 
 The list will override the normally presented emoji,
@@ -174,21 +185,27 @@ The path can also be a weblink which bemoji will download and use:
 bemoji -f "https://raw.githubusercontent.com/jchook/emoji-menu/master/data/emojis.txt"
 ```
 
-### Change the default emoji set
+### Download additional emoji sets
 
-bemoji downloads emoji for you to use on first invocation.
+bemoji automatically downloads an emoji list for you to use on first invocation.
-By default, it only downloads emoji, though you can have it download math symbols as well.
+By default, it only downloads emoji, though you can have it download math symbols and nerdfont icons as well.
-To change this setting, execute bemoji like the following:
+To download additional sets, execute bemoji like the following:
 
 ```bash
-bemoji -D all
+bemoji --download 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, nerd font icons, and a long list of math symbols.
-Other valid options for this setting are `emoji`, `math`, `none`.
+Other valid options for this setting are `emoji`, `math`, `nerd`, `none`.
+
+```bash
+bemoji -D "math emoji nerd"
+```
+
+The above command is equivalent to the previous `all` as you can mention multiple sets you want downloaded.
 
 If set to `none` and no files are in the emoji directory,
-bemoji will simply complain and not show anything.
+bemoji will complain and not show anything.
 
 ### Do not skip to new line after output
 
@@ -216,7 +233,15 @@ BEMOJI_CLIP_CMD="path/to/your/clipboard/tool"
 BEMOJI_TYPE_CMD="path/to/your/xdotool"
 ```
 
-This is pretty experimental and you'll have to see how well it works for you.
+The candidate list (in the case of picker tool) or the picked selection are passed to the tools through stdin.
+
+For example, to manually invoke fuzzel with no extra options as the picker for bemoji you would use:
+
+```bash
+BEMOJI_PICKER_CMD="fuzzel -d" bemoji
+```
+
+This is somewhat experimental still and you'll have to see how well it works for you.
 The setting can not be changed through the commandline alone.
 
 ### Execute a custom command with my emoji
@@ -226,7 +251,7 @@ You can execute bemoji with the `-e` flag with which you tell it not to do anyth
 This can be very useful for creating your own little script with it:
 
 ```bash
-bemoji -e | cat <(echo -n "https://emojipedia.org/") - | xargs xdg-open
+bemoji --echo | cat <(echo -n "https://emojipedia.org/") - | xargs xdg-open
 ```
 
 This snippet will open a wiki page for the picked emoji in your browser.
@@ -240,16 +265,16 @@ What follows is a list of all environment variables bemoji understands,
 with their default settings
 
 ```bash
-BEMOJI_DB_LOCATION=$XDG_DATA_HOME/bemoji # where the emoji lists reside
+BEMOJI_DB_LOCATION="$XDG_DATA_HOME/bemoji" # where the emoji lists reside
-BEMOJI_CACHE_LOCATION=$XDG_CACHE_HOME # where the cache file resides
+BEMOJI_HISTORY_LOCATION="$XDG_STATE_HOME" # where the state file resides
 BEMOJI_CUSTOM_LIST="" # the custom emoji list to display
 BEMOJI_DOWNLOAD_LIST="" # the default emoji lists to download to database
-BEMOJI_DEFAULT_COMMAND=<clip-tool> # which command to invoke by default
+BEMOJI_DEFAULT_COMMAND="" # which command to invoke by default
-BEMOJI_PICKER_CMD=bemenu # which picker tool to use
+BEMOJI_PICKER_CMD="bemenu" # which picker tool to use
-BEMOJI_CLIP_CMD=wl-copy # which clipboard tool to use
+BEMOJI_CLIP_CMD="wl-copy" # which clipboard tool to use
-BEMOJI_TYPE_CMD=wtype # which typing tool to use (ydotool will NOT work)
+BEMOJI_TYPE_CMD="wtype" # which typing tool to use (ydotool will NOT work)
 BEMOJI_PRIVATE_MODE=false # whether to save new entries
-BEMOJI_IGNORE_RECENT=false # whether to display recent entries
+BEMOJI_LIMIT_RECENT="" # whether to display recent entries
 BEMOJI_ECHO_NEWLINE=true # whether to end the output with a newline character
 ```
 
@@ -265,7 +290,12 @@ If you have an idea or improvement, don't hesitate to open a merge request!
 
 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`.
+To run the tests locally:
+```
+git submodule init
+git submodule update
+./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`
+To run the tests in a docker suite, execute `docker run --rm -it -v "$PWD:/code" bats/bats:latest /code/test` after initializing the git submodules as listed above.

bemoji

@@ -1,14 +1,14 @@
 #!/usr/bin/env bash
 
-bm_version=0.2.0
+bm_version=0.4.0
 # Emoji default database location
 bm_db_location=${BEMOJI_DB_LOCATION:-"${XDG_DATA_HOME:-$HOME/.local/share}/bemoji"}
 # Setting custom emoji list file location:
 # BEMOJI_CUSTOM_LIST=/my/location/emojis.txt
-# Setting custom recent emoji cache:
+# Setting custom recent emoji history:
-# BEMOJI_CACHE_LOCATION=/path/to/my/recents/directory
+# BEMOJI_HISTORY_LOCATION=/path/to/my/recents/directory
-bm_cache_dir="${BEMOJI_CACHE_LOCATION:-${XDG_CACHE_HOME:-$HOME/.cache}}"
+bm_state_dir="${BEMOJI_HISTORY_LOCATION:-${XDG_STATE_HOME:-$HOME/.local/state}}"
-bm_history_file="${bm_cache_dir}/bemoji-history.txt"
+bm_history_file="${bm_state_dir}/bemoji-history.txt"
 
 # Command to run after user chooses an emoji
 bm_default_cmd="$BEMOJI_DEFAULT_CMD"
@@ -18,7 +18,16 @@ bm_echo_newline=${BEMOJI_ECHO_NEWLINE:-true}
 # Do not save choices
 bm_private_mode=${BEMOJI_PRIVATE_MODE:-false}
 # Do not sort results
-bm_ignore_recent=${BEMOJI_IGNORE_RECENT:-false}
+bm_limit_recent="$BEMOJI_LIMIT_RECENT"
+
+declare -A default_pickers=(
+	["bemenu"]="bemenu -p 🔍 -i -l 20"
+	["wofi"]="wofi -p 🔍 -i --show dmenu"
+	["rofi"]="rofi -p 🔍 -i -dmenu --kb-custom-1 "Alt+1" --kb-custom-2 "Alt+2""
+	["dmenu"]="dmenu -p 🔍 -i -l 20"
+	["ilia"]="ilia -n -p textlist -l 'Emoji' -i desktop-magnifier"
+	["fuzzel"]="fuzzel -d -p 🔍"
+)
 
 # Report usage
 usage() {
@@ -28,19 +37,19 @@ usage() {
 	echo "Invoked without arguments sends the picked emoji to the clipboard."
 	echo
 	echo " Command options (can be combined):"
-    echo "   -t             Simulate typing the emoji choice with the keyboard."
+	echo "  -t, --type                 Simulate typing the emoji choice with the keyboard."
-    echo "   -c             Send emoji choice to the clipboard. (default)"
+	echo "  -c, --clip                 Send emoji choice to the clipboard. (default)"
-    echo "   -e             Only echo out the picked emoji."
+	echo "  -e, --echo                 Only echo out the picked emoji."
 	echo ""
 	echo " Other options:"
-    echo "   -n             Do not print a newline after the picked emoji."
+	echo "  -n, --noline               Do not print a newline after the picked emoji."
-    echo "   -p             Do not save picked emoji to recent history."
+	echo "  -p, --private              Do not save picked emoji to recent history."
-    echo "   -P             Do not order emoji by recently used."
+	echo "  -P, --hist-limit <number>  Limit number of recent emoji to display."
-    echo "   -D <choice>    Choose specific default lists to download if none found locally."
+	echo "  -D, --download <choice>    Choose from default lists to download."
-    echo "                  Valid choices: all|none|emoji|math."
+	echo "                             Valid choices: all|none|emoji|math|nerd (multiple choices possible)."
-    echo "   -f <filepath>  Use a custom emoji database. Can be a url which will be retrieved."
+	echo "  -f, --file <filepath>      Use a custom emoji database. Can be a url which will be retrieved."
-    echo "   -v             Display current program version and directory configuration."
+	echo "  -v, --version              Display current program version and directory configuration."
-    echo "   -h             Show this help."
+	echo "  -h, --help                 Show this help."
 	echo
 	exit "$1"
 }
@@ -50,22 +59,72 @@ version() {
     exit
 }
 
-# Get Options
+msg() {
-while getopts ":f:D:tcenpPhv" o; do
+# Outputs a message to stderr, to be used for info, warning and error messages.
-    case "${o}" in
+    printf "%s\n" "$1" >&2
-    f) BEMOJI_CUSTOM_LIST="${OPTARG}" ;;
+}
-    t) bm_cmds+=(_typer) ;;
+
+parse_cli() {
+	while getopts cD:ef:hnpP:tv-: arg "$@"; do
+		case "$arg" in
 		c) bm_cmds+=(_clipper) ;;
+		D) _opt_set_download_list "${OPTARG}" ;;
 		e) bm_cmds+=(cat) ;;
-    n) bm_echo_newline=false;;
+		f) _opt_set_custom_list "${OPTARG}" ;;
-    D) BEMOJI_DOWNLOAD_LIST="${OPTARG}" ;;
-    p) bm_private_mode=true ;;
-    P) bm_ignore_recent=true ;;
 		h) usage 0 ;;
+		n) bm_echo_newline=false ;;
+		p) bm_private_mode=true ;;
+		P) _opt_set_hist_limit "${OPTARG}" ;;
+		t) bm_cmds+=(_typer) ;;
 		v) version ;;
-    *) usage 1 ;;
+		-)
+			LONG_OPTARG="${OPTARG#*=}"
+			case "$OPTARG" in
+			clip) bm_cmds+=(_clipper) ;;
+			download=?*) _opt_set_download_list "${LONG_OPTARG}" ;;
+			download*)
+				_opt_set_download_list "${*:$OPTIND:1}"
+				OPTIND=$((OPTIND + 1))
+				;;
+			echo) bm_cmds+=(cat) ;;
+			file=?*) _opt_set_custom_list "${LONG_OPTARG}" ;;
+			file*)
+				_opt_set_custom_list "${*:$OPTIND:1}"
+				OPTIND=$((OPTIND + 1))
+				;;
+			help) usage 0 ;;
+			noline) bm_echo_newline=false ;;
+			private) bm_private_mode=true ;;
+			hist-limit=?*) _opt_set_hist_limit "${LONG_OPTARG}" ;;
+			hist-limit*)
+				_opt_set_hist_limit "${*:$OPTIND:1}"
+				OPTIND=$((OPTIND + 1))
+				;;
+			type) bm_cmds+=(_typer) ;;
+			version) version ;;
+			'') break ;;
+			*)
+				echo "Unknown option: ${OPTARG}" 1>&2
+				usage 1
+				;;
 			esac
-done
+			;;
+		\?) exit 2 ;;
+		esac
+	done
+	shift $((OPTIND - 1))
+	OPTIND=1
+}
+
+_opt_set_custom_list() {
+	BEMOJI_CUSTOM_LIST="$1"
+}
+_opt_set_download_list() {
+	BEMOJI_DOWNLOAD_LIST="$1"
+}
+_opt_set_hist_limit() {
+	bm_limit_recent="$1"
+}
 
 prepare_db() {
     # Create list directory
@@ -73,34 +132,50 @@ prepare_db() {
         mkdir -p "$bm_db_location"
     fi
 
-    if [ -n "$(find "$bm_db_location" -maxdepth 0 -type d -empty 2>/dev/null)" ]; then
+    if [ -n "$BEMOJI_DOWNLOAD_LIST" ]; then
         # Populate default lists
         if echo "$BEMOJI_DOWNLOAD_LIST" | grep -q -e 'none'; then
-            printf "No emoji list found, but set to not download any default lists."
+            msg "Not downloading a default emoji list."
-            exit 1
+            return
         elif echo "$BEMOJI_DOWNLOAD_LIST" | grep -q -e 'all'; then
             dl_default_emoji
             dl_math_symbols
+            dl_nerd_symbols
             return
-        fi
+        else
-        if [ -z "$BEMOJI_DOWNLOAD_LIST" ] || echo "$BEMOJI_DOWNLOAD_LIST" | grep -q -e 'emoji'; then
+            if echo "$BEMOJI_DOWNLOAD_LIST" | grep -q -e 'emoji'; then
                 dl_default_emoji
             fi
             if echo "$BEMOJI_DOWNLOAD_LIST" | grep -q -e 'math'; then
                 dl_math_symbols
             fi
+            if echo "$BEMOJI_DOWNLOAD_LIST" | grep -q -e 'nerd'; then
+                dl_nerd_symbols
+            fi
+        fi
+    fi
+    if [ -n "$(find "$bm_db_location" -maxdepth 0 -type d -empty 2>/dev/null)" ]; then
+        dl_default_emoji
     fi
 }
 
 dl_default_emoji() {
-    curl -sSL "https://unicode.org/Public/emoji/14.0/emoji-test.txt" |
+    local emojis
-        sed -ne 's/^.*; fully-qualified.*# \(\S*\) \S* \(.*$\)/\1 \2/gp' >"$bm_db_location/emojis.txt"
+    emojis=$(curl -sSL "https://unicode.org/Public/emoji/latest/emoji-test.txt")
-    printf "Downloaded default emoji set."
+    printf "%s" "$emojis" | sed -ne 's/^.*; fully-qualified.*# \(\S*\) \S* \(.*$\)/\1 \2/gp' >"$bm_db_location/emojis.txt"
+    msg "Downloaded default emoji set."
 }
 dl_math_symbols() {
     curl -sSL "https://unicode.org/Public/math/latest/MathClassEx-15.txt" |
-        grep -ve '^#' | cut -d';' -f3,7 --output-delimiter=' ' >"$bm_db_location/math.txt"
+        grep -ve '^#' | cut -d';' -f3,7 | sed -e 's/;/ /' >"$bm_db_location/math.txt"
-    printf "Downloaded math symbols set."
+    msg "Downloaded math symbols set."
+}
+dl_nerd_symbols() {
+    local nerd all
+    nerd=$(curl -sSL "https://raw.githubusercontent.com/ryanoasis/nerd-fonts/master/css/nerd-fonts-generated.css")
+    all+=$(printf "%s" "$nerd" | sed -ne '/\.nf-/p' -e '/\s*[^_]content:/p' | sed -e 'N;s/^\.nf-\(.*\):before.* content: \"\\\(.*\)\";/\\U\2 \1/')
+    echo -e "$all" > "$bm_db_location/nerdfont.txt"
+    msg "Downloaded nerdfont symbols set."
 }
 
 gather_emojis() {
@@ -112,31 +187,39 @@ gather_emojis() {
         result=$(cat "$bm_db_location"/*.txt)
     fi
 
-    if [ "$bm_ignore_recent" = true ]; then
+    if [ -n "$bm_limit_recent" ] && [ "$bm_limit_recent" -eq 0 ]; then
         printf "%s" "$result"
-    else
+        return
-        printf "%s\n%s" "$(get_most_recent)" "$result" | cat -n - | sort -uk2 | sort -n | cut -f2-
     fi
+
+    printf "%s\n%s" "$(get_most_recent "$bm_limit_recent")" "$result" | cat -n - | sort -uk2 | sort -n | cut -f2-
 }
 
 get_most_recent() {
+    limit=${1}
     recent_file="$bm_history_file"
     if [ ! -f "$recent_file" ]; then
         touch "$recent_file"
     fi
     # TODO improve this messy line
-    sed -e '/^$/d' "$recent_file" |
+    local result
+    result=$(sed -e '/^$/d' "$recent_file" |
         sort |
         uniq -c |
-        sort -rn |
+        sort -k1rn |
         sed -e 's/^\s*//' |
-        cut -d' ' -f2-
+        cut -d' ' -f2-)
+    if [ -z "$limit" ]; then
+        echo "$result"
+    else
+        echo "$result" | head -n "$limit"
+    fi
 }
 
 add_to_recent() {
     if [ -z "$1" ]; then return; fi
-    if [ ! -d "$bm_cache_dir" ]; then
+    if [ ! -d "$bm_state_dir" ]; then
-        mkdir -p "$bm_cache_dir"
+        mkdir -p "$bm_state_dir"
     fi
     echo "$1" >>"$bm_history_file"
 }
@@ -153,23 +236,26 @@ _clipper() {
     elif [ -n "$DISPLAY" ] && command -v xsel >/dev/null 2>&1; then
         xsel -b
     else
-        printf "No suitable clipboard tool found."
+        msg "No suitable clipboard tool found."
         exit 1
     fi
 }
 
-# Set default typing uti
+# Set default typing util
 _typer() {
-    totype=$(cat -)
     if [ -n "$BEMOJI_TYPE_CMD" ]; then
         # shellcheck disable=SC2068
         ${BEMOJI_TYPE_CMD[@]}
-    elif [ -n "$WAYLAND_DISPLAY" ] && command -v wtype >/dev/null 2>&1; then
+        return
+    fi
+
+    totype=$(cat -)
+    if [ -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
         xdotool type --delay 30 "$totype"
     else
-        printf "No suitable typing tool found."
+        msg "No suitable typing tool found."
         exit 1
     fi
 }
@@ -179,20 +265,22 @@ _picker() {
     if [ -n "$BEMOJI_PICKER_CMD" ]; then
         # shellcheck disable=SC2068
         ${BEMOJI_PICKER_CMD[@]}
-    elif command -v bemenu >/dev/null 2>&1; then
+		return
-        bemenu -p 🔍 -i -l 20
-    elif command -v wofi >/dev/null 2>&1; then
-        wofi -p 🔍 -i --show dmenu
-    elif command -v rofi >/dev/null 2>&1; then
-        rofi -p 🔍 -i -dmenu --kb-custom-1 "Alt+1" --kb-custom-2 "Alt+2"
-    elif command -v dmenu >/dev/null 2>&1; then
-        dmenu -p 🔍 -i -l 20
-    else
-        printf "No suitable picker tool found."
-        exit 1
 	fi
+
+	for tool in "${!default_pickers[@]}"; do
+		if command -v "$tool" >/dev/null 2>&1; then
+			${default_pickers[$tool]}
+			return
+		fi
+	done
+
+	msg "No suitable picker tool found."
+	exit 1
 }
 
+parse_cli "$@"
+
 [ -n "$BEMOJI_CUSTOM_LIST" ] || prepare_db
 result=$(gather_emojis | _picker)
 exit_value="$?"
@@ -201,7 +289,7 @@ result=$(echo "$result" | grep -o '^\S\+' | tr -d '\n')
 
 case "$exit_value" in
 1)
-    exit
+    exit 1
     ;;
 0)
     if [ ${#bm_cmds[@]} -eq 0 ]; then

test/bemoji_cmds.bats

@@ -15,8 +15,8 @@ setup() {
 
     # 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"
+    export BEMOJI_HISTORY_LOCATION="$BATS_TEST_TMPDIR/history"
-    mkdir -p "$BEMOJI_DB_LOCATION" "$BEMOJI_CACHE_LOCATION"
+    mkdir -p "$BEMOJI_DB_LOCATION" "$BEMOJI_HISTORY_LOCATION"
     cat "$BATS_TEST_DIRNAME/resources/test_emoji.txt" > "$BEMOJI_DB_LOCATION/emoji.txt"
 }
 
@@ -54,6 +54,11 @@ setup() {
 typing result"
 }
 
+@test "Passes selection to custom typer tool through stdin" {
+    BEMOJI_TYPE_CMD="cat -" run bemoji -t 3>&-
+    assert_output "❤️"
+}
+
 @test "Runs custom default command" {
     BEMOJI_DEFAULT_CMD="echo my custom command" run bemoji 3>&-
     assert_output "my custom command"
@@ -64,6 +69,11 @@ typing result"
     assert_output "my clipping"
 }
 
+@test "Returns status code 1 on picker status code 1" {
+    BEMOJI_PICKER_CMD="return 1" run bemoji -e 3>&-
+    assert_failure 1
+}
+
 @test "Prints output with newline by default" {
     bats_require_minimum_version 1.5.0
     BEMOJI_PICKER_CMD="echo heart" run --keep-empty-lines -- bemoji -e
@@ -75,3 +85,29 @@ typing result"
     BEMOJI_PICKER_CMD="echo heart" run --keep-empty-lines -- bemoji -ne
     assert_output --regexp '^heart$'
 }
+
+@test "Understands long-form options" {
+    run bemoji --help
+    assert_success
+    assert_output --partial "A simple emoji picker."
+}
+
+@test "Understands long-form equals values" {
+    BEMOJI_CLIP_CMD="echo heart" run bemoji --hist-limit=0
+    assert_success
+}
+
+@test "Understands long-form spaced values" {
+    BEMOJI_CLIP_CMD="echo heart" run bemoji --hist-limit 0
+    assert_success
+}
+
+@test "Understands short-form spaced values" {
+    BEMOJI_CLIP_CMD="echo heart" run bemoji -P 0
+    assert_success
+}
+
+@test "Can concatenate short-form options and values" {
+    BEMOJI_CLIP_CMD="echo heart" run bemoji -neP0
+    assert_success
+}

test/bemoji_directories.bats

@@ -15,8 +15,8 @@ setup() {
 
     # 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"
+    export BEMOJI_HISTORY_LOCATION="$BATS_TEST_TMPDIR/history"
-    mkdir -p "$BEMOJI_DB_LOCATION" "$BEMOJI_CACHE_LOCATION"
+    mkdir -p "$BEMOJI_DB_LOCATION" "$BEMOJI_HISTORY_LOCATION"
     cat "$BATS_TEST_DIRNAME/resources/test_emoji.txt" > "$BEMOJI_DB_LOCATION/emoji.txt"
 }
 
@@ -38,8 +38,8 @@ database=$BATS_TEST_TMPDIR/xdb-db/bemoji
 }
 
 @test "sets XDG directory for history by default" {
-    unset BEMOJI_CACHE_LOCATION
+    unset BEMOJI_HISTORY_LOCATION
-    export XDG_CACHE_HOME="$BATS_TEST_TMPDIR/xdb-cache"
+    export XDG_STATE_HOME="$BATS_TEST_TMPDIR/xdb-cache"
     run bemoji -v
     assert_output --regexp "
 history=$BATS_TEST_TMPDIR/xdb-cache/bemoji-history.txt$"
@@ -54,10 +54,10 @@ database=$HOME/.local/share/bemoji
 }
 
 @test "falls back to default history location if no XDG found" {
-    unset BEMOJI_CACHE_LOCATION
+    unset BEMOJI_HISTORY_LOCATION
     run bemoji -v
     assert_output --regexp "
-history=$HOME/.cache/bemoji-history.txt$"
+history=$HOME/.local/state/bemoji-history.txt$"
 }
 
 @test "BEMOJI_DB_LOCATION sets correct db directory" {
@@ -67,8 +67,8 @@ database=$BATS_TEST_TMPDIR/database
 "
 }
 
-@test "BEMOJI_CACHE_LOCATION sets correct cache directory" {
+@test "BEMOJI_HISTORY_LOCATION sets correct history directory" {
     run bemoji -v
     assert_output --regexp "
-history=$BATS_TEST_TMPDIR/cache/bemoji-history.txt$"
+history=$BATS_TEST_TMPDIR/history/bemoji-history.txt$"
 }

test/bemoji_download.bats

@@ -0,0 +1,48 @@
+#!/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'
+    load 'test_helper/mocks/stub'
+
+    # mock out interactive picker for static emoji return
+    export BEMOJI_PICKER_CMD="echo heart"
+
+    # set up small default set of test emoji for each test
+    export BEMOJI_DB_LOCATION="$BATS_TEST_TMPDIR/database"
+    export BEMOJI_HISTORY_LOCATION="$BATS_TEST_TMPDIR/history"
+    mkdir -p "$BEMOJI_DB_LOCATION" "$BEMOJI_HISTORY_LOCATION"
+}
+
+@test "Runs emoji download on -D emoji option" {
+    stub curl \
+        "echo -e '1F605  ; fully-qualified # emoji E0.6 grinning face with sweat\nnot picked up\n1F605  ; fully-qualified # emoji2 E0.6 picked up'"
+    run bemoji -D emojis 3>&-
+    outcome=$(cat "$BEMOJI_DB_LOCATION/emojis.txt")
+    assert_equal "$outcome" "emoji grinning face with sweat
+emoji2 picked up"
+    unstub curl
+}
+
+@test "Runs maths download on -D maths option" {
+    stub curl \
+        "echo '03A3;A;Σ;Sigma;ISOGRK3;;GREEK CAPITAL LETTER SIGMA'"
+    run bemoji -D math 3>&-
+    outcome=$(cat "$BEMOJI_DB_LOCATION/math.txt")
+    assert_equal "$outcome" "Σ GREEK CAPITAL LETTER SIGMA"
+    unstub curl
+}
+@test "Runs nerdfont download on -D nerd option" {
+    stub curl \
+        "printf 'meangingless\nafiller lines\n.nf-md-pipe_wrench:before { \n content: \"\\\f1354\";\n }'"
+    run bemoji -D nerd 3>&-
+    outcome=$(cat "$BEMOJI_DB_LOCATION/nerdfont.txt")
+    assert_equal "$outcome" "󱍔 md-pipe_wrench"
+    unstub curl
+}

test/bemoji_errors.bats

@@ -0,0 +1,43 @@
+#!/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'
+
+    # set up small default set of test emoji for each test
+    export BEMOJI_DB_LOCATION="$BATS_TEST_TMPDIR/database"
+    export BEMOJI_HISTORY_LOCATION="$BATS_TEST_TMPDIR/history"
+    mkdir -p "$BEMOJI_DB_LOCATION" "$BEMOJI_HISTORY_LOCATION"
+    cat "$BATS_TEST_DIRNAME/resources/test_emoji.txt" > "$BEMOJI_DB_LOCATION/emoji.txt"
+
+    # these tests require stdout to be separated from stderr
+    # such run flags were only introduced in recent bats version
+    bats_require_minimum_version 1.5.0
+}
+
+@test "Prints clipper error to stderr" {
+    BEMOJI_PICKER_CMD="echo hi" run --separate-stderr bemoji 3>&-
+    assert_output ""
+    output="$stderr"
+    assert_output "No suitable clipboard tool found."
+}
+
+@test "Prints picker error to stderr" {
+    run --separate-stderr bemoji 3>&-
+    assert_output ""
+    output="$stderr"
+    assert_output "No suitable picker tool found."
+}
+
+@test "Prints typer error to stderr" {
+    BEMOJI_PICKER_CMD="echo hi" run --separate-stderr bemoji -t 3>&-
+    assert_output ""
+    output="$stderr"
+    assert_output "No suitable typing tool found."
+}

test/bemoji_history.bats

@@ -0,0 +1,57 @@
+#!/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_HISTORY_LOCATION="$BATS_TEST_TMPDIR/history"
+    mkdir -p "$BEMOJI_DB_LOCATION" "$BEMOJI_HISTORY_LOCATION"
+    cat "$BATS_TEST_DIRNAME/resources/test_emoji.txt" > "$BEMOJI_DB_LOCATION/emoji.txt"
+}
+
+@test "sorts by frecency" {
+    echo -e "there\nhello\nhello" > "$BEMOJI_HISTORY_LOCATION/bemoji-history.txt"
+    echo -e "database" > "$BEMOJI_DB_LOCATION/emoji.txt"
+    BEMOJI_CLIP_CMD="cat -" BEMOJI_PICKER_CMD="cat -" run bemoji 3>&-
+    assert_output "hellotheredatabase"
+}
+
+@test "history limiting uses sorted results" {
+    echo -e "zany\nmy\nisee\nonomatopeia" > "$BEMOJI_HISTORY_LOCATION/bemoji-history.txt"
+    echo -e "database" > "$BEMOJI_DB_LOCATION/emoji.txt"
+    BEMOJI_CLIP_CMD="cat -" BEMOJI_PICKER_CMD="cat -" run bemoji -P 1 3>&-
+    assert_output "iseedatabase"
+}
+
+@test "history limiting takes frecency into account" {
+    echo -e "there\nfriend\nhello\nhello" > "$BEMOJI_HISTORY_LOCATION/bemoji-history.txt"
+    echo -e "database" > "$BEMOJI_DB_LOCATION/emoji.txt"
+    BEMOJI_CLIP_CMD="cat -" BEMOJI_PICKER_CMD="cat -" run bemoji -P 1 3>&-
+    assert_output "hellodatabase"
+}
+
+@test "-P 0 disables history" {
+    echo -e "there\nfriend\nhello\nhello" > "$BEMOJI_HISTORY_LOCATION/bemoji-history.txt"
+    echo -e "database" > "$BEMOJI_DB_LOCATION/emoji.txt"
+    BEMOJI_CLIP_CMD="cat -" BEMOJI_PICKER_CMD="cat -" run bemoji -P 0 3>&-
+    assert_output "database"
+}
+
+@test "BEMOJI_LIMIT_RECENT=0 disables history" {
+    echo -e "there\nfriend\nhello\nhello" > "$BEMOJI_HISTORY_LOCATION/bemoji-history.txt"
+    echo -e "database" > "$BEMOJI_DB_LOCATION/emoji.txt"
+    BEMOJI_LIMIT_RECENT=0 BEMOJI_CLIP_CMD="cat -" BEMOJI_PICKER_CMD="cat -" run bemoji 3>&-
+    assert_output "database"
+}
+

test/test_helper/mocks

@@ -0,0 +1 @@
+Subproject commit 7e0fbf6bc705bd1b09daa2d5ff88962ddbe832f6