Frecency.el

#+PROPERTY: LOGGING nil

• frecency.el :noexport:

[[https://melpa.org/#/frecency][file:https://melpa.org/packages/frecency-badge.svg]]

This library provides a way to sort items by "frecency" (frequency and recency).

This package is based on the algorithm which was (perhaps originally) implemented in Mozilla Firefox, and has since been implemented in other software. Specifically, it is based on the implementation described in [[https://slack.engineering/a-faster-smarter-quick-switcher-77cbc193cb60][this article]].

• Installation :noexport_1:

This package requires Emacs 25.1 or later.

** MELPA

If you installed from MELPA, you're done.

** Manual

Install [[https://github.com/magnars/dash.el][dash.el]], and [[https://github.com/plexus/a.el][a.el]], then put this package in your =load-path=.

• Usage :noexport_1:

Load the library with:

#+BEGIN_SRC elisp (require 'frecency) #+END_SRC

The library operates on individual items. That is, you have a list of items that are frequently (or not-so-frequently) accessed, and you pass each item to these functions:

• =frecency-score= returns the score for an item, which you may use to sort a list of items (e.g. you may pass =frecency-score= to =cl-sort= as the =:key= function).
• =frecency-sort= returns a list sorted by frecency. Each item in the list must itself be a collection with valid frecency keys and values.
• =frecency-update= returns an item with its frecency values updated. If the item doesn't have any frecency keys (e.g. if it's the first time it's been accessed or recorded), they will be added.

An item should be an alist or a plist. These keys are used by the library:

• =:frecency-num-timestamps=
• =:frecency-timestamps=
• =:frecency-total-count=

All other keys are ignored and returned with the item.

The library uses alists by default, but it can operate on plists, hash-tables, or other collections by setting =:get-fn= and =:set-fn= when calling a function (e.g. when using plists, set them to =plist-get= and =plist-put= respectively). =:get-fn= should have the signature =(ITEM KEY)=, and =:set-fn= should have =(ITEM KEY VALUE)=.

** Customization

The variable =frecency-max-timestamps= controls how many timestamps are recorded, the number of which is used in the score calculation. It's set to 10 by default. Users can customize this in their config, and package authors can override it by let-binding the variable around calls to =frecency-update=.

• Changelog :noexport_1:

** 1.0

• Initial release.

• Development :noexport_1:

Contributions and suggestions are welcome.

• License :noexport:

GPLv3