Debian Codegraph @

translations/manual/template_lang.pot

raw
1 # SOME DESCRIPTIVE TITLE.
2 # Copyright (C) Kovid Goyal
3 # This file is distributed under the same license as the calibre package.
4 # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
5 #
6 #, fuzzy
7 msgid ""
8 msgstr ""
9 "Project-Id-Version: calibre 9.15.0\n"
10 "Report-Msgid-Bugs-To: \n"
11 "POT-Creation-Date: 2026-09-18 07:37+0530\n"
12 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
13 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
14 "Language-Team: LANGUAGE <[email protected]>\n"
15 "MIME-Version: 1.0\n"
16 "Content-Type: text/plain; charset=UTF-8\n"
17 "Content-Transfer-Encoding: 8bit\n"
18
19 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:4
20 msgid "The calibre template language"
21 msgstr ""
22
23 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:6
24 msgid "The calibre template language is a calibre-specific language used throughout calibre for tasks such as specifying file paths, formatting values, and computing the value for user-specified columns. Examples:"
25 msgstr ""
26
27 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:8
28 msgid "Specify the folder structure and file names when saving files from the calibre library to the disk or e-book reader."
29 msgstr ""
30
31 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:9
32 msgid "Define rules for adding icons and colors to the calibre book list."
33 msgstr ""
34
35 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:10
36 msgid "Define `virtual columns` that contain data from other columns."
37 msgstr ""
38
39 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:11
40 msgid "Advanced library searching."
41 msgstr ""
42
43 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:12
44 msgid "Advanced metadata search and replace."
45 msgstr ""
46
47 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:14
48 msgid "The language is built around the notion of a `template`, which specifies which book metadata to use, computations on that metadata, and how it is to be formatted."
49 msgstr ""
50
51 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:17
52 msgid "Basic templates"
53 msgstr ""
54
55 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:19
56 msgid "A basic template consists of one or more ``template expressions``. A ``template expression`` consists of text and names in curly brackets (``{}``) that is replaced by the corresponding metadata from the book being processed. For example, the default template in calibre used for saving books to device has 4 ``template expressions``::"
57 msgstr ""
58
59 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:23
60 msgid "For the book \"The Foundation\" by \"Isaac Asimov\" the template will become::"
61 msgstr ""
62
63 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:27
64 msgid "The slashes are not ``template expressions`` because they are not in between ``{}``. Such text is left where it appears. For example, if the template is::"
65 msgstr ""
66
67 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:31
68 msgid "then for \"The Foundation\" the template produces::"
69 msgstr ""
70
71 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:35
72 msgid "A ``template expression`` can access all the metadata available in calibre, including custom columns (columns you create yourself), by using a column's ``lookup name``. To find the lookup name for a `column` (sometimes called `fields`), hover your mouse over the column header in calibre's book list. Lookup names for custom columns always begin with ``#``. For series type columns there is an additional field named ``#lookup name_index`` that is the series index for that book in the series. For example, if you have a custom series column named ``#myseries``, there will also be a column named ``#myseries_index``. The standard series column's index is named ``series_index``."
73 msgstr ""
74
75 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:37
76 msgid "In addition to the standard column based fields, you also can use:"
77 msgstr ""
78
79 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:39
80 msgid "``{formats}`` - A list of formats available in the calibre library for a book"
81 msgstr ""
82
83 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:40
84 msgid "``{identifiers:select(isbn)}`` - The ISBN of the book"
85 msgstr ""
86
87 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:42
88 msgid "If the metadata for the field for a given book is not defined then the field in the template is replaced by the empty string (``''``). For example, consider the following template::"
89 msgstr ""
90
91 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:46
92 msgid "If Asimov's book \"Second Foundation\" is in the series \"Foundation\" then the template produces::"
93 msgstr ""
94
95 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:50
96 msgid "If a series has not been entered for the book then the template produces::"
97 msgstr ""
98
99 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:54
100 msgid "The template processor automatically removes multiple slashes and leading or trailing spaces."
101 msgstr ""
102
103 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:57
104 msgid "Advanced formatting"
105 msgstr ""
106
107 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:59
108 msgid "In addition to metadata substitution, templates can conditionally include additional text and control how substituted data is formatted."
109 msgstr ""
110
111 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:61
112 msgid "**Conditionally including text**"
113 msgstr ""
114
115 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:63
116 msgid "Sometimes you want text to appear in the output only if a field is not empty. A common case is ``series`` and ``series_index`` where you want either nothing or the two values separated by a hyphen. calibre handles this case using a special ``template expression`` syntax."
117 msgstr ""
118
119 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:65
120 msgid "For example and using the above Foundation example, assume you want the template to produce `Foundation - 3 - Second Foundation`. This template produces that output:"
121 msgstr ""
122
123 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:67
124 msgid "``{series} - {series_index} - {title}``"
125 msgstr ""
126
127 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:69
128 msgid "However, if a book has no series the template will produce `- - the title`, which is probably not what you want. Generally, people want the result be the title without the extraneous hyphens. You can accomplish this using the following template syntax:"
129 msgstr ""
130
131 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:71
132 msgid "``{field:|prefix_text|suffix_text}``"
133 msgstr ""
134
135 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:73
136 msgid "This ``template expression`` says that if ``field`` has the value `XXXX` then the result will be `prefix_textXXXXXsuffix_text`. If ``field`` is empty (has no value) then the result will be the empty string (nothing) because the prefix and suffix are ignored. The prefix and suffix can contain blanks."
137 msgstr ""
138
139 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:75
140 msgid "**Do not use subtemplates (`{ ... }`) or functions (see below) in the prefix or the suffix.**"
141 msgstr ""
142
143 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:77
144 msgid "Using this syntax, we can solve the above no-series problem with the template::"
145 msgstr ""
146
147 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:81
148 msgid "The hyphens will be included only if the book has a series index, which it has only if it has a series. Continuing the Foundation example again, the template will produce `Foundation - 1 - Second Foundation`."
149 msgstr ""
150
151 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:83
152 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:293
153 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:469
154 msgid "Notes:"
155 msgstr ""
156
157 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:85
158 msgid "You must include the colon after the ``lookup name`` if you are using a prefix or a suffix."
159 msgstr ""
160
161 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:86
162 msgid "You must use either no or both ``|`` characters. Using one, as in ``{field:| - }``, is not allowed."
163 msgstr ""
164
165 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:87
166 msgid "It is OK to provide no text for either the prefix or the suffix, such as in ``{series:|| - }``. The template ``{title:||}`` is the same as ``{title}``."
167 msgstr ""
168
169 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:89
170 msgid "**Formatting**"
171 msgstr ""
172
173 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:91
174 msgid "Suppose you want the ``series_index`` to be formatted as three digits with leading zeros. This does the trick:"
175 msgstr ""
176
177 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:93
178 msgid "``{series_index:0>3s}`` - Three digits with leading zeros"
179 msgstr ""
180
181 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:95
182 msgid "For trailing zeros, use:"
183 msgstr ""
184
185 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:97
186 msgid "``{series_index:0<3s}`` - Three digits with trailing zeros"
187 msgstr ""
188
189 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:99
190 msgid "If you use series indices with fractional values, e.g., 1.1, you might want the decimal points to line up. For example, you might want the indices 1 and 2.5 to appear as 01.00 and 02.50 so that they will sort correctly on a device that does lexical sorting. To do this, use:"
191 msgstr ""
192
193 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:101
194 msgid "``{series_index:0>5.2f}`` - Five characters consisting of two digits with leading zeros, a decimal point, then 2 digits after the decimal point."
195 msgstr ""
196
197 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:103
198 msgid "If you want only the first two letters of the data, use:"
199 msgstr ""
200
201 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:105
202 msgid "``{author_sort:.2}`` - Only the first two letters of the author sort name"
203 msgstr ""
204
205 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:107
206 msgid "Much of the calibre template language formatting comes from Python. For more details on the syntax of these advanced formatting operations see the `Python documentation <https://docs.python.org/3/library/string.html#formatstrings>`_."
207 msgstr ""
208
209 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:111
210 msgid "Using templates to define custom columns"
211 msgstr ""
212
213 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:113
214 msgid "Templates can be used to display information that isn't in calibre metadata, or to display metadata differently from calibre's normal format. For example, you might want to show the ``ISBN``, a field that calibre does not display. You can accomplish this creating a custom column with the type `Column built from other columns` (hereafter called `composite columns`) and providing a template to generate the displayed text. The column will display the result of evaluating the template. For example, to display the ISBN, create the column and enter ``{identifiers:select(isbn)}`` in the template box. To display a column containing the values of two series custom columns, separated by a comma, use ``{#series1:||,}{#series2}``."
215 msgstr ""
216
217 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:115
218 msgid "Composite columns can use any template option, including formatting."
219 msgstr ""
220
221 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:117
222 msgid "Note: You cannot edit the data displayed in a composite column. Instead you edit the source columns. If you edit a composite column, for example by double-clicking it, calibre will open the template for editing, not the underlying data."
223 msgstr ""
224
225 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:121
226 msgid "Templates and plugboards"
227 msgstr ""
228
229 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:123
230 msgid "Plugboards are used for changing the metadata written into books during send-to-device and save-to-disk operations. A plugboard permits you to specify a template to provide the data to write into the book's metadata. You can use plugboards to modify the following fields: authors, author_sort, language, publisher, tags, title, title_sort. This feature helps people who want to use different metadata in books on devices to solve sorting or display issues."
231 msgstr ""
232
233 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:125
234 msgid "When you create a plugboard, you specify the format and device for which the plugboard is to be used. A special device is provided, ``save_to_disk``, that is used when saving formats (as opposed to sending them to a device). Once you have chosen the format and device, you choose the metadata fields to change, providing templates to supply the new values. These templates are `connected` to their destination fields, hence the name `plugboards`. You can of course use composite columns in these templates."
235 msgstr ""
236
237 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:127
238 msgid "Plugboards are quite flexible and can be written in Single Function Mode, Template Program Mode, General Program Mode, or Python Template mode."
239 msgstr ""
240
241 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:129
242 msgid "When a plugboard might apply (Content server, save to disk, or send to device), calibre searches the defined plugboards to choose the correct one for the given format and device. For example, to find the appropriate plugboard for an EPUB book being sent to an ANDROID device, calibre searches the plugboards using the following search order:"
243 msgstr ""
244
245 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:133
246 msgid "a plugboard with an exact match on format and device, e.g., ``EPUB`` and ``ANDROID``"
247 msgstr ""
248
249 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:134
250 msgid "a plugboard with an exact match on format and the special ``any device`` choice, e.g., ``EPUB`` and ``any device``"
251 msgstr ""
252
253 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:135
254 msgid "a plugboard with the special ``any format`` choice and an exact match on device, e.g., ``any format`` and ``ANDROID``"
255 msgstr ""
256
257 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:136
258 msgid "a plugboard with ``any format`` and ``any device``"
259 msgstr ""
260
261 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:138
262 msgid "The tags and authors fields have special treatment, because both of these fields can hold more than one item. A book can have many tags and many authors. When you specify that one of these two fields is to be changed, the template's result is examined to see if more than one item is there. For tags, the result is cut apart wherever calibre finds a comma. For example, if the template produces the value ``Thriller, Horror``, then the result will be two tags, ``Thriller`` and ``Horror``. There is no way to put a comma in the middle of a tag."
263 msgstr ""
264
265 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:141
266 msgid "The same thing happens for authors, but using a different character for the cut, a `&` (ampersand) instead of a comma. For example, if the template produces the value ``Blogs, Joe&Posts, Susan``, then the book will end up with two authors, ``Blogs, Joe`` and ``Posts, Susan``. If the template produces the value ``Blogs, Joe;Posts, Susan``, then the book will have one author with a rather strange name."
267 msgstr ""
268
269 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:143
270 msgid "Plugboards affect the metadata written into the book when it is saved to disk or written to the device. Plugboards do not affect the metadata used by ``save to disk`` and ``send to device`` to create the file names. Instead, file names are constructed using the templates entered on the appropriate preferences window."
271 msgstr ""
272
273 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:148
274 msgid "Using functions in templates - Single Function Mode"
275 msgstr ""
276
277 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:150
278 msgid "Suppose you want to display the value of a field in upper case when that field is normally in title case. You can do this using `template functions`. For example, to display the title in upper case use the ``uppercase`` function, as in ``{title:uppercase()}``. To display it in title case, use ``{title:titlecase()}``."
279 msgstr ""
280
281 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:152
282 msgid "Functions go into the format part of the template, after the ``:`` and before the first ``|`` or the closing ``}`` if no prefix/suffix is used. If you have both a format and a function reference, the function comes after a second ``:``. Functions return the value of the column specified in the template, suitably modified."
283 msgstr ""
284
285 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:154
286 msgid "The syntax for using functions is one of::"
287 msgstr ""
288
289 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:161
290 msgid "Function names must always be followed by opening and closing parentheses. Some functions require extra values (arguments), and these go inside the parentheses. Arguments are separated by commas. Literal commas (commas as text, not argument separators) must be preceded by a backslash (``\\``) . The last (or only) argument cannot contain a textual closing parenthesis."
291 msgstr ""
292
293 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:163
294 msgid "Functions are evaluated before format specifications and the prefix/suffix. See further down for an example of using both a format and a function."
295 msgstr ""
296
297 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:165
298 msgid "**Important**: If you have programming experience, please note that the syntax in `Single Function Mode` is not what you expect. Strings are not quoted and spaces are significant. All arguments are considered to be constants; there are no expressions."
299 msgstr ""
300
301 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:167
302 msgid "**Do not use subtemplates (`{ ... }`) as function arguments.** Instead, use :ref:`Template Program Mode <template_mode>` and :ref:`General Program Mode <general_mode>`."
303 msgstr ""
304
305 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:169
306 msgid "Notes on calling functions in Single Function Mode:"
307 msgstr ""
308
309 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:171
310 msgid "When functions are used in Single Function Mode, the first parameter, ``value``, is automatically replaced by the content of the field specified in the template. For example, when the template ``{title:capitalize()}`` is processed, the content of the ``title`` field is passed as the parameter ``value`` to the capitalize function."
311 msgstr ""
312
313 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:172
314 msgid "In the function documentation, the notation ``[something]*`` means that ``something`` can be repeated zero or more times. The notation ``[something]+`` means that the ``something`` is repeated one or more times (must exist at least one time)."
315 msgstr ""
316
317 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:173
318 msgid "Some functions use regular expressions. In the template language regular expression matching is case-insensitive."
319 msgstr ""
320
321 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:175
322 msgid "Functions are documented in :ref:`template_functions_reference`. The documentation tells you what arguments the functions require and what the functions do. For example, here is the documentation of the :ref:`ff_ifempty` function."
323 msgstr ""
324
325 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:179
326 msgid "You see that the function requires two arguments, ``value`` and ``text_if_empty``. However, because we are using Single Function Mode, we omit the ``value`` argument, passing only ``text_if_empty``. For example, this template::"
327 msgstr ""
328
329 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:183
330 msgid "shows the tags for a book, if any. If it has no tags then it shows `No tags on this book`."
331 msgstr ""
332
333 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:185
334 msgid "The following functions are usable in Single Function Mode because their first parameter is ``value``."
335 msgstr ""
336
337 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:227
338 msgid "**Using functions and formatting in the same template**"
339 msgstr ""
340
341 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:229
342 msgid "Suppose you have an integer custom column ``#myint`` that you want displayed with leading zeros, as in ``003``. One way to do this is to use a format of ``0>3s``. However, by default if a number (integer or float) equals zero then the value is displayed as the empty string so zero values will produce the empty string, not ``000``. If you want to see ``000`` values then you use both the format string and the ``ifempty`` function to change the empty value back to a zero. The template would be::"
343 msgstr ""
344
345 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:233
346 msgid "Note that you can use the prefix and suffix as well. If you want the number to appear as ``[003]`` or ``[000]``, then use the template::"
347 msgstr ""
348
349 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:240
350 msgid "General Program Mode"
351 msgstr ""
352
353 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:242
354 msgid "`General Program Mode` (`GPM`) replaces `template expressions` with a program written in the `template language`. The syntax of the language is defined by the following grammar::"
355 msgstr ""
356
357 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:295
358 msgid "a ``top_expression`` always has a value. The value of an ``expression_list`` is the value of the last ``top_expression`` in the list. For example, the value of the expression list ``1;2;'foobar';3`` is ``3``."
359 msgstr ""
360
361 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:296
362 msgid "In a logical context, any non-empty value is ``True``"
363 msgstr ""
364
365 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:297
366 msgid "In a logical context, the empty value is ``False``"
367 msgstr ""
368
369 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:298
370 msgid "Strings and numbers can be used interchangeably. For example, ``10`` and ``'10'`` are the same thing."
371 msgstr ""
372
373 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:299
374 msgid "Comments are lines starting with a '#' character, possibly preceded by blanks or tabs."
375 msgstr ""
376
377 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:301
378 msgid "**Operator precedence**"
379 msgstr ""
380
381 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:303
382 msgid "The operator precedence (order of evaluation) from highest (evaluated first) to lowest (evaluated last) is:"
383 msgstr ""
384
385 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:305
386 msgid "Function calls, constants, parenthesized expressions, statement expressions, assignment expressions, field references."
387 msgstr ""
388
389 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:306
390 msgid "Unary plus (``+``) and minus (``-``). These operators evaluate right to left."
391 msgstr ""
392
393 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:308
394 msgid "These and all the other arithmetic operators return integers if the expression results in a fractional part equal to zero. For example, if an expression returns ``3.0`` it is changed to ``3``."
395 msgstr ""
396
397 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:309
398 msgid "Multiply (``*``) and divide (``/``). These operators are associative and evaluate left to right. Use parentheses if you want to change the order of evaluation."
399 msgstr ""
400
401 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:310
402 msgid "Add (``+``) and subtract (``-``). These operators are associative and evaluate left to right."
403 msgstr ""
404
405 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:311
406 msgid "Numeric and string comparisons. These operators return ``'1'`` if the comparison succeeds, otherwise the empty string (``''``). Comparisons are not associative: ``a < b < c`` is a syntax error."
407 msgstr ""
408
409 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:312
410 msgid "String concatenation (``&``). The ``&`` operator returns a string formed by concatenating the left-hand and right-hand expressions. Example: ``'aaa' & 'bbb'`` returns ``'aaabbb'``. The operator is associative and evaluates left to right."
411 msgstr ""
412
413 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:313
414 msgid "Unary logical not (``!``). This operator returns ``'1'`` if the expression is False (evaluates to the empty string), otherwise ``''``."
415 msgstr ""
416
417 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:314
418 msgid "Logical and (``&&``). This operator returns '1' if both the left-hand and right-hand expressions are True, or the empty string ``''`` if either is False. It is associative, evaluates left to right, and does `short-circuiting <https://chortle.ccsu.edu/java5/Notes/chap40/ch40_2.html>`_."
419 msgstr ""
420
421 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:315
422 msgid "Logical or (``||``). This operator returns ``'1'`` if either the left-hand or right-hand expression is True, or ``''`` if both are False. It is associative, evaluates left to right, and does `short-circuiting <https://chortle.ccsu.edu/java5/Notes/chap40/ch40_2.html>`_. It is an `inclusive or`, returning ``'1'`` if both the left- and right-hand expressions are True."
423 msgstr ""
424
425 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:317
426 msgid "**Field references**"
427 msgstr ""
428
429 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:319
430 msgid "A ``field_reference`` evaluates to the value of the metadata field named by lookup name that follows the ``$`` or ``$$``. Using ``$`` is equivalent to using the :ref:`ff_field` function. Using ``$$`` is equivalent to using the :ref:`ff_raw_field` function. Examples::"
431 msgstr ""
432
433 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:326
434 msgid "**If expressions**"
435 msgstr ""
436
437 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:328
438 msgid "``If`` expressions first evaluate the ``condition``. If the ``condition`` is True (a non-empty value) then the ``expression_list`` in the ``then`` clause is evaluated. If it is False then if present the ``expression_list`` in the ``elif`` or ``else`` clause is evaluated. The ``elif`` and ``else`` parts are optional. The words ``if``, ``then``, ``elif``, ``else``, and ``fi`` are reserved; you cannot use them as identifier names. You can put newlines and white space wherever they make sense. The ``condition`` is a ``top_expression`` not an ``expression_list``; semicolons are not allowed. The ``expression_lists`` are semicolon-separated sequences of ``top_expressions``. An ``if`` expression returns the result of the last ``top_expression`` in the evaluated ``expression_list``, or the empty string if no expression list was evaluated."
439 msgstr ""
440
441 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:330
442 msgid "Examples::"
443 msgstr ""
444
445 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:343
446 msgid "Nested ``if`` example::"
447 msgstr ""
448
449 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:356
450 msgid "As said above, an ``if`` produces a value. This means that all the following are equivalent::"
451 msgstr ""
452
453 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:362
454 msgid "For example, this program returns the value of the ``series`` column if the book has a series, otherwise the value of the ``title`` column::"
455 msgstr ""
456
457 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:366
458 msgid "**For expressions**"
459 msgstr ""
460
461 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:368
462 msgid "The ``for`` expression iterates over a list of values, processing them one at a time. The ``list_expression`` must evaluate either to a metadata field ``lookup name`` e.g., ``tags`` or ``#genre``, or to a list of values. The :ref:`ff_range` generates a list of numbers. 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``. A separator cannot be used if the list is generated by ``range()``. 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."
463 msgstr ""
464
465 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:370
466 msgid "Example: This template removes the first hierarchical name for each value in Genre (``#genre``), constructing a list with the new names::"
467 msgstr ""
468
469 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:380
470 msgid "If the original Genre is `History.Military, Science Fiction.Alternate History, ReadMe` then the template returns `Military, Alternate History, ReadMe`. You could use this template in calibre's :guilabel:`Edit metadata in bulk -> Search & replace` with :guilabel:`Search for` set to ``template`` to strip off the first level of the hierarchy and assign the resulting value to Genre."
471 msgstr ""
472
473 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:383
474 msgid "Note: the last line in the template, ``new_tags``, isn't strictly necessary in this case because ``for`` returns the value of the last top_expression in the expression list. The value of an assignment is the value of its expression, so the value of the ``for`` statement is what was assigned to ``new_tags``."
475 msgstr ""
476
477 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:385
478 msgid "**with expressions**"
479 msgstr ""
480
481 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:387
482 msgid "The ``with`` expression:"
483 msgstr ""
484
485 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:389
486 msgid "changes the current book to the book with calibre book id (an integer) produced by evaluating the ``top_expression``."
487 msgstr ""
488
489 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:390
490 msgid "runs the ``expression_list``."
491 msgstr ""
492
493 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:391
494 msgid "then resets the current book back to what it was."
495 msgstr ""
496
497 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:393
498 msgid "The ``with`` expression returns the result of the last ``top_expression`` in the evaluated ``expression_list``, or the empty string if no expression list was evaluated."
499 msgstr ""
500
501 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:396
502 msgid "For example, this template returns a list of the titles of each book selected in the GUI::"
503 msgstr ""
504
505 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:408
506 msgid "**Return stmt**"
507 msgstr ""
508
509 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:410
510 msgid "Return the value of the ``expression``. If executed in a function then it returns the value of the expression to the caller. If executed in the outermost context (the template) then it sets the value of the template to the value of the expression and exits the template."
511 msgstr ""
512
513 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:412
514 msgid "**Function definition**"
515 msgstr ""
516
517 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:414
518 msgid "If you have repeated code in a template then you can put that code into a local function. The ``def`` keyword starts the definition. It is followed by the function name, the argument list, then the code in the function. The function definition ends with the ``fed`` keyword."
519 msgstr ""
520
521 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:416
522 msgid "Arguments are positional. When a function is called the supplied arguments are matched left to right against the defined parameters, with the value of the argument assigned to the parameter. It is an error to provide more arguments than defined parameters. Parameters can have default values, such as ``a = 25``. If an argument is not supplied for that parameter then the default value is used, otherwise the parameter is set to the empty string."
523 msgstr ""
524
525 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:418
526 msgid "The ``return`` statement can be used in a local function."
527 msgstr ""
528
529 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:420
530 msgid "A function must be defined before it can be used."
531 msgstr ""
532
533 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:422
534 msgid "Example: This template computes an approximate duration in years, months, and days from a number of days. The function ``to_plural()`` formats the computed values. Note that the example also uses the ``&`` operator::"
535 msgstr ""
536
537 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:437
538 msgid "**Relational operators**"
539 msgstr ""
540
541 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:439
542 msgid "Relational operators return ``'1'`` if the comparison is true, otherwise the empty string (``''``)."
543 msgstr ""
544
545 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:441
546 msgid "There are two forms of relational operators: string comparisons and numeric comparisons."
547 msgstr ""
548
549 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:443
550 msgid "String comparisons do case-insensitive string comparison using lexical order. The supported string comparison operators are ``==``, ``!=``, ``<``, ``<=``, ``>``, ``>=``, ``in``, ``inlist``, and ``inlist_field``. For the ``in``, ``inlist``, and ``inlist_field`` operators, the result of the left hand expression is interpreted as a regular expression pattern. They are true if the value of left-hand regular expression matches the value of the right hand expression. The regular expressions are case-insensitive."
551 msgstr ""
552
553 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:446
554 msgid "The ``inlist`` operator is true if the left hand regular expression matches any one of the items in the right hand list where the items in the list are separated by commas. The ``inlist_field`` operator is true if the left hand regular expression matches any of the items in the field (column) named by the right hand expression, using the separator defined for the field. NB: the ``inlist_field`` operator requires the right hand expression to evaluate to a field name, while the ``inlist`` operator requires the right hand expression to evaluate to a string containing a comma-separated list. Because of this difference, ``inlist_field`` is substantially faster than ``inlist`` because no string conversions or list constructions are done."
555 msgstr ""
556
557 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:448
558 msgid "The numeric comparison operators are ``==#``, ``!=#``, ``<#``, ``<=#``, ``>#``, ``>=#``. The left and right expressions must evaluate to numeric values with two exceptions: both the string value \"None\" (undefined field) and the empty string evaluate to the value zero."
559 msgstr ""
560
561 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:450
562 msgid "Examples:"
563 msgstr ""
564
565 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:452
566 msgid "``program: field('series') == 'foo'`` returns ``'1'`` if the book's series is `foo`, otherwise ``''``."
567 msgstr ""
568
569 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:453
570 msgid "``program: 'f.o' in field('series')`` returns ``'1'`` if the book's series matches the regular expression ``f.o`` (e.g., `foo`, `Off Onyx`, etc.), otherwise ``''``."
571 msgstr ""
572
573 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:454
574 msgid "``program: 'science' inlist $#genre`` returns ``'1'`` if any of the values retrieved from the book's genres match the regular expression ``science``, e.g., `Science`, `History of Science`, `Science Fiction` etc., otherwise ``''``."
575 msgstr ""
576
577 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:455
578 msgid "``program: '^science$' inlist $#genre`` returns ``'1'`` if any of the book's genres exactly match the regular expression ``^science$``, e.g., `Science`, otherwise ``''``. The genres `History of Science` and `Science Fiction` don't match."
579 msgstr ""
580
581 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:456
582 msgid "``program: 'asimov' inlist $authors`` returns ``'1'`` if any author matches the regular expression ``asimov``, e.g., `Asimov, Isaac` or `Isaac Asimov`, otherwise ``''``."
583 msgstr ""
584
585 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:457
586 msgid "``program: 'asimov' inlist_field 'authors'`` returns ``'1'`` if any author matches the regular expression ``asimov``, e.g., `Asimov, Isaac` or `Isaac Asimov`, otherwise ``''``."
587 msgstr ""
588
589 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:458
590 msgid "``program: 'asimov$' inlist_field 'authors'`` returns ``'1'`` if any author matches the regular expression ``asimov$``, e.g., `Isaac Asimov`, otherwise ``''``. It doesn't match `Asimov, Isaac` because of the ``$`` anchor in the regular expression."
591 msgstr ""
592
593 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:459
594 msgid "``program: if field('series') != 'foo' then 'bar' else 'mumble' fi`` returns ``'bar'`` if the book's series is not `foo`. Otherwise it returns ``'mumble'``."
595 msgstr ""
596
597 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:460
598 msgid "``program: if field('series') == 'foo' || field('series') == '1632' then 'yes' else 'no' fi`` returns ``'yes'`` if series is either `foo` or `1632`, otherwise ``'no'``."
599 msgstr ""
600
601 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:461
602 msgid "``program: if '^(foo|1632)$' in field('series') then 'yes' else 'no' fi`` returns ``'yes'`` if series is either `foo` or `1632`, otherwise ``'no'``."
603 msgstr ""
604
605 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:462
606 msgid "``program: if 11 > 2 then 'yes' else 'no' fi`` returns ``'no'`` because the ``>`` operator does a lexical comparison."
607 msgstr ""
608
609 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:463
610 msgid "``program: if 11 ># 2 then 'yes' else 'no' fi`` returns ``'yes'`` because the ``>#`` operator does a numeric comparison."
611 msgstr ""
612
613 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:465
614 msgid "**Functions in General Program Mode**"
615 msgstr ""
616
617 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:467
618 msgid "See :ref:`template_functions_reference` for the list of functions built into the template language."
619 msgstr ""
620
621 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:471
622 msgid "As opposed to :ref:`Single Function Mode <single_mode>`, in General Program Mode you must specify the first parameter ``value``."
623 msgstr ""
624
625 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:472
626 msgid "All parameters are expression_lists (see the grammar above)."
627 msgstr ""
628
629 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:477
630 msgid "More complex programs in template expressions - Template Program Mode"
631 msgstr ""
632
633 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:479
634 msgid "`Template Program Mode` (`TPM`) is a blend of :ref:`General Program Mode <general_mode>` and :ref:`Single Function Mode <single_mode>`. `TPM` differs from Single Function Mode in that it permits writing template expressions that refer to other metadata fields, use nested functions, modify variables, and do arithmetic. It differs from `General Program Mode` in that the template is contained between ``{`` and ``}`` characters and doesn't begin with the word ``program:``. The program portion of the template is a General Program Mode expression list."
635 msgstr ""
636
637 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:482
638 msgid "Example: assume you want a template to show the series for a book if it has one, otherwise show the value of a custom field #genre. You cannot do this in the :ref:`Single Function Mode <single_mode>` because you cannot make reference to another metadata field within a template expression. In `TPM` you can, as the following expression demonstrates::"
639 msgstr ""
640
641 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:487
642 msgid "The example shows several things:"
643 msgstr ""
644
645 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:489
646 msgid "`TPM` is used if the expression begins with ``:'`` and ends with ``'}``. Anything else is assumed to be in :ref:`Single Function Mode <single_mode>`."
647 msgstr ""
648
649 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:491
650 msgid "If the template contains a prefix and suffix, the expression ends with ``'|`` where the ``|`` is the delimiter for the prefix. Example::"
651 msgstr ""
652
653 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:495
654 msgid "Functions must be given all their arguments. For example, the standard built-in functions must be given the initial parameter ``value``."
655 msgstr ""
656
657 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:496
658 msgid "The variable ``$`` is usable as the ``value`` argument and stands for the value of the field named in the template, ``series`` in this case."
659 msgstr ""
660
661 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:497
662 msgid "white space is ignored and can be used anywhere within the expression."
663 msgstr ""
664
665 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:498
666 msgid "constant strings are enclosed in matching quotes, either ``'`` or ``\"``."
667 msgstr ""
668
669 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:500
670 msgid "In `TPM`, using ``{`` and ``}`` characters in string literals can lead to errors or unexpected results because they confuse the template processor. It tries to treat them as template expression boundaries, not characters. In some but not all cases you can replace a ``{`` with ``[[`` and a ``}`` with `]]`. Advice: if your program contains ``{`` and ``}`` characters then you should use `General Program Mode`."
671 msgstr ""
672
673 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:505
674 msgid "Python Template Mode"
675 msgstr ""
676
677 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:507
678 msgid "Python Template Mode (PTM) lets you write templates using native Python and the `calibre API <https://manual.calibre-ebook.com/develop.html#api-documentation-for-various-parts-of-calibre>`_. The database API will be of most use; further discussion is beyond the scope of this manual. PTM templates are faster and can do more complicated operations but you must know how to write code in Python using the calibre API."
679 msgstr ""
680
681 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:509
682 msgid "A PTM template begins with:"
683 msgstr ""
684
685 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:527
686 msgid "You can add the above text to your template using the context menu, usually accessed with a right click. The comments are not significant and can be removed. You must use python indenting."
687 msgstr ""
688
689 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:529
690 msgid "The context object supports ``str(context)`` that returns a string of the context's contents, and ``context.attributes`` that returns a list of the attribute names in the context."
691 msgstr ""
692
693 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:531
694 msgid "The ``context.funcs`` attribute allows calling Built-in and User template functions, and Stored GPM/Python templates, so that you can execute them directly in your code. The functions are retrieved using their names. If the name conflicts with a Python keyword, add an underscore to the end of the name. Examples:"
695 msgstr ""
696
697 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:538
698 msgid "Here is an example of a PTM template that produces a list of all the authors for a series. The list is stored in a `Column built from other columns, behaves like tags`. It shows in :guilabel:`Book details` and has the :guilabel:`on separate lines` checked (in :guilabel:`Preferences->Look & feel->Book details`). That option requires the list to be comma-separated. To satisfy that requirement the template converts commas in author names to semicolons then builds a comma-separated list of authors. The authors are then sorted, which is why the template uses author_sort."
699 msgstr ""
700
701 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:559
702 msgid "The output in :guilabel:`Book details` looks like this:"
703 msgstr ""
704
705 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:561
706 msgid "E-book conversion dialog"
707 msgstr ""
708
709 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:569
710 msgid "Templates and URLs"
711 msgstr ""
712
713 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:571
714 msgid "You can use templates to construct URLs. Two cases are described here:"
715 msgstr ""
716
717 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:573
718 msgid "Custom column :guilabel:`Book details` search URLs"
719 msgstr ""
720
721 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:574
722 msgid "The calibre URL scheme"
723 msgstr ""
724
725 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:576
726 msgid "**Custom column book details search URLs**"
727 msgstr ""
728
729 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:578
730 msgid "When you create a custom column you can provide a URL to be used in :guilabel:`Book details` using a template. For example, if you have a custom column for `Translators` you can define a URL to take you to a site for translators. Book details search URLs can be provided for `Text`, `Enumerated`, `Series`, and `Column built from other column` column types."
731 msgstr ""
732
733 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:580
734 msgid "When an item with a `search template` is clicked in :guilabel:`Book details` the template is evaluated. It is provided the normal book metadata. It is also provided three additional fields:"
735 msgstr ""
736
737 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:582
738 msgid "``item_value``: the value of the clicked item."
739 msgstr ""
740
741 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:583
742 msgid "``item_value_quoted``: the value of clicked item, URL-encoded. Special characters are escaped to make them valid in URLs and spaces are replaced by ``'+'`` (plus) signs."
743 msgstr ""
744
745 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:584
746 msgid "``item_value_no_plus``: the value of clicked item, URL-encoded. Special characters are escaped to make them valid in URLs and spaces are replaced by the ``%20``, not plus."
747 msgstr ""
748
749 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:586
750 msgid "There are several ways to construct the URL. The following use Wikipedia as an example."
751 msgstr ""
752
753 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:588
754 msgid "The simplest is a basic template::"
755 msgstr ""
756
757 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:592
758 msgid "In some cases you might want to do more processing. There are four template functions you can use, depending on the complexity of the processing."
759 msgstr ""
760
761 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:599
762 msgid "For example, assume you have a custom column `Translators` (``#translators``) where the names are `Last name, First name`. You might need to convert the name to `First name Last name` when creating the URL. You can use the :ref:`ff_make_url` function to do this::"
763 msgstr ""
764
765 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:603
766 msgid "If we assume that the translator's name is `Boy-Żeleński, Tadeusz` then the above template produces the link::"
767 msgstr ""
768
769 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:607
770 msgid "Note that the person's first name is now first, the space is now a plus, and that the non-English characters in the last name are URL-encoded."
771 msgstr ""
772
773 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:609
774 msgid "The functions :ref:`ff_make_url_extended`, :ref:`ff_query_string`, and :ref:`ff_encode_for_url` might be useful depending upon any additional processing complexity."
775 msgstr ""
776
777 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:611
778 msgid "**The calibre URL scheme**"
779 msgstr ""
780
781 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:613
782 msgid "Calibre supports several different URLs to navigate your calibre libraries. This section shows how to use templates to construct some of the URLs. See :doc:`url_scheme` for details on the URLs available."
783 msgstr ""
784
785 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:616
786 msgid "Switch to a specific library. The syntax of this URL is::"
787 msgstr ""
788
789 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:620
790 msgid "``Library_Name`` must be replaced with the name of the calibre library you wish to open. The library name is shown in the title bar of the window. It is a simple name, not the file path to the library. You must spell it as shown in the title bar, including letter case. The character ``_`` (underscore) stands for the current library. If the name contains any spaces or special characters then it must be hex encoded using the :ref:`ff_to_hex` function, as in the following example::"
791 msgstr ""
792
793 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:628
794 msgid "The template generates the URL::"
795 msgstr ""
796
797 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:632
798 msgid "You can replace the ``current_library_name()`` function with the actual name of the library, as in::"
799 msgstr ""
800
801 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:636
802 msgid "Links to show books. These links select a book in the calibre library. The syntax for this URL is::"
803 msgstr ""
804
805 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:640
806 msgid "The ``book id`` is the numeric calibre id for the book, available to templates as ``$id``. As above, the library name might need to be hex encoded. Here is an example::"
807 msgstr ""
808
809 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:645
810 msgid "It produces the URL::"
811 msgstr ""
812
813 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:649
814 msgid "Searching for books. These links search for books in the specified calibre library. The syntax for this URL is::"
815 msgstr ""
816
817 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:654
818 msgid "where `query` is any valid calibre search expression. You must hex encode any query containing spaces or special characters, which generally means all of them. For example, the calibre search expression for searching for a hierarchical tag beginning with 'AA' is ``tags:\"=.AA\"``. This template constructs a search URL for that expression::"
819 msgstr ""
820
821 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:660
822 msgid "The resulting URL is::"
823 msgstr ""
824
825 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:664
826 msgid "Here is an example of the same URL built using the :ref:``ff_make_url_extended`` function instead of :ref:`ff_strcat`::"
827 msgstr ""
828
829 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:669
830 msgid "Open a book details window on a book in some library. The syntax for this URL is::"
831 msgstr ""
832
833 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:673
834 msgid "An example template is::"
835 msgstr ""
836
837 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:677
838 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:694
839 msgid "which produces the URL::"
840 msgstr ""
841
842 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:681
843 msgid "Open the notes associated with an author/series/etc. The syntax of the URL is::"
844 msgstr ""
845
846 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:686
847 msgid "``Field_Name`` is the lookup name of the field. If the field is a custom column then replace the ``#`` character with an underscore (``_``). ``Item_Id`` is the internal numeric ID of the value in the field. There isn't a template function that returns the ``Item_Id``, so templates will normally use the second form, ``Hex_Encoded_Item_Name``. Here is a sample template that opens the note for the person ``Boy-Żeleński, Tadeusz`` in the field ``#authtest``::"
848 msgstr ""
849
850 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:700
851 msgid "Stored templates"
852 msgstr ""
853
854 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:702
855 msgid "Both :ref:`General Program Mode <general_mode>` and :ref:`Python Template Mode <python_mode>` support saving templates and calling those templates from another template, much like calling stored functions. You save templates using :guilabel:`Preferences->Advanced->Template functions`. More information is provided in that dialog. You call a template the same way you call a function, passing positional arguments if desired. An argument can be any expression. Examples of calling a template, assuming the stored template is named ``foo``:"
856 msgstr ""
857
858 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:704
859 msgid "``foo()`` -- call the template passing no arguments."
860 msgstr ""
861
862 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:705
863 msgid "``foo(a, b)`` call the template passing the values of the two variables ``a`` and ``b``."
864 msgstr ""
865
866 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:706
867 msgid "``foo(if field('series') then field('series_index') else 0 fi)`` -- if the book has a ``series`` then pass the ``series_index``, otherwise pass the value ``0``."
868 msgstr ""
869
870 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:708
871 msgid "In GPM you retrieve the arguments passed in the call to the stored template using the ``arguments`` function. It both declares and initializes local variables, effectively parameters. The variables are positional; they get the value of the parameter given in the call in the same position. If the corresponding parameter is not provided in the call then ``arguments`` assigns that variable the provided default value. If there is no default value then the variable is set to the empty string. For example, the following ``arguments`` function declares 2 variables, ``key``, ``alternate``::"
872 msgstr ""
873
874 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:712
875 msgid "Examples, again assuming the stored template is named ``foo``:"
876 msgstr ""
877
878 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:714
879 msgid "``foo('#myseries')`` -- argument ``key`` is assigned the value ``'myseries'`` and the argument ``alternate`` is assigned the default value ``'series'``."
880 msgstr ""
881
882 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:715
883 msgid "``foo('series', '#genre')`` the variable ``key`` is assigned the value ``'series'`` and the variable ``alternate`` is assigned the value ``'#genre'``."
884 msgstr ""
885
886 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:716
887 msgid "``foo()`` -- the variable ``key`` is assigned the empty string and the variable ``alternate`` is assigned the value ``'series'``."
888 msgstr ""
889
890 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:718
891 msgid "In PTM the arguments are passed in the ``arguments`` parameter, which is a list of strings. There isn't any way to specify default values. You must check the length of the ``arguments`` list to be sure that the number of arguments is what you expect."
892 msgstr ""
893
894 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:720
895 msgid "An easy way to test stored templates is using the ``Template tester`` dialog. For ease of access give it a keyboard shortcut in :guilabel:`Preferences->Advanced->Keyboard shortcuts->Template tester`. Giving the ``Stored templates`` dialog a shortcut will help switching more rapidly between the tester and editing the stored template's source code."
896 msgstr ""
897
898 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:723
899 msgid "Providing additional information to templates"
900 msgstr ""
901
902 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:725
903 msgid "A developer can choose to pass additional information to the template processor, such as application-specific book metadata or information about what the processor is being asked to do. A template can access this information and use it during the evaluation."
904 msgstr ""
905
906 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:727
907 msgid "**Developer: how to pass additional information**"
908 msgstr ""
909
910 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:729
911 msgid "The additional information is a Python dictionary containing pairs ``variable_name: variable_value`` where the values must be strings. The template can access the dictionary, creating template local variables named ``variable_name`` containing the value ``variable_value``. The user cannot change the name so it is best to use names that won't collide with other template local variables, for example by prefixing the name with an underscore."
912 msgstr ""
913
914 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:731
915 msgid "This dictionary is passed to the template processor (the ``formatter``) using the named parameter ``global_vars=your_dict``. The full method signature is::"
916 msgstr ""
917
918 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:739
919 msgid "**Template writer: how to access the additional information**"
920 msgstr ""
921
922 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:741
923 msgid "You access the additional information (the ``globals`` dictionary) in a template using the template function::"
924 msgstr ""
925
926 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:745
927 msgid "where ``id`` is any legal variable name. This function checks whether the additional information provided by the developer contains the name. If it does then the function assigns the provided value to a template local variable with that name. If the name is not in the additional information and if an ``expression`` is provided, the ``expression`` is evaluated and the result is assigned to the local variable. If neither a value nor an expression is provided, the function assigns the empty string (``''``) to the local variable."
928 msgstr ""
929
930 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:747
931 msgid "A template can set a value in the ``globals`` dictionary using the template function::"
932 msgstr ""
933
934 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:751
935 msgid "This function sets the ``globals`` dictionary key:value pair ``id:value`` where ``value`` is the value of the template local variable ``id``. If that local variable doesn't exist then ``value`` is set to the result of evaluating ``expression``."
936 msgstr ""
937
938 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:754
939 msgid "Notes on the difference between modes"
940 msgstr ""
941
942 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:756
943 msgid "The three program modes, :ref:`Single Function Mode <single_mode>` (SFM), :ref:`Template Program Mode <template_mode>` (`TPM`), and :ref:`General Program Mode <general_mode>` (`GPM`), work differently. SFM is intended to be 'simple' so it hides a lot of programming language bits."
944 msgstr ""
945
946 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:758
947 msgid "Differences:"
948 msgstr ""
949
950 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:760
951 msgid "In SFM the value of the column is always passed as an 'invisible' first argument to a function included in the template."
952 msgstr ""
953
954 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:761
955 msgid "SFM doesn't support the difference between variables and strings; all values are strings."
956 msgstr ""
957
958 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:762
959 msgid "The following SFM template returns either the series name or the string \"no series\"::"
960 msgstr ""
961
962 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:766
963 msgid "The equivalent template in `TPM` is ::"
964 msgstr ""
965
966 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:770
967 msgid "The equivalent template in `GPM` is::"
968 msgstr ""
969
970 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:774
971 msgid "The first argument to ``ifempty`` is the value of the field ``series``. The second argument is the string ``no series``. In SFM the first argument, the value of the field, is automatically passed (the invisible argument)."
972 msgstr ""
973
974 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:775
975 msgid "Several template functions, for example ``booksize()`` and ``current_library_name()``, take no arguments. Because of the 'invisible argument' you cannot use these functions in SFM."
976 msgstr ""
977
978 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:776
979 msgid "Nested functions, where a function calls another function to compute an argument, cannot be used in SFM. For example this template, intended to return the first 5 characters of the series value uppercased, won't work in SFM::"
980 msgstr ""
981
982 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:780
983 msgid "`TPM` and `GPM` support nested functions. The above template in `TPM` would be::"
984 msgstr ""
985
986 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:784
987 msgid "In `GPM` it would be::"
988 msgstr ""
989
990 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:788
991 msgid "As noted in the above :ref:`Template Program Mode <template_mode>` section, using ``{`` and ``}`` characters in `TPM` string literals can lead to errors or unexpected results because they confuse the template processor. It tries to treat them as template boundaries, not characters. In some but not all cases you can replace a ``{`` with ``[[`` and a ``}`` with `]]`. Generally, if your program contains ``{`` and ``}`` characters then you should use `General Program Mode`."
992 msgstr ""
993
994 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:792
995 msgid "User-defined Python template functions"
996 msgstr ""
997
998 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:794
999 msgid "You can add your own Python functions to the template processor. Such functions can be used in any of the three template programming modes. The functions are added by going to :guilabel:`Preferences -> Advanced -> Template functions`. Instructions are shown in that dialog. Note that you can use `Python Templates` for a similar purpose. As calling user-defined functions is faster than calling a Python template, user-defined functions might be more efficient depending on the complexity of what the function or template does."
1000 msgstr ""
1001
1002 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:797
1003 msgid "Special notes for using templates in different contexts"
1004 msgstr ""
1005
1006 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:799
1007 msgid "In the GUI (:guilabel:`Columns made from other columns` and :guilabel:`Template searches`):"
1008 msgstr ""
1009
1010 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:801
1011 msgid "GPM templates work as before."
1012 msgstr ""
1013
1014 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:802
1015 msgid "Python templates have full access to the calibre database."
1016 msgstr ""
1017
1018 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:804
1019 msgid "In icon rules:"
1020 msgstr ""
1021
1022 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:806
1023 msgid "icon rule templates have no book data so field-based functions such as :ref:`ff_format_date_field`, :ref:`ff_list_count_field`, and :ref:`ff_check_yes_no` won't work."
1024 msgstr ""
1025
1026 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:808
1027 msgid "In the Content server:"
1028 msgstr ""
1029
1030 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:810
1031 msgid "Templates have access to the new API but not the old API (LibraryDatabase)."
1032 msgstr ""
1033
1034 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:811
1035 msgid "Because of the above, the following formatter functions are not guaranteed to work in GPM templates (composite columns, icon rules, etc) and should be avoided if you use the content server:"
1036 msgstr ""
1037
1038 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:813
1039 msgid ":ref:`ff_connected_device_name`"
1040 msgstr ""
1041
1042 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:814
1043 msgid ":ref:`ff_connected_device_uuid`"
1044 msgstr ""
1045
1046 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:815
1047 msgid ":ref:`ff_current_virtual_library_name`"
1048 msgstr ""
1049
1050 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:816
1051 msgid ":ref:`ff_is_marked`"
1052 msgstr ""
1053
1054 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:817
1055 msgid ":ref:`ff_virtual_libraries`"
1056 msgstr ""
1057
1058 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:820
1059 msgid "Special notes for save/send templates"
1060 msgstr ""
1061
1062 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:822
1063 msgid "Special processing is applied when a template is used in a :guilabel:`Save to disk` or :guilabel:`Send to device` template. The values of the fields are cleaned, replacing characters that are special to file systems with underscores, including slashes. This means that field text cannot be used to create folders. However, slashes are not changed in prefix or suffix strings, so slashes in these strings will cause folders to be created. Because of this, you can create variable-depth folder structure."
1064 msgstr ""
1065
1066 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:824
1067 msgid "For example, assume we want the folder structure `series/series_index - title`, with the caveat that if series does not exist, then the title should be in the top folder. The template to do this is::"
1068 msgstr ""
1069
1070 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:828
1071 msgid "The slash and the hyphen appear only if series is not empty."
1072 msgstr ""
1073
1074 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:830
1075 msgid "The lookup function lets us do even fancier processing. For example, assume that if a book has a series, then we want the folder structure `series/series index - title.fmt`. If the book does not have a series then we want the folder structure `genre/author_sort/title.fmt`. If the book has no genre then we want to use 'Unknown'. We want two completely different paths, depending on the value of series."
1076 msgstr ""
1077
1078 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:832
1079 msgid "To accomplish this, we:"
1080 msgstr ""
1081
1082 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:834
1083 msgid "Create a composite field (give it lookup name #aa) containing ``{series}/{series_index} - {title}``. If the series is not empty, then this template will produce `series/series_index - title`."
1084 msgstr ""
1085
1086 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:835
1087 msgid "Create a composite field (give it lookup name #bb) containing ``{#genre:ifempty(Unknown)}/{author_sort}/{title}``. This template produces `genre/author_sort/title`, where an empty genre is replaced with `Unknown`."
1088 msgstr ""
1089
1090 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:836
1091 msgid "Set the save template to ``{series:lookup(.,#aa,#bb)}``. This template chooses composite field ``#aa`` if series is not empty and composite field ``#bb`` if series is empty. We therefore have two completely different save paths, depending on whether or not `series` is empty."
1092 msgstr ""
1093
1094 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:839
1095 msgid "Tips"
1096 msgstr ""
1097
1098 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:841
1099 msgid "Use the Template Tester to test templates. Add the tester to the context menu for books in the library and/or give it a keyboard shortcut."
1100 msgstr ""
1101
1102 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:842
1103 msgid "Templates can use other templates by referencing composite columns built with the desired template. Alternatively, you can use Stored Templates."
1104 msgstr ""
1105
1106 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:843
1107 msgid "In a plugboard, you can set a field to empty (or whatever is equivalent to empty) by using the special template ``{}``. This template will always evaluate to an empty string."
1108 msgstr ""
1109
1110 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:844
1111 msgid "The technique described above to show numbers even if they have a zero value works with the standard field series_index."
1112 msgstr ""
1113
1114 #: ../../../home/kovid/work/calibre/manual/template_lang.rst:849
1115 msgid "Template function reference"
1116 msgstr ""