From bbe1ad6d1d4cadf638474742ab052b78c8cf4559 Mon Sep 17 00:00:00 2001 From: Mateen Ulhaq Date: Thu, 16 May 2019 20:14:08 -0700 Subject: [PATCH] Update README for new Rust-based frequency-index-scripts --- README.md | 125 ++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 97 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 9b7274a..9a82720 100644 --- a/README.md +++ b/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[@]}" + ``` + + + + 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)