Cutlery/calibre
1
0
Fork 0
mirror of https://github.com/kovidgoyal/calibre.git synced 2025-07-08 02:34:06 -04:00
Code Issues Packages Projects Releases Wiki Activity

Template documentation updates

Browse Source
This commit is contained in:
Charles Haley 2021-04-06 15:25:09 +01:00
parent 9273370150
commit 0999e9726f
2 changed files with 19 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
manual/template_lang.rst
View File

@ -226,7 +226,8 @@ General Program Mode
times_div_op ::= '*' | '/'
unary_op_expr ::= [ add_sub_op unary_op_expr ]* | expression
expression ::= identifier | constant | function | assignment | field_reference |
if_expression | for_expression | '(' expression_list ')'
if_expr | for_expr | break_expr | continue_expr |
'(' expression_list ')'
field_reference ::= '$' [ '$' ] [ '#' ] identifier
identifier ::= id_start [ id_rest ]*
id_start ::= letter | underscore
@ -234,13 +235,15 @@ General Program Mode
constant ::= " string " | ' string ' | number
function ::= identifier '(' expression_list [ ',' expression_list ]* ')'
assignment ::= identifier '=' top_expression
if_expression ::= 'if' condition 'then' expression_list
[ elif_expression ] [ 'else' expression_list ] 'fi'
if_expr ::= 'if' condition 'then' expression_list
[ elif_expr ] [ 'else' expression_list ] 'fi'
condition ::= top_expression
elif_expression ::= 'elif' condition 'then' expression_list elif_expression | ''
for_expression ::= 'for' identifier 'in' list_expression
elif_expr ::= 'elif' condition 'then' expression_list elif_expr | ''
for_expr ::= 'for' identifier 'in' list_expr
[ 'separator' separator_expr ] ':' expression_list 'rof'
list_expression ::= top_expression
list_expr ::= top_expression
break_expr ::= 'break'
continue_expr ::= 'continue'
separator_expr ::= top_expression
Notes:
@ -317,7 +320,7 @@ As a last example, this program returns the value of the ``series`` column if th
**For Expressions**
The ``for`` expression iterates over a list of values, processing them one at a time. The ``list_expression`` must evaluate to either a metadata field ``lookup name``, for example ``tags`` or ``#genre``, or a list of values. If the result is a valid ``lookup name`` then the field's value is fetched and the separator specified for that field type is used. If the result isn't a valid lookup name then it is assumed to be a list of values. The list is assumed to be separated by commas unless the optional keyword ``separator`` is supplied, in which case the list values must be separated by the result of evaluating the ``separator_expr``. Each value in the list is assigned to the specified variable then the ``expression_list`` is evaluated.
The ``for`` expression iterates over a list of values, processing them one at a time. The ``list_expression`` must evaluate to either a metadata field ``lookup name``, for example ``tags`` or ``#genre``, or a list of values. If the result is a valid ``lookup name`` then the field's value is fetched and the separator specified for that field type is used. If the result isn't a valid lookup name then it is assumed to be a list of values. The list is assumed to be separated by commas unless the optional keyword ``separator`` is supplied, in which case the list values must be separated by the result of evaluating the ``separator_expr``. Each value in the list is assigned to the specified variable then the ``expression_list`` is evaluated. You can use ``break`` to jump out of the loop, and ``continue`` to jump to the beginning of the loop for the next iteration.
Example: This template removes the first hierarchical name for each value in Genre (``#genre``), constructing a list with the new names::

18
src/calibre/gui2/preferences/template_functions.py
View File

@ -75,16 +75,16 @@ class ConfigWidget(ConfigWidgetBase, Ui_Form):
''')
self.textBrowser.setHtml(help_text)
help_text = '<p>' + _('''
Here you can add and remove stored templates used in template processing.
You use a stored template in another template with the '{0}' template
function, as in '{0}(some_name, arguments...)'. Stored templates must use
General Program Mode -- they must begin with the text '{1}'.
In the stored template you retrieve the arguments using the '{2}()'
template function, as in '{2}(var1, var2, ...)'. The calling arguments
are copied to the named variables. See the template language tutorial
for more information.
Here you can create, edit (replace), and delete stored templates used
in template processing. You use a stored template in another template as
if it were a template function, for example 'some_name(arg1, arg2...)'.
Stored templates must use General Program Mode -- they must begin with
the text '{0}'. You retrieve arguments passed to a stored template using
the '{1}()' template function, as in '{1}(var1, var2, ...)'. The passed
arguments are copied to the named variables. See the template language
tutorial for more information.
''') + '</p>'
self.st_textBrowser.setHtml(help_text.format('call', 'program:', 'arguments'))
self.st_textBrowser.setHtml(help_text.format('program:', 'arguments'))
self.st_textBrowser.adjustSize()
def initialize(self):