🦊 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.

CHANGELOG.md

@@ -9,7 +9,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 <!-- ### Added -->
 
-<!-- ### Changed -->
+### 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
 
 <!-- ### Deprecated -->
 

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.
@@ -247,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

@@ -5,10 +5,10 @@ bm_version=0.3.0
 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"
@@ -140,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$"
 }