From 1193ca30053978e28cbae8f9f5161e1aa3acc841 Mon Sep 17 00:00:00 2001
From: redxef <redxef@redxef.at>
Date: Tue, 19 Nov 2024 21:57:51 +0100
Subject: [PATCH] docs: document SortProgram and give a simple example.

---
 README.md | 23 ++++++++++++++++++++++-
 1 file changed, 22 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 955cfe1..2f8f8d7 100644
--- a/README.md
+++ b/README.md
@@ -29,6 +29,7 @@ Playlists:
   UserId: 6eec632a-ff0d-4d09-aad0-bf9e90b14bc6
 Name: Rock
 Program: (begin (invoke item "IsFavoriteOrLiked" (user)))
+SortProgram: (begin items)
 Filename: /config/data/smartplaylists/Rock.yaml
 Enabled: true
 ```
@@ -84,7 +85,10 @@ still work and remember the correct playlist.
 
 A lisp program to decide on a per item basis if it should be included in
 the playlist, return `nil` to not include items, return any other value
-to include them.
+to include them. Global variables `user` and `item` are predefined
+and contain a [User](https://github.com/jellyfin/jellyfin/blob/master/Jellyfin.Data/Entities/User.cs) and
+[BaseItem](https://github.com/jellyfin/jellyfin/blob/master/MediaBrowser.Controller/Entities/BaseItem.cs)
+respectively.
 
 **!!! The filter expression will include all items matching, if you do
 not specify the kind of item to include/exclude all of them will be
@@ -98,6 +102,23 @@ The configuration page defines some useful functions to make it easier
 to create filters. The above filter for liked items could be simplified
 to: `(is-favourite)`.
 
+### SortProgram
+
+This works exactly like [Program](#program), but the input is the
+user and a list of items (`items`) matched by [Program](#program).
+The default is `(begin items)`, which doesn't sort at all. To sort
+the items by name you could use the following program:
+
+```lisp
+(qsort
+  (lambda
+    (a b)
+    (string>
+      (car (getitems a "Name"))
+      (car (getitems b "Name"))))
+  items)
+```
+
 #### Available definitions
 
 - **lower**: lowercases a string (`(eq (lower "SomeString") "somestring")`)