🦊 BREAKING: Use new XDG Base specification for state (#5)

Switched the history from using the XDG_CACHE_HOME directory by default
to use XDG_STATE_HOME by default.

This makes sense since cache can (and should be prepared to) be wiped at
any moment and the program functionality should not be hindered by this.
Since we need to retain history through such wipes the newly introduced
state directory is the perfect match for keeping the history file in.

This does constitute a breaking change for existing histories which need
to be moved to the new directory if they made use of the old cache
directory.

Concurrent with this we are renaming `XDG_CACHE_LOCATION` environment
variable to `XDG_HISTORY_LOCATION` so this is a second breaking change
for those using a custom location for their histories.

This change attempts to make the naming scheme coherent and remove some
left-over naming cruft from the old location being the cache directory.

This provides one of the larger changes to the program so far.

Fixes #5.

.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

@@ -3,3 +3,76 @@ pipeline:
     image: bats/bats
     commands:
       - /opt/bats/bin/bats test
+
+  release-prep: # prepare changelog and version information for release candidate
+    when:
+      event: tag
+      tag: 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
+      tag: 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
+      tag: 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
+      - tar -czvf bemoji-$BM_VERSION.tar.gz build/*
+      - zip -r bemoji-$BM_VERSION.zip build/*
+      - mv bemoji-$BM_VERSION.tar.gz bemoji-$BM_VERSION.zip dist
+
+  release-gitea:
+    group: release
+    when:
+      event: tag
+      tag: 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
+      tag: 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\":\"$BM_VERSION\",\"target_commitish\":\"main\",\"name\":\"$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,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+<!-- ### Added -->
+
+<!-- ### Changed -->
+
+<!-- ### Deprecated -->
+
+<!-- ### Removed -->
+
+<!-- ### Fixed -->
+
+<!-- ### Security -->
+
+## [0.3.0] - 2022-11-10
+
 ### Added
 
 - Add new option `-n` which suppresses printing the final newline character in output
@@ -14,18 +28,19 @@ 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 -->
+- (!) 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
-<!-- ### Removed -->
+  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
 
 - 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

README.md

@@ -144,14 +144,14 @@ 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_STATE_HOME/bemoji-history.txt`,
-so most often in `~/.cache/bemoji-history.txt`
+so most often in `~/.local/state/bemoji-history.txt`
 
 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.
@@ -174,11 +174,11 @@ 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 set
 
-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.
-To change this setting, execute bemoji like the following:
+To download additional sets, execute bemoji like the following:
 
 ```bash
 bemoji -D all
@@ -187,8 +187,14 @@ 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.
 Other valid options for this setting are `emoji`, `math`, `none`.
 
+```bash
+bemoji -D "math emoji"
+```
+
+The above command is equivalent 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
 
@@ -241,7 +247,7 @@ with their default settings
 
 ```bash
 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

@@ -1,14 +1,14 @@
 #!/usr/bin/env bash
 
-bm_version=0.2.0
+bm_version=0.3.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"
@@ -36,8 +36,8 @@ usage() {
     echo "   -n             Do not print a newline after the picked emoji."
     echo "   -p             Do not save picked emoji to recent history."
     echo "   -P             Do not order emoji by recently used."
-    echo "   -D <choice>    Choose specific default lists to download if none found locally."
+    echo "   -D <choice>    Choose from default lists to download."
-    echo "                  Valid choices: all|none|emoji|math."
+    echo "                  Valid choices: all|none|emoji|math (multiple choices possible)."
     echo "   -f <filepath>  Use a custom emoji database. Can be a url which will be retrieved."
     echo "   -v             Display current program version and directory configuration."
     echo "   -h             Show this help."
@@ -73,34 +73,39 @@ 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."
+            printf "Not downloading a default emoji list.\n"
-            exit 1
+            return
         elif echo "$BEMOJI_DOWNLOAD_LIST" | grep -q -e 'all'; then
             dl_default_emoji
             dl_math_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
         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/14.0/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"
+    printf "Downloaded default emoji set.\n"
 }
 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."
+    printf "Downloaded math symbols set.\n"
 }
 
 gather_emojis() {
@@ -135,8 +140,8 @@ get_most_recent() {
 
 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"
 }

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"
 }
 

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,40 @@
+#!/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/test_helper/mocks

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