From 0999e9726f1d800ed13a0e8d10e48ab3d58d4180 Mon Sep 17 00:00:00 2001 From: Charles Haley Date: Tue, 6 Apr 2021 15:25:09 +0100 Subject: [PATCH] Template documentation updates --- manual/template_lang.rst | 17 ++++++++++------- .../gui2/preferences/template_functions.py | 18 +++++++++--------- 2 files changed, 19 insertions(+), 16 deletions(-) diff --git a/manual/template_lang.rst b/manual/template_lang.rst index bc4a66cef2..259c7fe17d 100644 --- a/manual/template_lang.rst +++ b/manual/template_lang.rst @@ -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:: diff --git a/src/calibre/gui2/preferences/template_functions.py b/src/calibre/gui2/preferences/template_functions.py index c09d2eee1b..43f8a871db 100644 --- a/src/calibre/gui2/preferences/template_functions.py +++ b/src/calibre/gui2/preferences/template_functions.py @@ -75,16 +75,16 @@ class ConfigWidget(ConfigWidgetBase, Ui_Form): ''') self.textBrowser.setHtml(help_text) help_text = '

' + _(''' - 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. ''') + '

' - 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):