Update README for new Rust-based frequency-index-scripts

README.md

@@ -1,44 +1,113 @@
-Maintain a index sorted by [frecency](https://en.wikipedia.org/wiki/Frecency) (frequency + recency).
-These scripts were designed for usage with [rofi](https://github.com/DaveDavenport/rofi).
+Maintain a database sorted by [frecency](https://en.wikipedia.org/wiki/Frecency) (frequency + recency).
+
+## Installation
+
+Simply [download the latest release](https://github.com/SicariusNoctis/frece/releases) and add the `frece` executable to `PATH`.
+
+Arch users may install from the AUR packages [`frece-bin`](https://aur.archlinux.org/packages/frece-bin) or [`frece-git`](https://aur.archlinux.org/packages/frece-git).
 
 ## Usage
 
-Initially, construct an index. For example, the following constructs a directory index:
+### Commands
 
-    ./examples/refresh_dir_index.sh
+`frece` provides the following subcommands:
 
-Now we may use the index with rofi as follows:
+```
+increment    Increases an entry's count and resets its timer
+init         Creates a database file from given list of entries
+print        Prints list of frecency sorted entries
+update       Updates a database file from given list of entries
+```
 
-    ./examples/rofi_dir.sh $ROFI_ARGS
+See `frece --help` or the [`Examples`](#examples) section for more information.
 
-where you may specify your own `$ROFI_ARGS`, such as `-hide-scrollbar`. This will open up a menu with entries sorted by frecency:
+### Examples
 
-![](https://i.imgur.com/ylkVqBg.jpg)
+#### General
 
-Similarly, other examples are offered, including a rofi script to copy emojis to clipboard:
+Begin by creating a database:
 
-![](https://i.imgur.com/1PAaIGm.jpg)
+```bash
+# Create list of entries
+$ echo "apple
+banana
+cherry" > fruits.txt
+
+# Initialize a database using list of items
+$ frece init "fruits.db" "fruits.txt"
+```
+
+Access entries and print out a frecency sorted list of entries:
+
+```bash
+# Access an entry
+$ frece increment "fruits.db" "cherry"
+
+# Print out frecency sorted list
+$ frece print "fruits.db"
+
+cherry
+apple
+banana
+```
+
+Furthermore, a database can be updated with *new* entries:
+
+```bash
+# Create another list
+$ echo "apple
+cherry
+elderberry
+grapefruit" > fruits.txt
+
+# Update database with new list
+# Optionally, purge old entries like "banana"
+$ frece update "fruits.db" "fruits.txt" --purge-old
 
-## Features
+# Print out frecency sorted list (verbosely)
+$ frece print "fruits.db" --verbose
 
-To list the current frecency rankings:
+frecency   count  last access date           item
+0.128476       1  2019-05-17T00:49:14+00:00  cherry
+0.000000       0  1970-01-01T00:00:00+00:00  apple
+0.000000       0  1970-01-01T00:00:00+00:00  elderberry
+0.000000       0  1970-01-01T00:00:00+00:00  grapefruit
+```
 
-    ./list_index.sh ~/.dir_index.txt ~/.dir_frequent.txt list
+#### Rofi
 
-outputs:
+The following examples may be found in the [`examples`](examples) directory:
 
-    rank    directory
-    .105    /mnt/data/Dropbox/sfu/Current
-    .050    /mnt/data/Dropbox/sfu/Y4S2 2018Sp/ENSC 410
-    .048    /mnt/data/Dropbox/DB Pictures/Digital Art/Landscapes
-    .042    /mnt/data/Dropbox
-    .039    /mnt/data/Dropbox/sfu/Y4S2 2018Sp/ENSC 495/Course Notes
-    .030    /mnt/data/Dropbox/sfu/Y4S2 2018Sp/ENSC 495/Labs/Lab 1
-    .030    /mnt/data/Dropbox/sfu/Y4S2 2018Sp/ENSC 495
-    .030    /mnt/data/Dropbox/sfu/Y4S2 2018Sp/ENSC 327
-    .030    /mnt/data/Downloads
-    .022    /mnt/data/Dropbox/sfu/Y4S2 2018Sp/ENSC 350/Labs/lab4
-    .022    /mnt/data/Dropbox/eBooks/0Current
-    .021    /mnt/data/Dropbox/Camera Uploads/Screenshots
-    .020    /mnt/data/Dropbox/DB Pictures/Wallpaper Unsorted
+```bash
+examples/dir        Open a directory
+examples/emoji      Copy an emoji to clipboard
+examples/file       Open a file
+```
 
+For instance, `examples/dir` may be used as follows:
+
+1. Initialize/update a database in `$HOME/.frece_dir.db`, providing a list of paths to directories to index:
+
+    ```bash
+    SEARCH_PATHS=("$HOME" "/some/other/path")
+    ./examples/dir_update.sh "${SEARCH_PATHS[@]}"
+    ```
+
+   Tip: run this periodically via a systemd timer or cronjob to refresh the database.
+
+2. Open with [rofi](https://github.com/davatorium/rofi), optionally providing a list of arguments:
+
+    ```bash
+    ROFI_ARGS=(-p 'folders' -i -levenshtein-sort)
+    ./examples/dir_rofi.sh "${ROFI_ARGS[@]}"
+    ```
+
+    <!-- TODO verify above -->
+
+    This will open up a rofi menu with entries sorted by frecency:
+
+    ![](https://i.imgur.com/ylkVqBg.jpg)
+
+Similarly, other examples are offered, including a rofi script to copy emojis to clipboard:
+
+![](https://i.imgur.com/1PAaIGm.jpg)