3.1 Score File Format

The score file is plain-text file containing a single Lisp form. Under the hood, elfeed-score opens your file, inserts its contents into a temporary buffer, and calls read-from-string (see read-from-string in Emacs Lisp) on the contents.

The form is a list of lists; each sub-list begins with a symbol or a string identifying that sub-list’s nature & purpose. The sub-list identifiers elfeed-score recognizes are:

Until elfeed-score 0.7, all rules were serialized to flat lists, with each attribute in a known position in the list (for instance, title rules wrote down their match text in position 0, the match value in position 1, and so forth, while the other rule types each had their own format).

As time went on, the number of attributes for any given rule type grew. Using flat lists as a serialization format became untenable for two reasons:

  1. Having to "just know" that slot i was for this & slot j was for that became increasingly burdensome for the package author, let alone contributors & users.
  2. It makes validation hard: if the score file author forgets that slot i is for this thing, but provides the thing that goes in slot i + 1, then when elfeed-score calls (nth in i) it will get something back, but will not discover that it’s the wrong sort of thing for some time, which makes it hard to craft a usable error message; worse, elfeed-score may never discover it & instead fail silently.

Beginning with build 0.7.3 (format version 6), elfeed-score now uses property lists as its serialization format. This will address these two issues, at the cost of making authoring rules more prolix: instead of saying:

("match text" 100...)

you’ll now have to say:

(:text "match text" :value 100...)

Given that fields set to their default values do not have to be specified, this will hopefully not be too inconvenient, and will enable better error messages on reading score files.