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:

• version The sublist named by the symbol version contains the version of the score file format. You do not need to include this in your initial score file; it is written out automatically by elfeed-score. elfeed-score maintains backward compatibiliy in that score files in older format versions are still recognized. The most recent format version will always be used when the score file is updated, however. Also, an older elfeed-score will reject a more recent score file.

  When elfeed-score loads a score file that uses an archaic version (i.e. a version less than elfeed-score-serde-current-format) it will announce the fact that your score file will be updated and make a backup of your current score file in %s.~%d~ where %s is replaced by elfeed-score-serde-score-file and %d is replaced by your score file’s current version (so that you will end up with a copy of the last score file in each format over time).

  Variable: elfeed-score-serde-current-format ¶

  The version of the score file format employed by elfeed-score.

  It will also immediately re-write the score file in the current format.

• “title” The sublist named by the string “title” contains rules that match against elfeed entry titles, on which more below in title Rules.
• “content” The sublist named by the string “content” contains rules that match against elfeed entry content, on which more below in content Rules.
• “title-or-content” The sublist named by the string “title-or-content” contains rules that match against both entry title and content, on which more below in title-or-content Rules.
• “authors” This sublist contains rules that match against the entry author, on which more below in authors Rules.
• “tag” This sublist contains rules that match against entries’ tags; see tag Rules below for more details.
• “feed” This sublist contains rules that match against entries’ feed; see feed Rules below for more details.
• “adjust-tags” This sublist contains rules that will be applied after an entry’s score has been computed and that add or remove tags based on that score. Details below at adjust-tags Rules.
• mark This sublist contains an integer; if an entry’s final score is below this value, the entry will be marked as “read”. Details below in mark Rule.

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.