elfeed-score ¶

2.1.1 Scoring Generalities ¶

elfeed is an extensible RSS & Atom reader for Emacs. By default, it will display entries in reverse chronological order. This package defines a bit of metadata for each of your elfeed entries: a "score". A score is an integer (negative or positive), and higher scores denote entries of greater interest to you. This package also (optionally) installs a new sort function, so that Elfeed will display entries with higher scores before entries with lower scores (entries with the same scores will still be sorted in reverse chronological order). It also provides an entry display function for the search buffer that displays each entry’s score, should you choose to install it.

While you can manually assign a score to an entry (see Manual Scoring), you will likely find it more convenient to create rules for scoring that will be automatically applied to each new entry every time you update Elfeed. You can score against title, feed, content & authors by defining strings that will be matched against those attributes by substring, regexp or whole-word match. You can score against the feed. You can also score against the presence or absence of tags. Most kinds of rules can be scoped by Elfeed entry tags, so that a rule will only be applied if an entry has certain tags (or does not have certain tags). Many kinds of rules may also be scoped by feed, so that a rule will only be applied to entries from certain feeds (or not from certain feeds). Each rule defines an integral value, and the rules are applied in order of definition. The new entry’s score begins at elfeed-score-scoring-default-score, and is adjusted by the value defined by each matching scoring rule.

User Option: elfeed-score-scoring-default-score ¶

The default score for an elfeed entry.

For instance, here’s a subset of my scoring file at the moment:

