Extend documentation

README.rst

@@ -266,161 +266,193 @@ Fields
 Functions
 ^^^^^^^^^
 
-:: 
+alpha
+ ``%alpha{text}``: This function first ASCIIfies the given text, then all
+ non alphabet characters are replaced with whitespaces.
+
+ **Example:** ``%alpha{a1b23c}`` → ``a b c``
+
+alphanum
+ ``%alphanum{text}``: This function first ASCIIfies the given text, then all
+ non alpanumeric characters are replaced with whitespaces.
+
+ **Example:** ``%alphanum{après-évêque1}`` → ``apres eveque1``
+
+asciify
+ ``%asciify{text}``: Translate non-ASCII characters to their ASCII
+ equivalents. For example, “café” becomes “cafe”. Uses the mapping provided
+ by the unidecode module.
+
+ **Example:** ``%asciify{äÄöÖüÜ}`` → ``aeAeoeOeueUe``
+
+delchars
+ ``%delchars{text,chars}``: Delete every single character of “chars“ in
+ “text”.
+
+ **Example:** ``%delchars{Schubert, ue}`` → ``Schbrt``
 
- alpha
- -----
+deldupchars
+ ``%deldupchars{text,chars}``: Search for duplicate characters and replace
+ with only one occurrance of this characters.
 
- %alpha{text}
- This function first ASCIIfies the given text, then all non alphabet
- characters are replaced with whitespaces.
+ **Example:** ``%deldupchars{a---b___c...d}`` → ``a-b_c.d``; ``%deldupchars{a
+ ---b___c, -}`` → ``a-b___c``
 
- alphanum
- --------
+first
+ ``%first{text}`` or ``%first{text,count,skip}`` or
+ ``%first{text,count,skip,sep,join}``: Returns the first item, separated by
+ ``;``. You can use ``%first{text,count,skip}``, where count is the number of
+ items (default 1) and skip is number to skip (default 0). You can also use
+ ``%first{text,count,skip,sep,join}`` where ``sep`` is the separator, like
+ ``;`` or ``/`` and join is the text to concatenate the items.
 
- %alphanum{text}
- This function first ASCIIfies the given text, then all non alpanumeric
- characters are replaced with whitespaces.
+ **Example:** ``%first{Alice / Bob / Eve,2,0, / , & }`` → ``Alice & Bob``
 
- asciify
- -------
+if
+ ``%if{condition,trueval}`` or ``%if{condition,trueval,falseval}``: 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 ``falseval`` is left off).
 
- %asciify{text}
- Translate non-ASCII characters to their ASCII equivalents. For
- example, “café” becomes “cafe”. Uses the mapping provided by the
- unidecode module.
+ **Example:** ``x%if{false,foo}`` → ``x``
 
- delchars
- --------
+ifdef
+ ``%ifdef{field}``, ``%ifdef{field,trueval}`` or
+ ``%ifdef{field,trueval,falseval}``: If field exists, then return
+ ``trueval`` or field (default). Otherwise, returns ``falseval``. The field
+ should be entered without ``$``.
 
- %delchars{text,chars}
- Delete every single character of “chars“ in “text”.
+ **Example:** ``%ifdef{compilation,Compilation}``
 
- deldupchars
- -----------
+ifdefempty
+ ``%ifdefempty{field,text}`` or ``%ifdefempty{field,text,falsetext}``: If
+ field exists and is empty, then return ``truetext``. Otherwise, returns
+ ``falsetext``. The field should be entered without ``$``.
 
- %deldupchars{text,chars}
- Search for duplicate characters and replace with only one occurrance
- of this characters.
+ **Example:** ``%ifdefempty{compilation,Album,Compilation}``
 
- first
- -----
+ifdefnotempty
+ ``%ifdefnotempty{field,text}`` or ``%ifdefnotempty{field,text,falsetext}``:
+ If field is not empty, then return ``truetext``. Otherwise, returns
+ ``falsetext``. The field should be entered without ``$``.
 
