Add README

README.org

@@ -0,0 +1,71 @@
+#+title: elfeed-prune
+#+author: Bram Schoenmakers <me@bramschoenmakers.nl>
+
+* Introduction
+
+/elfeed-prune/ is a hack that allows you to remove items from the elfeed database. *Use at your own risk, elfeed was not designed to support this*.
+
+[[https://github.com/skeeto/elfeed][elfeed]] is a powerful and customizable RSS reader for Emacs. It's performing well with thousands of entries stored in the database, thanks to the design choices that were made to implement it. However, removing entries [[https://nullprogram.com/blog/2013/11/26/][wasn't considered a use-case]] and elfeed doesn't provide such functionality.
+
+This package provides the =elfeed-prune= command, which removes entries that match a predicate from the database. It messes with the internal database structure to remove entries. It's wise to make a backup of your ~/.elfeed folder, this package won't do it for you.
+
+* Installation
+
+Simply clone this repository and put it in your =load-path=.
+
+This package will never be provided on MELPA, as it is a glorified hack for elfeed. Again, use at your own risk.
+
+* Configuration
+
+| Variable                     | Default | Description                                                   |
+|------------------------------+---------+---------------------------------------------------------------|
+| elfeed-prune-enable          | nil     | Enable the package, otherwise it will perform dry runs only.  |
+| elfeed-prune-predicates      |         | List of functions to evaluate if an entry should be pruned.   |
+| elfeed-prune-keep-predicates |         | List of functions to evaluate if an entry should be kept.     |
+| elfeed-prune-days-read       | 90      | Read entries older than this amount of days will be pruned.   |
+| elfeed-prune-days-unread     | 30      | Unread entries older than this amount of days will be pruned. |
+| elfeed-prune-gc              | t       | Remove content of pruned entries.                             |
+
+By default, items will be pruned based on their age, or if they belong to a feed that's no longer in your =elfeed-feeds= variable.
+
+A predicate can be added to =elfeed-prune-predicates= or =elfeed-prune-keep-predicates=, which is a function that takes two parameters: an (elfeed) entry object and a feed object that corresponds to that entry..
+
+Any predicate in =elfeed-prune-predicates= that returns =t= gets pruned, unless any predicate in =elfeed-prune-keep-predicates= returns =t= for that same entry.
+
+Below there are some additional predicates that you could add, using scoring or tagging.
+
+** use-package example
+
+#+begin_src elisp
+  (use-package elfeed-prune
+    :after elfeed
+    :commands
+    elfeed-prune
+    :ensure nil
+    :load-path "lisp/elfeed-prune"
+    ;; :custom
+    ;; (elfeed-prune-enable nil)
+    :config
+    (defun bram85-elfeed-prune-entry-score-too-low-p (entry _)
+      (let ((score (elfeed-score-scoring-get-score-from-entry entry)))
+        (<= score -5)))
+
+    (add-to-list 'elfeed-prune-predicates
+                 #'bram85-elfeed-prune-entry-score-too-low-p)
+
+    (defun bram85-elfeed-prune-entry-high-score-p (entry _)
+      (let ((score (elfeed-score-scoring-get-score-from-entry entry)))
+        (> score 2)))
+
+    (add-to-list 'elfeed-prune-keep-predicates
+                 #'bram85-elfeed-prune-entry-high-score-p)
+
+    ;; Keep entries that have the 'star' tag.
+    (defun bram85-elfeed-prune-entry-starred-p (entry _)
+      "Returns t iff the ENTRY has a star tag."
+      (let ((tags (elfeed-entry-tags entry)))
+        (seq-contains-p tags 'star)))
+
+    (add-to-list 'elfeed-prune-keep-predicates
+                 #'bram85-elfeed-prune-entry-starred-p))
+#+end_src