documentation for function calls (#231)

docs/changelog.rst

@@ -4,6 +4,12 @@ Changelog
 1.0b12 (in development)
 -----------------------
 
+This release focuses on making beets' path formatting vastly more powerful.
+
+* **Functions in path formats** provide a simple way to write complex file
+  naming rules: for example, ``%upper{%left{$artist,1}}`` will insert the
+  capitalized first letter of the track's artist. For more details, see
+  :doc:`/reference/pathformat`.
 * Fix an incompatibility in BPD with libmpc (the library that powers mpc and
   ncmpc).
 

docs/reference/pathformat.rst

@@ -2,12 +2,13 @@ Path Formats
 ============
 
 The ``[paths]`` section of the config file (see :doc:`config`) lets
-you specify the directory and file naming scheme for your music library. You
-specify templates using Python template string notation---that is, prefixing
-names with ``$`` characters---and beets fills in the appropriate values.
+you specify the directory and file naming scheme for your music library.
+Templates substitute symbols like ``$title`` (any field value prefixed by ``$``)
+with the appropriate value from the track's metadata. Beets adds the filename
+extension automatically.
 
-For example, consider this path format string: ``$albumartist/$album/$track
-$title``
+For example, consider this path format string:
+``$albumartist/$album/$track $title``
 
 Here are some paths this format will generate:
 
@@ -17,6 +18,17 @@ Here are some paths this format will generate:
 
 * ``The Magnetic Fields/Realism/01 You Must Be Out of Your Mind.mp3``
 
+Because ``$`` is used to delineate a field reference, you can use ``$$`` to emit
+a dollars sign. As with `Python template strings`_, ``${title}`` is equivalent
+to ``$title``; you can use this if you need to separate the field name from the
+following text.
+
+.. _Python template strings: http://docs.python.org/library/string.html#template-strings
+
+
+A Note About Artists
+--------------------
+
 Note that in path formats, you almost certainly want to use ``$albumartist`` and
 not ``$artist``. The latter refers to the "track artist" when it is present,
 which means that albums that have tracks from different artists on them (like
@@ -30,18 +42,32 @@ probably don't want that! So use ``$albumartist``.
 
 As a convenience, however, beets allows ``$albumartist`` to fall back to the value for ``$artist`` and vice-versa if one tag is present but the other is not.
 
-Upgrading from 1.0b6
---------------------
 
-Versions of beets prior to 1.0b7 didn't use a ``[paths]`` section. Instead, they
-used a single ``path_format`` setting for all music. To support old
-configuration files, this setting is still respected and overrides the default
-path formats. However, the setting is deprecated and, if you want to use
-flexible path formats, you need to remove the ``path_format`` setting and use a
-``[paths]`` section instead.
+Functions
+---------
 
-Possible Values
----------------
+Beets path formats also support *function calls*, which can be used to transform
+text and perform logical manipulations. The syntax for function calls is like
+this: ``%func{arg,arg}``. For example, the ``upper`` function makes its argument
+upper-case, so ``%upper{beets rocks}`` will be replaced with ``BEETS ROCKS``.
+You can, of course, nest function calls and place variable references in
+function arguments, so ``%upper{$artist}`` becomes the upper-case version of the
+track's artists.
+
+These functions are built in to beets:
+
+* ``%lower{text}``: Convert ``text`` to lowercase. 
+* ``%upper{text}``: Convert ``text`` to UPPERCASE.
+* ``%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``.
+* ``%if{condition,text}`` or ``%if{condition,truetext,falsetext}``: If
+  ``condition`` is nonempty (or nonzero, if it's a number), then returns
+  the second argument. Otherwise, returns the third argument if specified (or
+  nothing if ``falsetext`` is left off).
+
+Available Values
+----------------
 
 Here's a (comprehensive?) list of the different values available to path
 formats. (I will try to keep it up to date, but I might forget. The current list