- %first{text} or %first{text,count,skip} or
- %first{text,count,skip,sep,join}
- Returns the first item, separated by ; . You can use
- %first{text,count,skip}, where count is the number of items (default
- 1) and skip is number to skip (default 0). You can also use
- %first{text,count,skip,sep,join} where sep is the separator, like ; or
- / and join is the text to concatenate the items.
+ **Example:** ``%ifdefnotempty{compilation,Compilation,Album}``
 
- if
- --
+initial
+ ``%initial{text}``: Get the first character of a text in lowercase. The
+ text is converted to ASCII. All non word characters are erased.
 
- %if{condition,truetext} 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).
+ **Example:** ``%initial{Schubert}`` → ``s``
 
- ifdef
-  -----
+left
+ ``%left{text,n}``: Return the first “n” characters of “text”.
 
- %ifdef{field}, %ifdef{field,text} or %ifdef{field,text,falsetext}
- If field exists, then return truetext or field (default). Otherwise,
- returns falsetext. The field should be entered without $.
+ **Example:** ``%left{Schubert, 3}`` → ``Sch``
 
- ifdefempty
-  ----------
+lower
+ ``%lower{text}``: Convert “text” to lowercase.
 
- %ifdefempty{field,text} or %ifdefempty{field,text,falsetext}
- If field exists and is empty, then return truetext. Otherwise, returns
- falsetext. The field should be entered without $.
+ **Example:** ``%lower{SCHUBERT}`` → ``schubert``
 
- ifdefnotempty
- -------------
+nowhitespace
+ ``%nowhitespace{text,replace}``: Replace all whitespace characters with
+ ``replace``. By default: a dash (``-``)
 
- %ifdefnotempty{field,text} or %ifdefnotempty{field,text,falsetext}
- If field is not empty, then return truetext. Otherwise, returns
- falsetext. The field should be entered without $.
+ **Example:** ``%nowhitespace{a b}`` → ``a-b``; ``%nowhitespace{a b, _}`` →
+ ``a_b``
 
- initial
-  -------
+num
+ ``%num{number,count}``: Pad decimal number with leading zeros.
 
- %initial{text}
- Get the first character of a text in lowercase. The text is converted
- to ASCII. All non word characters are erased.
+ **Example:** ``%num{7,3}`` → ``007``
 
- left
- ----
+replchars
+ ``%replchars{text,chars,replace}``: Replace the characters “chars” in
+ “text” with “replace”.
 
- %left{text,n}
- Return the first “n” characters of “text”.
+ **Example:** ``%replchars{Schubert,-,ue}`` → ``Sch-b-rt``
 
- lower
-  -----
+right
+ ``%right{text,n}``: Return the last “n” characters of “text”.
 
- %lower{text}
- Convert “text” to lowercase.
+ **Example:** ``%right{Schubert,3}`` → ``ert``
 
- nowhitespace
- ------------
+sanitize
+ ``%sanitize{text}``: Delete characters that are not allowed in most file
+ systems.
 
- %nowhitespace{text,replace}
- Replace all whitespace characters with replace. By default: a dash (-)
- %nowhitespace{$track,_}
+ **Example:** ``%sanitize{x:*?<>|/~&x}`` → ``xx``
 
- num
- ---
+shorten
+ ``%shorten{text}`` or ``%shorten{text,max_size}``: Shorten “text” on word
+ boundarys.
 
- %num{number,count}
- Pad decimal number with leading zeros.
- %num{$track,3}
+ **Example:** ``%shorten{Lorem ipsum dolor sit, 10}`` → ``Lorem``
 
- replchars
- ---------
+time
+ ``%time{date_time,format,curformat}``: Return the date and time in any
+ format accepted by ``strftime``. For example, to get the year, use
+ ``%time{$added,%Y}``.
 
