From 0b067e9f5b25b7b3583a08f6b83c5b5949f01773 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?T=C3=A2nio=20Scherer?= <tanioms3@gmail.com>
Date: Wed, 28 Aug 2024 21:31:36 -0300
Subject: [PATCH] Create a new template function: capitalize

Update documentation

Update changelog
---
 beets/library.py              | 5 +++++
 docs/changelog.rst            | 2 ++
 docs/reference/pathformat.rst | 1 +
 test/test_library.py          | 4 ++++
 4 files changed, 12 insertions(+)

diff --git a/beets/library.py b/beets/library.py
index 84f6a7bf0..b97a80b13 100644
--- a/beets/library.py
+++ b/beets/library.py
@@ -1783,6 +1783,11 @@ class DefaultTemplateFunctions:
         """Convert a string to upper case."""
         return s.upper()
 
+    @staticmethod
+    def tmpl_capitalize(s):
+        """Converts to a capitalized string."""
+        return s.capitalize()
+
     @staticmethod
     def tmpl_title(s):
         """Convert a string to title case."""
diff --git a/docs/changelog.rst b/docs/changelog.rst
index 38997d4a9..bb36281e8 100644
--- a/docs/changelog.rst
+++ b/docs/changelog.rst
@@ -8,6 +8,8 @@ Changelog goes here! Please add your entry to the bottom of one of the lists bel
 
 New features:
 
+* New template function added: ``%capitalize``. Converts the first letter of
+  the text to uppercase and the rest to lowercase.
 * Ability to query albums with track db fields and vice-versa, for example
   `beet list -a title:something` or `beet list artpath:cover`. Consequently
   album queries involving `path` field have been sped up, like `beet list -a
diff --git a/docs/reference/pathformat.rst b/docs/reference/pathformat.rst
index 7c52a92eb..d80bdec34 100644
--- a/docs/reference/pathformat.rst
+++ b/docs/reference/pathformat.rst
@@ -60,6 +60,7 @@ These functions are built in to beets:
 
 * ``%lower{text}``: Convert ``text`` to lowercase.
 * ``%upper{text}``: Convert ``text`` to UPPERCASE.
+* ``%capitalize{text}``: Make the first letter of ``text`` UPPERCASE and the rest lowercase.
 * ``%title{text}``: Convert ``text`` to Title Case.
 * ``%left{text,n}``: Return the first ``n`` characters of ``text``.
 * ``%right{text,n}``: Return the last ``n`` characters of  ``text``.
diff --git a/test/test_library.py b/test/test_library.py
index 4e9c50b44..9b29505a3 100644
--- a/test/test_library.py
+++ b/test/test_library.py
@@ -629,6 +629,10 @@ class DestinationFunctionTest(BeetsTestCase, PathFormattingMixin):
         self._setf("%upper{$title}")
         self._assert_dest(b"/base/THE TITLE")
 
+    def test_capitalize_variable(self):
+        self._setf("%capitalize{$title}")
+        self._assert_dest(b"/base/The title")
+
     def test_title_case_variable(self):
         self._setf("%title{$title}")
         self._assert_dest(b"/base/The Title")