;;; Elfeed score file                                     -*- lisp -*-
  (("title"
    (:text "OPEN THREAD" :value -1000 :type S)
    (:text "raymond c\\(hen\\)?" :value 250 :type r 
     :tags (t .(@dev)))
   ("content"
    (:text "type erasure" :value 500 :type s))
   ("title-or-content"
    (:text "california" :title-value 150 :content-value 100 :type s)
    (:text "china" :title-value 150 :content-value 100 :type w))
   ("feed"
    (:text "Essays in Idleness" :value 250 :type S :attr t)
    (:text "Irreal" :value 250 :type S :attr t)
    (:text "Julia Evans" :value 100 :type :type s :attr t)
    (:text "National Weather Service" :value 400 :type S :attr t)
    (:text "emacs-news – sacha chua" :value 350 :type S :attr t))
   ("authors"
     (:text "Jim Geraghty" :value 500 :type s))
   ("tag"
    (:tags (t . reddit-question)
     :value 750))
   (mark -2500))

Like Gnus scoring, this may look like Lisp code, but it is not directly evaluated. It will be read by the Lisp reader, so it must at least be a valid Lisp s-expression.

For details of how to form s-expressions elfeed-score will understand, see below.

2.1.2 Manual Scoring ¶

Scores may also be set on entries manually:

Command: elfeed-score-set-score score ignore-region ¶

Set the score of one or more Elfeed entries to score (given as a prefix argument).

Since these scores are presumably significant to the user who took the trouble to set them, such scores will not be overwritten by other scoring operations (such as the new entry hook which elfeed-score installs). Since this behavior was implemented only recently, it is controlled by a configuration variable:

User Option: elfeed-score-scoring-manual-is-sticky ¶

This customization variable, if true, will make manual scores “sticky” in that they will not be overwritten by other scoring operations (they can, however, be overwritten by a subsequent manual scoring operation). If nil, manual scoring is treated no differently than any other scoring operation.

2.1.3 Scoring Statistics ¶

elfeed-score maintains statistics on when & how frequently each rule matches an entry (on which more below). In earlier versions of the package, each rule’s stats were maintained in the rule structure itself & were persisted along with each rule to the score file.

This turned out to be ill-conceived, leading to split-brain when the user edited their score file with un-written stats still in memory.

Today, elfeed-score maintains a separate datastructure holding this information & automatically writes it to disk in a separate file. The location of the stats file is defined in elfeed-score-rule-stats-file.

User Option: elfeed-score-rule-stats-file ¶

The location at which scoring rule stats are maintained.

The default value is elfeed.stats in user-emacs-directory, which see user-emacs-directory in Emacs Lisp.

Since this file is meant to be maintained automatically by elfeed-score, this manual won’t go over the file format.

3.2.1 title Rules ¶

“title rules” are rules that are matched against each entry’s title. You may match by substring, regexp or whole word. The match may be case sensitive or case-insensitive. Of course, the rule needs to specify the amount to be added to an entry’s score on successful match.

In the score file (see The Score File), title rules are represented by a property list of up to six attributes:

1. :text: The match text.
2. :value: The match value. This is an integer specifying the amount by which the entry’s score should be adjusted, should the text match
3. :type: The match type.

   This is a symbol, and must be one of s, S, r, R, w or W for case-insensitive substring match, case-sensitive substring match, case-insensitive regexp match or case-sensitive regexp match, and case-insensitive or case-sensitive whole word match, respectively.

   Note that regular expressions use Emacs Lisp regular expression syntax (see Regular Expressions in Emacs Lisp).

   Whole word matching just feeds the match text to word-search-regexp (see String Search in Emacs Lisp) before doing a regexp search.

4. :tags: Tag scoping rules.

   You may wish to apply this rule only to entries that have certain tags (or that do not have certain tags). See Scoping Rules by Tags for how to do that.

   This property is optional.

5. :feeds: Feed scoping rules.

   You may wish to apply this rule only to entries that came from certain feeds (or did not come from certain feeds). See Scoping Rules by Feed for how to do that.

   This property is optional.

6. :comment: Rule comment

   An optional, free-form note on this rule. Since Lisp comments will be lost on read, this provides a way for the score file author to annotate rules.

So, for instance, the following rule:

("title"
  (:text "rust.*who.s hiring" :value 1500 :type r))

would match each entry’s title against the regular expression “rust.*who.s hiring” (without regard to case) and adds 1500 to the score of any entry that matches.

Note that it takes advantage of the fact that only the :text, :value & :type properties are required.

3.2.2 content Rules ¶

“content rules” are very similar to title Rules except that they match against an entry’s content rather than its title. For that reason, this section will be very brief– refer to title Rules for the details of each element.

In the score file (see The Score File), content rules are represented by six properties:

1. :text The match text
2. :value The match value
3. :type The match type as per above.
4. :tags Tag scoping rules
5. :feeds Feed scoping rules
6. :comment Comment

As above, only the first three elements are required.

3.2.3 title-or-content Rules ¶

When searching for text in entries on which to score, it can be convenient to check both title and content. Rather than repeating each rule in both the “title” and “content” elements of the score file, you can use “title-or-content” rules. These rules consist of seven elements, not six:

1. :text The match text, as with title & content rules
2. :title-value The title match value

   The value by which an entry’s score will be adjusted when the title matches. This allows different scoring values for title & content matches, on the assumption that a title match would be considered more significant.

3. :content-value The content match value

   The value by which an entry’s score will be adjusted when the content matches.

4. :type The match type as per above.
5. :tags Tag scoping rules
6. :feeds Feed scoping rules
7. :comment Comment

Note that both entry attributes are checked, so both score values have the potential to added to any given entry.

For instance, the following rule:

("title-or-content"
  (:text "california" :title-value 150 :content-value 100 :type s))

would add 150 to any element who’s title contains the string “california”, as well as 100 if its content also contains that text.

3.2.4 feed Rules ¶

You can adjust an entry’s score on the basis of the feed that produced it with a “feed” rule. For instance I use this to prioritize certain sources. A feed rule is defined by the following six elements:

1. :text: Match text The text to be matched against the feed title, URL or author
2. :value: Match value The value by which an entry’s score will be adjusted should there be a match
3. :type: Match type The match type as per above.
4. :attr: Feed attribute One of the symbols t, u or a for title, URL, or author respectively; this determines the attribute of the feed against which this rule’s text will be matched.
5. :tags: Tag scoping rules You may wish to apply this rule only to entries that have certain tags (or that do not have certain tags). See below for how to do that.
6. :comment Comment

For example, this rule:

("feed"
  (:text "National Weather Service" :value 400 :type S :attr t))

will check the feed title for each entry against the string “National Weather Service” (case will count). Should there be a match, the corresponding entry will have 400 added to its score.

3.2.5 authors Rules ¶

Some feeds are not produced by a single author. A feed that contains academic papers, for instance, may tag each entry with the authors of the paper to which that entry corresponds. You can score against an entry’s authors with an authors rule.

1. :text: The match text For each entry, if the “authors” meta-data is present, the authors’ names will be concatenated (separated by “, “) and matched against this text for scoring purposes.
2. :value: The match value This is an integer specifying the amount by which the entry’s score should be adjusted, should the text match
3. :type: The match type
4. :tags: Tag scoping rules

   You may wish to apply this rule only to entries that have certain tags (or that do not have certain tags). See below for how to do that.

5. :feeds: Feed scoping rules

   You may wish to apply this rule only to entries that came from certain feeds (or did not come from certain feeds). See below for how to do that.

6. :comment Comment

3.2.6 tag Rules ¶

elfeed allows one to automatically tag new entries as they are discovered. It can therefore be convenient to group entries that come from many different feeds but share a tag or tags. That is the purpose of “tag” rules.

“tag” rules are defined by four properties:

1. :tags: Tags

   The tags whose presence or absence will trigger this rule. They are specified as a cons cell (see cons cell in Emacs Lisp) of the form:

   (switch . tags)
   

   switch is either t or nil and tags is either a tag (i.e. a symbol) or a list of tags. If switch is true, this rule will apply to any entry tagged with one or more tags listed in tags. Conversely, if switch is false, the rule will apply to entries who posses none of the tags in tags.

2. :value: Match value The amount by which an entry’s score shall be adjusted should this rule match.
3. :comment Comment

3.2.7 link Rules ¶

“link rules” are rules that are matched against each entry’s Link attribute. They are similar to title Rules excepting the entry attribute to be matched. For that reason, this section will be brief– refer to title Rules for the details of each element.

In the score file (see The Score File), link rules are represented by seven properties:

1. :text The match text
2. :value The match value
3. :type The match type as per above.
4. :tags Tag scoping rules
5. :feeds Feed scoping rules
6. :comment Comment

As above, only the first three elements are required.

3.2.8 UDF Rules ¶

If none of the other rule types will do, you can define your own scoring function. “UDF“ stands for user-defined function: such a function shall take a single parameter of type elfeed-entry and return either nil (to indicate no interest in this entry) or an integer (representing this rule’s contribution to this entry’s score).

In the score file (see The Score File), UDF rules are represented by five properties:

1. :function The user-defined function; typically this will be a lambda form or a symbol
2. :display-name elfeed-score will attempt to deduce a name for the function; if this value is specified, the given string will be used for logging, pretty-print & so forth
3. :tags Tag scoping rules
4. :feeds Feed scoping rules
5. :comment Comment

3.2.9 adjust-tags Rules ¶

Until now, all the rules have been used to determine an entry’s score. The “adjust-tags” rule (and the “mark” rule below) act on entries after their scores have been determined.

The adust-tags rule was inspired by John Kitchin’s article Scoring Elfeed Articles. He computes a score and adds one or two tags to entries whose score is sufficiently high. It always bothered me that elfeed-score couldn’t do that, so in build 0.4.3, I added this rule type. These will add or remove tags based on whether the entry’s score is above or below a given threshold.

adjust-tags rules are given by four properties:

1. :threshold: The threshold at which the rule shall apply

   This is defined by a cons cell (see cons cell in Emacs Lisp) of the form:

   (switch . threshold)
   

   switch may be t or nil and threshold is the threshold against which each entry’s score shall be compared. If switch is t, the rule applies if the score is greater than or equal to threshold; if switch is nil the rule applies if score is less than or equal to threshold.

2. :tags: The tags to be added or removed

   This is also given by a cons cell

   (switch . tags)
   

   If switch is t & the rule applies, tags (either a single tag or a list of tags) will be added to the entry; if switch is nil, they will be removed

3. :comment Comment

For example, the following rules:

(("adjust-tags"
  (:threshold (t . 1000) :tags (t . a))
  (:threshold (nil . -1000) :tags (nil . b)))

will add the tag 'a to all entries whose score is 1000 or more, and remove tag 'b from all entries whose score is -1000 or less.

3.2.10 mark Rule ¶

Like the “adjust-tag” rule (see above, the mark rule operates on an entry after scoring has completed. If present, it simply specifies an integer; any entry whose score is below this number will be marked as read (in that it will have the 'unread tag removed from it). Since bookmarked elfeed searches typically specify the 'unread tag as a criterion, this essentially means “if an entry’s score is below this number, don’t even show it to me.”

Unlike the other rules, there may only be one mark rule.

Example:

(mark -2500)

3.3.1 Scoping Rules by Tags ¶

“title”, “content”, “title-or-content”, “authors” & “feed” rules can be scoped by tag (see Types of Rules). In the description of each of these type of rules above, you will note a slot reserved for “tag scoping rules”. In each case these rules are expressed as a cons cell of the form:

(boolean . (tag...))

The car is a boolean, and the cdr is a list of tags. If the former is t, the rule will only be applied if the entry has at least one of the tags listed. If the boolean value is nil, the rule will only apply if the entry has *none* of the tags listed.

For instance, this is an entry in my score file at the time of this writing:

("title-or-content
  (:text "workspace" :title-value 150 :content-value 75 :type s
   :date 1611937077.6047099
   :tags (t linux)
   :hits 48)

It performs a case-insensitive substring match against entry title and content, adding 150 & 75 points to an entry’s score on match, respectively. It matched most recently at Friday, January 29, 2021 8:17:57.604 AM PST, and has matched 48 times in total.

Of particular interest here is the fact that it will only be applied to entries with the tag 'linux, since “workspace” is fairly generic term, and I am only specific interested in the term as it applies to Linux window managers.

3.3.2 Scoping Rules by Feed ¶

“title”, “content”, “title-or-content” & “authors” rules can also be scoped by feed; that is, you can arrange to have such rules only apply to entries from certain feeds (or apply only to entries not from certain feeds) (see Types of Rules).

Each of these rule types reserves a slot in their definiotn for “feed scope rules”. Such fules are expressed as a cons cell:

(boolean . ((attr match-type matex-text)...))

The car is a boolean, and the cdr is a list of feed selectors. If the former is t, the rule will only be applied if the entry’s feed matches at least one of the selectors listed. If the boolean value is nil, the rule will only apply if the entry’s feed matches none of the selectors listed.

Each selector is itself a three-tuple consisting of:

1. Feed attribute One of the symbols t, u or a for title, URL, or author respectively; this determines the attribute of the feed against which this rule’s text will be matched.
2. Match type The match type as per above.
3. Match text

Example:

("title"
  (:text "foo" :value 100 :type s
   :feeds (t . ((t S "Bar")))))

This defines a title rule See title Rules that checks for a substring matching “foo” in the entry title and adds 100 points to its score on match. However, it will only match entries originating from feeds whose title contains the string “Bar” (case-sensitive).