- %replchars{text,chars,replace}
- Replace the characters “chars” in “text” with “replace”.
- %replchars{text,ex,-} > t--t
+ **Example:** ``%time{30 Nov 2024,%Y,%d %b %Y}`` → ``2024``
 
- right
-  -----
+title
+ ``%title{text}``: Convert “text” to Title Case.
 
- %right{text,n}
- Return the last “n” characters of “text”.
+ **Example:** ``%title{franz schubert}`` → ``Franz Schubert``
 
- sanitize
-  --------
+upper
+ ``%upper{text}``: Convert “text” to UPPERCASE.
 
- %sanitize{text}
- Delete in most file systems not allowed characters.
+ **Example:** ``%upper{foo}`` → ``FOO``
 
- shorten
- -------
+Template Symbols (or Variables)
+ In path templates, symbols or varialbes such as ``$title``
+ (any name with the prefix ``$``) are replaced by the corresponding value.
 
- %shorten{text} or %shorten{text,max_size}
- Shorten “text” on word boundarys.
- %shorten{$title,32}
+ 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 a field name from the
+ text that follows it.
 
- time
- ----
+.. _Python template strings: https://docs.python.org/library/string.html#template-strings
 
- %time{date_time,format,curformat}
- Return the date and time in any format accepted by strftime. For
- example, to get the year some music was added to your library, use
- %time{$added,%Y}.
+Template Functions (or Macros)
+ Path templates 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{lorem ipsum}`` will be replaced with ``LOREM IPSUM``.
+ You can, of course, nest function calls and place variable references in
+ function arguments, so ``%upper{$title}`` becomes the upper-case version of the
+ title.
 
- title
- -----
+Syntax Details
+ The characters ``$``, ``%``, ``{``, ``}``, and ``,`` are “special” in the path
+ template syntax. This means that, for example, if you want a ``%`` character to
+ appear in your paths, you’ll need to be careful that you don’t accidentally
+ write a function call. To escape any of these characters (except ``{``, and
+ ``,`` outside a function argument), prefix it with a ``$``. For example,
+ ``$$`` becomes ``$``; ``$%`` becomes ``%``, etc. The only exceptions are:
 
- %title{text}
- Convert “text” to Title Case.
+ * ``${``, which is ambiguous with the variable reference syntax (like
+ ``${title}``). To insert a ``{`` alone, it's always sufficient to just type
+ ``{``.
+ * commas are used as argument separators in function calls. Inside of a
+ function’s argument, use ``$,`` to get a literal ``,`` character. Outside of
+ any function argument, escaping is not necessary: ``,`` by itself will
+ produce ``,`` in the output.
 
- upper
- -----
+ If a value or function is undefined, the syntax is simply left unreplaced. For
+ example, if you write ``$foo`` in a path template, this will yield ``$foo`` in
+ the resulting paths because "foo" is not a valid field name. The same is true of
+ syntax errors like unclosed ``{}`` pairs; if you ever see template syntax
+ constructs leaking into your paths, check your template for errors.
 
- %upper{text}
- Convert “text” to UPPERCASE.
+ If an error occurs in the Python code that implements a function, the function
+ call will be expanded to a string that describes the exception so you can debug
+ your template. For example, the second parameter to ``%left`` must be an
+ integer; if you write ``%left{foo,bar}``, this will be expanded to something
+ like ``<ValueError: invalid literal for int()>``.
 
 The following example assumes that the folder ``/home/xyz/messy-leadsheets``
 contains the following three MuseScore files: ``folsom prison blues.mscz``,

README_template.rst

@@ -231,7 +231,9 @@ Fields
 Functions
 ^^^^^^^^^
 
-{{ cli('musescore-manager --list-functions') | literal }}
+{{ cli('tmep-doc --functions-rst') }}
+
+{{ cli('tmep-doc --introduction-rst') }}
 
 The following example assumes that the folder ``/home/xyz/messy-leadsheets``
 contains the following three MuseScore files: ``folsom prison blues.mscz``,