1# SOME DESCRIPTIVE TITLE. 2# Copyright (C) Kovid Goyal 3# This file is distributed under the same license as the calibre package. 4# 5# Translators: 6msgid "" 7msgstr "" 8"Project-Id-Version: calibre\n" 9"Report-Msgid-Bugs-To: \n" 10"POT-Creation-Date: 2021-12-01 12:56+0000\n" 11"PO-Revision-Date: 2021-11-15 02:47+0000\n" 12"Last-Translator: Kovid Goyal <kovid@kovidgoyal.net>\n" 13"Language-Team: Breton (http://www.transifex.com/calibre/calibre/language/br/)\n" 14"MIME-Version: 1.0\n" 15"Content-Type: text/plain; charset=UTF-8\n" 16"Content-Transfer-Encoding: 8bit\n" 17"Language: br\n" 18"Plural-Forms: nplurals=5; plural=((n%10 == 1) && (n%100 != 11) && (n%100 !=71) && (n%100 !=91) ? 0 :(n%10 == 2) && (n%100 != 12) && (n%100 !=72) && (n%100 !=92) ? 1 :(n%10 ==3 || n%10==4 || n%10==9) && (n%100 < 10 || n% 100 > 19) && (n%100 < 70 || n%100 > 79) && (n%100 < 90 || n%100 > 99) ? 2 :(n != 0 && n % 1000000 == 0) ? 3 : 4);\n" 19 20#: ../../__w/calibre/calibre/manual/template_lang.rst:4 21msgid "The calibre template language" 22msgstr "" 23 24#: ../../__w/calibre/calibre/manual/template_lang.rst:6 25msgid "" 26"The calibre template language is a calibre-specific language used throughout" 27" calibre for tasks such as specifying file paths, formatting values, and " 28"computing the value for user-specified columns. Examples:" 29msgstr "" 30 31#: ../../__w/calibre/calibre/manual/template_lang.rst:8 32msgid "" 33"Specify the folder structure and file names when saving files from the " 34"calibre library to the disk or e-book reader." 35msgstr "" 36 37#: ../../__w/calibre/calibre/manual/template_lang.rst:9 38msgid "Define rules for adding icons and colors to the calibre book list." 39msgstr "" 40 41#: ../../__w/calibre/calibre/manual/template_lang.rst:10 42msgid "Define `virtual columns` that contain data from other columns." 43msgstr "" 44 45#: ../../__w/calibre/calibre/manual/template_lang.rst:11 46msgid "Advanced library searching." 47msgstr "" 48 49#: ../../__w/calibre/calibre/manual/template_lang.rst:12 50msgid "Advanced metadata search and replace." 51msgstr "" 52 53#: ../../__w/calibre/calibre/manual/template_lang.rst:14 54msgid "" 55"The language is built around the notion of a `template`, which specifies " 56"which book metadata to use, computations on that metadata, and how it is to " 57"be formatted." 58msgstr "" 59 60#: ../../__w/calibre/calibre/manual/template_lang.rst:17 61msgid "Basic templates" 62msgstr "" 63 64#: ../../__w/calibre/calibre/manual/template_lang.rst:19 65msgid "" 66"A basic template consists one or more ``template expressions``. A ``template" 67" expression`` consists of text and names in curly brackets (``{}``) that is " 68"replaced by the corresponding metadata from the book being processed. For " 69"example, the default template in calibre used for saving books to device has" 70" 4 ``template expressions``::" 71msgstr "" 72 73#: ../../__w/calibre/calibre/manual/template_lang.rst:23 74msgid "For the book \"The Foundation\" by \"Isaac Asimov\" the will become::" 75msgstr "" 76 77#: ../../__w/calibre/calibre/manual/template_lang.rst:27 78msgid "" 79"The slashes are not ``template expressions`` because they are in between in " 80"``{}``. Such text is left where it appears. For example, if the template " 81"is::" 82msgstr "" 83 84#: ../../__w/calibre/calibre/manual/template_lang.rst:31 85msgid "then for \"The Foundation\" the template produces::" 86msgstr "" 87 88#: ../../__w/calibre/calibre/manual/template_lang.rst:35 89msgid "" 90"A ``template expression`` can access all the metadata available in calibre, " 91"including custom columns (columns you create yourself), by using a column's " 92"``lookup name``. To find the lookup name for a `column` (sometimes called " 93"`fields`), hover your mouse over the column header in calibre's book list. " 94"Lookup names for custom columns always begin with ``#``. For series type " 95"columns there is an additional field named ``#lookup name_index`` that is " 96"the series index for that book in the series. For example, if you have a " 97"custom series column named ``#myseries``, there will also be a column named " 98"``#myseries_index``. The standard series column's index is named " 99"``series_index``." 100msgstr "" 101 102#: ../../__w/calibre/calibre/manual/template_lang.rst:37 103msgid "In addition to the standard column based fields, you also can use:" 104msgstr "" 105 106#: ../../__w/calibre/calibre/manual/template_lang.rst:39 107msgid "" 108"``{formats}`` - A list of formats available in the calibre library for a " 109"book" 110msgstr "" 111 112#: ../../__w/calibre/calibre/manual/template_lang.rst:40 113msgid "``{identifiers:select(isbn)}`` - The ISBN of the book" 114msgstr "" 115 116#: ../../__w/calibre/calibre/manual/template_lang.rst:42 117msgid "" 118"If the metadata for the field for a given book is not defined then the field" 119" in the template is replaced by the empty string (``''``). For example, " 120"consider the following template::" 121msgstr "" 122 123#: ../../__w/calibre/calibre/manual/template_lang.rst:46 124msgid "" 125"If Asimov's book \"Second Foundation\" is in the series \"Foundation\" then " 126"the template produces::" 127msgstr "" 128 129#: ../../__w/calibre/calibre/manual/template_lang.rst:50 130msgid "" 131"If a series has not been entered for the book then the template produces::" 132msgstr "" 133 134#: ../../__w/calibre/calibre/manual/template_lang.rst:54 135msgid "" 136"The template processor automatically removes multiple slashes and leading or" 137" trailing spaces." 138msgstr "" 139 140#: ../../__w/calibre/calibre/manual/template_lang.rst:57 141msgid "Advanced formatting" 142msgstr "" 143 144#: ../../__w/calibre/calibre/manual/template_lang.rst:59 145msgid "" 146"In addition to metadata substitution, templates can conditionally include " 147"additional text and control how substituted data is formatted." 148msgstr "" 149 150#: ../../__w/calibre/calibre/manual/template_lang.rst:61 151msgid "**Conditionally including text**" 152msgstr "" 153 154#: ../../__w/calibre/calibre/manual/template_lang.rst:63 155msgid "" 156"Sometimes you want text to appear in the output only if a field is not " 157"empty. A common case is ``series`` and ``series_index`` where you want " 158"either nothing or the two values separated by a hyphen. calibre handles this" 159" case using a special ``template expression`` syntax." 160msgstr "" 161 162#: ../../__w/calibre/calibre/manual/template_lang.rst:65 163msgid "" 164"For example and using the above Foundation example, assume you want the " 165"template to produce `Foundation - 3 - Second Foundation`. This template " 166"produces that output:" 167msgstr "" 168 169#: ../../__w/calibre/calibre/manual/template_lang.rst:67 170msgid "``{series} - {series_index} - {title}``" 171msgstr "" 172 173#: ../../__w/calibre/calibre/manual/template_lang.rst:69 174msgid "" 175"However, if a book has no series the template will produce `- - the title`, " 176"which is probably not what you want. Generally, people want the result be " 177"the title without the extraneous hyphens. You can accomplish this using the " 178"following template syntax:" 179msgstr "" 180 181#: ../../__w/calibre/calibre/manual/template_lang.rst:71 182msgid "``{field:|prefix_text|suffix_text}``" 183msgstr "" 184 185#: ../../__w/calibre/calibre/manual/template_lang.rst:73 186msgid "" 187"This ``template expression`` says that if ``field`` has the value `XXXX` " 188"then the result will be `prefix_textXXXXXsuffix_text`. If ``field`` is empty" 189" (has no value) then the result will be the empty string (nothing) because " 190"the prefix and suffix are ignored. The prefix and suffix can contain blanks." 191msgstr "" 192 193#: ../../__w/calibre/calibre/manual/template_lang.rst:75 194msgid "" 195"**Do not use subtemplates (`{ ... }`) or functions (see below) in the prefix" 196" or the suffix.**" 197msgstr "" 198 199#: ../../__w/calibre/calibre/manual/template_lang.rst:77 200msgid "" 201"Using this syntax, we can solve the above no-series problem with the " 202"template::" 203msgstr "" 204 205#: ../../__w/calibre/calibre/manual/template_lang.rst:81 206msgid "" 207"The hyphens will be included only if the book has a series index, which it " 208"has only if it has a series. Continuing the Foundation example again, the " 209"template will produce `Foundation - 1 - Second Foundation`." 210msgstr "" 211 212#: ../../__w/calibre/calibre/manual/template_lang.rst:83 213#: ../../__w/calibre/calibre/manual/template_lang.rst:249 214msgid "Notes:" 215msgstr "" 216 217#: ../../__w/calibre/calibre/manual/template_lang.rst:85 218msgid "" 219"You must include the colon after the ``lookup name`` if you are using a " 220"prefix or a suffix." 221msgstr "" 222 223#: ../../__w/calibre/calibre/manual/template_lang.rst:86 224msgid "" 225"You must either use either no or both ``|`` characters. Using one, as in " 226"``{field:| - }``, is not allowed." 227msgstr "" 228 229#: ../../__w/calibre/calibre/manual/template_lang.rst:87 230msgid "" 231"It is OK to provide no text for either the prefix or the suffix, such as in " 232"``{series:|| - }``. The template ``{title:||}`` is the same as ``{title}``." 233msgstr "" 234 235#: ../../__w/calibre/calibre/manual/template_lang.rst:89 236msgid "**Formatting**" 237msgstr "" 238 239#: ../../__w/calibre/calibre/manual/template_lang.rst:91 240msgid "" 241"Suppose you want the ``series_index`` to be formatted as three digits with " 242"leading zeros. This does the trick:" 243msgstr "" 244 245#: ../../__w/calibre/calibre/manual/template_lang.rst:93 246msgid "``{series_index:0>3s}`` - Three digits with leading zeros" 247msgstr "" 248 249#: ../../__w/calibre/calibre/manual/template_lang.rst:95 250msgid "For trailing zeros, use:" 251msgstr "" 252 253#: ../../__w/calibre/calibre/manual/template_lang.rst:97 254msgid "``{series_index:0<3s}`` - Three digits with trailing zeros" 255msgstr "" 256 257#: ../../__w/calibre/calibre/manual/template_lang.rst:99 258msgid "" 259"If you use series indices with fractional values, e.g., 1.1, you might want " 260"the decimal points to line up. For example, you might want the indices 1 and" 261" 2.5 to appear as 01.00 and 02.50 so that they will sort correctly on a " 262"device that does lexical sorting. To do this, use:" 263msgstr "" 264 265#: ../../__w/calibre/calibre/manual/template_lang.rst:101 266msgid "" 267"``{series_index:0>5.2f}`` - Five characters consisting of two digits with " 268"leading zeros, a decimal point, then 2 digits after the decimal point." 269msgstr "" 270 271#: ../../__w/calibre/calibre/manual/template_lang.rst:103 272msgid "If you want only the first two letters of the data, use:" 273msgstr "" 274 275#: ../../__w/calibre/calibre/manual/template_lang.rst:105 276msgid "" 277"``{author_sort:.2}`` - Only the first two letters of the author sort name" 278msgstr "" 279 280#: ../../__w/calibre/calibre/manual/template_lang.rst:107 281msgid "" 282"Much of the calibre template language formatting comes from Python. For more" 283" details on the syntax of these advanced formatting operations see the " 284"`Python documentation " 285"<https://docs.python.org/3/library/string.html#formatstrings>`_." 286msgstr "" 287 288#: ../../__w/calibre/calibre/manual/template_lang.rst:111 289msgid "Using templates to define custom columns" 290msgstr "" 291 292#: ../../__w/calibre/calibre/manual/template_lang.rst:113 293msgid "" 294"Templates can be used to display information that isn't in calibre metadata," 295" or to display metadata differently from calibre's normal format. For " 296"example, you might want to show the ``ISBN``, a field that calibre does not " 297"display. You can accomplish this creating a custom column with the type " 298"`Column built from other columns` (hereafter called `composite columns`) and" 299" providing a template to generate the displayed text. The column will " 300"display the result of evaluating the template. For example, to display the " 301"ISBN, create the column and enter ``{identifiers:select(isbn)}`` in the " 302"template box. To display a column containing the values of two series custom" 303" columns, separated by a comma, use ``{#series1:||,}{#series2}``." 304msgstr "" 305 306#: ../../__w/calibre/calibre/manual/template_lang.rst:115 307msgid "Composite columns can use any template option, including formatting." 308msgstr "" 309 310#: ../../__w/calibre/calibre/manual/template_lang.rst:117 311msgid "" 312"Note: You cannot edit the data displayed in a composite column. Instead you " 313"edit the source columns. If you edit a composite column, for example by " 314"double-clicking it, calibre will open the template for editing, not the " 315"underlying data." 316msgstr "" 317 318#: ../../__w/calibre/calibre/manual/template_lang.rst:122 319msgid "Using functions in templates - Single Function Mode" 320msgstr "" 321 322#: ../../__w/calibre/calibre/manual/template_lang.rst:124 323msgid "" 324"Suppose you want to display the value of a field in upper case when that " 325"field is normally in title case. You can do this using `template functions`." 326" For example, to display the title in upper case use the ``uppercase`` " 327"function, as in ``{title:uppercase()}``. To display it in title case, use " 328"``{title:titlecase()}``." 329msgstr "" 330 331#: ../../__w/calibre/calibre/manual/template_lang.rst:126 332msgid "" 333"Functions go into the format part of the template, after the ``:`` and " 334"before the first ``|`` or the closing ``}`` if no prefix/suffix is used. If " 335"you have both a format and a function reference, the function comes after a " 336"second ``:``. Functions return the value of the column specified in the " 337"template, suitably modified." 338msgstr "" 339 340#: ../../__w/calibre/calibre/manual/template_lang.rst:128 341msgid "The syntax for using functions is one of::" 342msgstr "" 343 344#: ../../__w/calibre/calibre/manual/template_lang.rst:135 345msgid "" 346"Function names must always be followed by opening and closing parentheses. " 347"Some functions require extra values (arguments), and these go inside the " 348"parentheses. Arguments are separated by commas. Literal commas (commas as " 349"text, not argument separators) must be preceded by a backslash (``\\``) . " 350"The last (or only) argument cannot contain a textual closing parenthesis." 351msgstr "" 352 353#: ../../__w/calibre/calibre/manual/template_lang.rst:137 354msgid "" 355"Functions are evaluated before format specifications and the prefix/suffix. " 356"See further down for an example of using both a format and a function." 357msgstr "" 358 359#: ../../__w/calibre/calibre/manual/template_lang.rst:139 360msgid "" 361"**Important**: If you have programming experience, please note that the " 362"syntax in `Single Function Mode` is not what you expect. Strings are not " 363"quoted and spaces are significant. All arguments are considered to be " 364"constants; there are no expressions." 365msgstr "" 366 367#: ../../__w/calibre/calibre/manual/template_lang.rst:141 368msgid "" 369"**Do not use subtemplates (`{ ... }`) as function arguments.** Instead, use " 370":ref:`Template Program Mode <template_mode>` and :ref:`General Program Mode " 371"<general_mode>`." 372msgstr "" 373 374#: ../../__w/calibre/calibre/manual/template_lang.rst:143 375msgid "" 376"Some functions require regular expressions. In the template language regular" 377" expression matching is case-insensitive." 378msgstr "" 379 380#: ../../__w/calibre/calibre/manual/template_lang.rst:145 381msgid "" 382"In the function documentation below, the notation ``[something]*`` means " 383"that ``something`` can be repeated zero or more times. The notation " 384"``[something]+`` means that the ``something`` is repeated one or more times " 385"(must exist at least one time)." 386msgstr "" 387 388#: ../../__w/calibre/calibre/manual/template_lang.rst:147 389msgid "The functions intended for use in Single Function Mode are:" 390msgstr "" 391 392#: ../../__w/calibre/calibre/manual/template_lang.rst:150 393msgid "" 394"``capitalize()`` -- returns the value with the first letter upper case and " 395"the rest lower case." 396msgstr "" 397 398#: ../../__w/calibre/calibre/manual/template_lang.rst:151 399msgid "" 400"``contains(pattern, text if match, text if not match)`` -- checks if the " 401"value is matched by the regular expression ``pattern``. Returns ``text if " 402"match`` if the pattern matches the value, otherwise returns ``text if no " 403"match``." 404msgstr "" 405 406#: ../../__w/calibre/calibre/manual/template_lang.rst:152 407msgid "" 408"``count(separator)`` -- interprets the value as a list of items separated by" 409" ``separator`` and returns the number of items in the list. Most lists use a" 410" comma as the separator, but ``authors`` uses an ampersand (&). Examples: " 411"``{tags:count(,)}``, ``{authors:count(&)}``. Aliases: ``count()``, " 412"``list_count()``" 413msgstr "" 414 415#: ../../__w/calibre/calibre/manual/template_lang.rst:153 416msgid "" 417"``format_number(template)`` -- interprets the value as a number and formats " 418"that number using a Python formatting template such as ``{0:5.2f}`` or " 419"``{0:,d}`` or ``${0:5,.2f}``. The formatting template must begin with " 420"``{0:`` and end with ``}`` as in the above examples. Exception: you can " 421"leave off the leading \"{0:\" and trailing \"}\" if the format template " 422"contains only a format. See the template language and the `Python " 423"documentation " 424"<https://docs.python.org/3/library/string.html#formatstrings>`_ for more " 425"examples. Returns the empty string if formatting fails." 426msgstr "" 427 428#: ../../__w/calibre/calibre/manual/template_lang.rst:154 429msgid "" 430"``human_readable()`` -- expects the value to be a number and returns a " 431"string representing that number in KB, MB, GB, etc." 432msgstr "" 433 434#: ../../__w/calibre/calibre/manual/template_lang.rst:155 435msgid "" 436"``ifempty(text if empty)`` -- if the value is not empty then return the " 437"value of the field, otherwise return `text if empty`." 438msgstr "" 439 440#: ../../__w/calibre/calibre/manual/template_lang.rst:156 441msgid "" 442"``in_list(separator, [ pattern, found_val, ]* not_found_val)`` -- interpret " 443"the value as a list of items separated by ``separator``, checking the " 444"``pattern`` against each item in the list. If the ``pattern`` matches an " 445"item then return ``found_val``, otherwise return ``not_found_val``. The pair" 446" ``pattern`` and ``found_value`` can be repeated as many times as desired, " 447"permitting returning different values depending on the item's value. The " 448"patterns are checked in order, and the first match is returned." 449msgstr "" 450 451#: ../../__w/calibre/calibre/manual/template_lang.rst:157 452msgid "" 453"``language_strings(localize)`` -- return the `language names " 454"<https://www.loc.gov/standards/iso639-2/php/code_list.php>`_ for the " 455"`language codes <https://www.loc.gov/standards/iso639-2/php/code_list.php>`_" 456" passed in as the value. Example: ``{languages:language_strings()}``. If " 457"``localize`` is zero, return the strings in English. If ``localize`` is not " 458"zero, return the strings in the language of the current locale. " 459"``Lang_codes`` is a comma-separated list." 460msgstr "" 461 462#: ../../__w/calibre/calibre/manual/template_lang.rst:158 463msgid "" 464"``list_item(index, separator)`` -- interpret the value as a list of items " 465"separated by ``separator``, returning the 'index'th item. The first item is " 466"number zero. The last item has the index ``-1`` as in " 467"``list_item(-1,separator)``. If the item is not in the list, then the empty " 468"string is returned." 469msgstr "" 470 471#: ../../__w/calibre/calibre/manual/template_lang.rst:159 472msgid "" 473"``lookup([ pattern, key, ]* else_key)`` -- The patterns will be checked " 474"against the value in order. If a pattern matches then the value of the field" 475" named by ``key`` is returned. If no pattern matches then the value of the " 476"field named by ``else_key`` is returned. See``switch`` (below)." 477msgstr "" 478 479#: ../../__w/calibre/calibre/manual/template_lang.rst:160 480msgid "``lowercase()`` -- returns the value of the field in lower case." 481msgstr "" 482 483#: ../../__w/calibre/calibre/manual/template_lang.rst:161 484msgid "" 485"``rating_to_stars(use_half_stars)`` -- Returns the rating as string of star " 486"(``★``) characters. The value must be a number between 0 and 5. Set " 487"use_half_stars to 1 if you want half star characters for fractional numbers " 488"available with custom ratings columns." 489msgstr "" 490 491#: ../../__w/calibre/calibre/manual/template_lang.rst:162 492msgid "" 493"``re(pattern, replacement)`` -- return the value after applying the regular " 494"expression. All instances of ``pattern`` in the value are replaced with " 495"``replacement``. The template language uses case insensitive `Python regular" 496" expressions <https://docs.python.org/3/library/re.html>`_." 497msgstr "" 498 499#: ../../__w/calibre/calibre/manual/template_lang.rst:163 500msgid "" 501"``select(key)`` -- interpret the value as a comma-separated list of items " 502"with each item having the form ``id:value`` (the calibre ``identifier`` " 503"format). The function finds the first pair with the id equal to key and " 504"returns the corresponding value. If no id matches then the function returns " 505"the empty string." 506msgstr "" 507 508#: ../../__w/calibre/calibre/manual/template_lang.rst:164 509msgid "" 510"``shorten(left chars, middle text, right chars)`` -- Return a shortened " 511"version of the value, consisting of ``left chars`` characters from the " 512"beginning of the value, followed by ``middle text``, followed by ``right " 513"chars`` characters from the end of the value. ``Left chars`` and ``right " 514"chars`` must be non-negative integers. Example: assume you want to display " 515"the title with a length of at most 15 characters in length. One template " 516"that does this is ``{title:shorten(9,-,5)}``. For a book with the title " 517"`Ancient English Laws in the Times of Ivanhoe` the result will be `Ancient " 518"E-nhoe`: the first 9 characters of the title, a ``-``, then the last 5 " 519"characters. If the value's length is less than ``left chars`` + ``right " 520"chars`` + the length of ``middle text`` then the value will be returned " 521"unchanged. For example, the title `The Dome` would not be changed." 522msgstr "" 523 524#: ../../__w/calibre/calibre/manual/template_lang.rst:165 525msgid "" 526"``str_in_list(separator, [ string, found_val, ]+ not_found_val)`` -- " 527"interpret the value as a list of items separated by ``separator`` then " 528"compare ``string`` against each value in the list. The ``string`` is not a " 529"regular expression. If ``string`` is equal to any item (ignoring case) then " 530"return the corresponding ``found_val``. If ``string`` contains " 531"``separators`` then it is also treated as a list and each subvalue is " 532"checked. The ``string`` and ``found_value`` pairs can be repeated as many " 533"times as desired, permitting returning different values depending on " 534"string's value. If none of the strings match then ``not_found_value`` is " 535"returned. The strings are checked in order. The first match is returned." 536msgstr "" 537 538#: ../../__w/calibre/calibre/manual/template_lang.rst:166 539msgid "" 540"``subitems(start_index, end_index)`` -- This function breaks apart lists of " 541"tag-like hierarchical items such as genres. It interprets the value as a " 542"comma-separated list of tag-like items, where each item is a period-" 543"separated list. It returns a new list made by extracting from each item the " 544"components from ``start_index`` to ``end_index``, then merging the results " 545"back together. Duplicates are removed. The first subitem in a period-" 546"separated list has an index of zero. If an index is negative then it counts " 547"from the end of the list. As a special case, an end_index of zero is assumed" 548" to be the length of the list." 549msgstr "" 550 551#: ../../__w/calibre/calibre/manual/template_lang.rst:168 552#: ../../__w/calibre/calibre/manual/template_lang.rst:351 553msgid "Examples:" 554msgstr "" 555 556#: ../../__w/calibre/calibre/manual/template_lang.rst:170 557msgid "Assuming a #genre column containing `A.B.C`:" 558msgstr "" 559 560#: ../../__w/calibre/calibre/manual/template_lang.rst:172 561msgid "``{#genre:subitems(0,1)}`` returns \"A\"" 562msgstr "" 563 564#: ../../__w/calibre/calibre/manual/template_lang.rst:173 565msgid "``{#genre:subitems(0,2)}`` returns \"A.B\"" 566msgstr "" 567 568#: ../../__w/calibre/calibre/manual/template_lang.rst:174 569msgid "``{#genre:subitems(1,0)}`` returns \"B.C\"" 570msgstr "" 571 572#: ../../__w/calibre/calibre/manual/template_lang.rst:176 573msgid "Assuming a #genre column containing \"A.B.C, D.E\":" 574msgstr "" 575 576#: ../../__w/calibre/calibre/manual/template_lang.rst:178 577msgid "``{#genre:subitems(0,1)}`` returns \"A, D\"" 578msgstr "" 579 580#: ../../__w/calibre/calibre/manual/template_lang.rst:179 581msgid "``{#genre:subitems(0,2)}`` returns \"A.B, D.E\"" 582msgstr "" 583 584#: ../../__w/calibre/calibre/manual/template_lang.rst:181 585msgid "" 586"``sublist(start_index, end_index, separator)`` -- interpret the value as a " 587"list of items separated by ``separator``, returning a new list made from the" 588" items from ``start_index`` to ``end_index``. The first item is number zero." 589" If an index is negative, then it counts from the end of the list. As a " 590"special case, an end_index of zero is assumed to be the length of the list." 591msgstr "" 592 593#: ../../__w/calibre/calibre/manual/template_lang.rst:183 594msgid "" 595"Examples assuming that the tags column (which is comma-separated) contains " 596"\"A, B ,C\":" 597msgstr "" 598 599#: ../../__w/calibre/calibre/manual/template_lang.rst:185 600msgid "``{tags:sublist(0,1,\\,)}`` returns \"A\"" 601msgstr "" 602 603#: ../../__w/calibre/calibre/manual/template_lang.rst:186 604msgid "``{tags:sublist(-1,0,\\,)}`` returns \"C\"" 605msgstr "" 606 607#: ../../__w/calibre/calibre/manual/template_lang.rst:187 608msgid "``{tags:sublist(0,-1,\\,)}`` returns \"A, B\"" 609msgstr "" 610 611#: ../../__w/calibre/calibre/manual/template_lang.rst:189 612msgid "" 613"``swap_around_articles(separator)`` -- returns the value with articles moved" 614" to the end. The value can be a list, in which case each item in the list is" 615" processed. If the value is a list then you must provide the ``separator``. " 616"If no ``separator`` is provided then the value is treated as being a single " 617"value, not a list. The `articles` are those used by calibre to generate the " 618"``title_sort``." 619msgstr "" 620 621#: ../../__w/calibre/calibre/manual/template_lang.rst:190 622msgid "" 623"``swap_around_comma()`` -- given a value of the form ``B, A``, return ``A " 624"B``. This is most useful for converting names in LN, FN format to FN LN. If " 625"there is no comma in the value then the function returns the value " 626"unchanged." 627msgstr "" 628 629#: ../../__w/calibre/calibre/manual/template_lang.rst:191 630msgid "" 631"``switch([pattern, value,]+ else_value)`` -- for each ``pattern, value`` " 632"pair, checks if the value matches the regular expression ``pattern`` and if " 633"so returns the associated ``value``. If no ``pattern`` matches, then " 634"``else_value`` is returned. You can have as many ``pattern, value`` pairs as" 635" you wish. The first match is returned." 636msgstr "" 637 638#: ../../__w/calibre/calibre/manual/template_lang.rst:192 639msgid "" 640"``test(text if not empty, text if empty)`` -- return ``text if not empty`` " 641"if the value is not empty, otherwise return ``text if empty``." 642msgstr "" 643 644#: ../../__w/calibre/calibre/manual/template_lang.rst:193 645msgid "``titlecase()`` -- returns the value of the field in title case." 646msgstr "" 647 648#: ../../__w/calibre/calibre/manual/template_lang.rst:194 649msgid "" 650"``transliterate()`` -- Return a string in a latin alphabet formed by " 651"approximating the sound of the words in the source field. For example, if " 652"the source field is ``Фёдор Миха́йлович Достоевский`` this function returns " 653"``Fiodor Mikhailovich Dostoievskii``." 654msgstr "" 655 656#: ../../__w/calibre/calibre/manual/template_lang.rst:195 657msgid "``uppercase()`` -- returns the value of the field in upper case." 658msgstr "" 659 660#: ../../__w/calibre/calibre/manual/template_lang.rst:197 661msgid "**Using functions and formatting in the same template**" 662msgstr "" 663 664#: ../../__w/calibre/calibre/manual/template_lang.rst:199 665msgid "" 666"Suppose you have an integer custom column ``#myint`` that you want displayed" 667" with leading zeros, as in ``003``. One way to do this is to use a format of" 668" ``0>3s``. However, by default if a number (integer or float) equals zero " 669"then the value is displayed as the empty string so zero values will produce " 670"the empty string, not ``000``. If you want to see ``000`` values then you " 671"use both the format string and the ``ifempty`` function to change the empty " 672"value back to a zero. The template would be::" 673msgstr "" 674 675#: ../../__w/calibre/calibre/manual/template_lang.rst:203 676msgid "" 677"Note that you can use the prefix and suffix as well. If you want the number " 678"to appear as ``[003]`` or ``[000]``, then use the template::" 679msgstr "" 680 681#: ../../__w/calibre/calibre/manual/template_lang.rst:210 682msgid "General Program Mode" 683msgstr "" 684 685#: ../../__w/calibre/calibre/manual/template_lang.rst:212 686msgid "" 687"`General Program Mode` (`GPM`) replaces `template expressions` with a " 688"program written in the `template language`. The syntax of the language is " 689"defined by the following grammar::" 690msgstr "" 691 692#: ../../__w/calibre/calibre/manual/template_lang.rst:251 693msgid "" 694"a ``top_expression`` always has a value. The value of an ``expression_list``" 695" is the value of the last ``top_expression`` in the list. For example, the " 696"value of the expression list ``1;2;'foobar';3`` is ``3``." 697msgstr "" 698 699#: ../../__w/calibre/calibre/manual/template_lang.rst:252 700msgid "In a logical context, any non-empty value is ``True``" 701msgstr "" 702 703#: ../../__w/calibre/calibre/manual/template_lang.rst:253 704msgid "In a logical context, the empty value is ``False``" 705msgstr "" 706 707#: ../../__w/calibre/calibre/manual/template_lang.rst:254 708msgid "" 709"Strings and numbers can be used interchangeably. For example, ``10`` and " 710"``'10'`` are the same thing." 711msgstr "" 712 713#: ../../__w/calibre/calibre/manual/template_lang.rst:255 714msgid "" 715"Comments are lines starting with a '#' character. Comments beginning later " 716"in a line are not supported." 717msgstr "" 718 719#: ../../__w/calibre/calibre/manual/template_lang.rst:257 720msgid "**Operator precedence**" 721msgstr "" 722 723#: ../../__w/calibre/calibre/manual/template_lang.rst:259 724msgid "" 725"The operator precedence (order of evaluation) from highest (evaluated first)" 726" to lowest (evaluated last) is:" 727msgstr "" 728 729#: ../../__w/calibre/calibre/manual/template_lang.rst:261 730msgid "" 731"Function calls, constants, parenthesized expressions, statement expressions," 732" assignment expressions, field references." 733msgstr "" 734 735#: ../../__w/calibre/calibre/manual/template_lang.rst:262 736msgid "" 737"Unary plus (``+``) and minus (``-``). These operators evaluate right to " 738"left." 739msgstr "" 740 741#: ../../__w/calibre/calibre/manual/template_lang.rst:264 742msgid "" 743"These and all the other arithmetic operators return integers if the " 744"expression results in a fractional part equal to zero. For example, if an " 745"expression returns ``3.0`` it is changed to ``3``." 746msgstr "" 747 748#: ../../__w/calibre/calibre/manual/template_lang.rst:265 749msgid "" 750"Multiply (``*``) and divide (``/``). These operators are associative and " 751"evaluate left to right. Use parentheses if you want to change the order of " 752"evaluation." 753msgstr "" 754 755#: ../../__w/calibre/calibre/manual/template_lang.rst:266 756msgid "" 757"Add (``+``) and subtract (``-``). These operators are associative and " 758"evaluate left to right." 759msgstr "" 760 761#: ../../__w/calibre/calibre/manual/template_lang.rst:267 762msgid "" 763"Numeric and string comparisons. These operators return ``'1'`` if the " 764"comparison succeeds, otherwise the empty string (``''``). Comparisons are " 765"not associative: ``a < b < c`` is a syntax error." 766msgstr "" 767 768#: ../../__w/calibre/calibre/manual/template_lang.rst:268 769msgid "" 770"Unary logical not (``!``). This operator returns ``'1'`` if the expression " 771"is False (evaluates to the empty string), otherwise ``''``." 772msgstr "" 773 774#: ../../__w/calibre/calibre/manual/template_lang.rst:269 775msgid "" 776"Logical and (``&&``). This operator returns '1' if both the left-hand and " 777"right-hand expressions are True, or the empty string ``''`` if either is " 778"False. It is associative, evaluates left to right, and does `short-" 779"circuiting <https://chortle.ccsu.edu/java5/Notes/chap40/ch40_2.html>`_." 780msgstr "" 781 782#: ../../__w/calibre/calibre/manual/template_lang.rst:270 783msgid "" 784"Logical or (``||``). This operator returns ``'1'`` if either the left-hand " 785"or right-hand expression is True, or ``''`` if both are False. It is " 786"associative, evaluates left to right, and does `short-circuiting " 787"<https://chortle.ccsu.edu/java5/Notes/chap40/ch40_2.html>`_. It is an " 788"`inclusive or`, returning ``'1'`` if both the left- and right-hand " 789"expressions are True." 790msgstr "" 791 792#: ../../__w/calibre/calibre/manual/template_lang.rst:272 793msgid "**Field references**" 794msgstr "" 795 796#: ../../__w/calibre/calibre/manual/template_lang.rst:274 797msgid "" 798"A ``field_reference`` evaluates to the value of the metadata field named by " 799"lookup name that follows the ``$`` or ``$$``. Using ``$`` is equivalent to " 800"using the ``field()`` function. Using ``$$`` is equivalent to using the " 801"``raw_field`` function. Examples::" 802msgstr "" 803 804#: ../../__w/calibre/calibre/manual/template_lang.rst:281 805msgid "**If expressions**" 806msgstr "" 807 808#: ../../__w/calibre/calibre/manual/template_lang.rst:283 809msgid "" 810"``If`` expressions first evaluate the ``condition``. If the ``condition`` is" 811" True (a non-empty value) then the ``expression_list`` in the ``then`` " 812"clause is evaluated. If it is False then if present the ``expression_list`` " 813"in the ``elif`` or ``else`` clause is evaluated. The ``elif`` and ``else`` " 814"parts are optional. The words ``if``, ``then``, ``elif``, ``else``, and " 815"``fi`` are reserved; you cannot use them as identifier names. You can put " 816"newlines and white space wherever they make sense. The ``condition`` is a " 817"``top_expression`` not an ``expression_list``; semicolons are not allowed. " 818"The ``expression_lists`` are semicolon-separated sequences of " 819"``top_expressions``. An ``if`` expression returns the result of the last " 820"``top_expression`` in the evaluated ``expression_list``, or the empty string" 821" if no expression list was evaluated." 822msgstr "" 823 824#: ../../__w/calibre/calibre/manual/template_lang.rst:285 825msgid "Examples::" 826msgstr "" 827 828#: ../../__w/calibre/calibre/manual/template_lang.rst:298 829msgid "Nested ``if`` example::" 830msgstr "" 831 832#: ../../__w/calibre/calibre/manual/template_lang.rst:311 833msgid "" 834"As said above, an ``if`` produces a value. This means that all the following" 835" are equivalent::" 836msgstr "" 837 838#: ../../__w/calibre/calibre/manual/template_lang.rst:317 839msgid "" 840"As a last example, this program returns the value of the ``series`` column " 841"if the book has a series, otherwise the value of the ``title`` column::" 842msgstr "" 843 844#: ../../__w/calibre/calibre/manual/template_lang.rst:321 845msgid "**For expressions**" 846msgstr "" 847 848#: ../../__w/calibre/calibre/manual/template_lang.rst:323 849msgid "" 850"The ``for`` expression iterates over a list of values, processing them one " 851"at a time. The ``list_expression`` must evaluate to either a metadata field " 852"``lookup name``, for example ``tags`` or ``#genre``, or a list of values. If" 853" the result is a valid ``lookup name`` then the field's value is fetched and" 854" the separator specified for that field type is used. If the result isn't a " 855"valid lookup name then it is assumed to be a list of values. The list is " 856"assumed to be separated by commas unless the optional keyword ``separator`` " 857"is supplied, in which case the list values must be separated by the result " 858"of evaluating the ``separator_expr``. Each value in the list is assigned to " 859"the specified variable then the ``expression_list`` is evaluated. You can " 860"use ``break`` to jump out of the loop, and ``continue`` to jump to the " 861"beginning of the loop for the next iteration." 862msgstr "" 863 864#: ../../__w/calibre/calibre/manual/template_lang.rst:325 865msgid "" 866"Example: This template removes the first hierarchical name for each value in" 867" Genre (``#genre``), constructing a list with the new names::" 868msgstr "" 869 870#: ../../__w/calibre/calibre/manual/template_lang.rst:335 871msgid "" 872"If the original Genre is `History.Military, Science Fiction.Alternate " 873"History, ReadMe` then the template returns `Military, Alternate History, " 874"ReadMe`. You could use this template in calibre's :guilabel:`Edit metadata " 875"in bulk -> Search & replace` with :guilabel:`Search for` set to ``template``" 876" to strip off the first level of the hierarchy and assign the resulting " 877"value to Genre." 878msgstr "" 879 880#: ../../__w/calibre/calibre/manual/template_lang.rst:338 881msgid "" 882"Note: the last line in the template, ``new_tags``, isn't strictly necessary " 883"in this case because ``for`` returns the value of the last top_expression in" 884" the expression list. The value of an assignment is the value of its " 885"expression, so the value of the ``for`` statement is what was assigned to " 886"``new_tags``." 887msgstr "" 888 889#: ../../__w/calibre/calibre/manual/template_lang.rst:340 890msgid "**Relational operators**" 891msgstr "" 892 893#: ../../__w/calibre/calibre/manual/template_lang.rst:342 894msgid "" 895"Relational operators return ``'1'`` if the comparison is true, otherwise the" 896" empty string ('')." 897msgstr "" 898 899#: ../../__w/calibre/calibre/manual/template_lang.rst:344 900msgid "" 901"There are two forms of relational operators: string comparisons and numeric " 902"comparisons." 903msgstr "" 904 905#: ../../__w/calibre/calibre/manual/template_lang.rst:346 906msgid "" 907"String comparisons do case-insensitive string comparison using lexical " 908"order. The supported string comparison operators are ``==``, ``!=``, ``<``, " 909"``<=``, ``>``, ``>=``, ``in``, and ``inlist``. For the ``in`` operator, the " 910"result of the left hand expression is interpreted as a regular expression " 911"pattern. The ``in`` operator is True if the value of left-hand regular " 912"expression matches the value of the right hand expression. The ``inlist`` " 913"operator is true if the left hand regular expression matches any one of the " 914"items in the right hand list where the items in the list are separated by " 915"commas. The matches are case-insensitive." 916msgstr "" 917 918#: ../../__w/calibre/calibre/manual/template_lang.rst:349 919msgid "" 920"The numeric comparison operators are ``==#``, ``!=#``, ``<#``, ``<=#``, " 921"``>#``, ``>=#``. The left and right expressions must evaluate to numeric " 922"values with two exceptions: both the string value \"None\" (undefined field)" 923" and the empty string evaluate to the value zero." 924msgstr "" 925 926#: ../../__w/calibre/calibre/manual/template_lang.rst:353 927msgid "" 928"``program: field('series') == 'foo'`` returns ``'1'`` if the book's series " 929"is 'foo', otherwise ``''``." 930msgstr "" 931 932#: ../../__w/calibre/calibre/manual/template_lang.rst:354 933msgid "" 934"``program: 'f.o' in field('series')`` returns ``'1'`` if the book's series " 935"matches the regular expression ``f.o`` (e.g., `foo`, `Off Onyx`, etc.), " 936"otherwise ``''``." 937msgstr "" 938 939#: ../../__w/calibre/calibre/manual/template_lang.rst:355 940msgid "" 941"``program: 'science' inlist field('#genre')`` returns ``'1'`` if any of the " 942"book's genres match the regular expression ``science``, e.g., `Science`, " 943"`History of Science`, `Science Fiction` etc.), otherwise ``''``." 944msgstr "" 945 946#: ../../__w/calibre/calibre/manual/template_lang.rst:356 947msgid "" 948"``program: '^science$' inlist field('#genre')`` returns ``'1'`` if any of " 949"the book's genres exactly match the regular expression ``^science$``, e.g., " 950"`Science`. The genres `History of Science` and `Science Fiction` don't " 951"match. If there isn't a match then returns ``''``." 952msgstr "" 953 954#: ../../__w/calibre/calibre/manual/template_lang.rst:357 955msgid "" 956"``program: if field('series') != 'foo' then 'bar' else 'mumble' fi`` returns" 957" ``'bar'`` if the book's series is not ``foo``. Otherwise it returns " 958"``'mumble'``." 959msgstr "" 960 961#: ../../__w/calibre/calibre/manual/template_lang.rst:358 962msgid "" 963"``program: if field('series') == 'foo' || field('series') == '1632' then " 964"'yes' else 'no' fi`` returns ``'yes'`` if series is either ``'foo'`` or " 965"``'1632'``, otherwise ``'no'``." 966msgstr "" 967 968#: ../../__w/calibre/calibre/manual/template_lang.rst:359 969msgid "" 970"``program: if '^(foo|1632)$' in field('series') then 'yes' else 'no' fi`` " 971"returns ``'yes'`` if series is either ``'foo'`` or ``'1632'``, otherwise " 972"``'no'``." 973msgstr "" 974 975#: ../../__w/calibre/calibre/manual/template_lang.rst:360 976msgid "" 977"``program: if 11 > 2 then 'yes' else 'no' fi`` returns ``'no'`` because the " 978"``>`` operator does a lexical comparison." 979msgstr "" 980 981#: ../../__w/calibre/calibre/manual/template_lang.rst:361 982msgid "" 983"``program: if 11 ># 2 then 'yes' else 'no' fi`` returns ``'yes'`` because " 984"the ``>#`` operator does a numeric comparison." 985msgstr "" 986 987#: ../../__w/calibre/calibre/manual/template_lang.rst:363 988msgid "**Additional available functions**" 989msgstr "" 990 991#: ../../__w/calibre/calibre/manual/template_lang.rst:365 992msgid "" 993"The following functions are available in addition to those described in " 994":ref:`Single Function Mode <single_mode>`." 995msgstr "" 996 997#: ../../__w/calibre/calibre/manual/template_lang.rst:367 998msgid "" 999"In `GPM` the functions described in `Single Function Mode` all require an " 1000"additional first parameter specifying the value to operate upon. All " 1001"parameters are expression_lists (see the grammar above)." 1002msgstr "" 1003 1004#: ../../__w/calibre/calibre/manual/template_lang.rst:369 1005msgid "" 1006"``add(x [, y]*)`` -- returns the sum of its arguments. Throws an exception " 1007"if an argument is not a number. In most cases you can use the ``+`` operator" 1008" instead of this function." 1009msgstr "" 1010 1011#: ../../__w/calibre/calibre/manual/template_lang.rst:370 1012msgid "" 1013"``and(value [, value]*)`` -- returns the string \"1\" if all values are not " 1014"empty, otherwise returns the empty string. You can have as many values as " 1015"you want. In most cases you can use the ``&&`` operator instead of this " 1016"function. One reason not to replace ``and`` with ``&&`` is if short-" 1017"circuiting can change the results because of side effects. For example, " 1018"``and(a='',b=5)`` will always do both assignments, where the ``&&`` operator" 1019" won't do the second." 1020msgstr "" 1021 1022#: ../../__w/calibre/calibre/manual/template_lang.rst:371 1023msgid "" 1024"``assign(id, val)`` -- assigns ``val`` to ``id``, then returns ``val``. " 1025"``id`` must be an identifier, not an expression. In most cases you can use " 1026"the ``=`` operator instead of this function." 1027msgstr "" 1028 1029#: ../../__w/calibre/calibre/manual/template_lang.rst:372 1030msgid "" 1031"``approximate_formats()`` -- return a comma-separated list of formats " 1032"associated with the book. There is no guarantee that the list is correct, " 1033"although it probably is. This and other zero-parameter functions can be " 1034"called in Template Program Mode (see below) using the template " 1035"``{:'approximate_formats()'}``. Note that resulting format names are always " 1036"uppercase, as in EPUB. The ``approximate_formats()`` function is " 1037"significantly faster than the ``formats_...`` functions discussed below." 1038msgstr "" 1039 1040#: ../../__w/calibre/calibre/manual/template_lang.rst:373 1041msgid "" 1042"``author_links(val_separator, pair_separator)`` -- returns a string " 1043"containing a list of authors and those authors' link values in the form::" 1044msgstr "" 1045 1046#: ../../__w/calibre/calibre/manual/template_lang.rst:377 1047msgid "" 1048"An author is separated from its link value by the ``val_separator`` string " 1049"with no added spaces. ``author:linkvalue`` pairs are separated by the " 1050"``pair_separator`` string argument with no added spaces. It is up to you to " 1051"choose separator strings that do not occur in author names or links. An " 1052"author is included even if the author link is empty." 1053msgstr "" 1054 1055#: ../../__w/calibre/calibre/manual/template_lang.rst:378 1056msgid "" 1057"``author_sorts(val_separator)`` -- returns a string containing a list of " 1058"author's sort values for the authors of the book. The sort is the one in the" 1059" author metadata information (different from the author_sort in books). The " 1060"returned list has the form ``author sort 1`` ``val_separator`` ``author sort" 1061" 2`` etc. with no added spaces. The author sort values in this list are in " 1062"the same order as the authors of the book. If you want spaces around " 1063"``val_separator`` then include them in the ``val_separator`` string." 1064msgstr "" 1065 1066#: ../../__w/calibre/calibre/manual/template_lang.rst:379 1067msgid "" 1068"``booksize()`` -- returns the value of the calibre 'size' field. Returns '' " 1069"if there are no formats." 1070msgstr "" 1071 1072#: ../../__w/calibre/calibre/manual/template_lang.rst:380 1073msgid "" 1074"``check_yes_no(field_name, is_undefined, is_false, is_true)`` -- checks if " 1075"the value of the yes/no field named by the lookup name ``field_name`` is one" 1076" of the values specified by the parameters, returning ``'yes'`` if a match " 1077"is found otherwise returning the empty string. Set the parameter " 1078"``is_undefined``, ``is_false``, or ``is_true`` to 1 (the number) to check " 1079"that condition, otherwise set it to 0. Example:" 1080msgstr "" 1081 1082#: ../../__w/calibre/calibre/manual/template_lang.rst:382 1083msgid "" 1084"``check_yes_no(\"#bool\", 1, 0, 1)`` returns ``'yes'`` if the yes/no field " 1085"``#bool`` is either True or undefined (neither True nor False)." 1086msgstr "" 1087 1088#: ../../__w/calibre/calibre/manual/template_lang.rst:384 1089msgid "" 1090"More than one of ``is_undefined``, ``is_false``, or ``is_true`` can be set " 1091"to 1." 1092msgstr "" 1093 1094#: ../../__w/calibre/calibre/manual/template_lang.rst:385 1095msgid "" 1096"``ceiling(x)`` -- returns the smallest integer greater than or equal to " 1097"``x``. Throws an exception if ``x`` is not a number." 1098msgstr "" 1099 1100#: ../../__w/calibre/calibre/manual/template_lang.rst:386 1101msgid "" 1102"``character(character_name)`` -- returns the character named by " 1103"character_name. For example, ``character('newline')`` returns a newline " 1104"character (``'\\n'``). The supported character names are ``newline``, " 1105"``return``, ``tab``, and ``backslash``." 1106msgstr "" 1107 1108#: ../../__w/calibre/calibre/manual/template_lang.rst:387 1109msgid "" 1110"``cmp(x, y, lt, eq, gt)`` -- compares ``x`` and ``y`` after converting both " 1111"to numbers. Returns ``lt`` if ``x <# y``, ``eq`` if ``x ==# y``, otherwise " 1112"``gt``. This function can usually be replaced with one of the numeric " 1113"compare operators (``==#``, ``<#``, ``>#``, etc)." 1114msgstr "" 1115 1116#: ../../__w/calibre/calibre/manual/template_lang.rst:388 1117msgid "" 1118"``connected_device_name(storage_location_key)`` -- if a device is connected " 1119"then return the device name, otherwise return the empty string. Each storage" 1120" location on a device has its own device name. The ``storage_location_key`` " 1121"names are ``'main'``, ``'carda'`` and ``'cardb'``. This function works only " 1122"in the GUI." 1123msgstr "" 1124 1125#: ../../__w/calibre/calibre/manual/template_lang.rst:389 1126msgid "" 1127"``connected_device_uuid(storage_location_key)`` -- if a device is connected " 1128"then return the device uuid (unique id), otherwise return the empty string. " 1129"Each storage location on a device has a different uuid. The " 1130"``storage_location_key`` location names are ``'main'``, ``'carda'`` and " 1131"``'cardb'``. This function works only in the GUI." 1132msgstr "" 1133 1134#: ../../__w/calibre/calibre/manual/template_lang.rst:390 1135msgid "" 1136"``current_library_name()`` -- return the last name on the path to the " 1137"current calibre library." 1138msgstr "" 1139 1140#: ../../__w/calibre/calibre/manual/template_lang.rst:391 1141msgid "" 1142"``current_library_path()`` -- return the full path to the current calibre " 1143"library." 1144msgstr "" 1145 1146#: ../../__w/calibre/calibre/manual/template_lang.rst:392 1147msgid "" 1148"``current_virtual_library_name()`` -- return the name of the current virtual" 1149" library if there is one, otherwise the empty string. Library name case is " 1150"preserved. Example: ``program: current_virtual_library_name()``. This " 1151"function works only in the GUI." 1152msgstr "" 1153 1154#: ../../__w/calibre/calibre/manual/template_lang.rst:393 1155msgid "" 1156"``date_arithmetic(date, calc_spec, fmt)`` -- Calculate a new date from " 1157"``date`` using ``calc_spec``. Return the new date formatted according to " 1158"optional ``fmt``: if not supplied then the result will be in ISO format. The" 1159" calc_spec is a string formed by concatenating pairs of ``vW`` " 1160"(``valueWhat``) where ``v`` is a possibly-negative number and W is one of " 1161"the following letters:" 1162msgstr "" 1163 1164#: ../../__w/calibre/calibre/manual/template_lang.rst:395 1165msgid "``s``: add ``v`` seconds to ``date``" 1166msgstr "" 1167 1168#: ../../__w/calibre/calibre/manual/template_lang.rst:396 1169msgid "``m``: add ``v`` minutes to ``date``" 1170msgstr "" 1171 1172#: ../../__w/calibre/calibre/manual/template_lang.rst:397 1173msgid "``h``: add ``v`` hours to ``date``" 1174msgstr "" 1175 1176#: ../../__w/calibre/calibre/manual/template_lang.rst:398 1177msgid "``d``: add ``v`` days to ``date``" 1178msgstr "" 1179 1180#: ../../__w/calibre/calibre/manual/template_lang.rst:399 1181msgid "``w``: add ``v`` weeks to ``date``" 1182msgstr "" 1183 1184#: ../../__w/calibre/calibre/manual/template_lang.rst:400 1185msgid "``y``: add ``v`` years to ``date``, where a year is 365 days." 1186msgstr "" 1187 1188#: ../../__w/calibre/calibre/manual/template_lang.rst:402 1189msgid "" 1190"Example: ``'1s3d-1m'`` will add 1 second, add 3 days, and subtract 1 minute " 1191"from ``date``." 1192msgstr "" 1193 1194#: ../../__w/calibre/calibre/manual/template_lang.rst:403 1195msgid "" 1196"``days_between(date1, date2)`` -- return the number of days between " 1197"``date1`` and ``date2``. The number is positive if ``date1`` is greater than" 1198" ``date2``, otherwise negative. If either ``date1`` or ``date2`` are not " 1199"dates, the function returns the empty string." 1200msgstr "" 1201 1202#: ../../__w/calibre/calibre/manual/template_lang.rst:404 1203msgid "" 1204"``divide(x, y)`` -- returns ``x / y``. Throws an exception if either ``x`` " 1205"or ``y`` are not numbers. This function can usually be replaced by the ``/``" 1206" operator." 1207msgstr "" 1208 1209#: ../../__w/calibre/calibre/manual/template_lang.rst:405 1210msgid "" 1211"``eval(string)`` -- evaluates the string as a program, passing the local " 1212"variables. This permits using the template processor to construct complex " 1213"results from local variables. In :ref:`Template Program Mode " 1214"<template_mode>`, because the `{` and `}` characters are interpreted before " 1215"the template is evaluated you must use `[[` for the `{` character and `]]` " 1216"for the ``}`` character. They are converted automatically. Note also that " 1217"prefixes and suffixes (the `|prefix|suffix` syntax) cannot be used in the " 1218"argument to this function when using :ref:`Template Program Mode " 1219"<template_mode>`." 1220msgstr "" 1221 1222#: ../../__w/calibre/calibre/manual/template_lang.rst:406 1223msgid "" 1224"``field(lookup_name)`` -- returns the value of the metadata field with " 1225"lookup name ``lookup_name``." 1226msgstr "" 1227 1228#: ../../__w/calibre/calibre/manual/template_lang.rst:407 1229msgid "" 1230"``field_exists(field_name)`` -- checks if a field (column) with the lookup " 1231"name ``field_name`` exists, returning ``'1'`` if so and the empty string if " 1232"not." 1233msgstr "" 1234 1235#: ../../__w/calibre/calibre/manual/template_lang.rst:408 1236msgid "" 1237"``finish_formatting(val, fmt, prefix, suffix)`` -- apply the format, prefix," 1238" and suffix to a value in the same way as done in a template like " 1239"``{series_index:05.2f| - |- }``. This function is provided to ease " 1240"conversion of complex single-function- or template-program-mode templates to" 1241" `GPM` Templates. For example, the following program produces the same " 1242"output as the above template::" 1243msgstr "" 1244 1245#: ../../__w/calibre/calibre/manual/template_lang.rst:412 1246msgid "" 1247"Another example: for the template " 1248"``{series:re(([^\\s])[^\\s]+(\\s|$),\\1)}{series_index:0>2s| - | - " 1249"}{title}`` use::" 1250msgstr "" 1251 1252#: ../../__w/calibre/calibre/manual/template_lang.rst:421 1253msgid "" 1254"``first_matching_cmp(val, [ cmp, result, ]* else_result)`` -- compares ``val" 1255" < cmp`` in sequence, returning the associated result for the first " 1256"comparison that succeeds. Returns else_result if no comparison succeeds. " 1257"Example::" 1258msgstr "" 1259 1260#: ../../__w/calibre/calibre/manual/template_lang.rst:426 1261msgid "" 1262"returns ``\"large\"``. The same example with a first value of 16 returns " 1263"``\"giant\"``." 1264msgstr "" 1265 1266#: ../../__w/calibre/calibre/manual/template_lang.rst:428 1267msgid "" 1268"``first_non_empty(value [, value]*)`` -- returns the first ``value`` that is" 1269" not empty. If all values are empty, then the empty string is returned. You " 1270"can have as many values as you want." 1271msgstr "" 1272 1273#: ../../__w/calibre/calibre/manual/template_lang.rst:429 1274msgid "" 1275"``floor(x)`` -- returns the largest integer less than or equal to ``x``. " 1276"Throws an exception if ``x`` is not a number." 1277msgstr "" 1278 1279#: ../../__w/calibre/calibre/manual/template_lang.rst:430 1280msgid "" 1281"``format_date(val, format_string)`` -- format the value, which must be a " 1282"date string, using the format_string, returning a string. The formatting " 1283"codes are:" 1284msgstr "" 1285 1286#: ../../__w/calibre/calibre/manual/template_lang.rst:432 1287msgid "``d :`` the day as number without a leading zero (1 to 31)" 1288msgstr "" 1289 1290#: ../../__w/calibre/calibre/manual/template_lang.rst:433 1291msgid "``dd :`` the day as number with a leading zero (01 to 31)" 1292msgstr "" 1293 1294#: ../../__w/calibre/calibre/manual/template_lang.rst:434 1295msgid "``ddd :`` the abbreviated localized day name (e.g. \"Mon\" to \"Sun\")." 1296msgstr "" 1297 1298#: ../../__w/calibre/calibre/manual/template_lang.rst:435 1299msgid "``dddd :`` the long localized day name (e.g. \"Monday\" to \"Sunday\")." 1300msgstr "" 1301 1302#: ../../__w/calibre/calibre/manual/template_lang.rst:436 1303msgid "``M :`` the month as number without a leading zero (1 to 12)." 1304msgstr "" 1305 1306#: ../../__w/calibre/calibre/manual/template_lang.rst:437 1307msgid "``MM :`` the month as number with a leading zero (01 to 12)" 1308msgstr "" 1309 1310#: ../../__w/calibre/calibre/manual/template_lang.rst:438 1311msgid "``MMM :`` the abbreviated localized month name (e.g. \"Jan\" to \"Dec\")." 1312msgstr "" 1313 1314#: ../../__w/calibre/calibre/manual/template_lang.rst:439 1315msgid "``MMMM :`` the long localized month name (e.g. \"January\" to \"December\")." 1316msgstr "" 1317 1318#: ../../__w/calibre/calibre/manual/template_lang.rst:440 1319msgid "``yy :`` the year as two digit number (00 to 99)." 1320msgstr "" 1321 1322#: ../../__w/calibre/calibre/manual/template_lang.rst:441 1323msgid "``yyyy :`` the year as four digit number." 1324msgstr "" 1325 1326#: ../../__w/calibre/calibre/manual/template_lang.rst:442 1327msgid "" 1328"``h :`` the hours without a leading 0 (0 to 11 or 0 to 23, depending on " 1329"am/pm)" 1330msgstr "" 1331 1332#: ../../__w/calibre/calibre/manual/template_lang.rst:443 1333msgid "" 1334"``hh :`` the hours with a leading 0 (00 to 11 or 00 to 23, depending on " 1335"am/pm)" 1336msgstr "" 1337 1338#: ../../__w/calibre/calibre/manual/template_lang.rst:444 1339msgid "``m :`` the minutes without a leading 0 (0 to 59)" 1340msgstr "" 1341 1342#: ../../__w/calibre/calibre/manual/template_lang.rst:445 1343msgid "``mm :`` the minutes with a leading 0 (00 to 59)" 1344msgstr "" 1345 1346#: ../../__w/calibre/calibre/manual/template_lang.rst:446 1347msgid "``s :`` the seconds without a leading 0 (0 to 59)" 1348msgstr "" 1349 1350#: ../../__w/calibre/calibre/manual/template_lang.rst:447 1351msgid "``ss :`` the seconds with a leading 0 (00 to 59)" 1352msgstr "" 1353 1354#: ../../__w/calibre/calibre/manual/template_lang.rst:448 1355msgid "" 1356"``ap :`` use a 12-hour clock instead of a 24-hour clock, with 'ap' " 1357"replaced by the localized string for am or pm." 1358msgstr "" 1359 1360#: ../../__w/calibre/calibre/manual/template_lang.rst:449 1361msgid "" 1362"``AP :`` use a 12-hour clock instead of a 24-hour clock, with 'AP' " 1363"replaced by the localized string for AM or PM." 1364msgstr "" 1365 1366#: ../../__w/calibre/calibre/manual/template_lang.rst:450 1367msgid "" 1368"``iso :`` the date with time and timezone. Must be the only format present." 1369msgstr "" 1370 1371#: ../../__w/calibre/calibre/manual/template_lang.rst:451 1372msgid "" 1373"``to_number :`` convert the date & time into a floating point number (a " 1374"`timestamp`)" 1375msgstr "" 1376 1377#: ../../__w/calibre/calibre/manual/template_lang.rst:452 1378msgid "" 1379"``from_number :`` convert a floating point number (a `timestamp`) into an " 1380"``iso`` formatted date. If you want a different date format then add the " 1381"desired formatting string after ``from_number`` and a colon (``:``). " 1382"Example: ``from_number:MMM dd yyyy``" 1383msgstr "" 1384 1385#: ../../__w/calibre/calibre/manual/template_lang.rst:454 1386msgid "" 1387"You might get unexpected results if the date you are formatting contains " 1388"localized month names, which can happen if you changed the date format " 1389"tweaks to contain ``MMMM``. In this case, instead of using the ``field()`` " 1390"function as in::" 1391msgstr "" 1392 1393#: ../../__w/calibre/calibre/manual/template_lang.rst:458 1394msgid "use the ``raw_field()`` function as in::" 1395msgstr "" 1396 1397#: ../../__w/calibre/calibre/manual/template_lang.rst:462 1398msgid "" 1399"``formats_modtimes(date_format_string)`` -- return a comma-separated list of" 1400" colon-separated items ``FMT:DATE`` representing modification times for the " 1401"formats of a book. The ``date_format_string`` parameter specifies how the " 1402"date is to be formatted. See the ``format_date()`` function for details. You" 1403" can use the ``select`` function to get the modification time for a specific" 1404" format. Note that format names are always uppercase, as in EPUB." 1405msgstr "" 1406 1407#: ../../__w/calibre/calibre/manual/template_lang.rst:463 1408msgid "" 1409"``formats_paths()`` -- return a comma-separated list of colon-separated " 1410"items ``FMT:PATH`` giving the full path to the formats of a book. You can " 1411"use the select function to get the path for a specific format. Note that " 1412"format names are always uppercase, as in EPUB." 1413msgstr "" 1414 1415#: ../../__w/calibre/calibre/manual/template_lang.rst:464 1416msgid "" 1417"``formats_sizes()`` -- return a comma-separated list of colon-separated " 1418"``FMT:SIZE`` items giving the sizes in bytes of the formats of a book. You " 1419"can use the select function to get the size for a specific format. Note that" 1420" format names are always uppercase, as in EPUB." 1421msgstr "" 1422 1423#: ../../__w/calibre/calibre/manual/template_lang.rst:465 1424msgid "" 1425"``fractional_part(x)`` -- returns the value after the decimal point. For " 1426"example, ``fractional_part(3.14)`` returns ``0.14``. Throws an exception if " 1427"``x`` is not a number." 1428msgstr "" 1429 1430#: ../../__w/calibre/calibre/manual/template_lang.rst:466 1431msgid "" 1432"``has_cover()`` -- return ``'Yes'`` if the book has a cover, otherwise the " 1433"empty string." 1434msgstr "" 1435 1436#: ../../__w/calibre/calibre/manual/template_lang.rst:467 1437msgid "" 1438"``is_marked()`` -- check whether the book is `marked` in calibre. If it is " 1439"then return the value of the mark, either ``'true'`` (lower case) or a " 1440"comma-separated list of named marks. Returns ``''`` (the empty string) if " 1441"the book is not marked. This function works only in the GUI." 1442msgstr "" 1443 1444#: ../../__w/calibre/calibre/manual/template_lang.rst:468 1445msgid "" 1446"``language_codes(lang_strings)`` -- return the `language codes " 1447"<https://www.loc.gov/standards/iso639-2/php/code_list.php>`_ for the " 1448"language names passed in `lang_strings`. The strings must be in the language" 1449" of the current locale. ``Lang_strings`` is a comma-separated list." 1450msgstr "" 1451 1452#: ../../__w/calibre/calibre/manual/template_lang.rst:469 1453msgid "" 1454"``list_contains(value, separator, [ pattern, found_val, ]* not_found_val)`` " 1455"-- (Alias of ``in_list``) Interpreting the value as a list of items " 1456"separated by ``separator``, evaluate the ``pattern`` against each value in " 1457"the list. If the ``pattern`` matches any value then return ``found_val``, " 1458"otherwise return ``not_found_val``. The ``pattern`` and ``found_value`` can " 1459"be repeated as many times as desired, permitting returning different values " 1460"depending on the search. The patterns are checked in order. The first match " 1461"is returned. Aliases: ``in_list()``, ``list_contains()``" 1462msgstr "" 1463 1464#: ../../__w/calibre/calibre/manual/template_lang.rst:470 1465msgid "" 1466"``list_count(value, separator)`` -- interprets ``value`` as a list of items " 1467"separated by ``separator``, returning the count of items in the list. " 1468"Aliases: ``count()``, ``list_count()``" 1469msgstr "" 1470 1471#: ../../__w/calibre/calibre/manual/template_lang.rst:471 1472msgid "" 1473"``list_count_matching(list, pattern, separator)`` -- interprets ``list`` as " 1474"a list of items separated by ``separator``, returning the number of items in" 1475" the list that match the regular expression ``pattern``. Aliases: " 1476"``list_count_matching()``, ``count_matching()``" 1477msgstr "" 1478 1479#: ../../__w/calibre/calibre/manual/template_lang.rst:472 1480msgid "" 1481"``list_difference(list1, list2, separator)`` -- return a list made by " 1482"removing from ``list1`` any item found in ``list2`` using a case-insensitive" 1483" comparison. The items in ``list1`` and ``list2`` are separated by " 1484"separator, as are the items in the returned list." 1485msgstr "" 1486 1487#: ../../__w/calibre/calibre/manual/template_lang.rst:473 1488msgid "" 1489"``list_equals(list1, sep1, list2, sep2, yes_val, no_val)`` -- return " 1490"``yes_val`` if ``list1`` and `list2` contain the same items, otherwise " 1491"return ``no_val``. The items are determined by splitting each list using the" 1492" appropriate separator character (``sep1`` or ``sep2``). The order of items " 1493"in the lists is not relevant. The comparison is case-insensitive." 1494msgstr "" 1495 1496#: ../../__w/calibre/calibre/manual/template_lang.rst:474 1497msgid "" 1498"``list_intersection(list1, list2, separator)`` -- return a list made by " 1499"removing from ``list1`` any item not found in ``list2``, using a case-" 1500"insensitive comparison. The items in ``list1`` and ``list2`` are separated " 1501"by separator, as are the items in the returned list." 1502msgstr "" 1503 1504#: ../../__w/calibre/calibre/manual/template_lang.rst:475 1505msgid "" 1506"``list_re(src_list, separator, include_re, opt_replace)`` -- Construct a " 1507"list by first separating ``src_list`` into items using the ``separator`` " 1508"character. For each item in the list, check if it matches ``include_re``. If" 1509" it does then add it to the list to be returned. If ``opt_replace`` is not " 1510"the empty string then apply the replacement before adding the item to the " 1511"returned list." 1512msgstr "" 1513 1514#: ../../__w/calibre/calibre/manual/template_lang.rst:476 1515msgid "" 1516"``list_re_group(src_list, separator, include_re, search_re [, " 1517"template_for_group]*)`` -- Like list_re except replacements are not " 1518"optional. It uses ``re_group(item, search_re, template ...)`` when doing the" 1519" replacements." 1520msgstr "" 1521 1522#: ../../__w/calibre/calibre/manual/template_lang.rst:477 1523msgid "" 1524"``list_remove_duplicates(list, separator)`` -- return a list made by " 1525"removing duplicate items in ``list``. If items differ only in case then the " 1526"last is returned. The items in ``list`` are separated by ``separator``, as " 1527"are the items in the returned list." 1528msgstr "" 1529 1530#: ../../__w/calibre/calibre/manual/template_lang.rst:478 1531msgid "" 1532"``list_sort(list, direction, separator)`` -- return ``list`` sorted using a " 1533"case-insensitive lexical sort. If ``direction`` is zero, ``list`` is sorted " 1534"ascending, otherwise descending. The list items are separated by " 1535"``separator``, as are the items in the returned list." 1536msgstr "" 1537 1538#: ../../__w/calibre/calibre/manual/template_lang.rst:479 1539msgid "" 1540"``list_split(list_val, sep, id_prefix)`` -- splits ``list_val`` into " 1541"separate values using ``sep``, then assigns the values to local variables " 1542"named ``id_prefix_N`` where N is the position of the value in the list. The " 1543"first item has position 0 (zero). The function returns the last element in " 1544"the list." 1545msgstr "" 1546 1547#: ../../__w/calibre/calibre/manual/template_lang.rst:481 1548msgid "Example::" 1549msgstr "" 1550 1551#: ../../__w/calibre/calibre/manual/template_lang.rst:485 1552msgid "is equivalent to::" 1553msgstr "" 1554 1555#: ../../__w/calibre/calibre/manual/template_lang.rst:491 1556msgid "" 1557"``list_union(list1, list2, separator)`` -- return a list made by merging the" 1558" items in ``list1`` and ``list2``, removing duplicate items using a case-" 1559"insensitive comparison. If items differ in case, the one in ``list1`` is " 1560"used. The items in ``list1`` and ``list2`` are separated by ``separator``, " 1561"as are the items in the returned list. Aliases: ``merge_lists()``, " 1562"``list_union()``" 1563msgstr "" 1564 1565#: ../../__w/calibre/calibre/manual/template_lang.rst:492 1566msgid "" 1567"``mod(x, y)`` -- returns the ``floor`` of the remainder of ``x / y``. Throws" 1568" an exception if either ``x`` or ``y`` is not a number." 1569msgstr "" 1570 1571#: ../../__w/calibre/calibre/manual/template_lang.rst:493 1572msgid "" 1573"``multiply(x [, y]*)`` -- returns the product of its arguments. Throws an " 1574"exception if any argument is not a number. This function can usually be " 1575"replaced by the ``*`` operator." 1576msgstr "" 1577 1578#: ../../__w/calibre/calibre/manual/template_lang.rst:494 1579msgid "" 1580"``not(value)`` -- returns the string \"1\" if the value is empty, otherwise " 1581"returns the empty string. This function can usually be replaced with the " 1582"unary not (``!``) operator." 1583msgstr "" 1584 1585#: ../../__w/calibre/calibre/manual/template_lang.rst:495 1586msgid "" 1587"``ondevice()`` -- return the string ``'Yes'`` if ``ondevice`` is set, " 1588"otherwise return the empty string." 1589msgstr "" 1590 1591#: ../../__w/calibre/calibre/manual/template_lang.rst:496 1592msgid "" 1593"``or(value [, value]*)`` -- returns the string ``'1'`` if any value is not " 1594"empty, otherwise returns the empty string. You can have as many values as " 1595"you want. This function can usually be replaced by the ``||`` operator. A " 1596"reason it cannot be replaced is if short-circuiting will change the results " 1597"because of side effects." 1598msgstr "" 1599 1600#: ../../__w/calibre/calibre/manual/template_lang.rst:497 1601msgid "" 1602"``print(a [, b]*)`` -- prints the arguments to standard output. Unless you " 1603"start calibre from the command line (``calibre-debug -g``), the output will " 1604"go to a black hole. The ``print`` function always returns the empty string." 1605msgstr "" 1606 1607#: ../../__w/calibre/calibre/manual/template_lang.rst:498 1608msgid "" 1609"``raw_field(lookup_name [, optional_default])`` -- returns the metadata " 1610"field named by ``lookup_name`` without applying any formatting. It evaluates" 1611" and returns the optional second argument ``optional_default`` if the " 1612"field's value is undefined (``None``)." 1613msgstr "" 1614 1615#: ../../__w/calibre/calibre/manual/template_lang.rst:499 1616msgid "" 1617"``raw_list(lookup_name, separator)`` -- returns the metadata list named by " 1618"``lookup_name`` without applying any formatting or sorting, with the items " 1619"separated by separator." 1620msgstr "" 1621 1622#: ../../__w/calibre/calibre/manual/template_lang.rst:500 1623msgid "" 1624"``re_group(value, pattern [, template_for_group]*)`` -- return a string " 1625"made by applying the regular expression pattern to ``value`` and replacing " 1626"each matched instance with the the value returned by the corresponding " 1627"template. In :ref:`Template Program Mode <template_mode>`, like for the " 1628"``template`` and the ``eval`` functions, you use ``[[`` for ``{`` and ``]]``" 1629" for ``}``." 1630msgstr "" 1631 1632#: ../../__w/calibre/calibre/manual/template_lang.rst:502 1633msgid "" 1634"The following example looks for a series with more than one word and " 1635"uppercases the first word::" 1636msgstr "" 1637 1638#: ../../__w/calibre/calibre/manual/template_lang.rst:506 1639msgid "" 1640"``round(x)`` -- returns the nearest integer to ``x``. Throws an exception if" 1641" ``x`` is not a number." 1642msgstr "" 1643 1644#: ../../__w/calibre/calibre/manual/template_lang.rst:507 1645msgid "``series_sort()`` -- returns the series sort value." 1646msgstr "" 1647 1648#: ../../__w/calibre/calibre/manual/template_lang.rst:508 1649msgid "" 1650"``strcat(a [, b]*)`` -- can take any number of arguments. Returns a string " 1651"formed by concatenating all the arguments." 1652msgstr "" 1653 1654#: ../../__w/calibre/calibre/manual/template_lang.rst:509 1655msgid "" 1656"``strcat_max(max, string1 [, prefix2, string2]*)`` -- Returns a string " 1657"formed by concatenating the arguments. The returned value is initialized to " 1658"``string1``. Strings made from ``prefix, string`` pairs are added to the end" 1659" of the value as long as the resulting string length is less than ``max``. " 1660"Prefixes can be empty. Returns ``string1`` even if ``string1`` is longer " 1661"than ``max``. You can pass as many ``prefix, string`` pairs as you wish." 1662msgstr "" 1663 1664#: ../../__w/calibre/calibre/manual/template_lang.rst:510 1665msgid "" 1666"``strcmp(x, y, lt, eq, gt)`` -- does a case-insensitive lexical comparison " 1667"of ``x`` and ``y``. Returns ``lt`` if ``x < y``, ``eq`` if ``x == y``, " 1668"otherwise ``gt``. This function can often be replaced by one of the lexical " 1669"comparison operators (``==``, ``>``, ``<``, etc.)" 1670msgstr "" 1671 1672#: ../../__w/calibre/calibre/manual/template_lang.rst:511 1673msgid "``strlen(value)`` -- Returns the length of the string ``value``." 1674msgstr "" 1675 1676#: ../../__w/calibre/calibre/manual/template_lang.rst:512 1677msgid "" 1678"``substr(str, start, end)`` -- returns the ``start``'th through the " 1679"``end``'th characters of ``str``. The first character in ``str`` is the " 1680"zero'th character. If ``end`` is negative, then it indicates that many " 1681"characters counting from the right. If ``end`` is zero, then it indicates " 1682"the last character. For example, ``substr('12345', 1, 0)`` returns " 1683"``'2345'``, and ``substr('12345', 1, -1)`` returns ``'234'``." 1684msgstr "" 1685 1686#: ../../__w/calibre/calibre/manual/template_lang.rst:513 1687msgid "" 1688"``subtract(x, y)`` -- returns ``x - y``. Throws an exception if either ``x``" 1689" or ``y`` are not numbers. This function can usually be replaced by the " 1690"``-`` operator." 1691msgstr "" 1692 1693#: ../../__w/calibre/calibre/manual/template_lang.rst:514 1694msgid "" 1695"``today()`` -- return a date+time string for today (now). This value is " 1696"designed for use in `format_date` or `days_between`, but can be manipulated " 1697"like any other string. The date is in `ISO " 1698"<https://en.wikipedia.org/wiki/ISO_8601>`_ date/time format." 1699msgstr "" 1700 1701#: ../../__w/calibre/calibre/manual/template_lang.rst:515 1702msgid "" 1703"``template(x)`` -- evaluates ``x`` as a template. The evaluation is done in " 1704"its own context, meaning that variables are not shared between the caller " 1705"and the template evaluation." 1706msgstr "" 1707 1708#: ../../__w/calibre/calibre/manual/template_lang.rst:520 1709msgid "More complex programs in template expressions - Template Program Mode" 1710msgstr "" 1711 1712#: ../../__w/calibre/calibre/manual/template_lang.rst:522 1713msgid "" 1714"`Template Program Mode` (`TPM`) is a blend of :ref:`General Program Mode " 1715"<general_mode>` and :ref:`Single Function Mode <single_mode>`. `TPM` differs" 1716" from Single Function Mode in that it permits writing template expressions " 1717"that refer to other metadata fields, use nested functions, modify variables," 1718" and do arithmetic. It differs from `General Program Mode` in that the " 1719"template is contained between ``{`` and ``}`` characters and doesn't begin " 1720"with the word ``program:``. The program portion of the template is a General" 1721" Program Mode expression list." 1722msgstr "" 1723 1724#: ../../__w/calibre/calibre/manual/template_lang.rst:525 1725msgid "" 1726"Example: assume you want a template to show the series for a book if it has " 1727"one, otherwise show the value of a custom field #genre. You cannot do this " 1728"in the :ref:`Single Function Mode <single_mode>` because you cannot make " 1729"reference to another metadata field within a template expression. In `TPM` " 1730"you can, as the following expression demonstrates::" 1731msgstr "" 1732 1733#: ../../__w/calibre/calibre/manual/template_lang.rst:530 1734msgid "The example shows several things:" 1735msgstr "" 1736 1737#: ../../__w/calibre/calibre/manual/template_lang.rst:532 1738msgid "" 1739"`TPM` is used if the expression begins with ``:'`` and ends with ``'``. " 1740"Anything else is assumed to be in :ref:`Single Function Mode <single_mode>`." 1741msgstr "" 1742 1743#: ../../__w/calibre/calibre/manual/template_lang.rst:533 1744msgid "" 1745"the variable ``$`` stands for the field named in the template: the " 1746"expression is operating upon, ``#series`` in this case." 1747msgstr "" 1748 1749#: ../../__w/calibre/calibre/manual/template_lang.rst:534 1750msgid "" 1751"functions must be given all their arguments. There is no default value. For " 1752"example, the standard built-in functions must be given an additional initial" 1753" parameter indicating the source field." 1754msgstr "" 1755 1756#: ../../__w/calibre/calibre/manual/template_lang.rst:535 1757msgid "white space is ignored and can be used anywhere within the expression." 1758msgstr "" 1759 1760#: ../../__w/calibre/calibre/manual/template_lang.rst:536 1761msgid "" 1762"constant strings are enclosed in matching quotes, either ``'`` or ``\"``." 1763msgstr "" 1764 1765#: ../../__w/calibre/calibre/manual/template_lang.rst:538 1766msgid "" 1767"All the functions listed under `Single Function Mode` and `General Program " 1768"Mode` can be used in `TPM`." 1769msgstr "" 1770 1771#: ../../__w/calibre/calibre/manual/template_lang.rst:540 1772msgid "" 1773"In `TPM`, using ``{`` and ``}`` characters in string literals can lead to " 1774"errors or unexpected results because they confuse the template processor. It" 1775" tries to treat them as template expression boundaries, not characters. In " 1776"some but not all cases you can replace a ``{`` with ``[[`` and a ``}`` with " 1777"`]]`. Generally, if your program contains ``{`` and ``}`` characters then " 1778"you should use `General Program Mode`." 1779msgstr "" 1780 1781#: ../../__w/calibre/calibre/manual/template_lang.rst:542 1782msgid "" 1783"As with `General Program Mode`, for functions documented under :ref:`Single " 1784"Function Mode <single_mode>` you must supply the value the function is to " 1785"act upon as the first parameter in addition to the documented parameters. In" 1786" `TPM` you can use ``$`` to access the value specified by the ``lookup " 1787"name`` for the template expression." 1788msgstr "" 1789 1790#: ../../__w/calibre/calibre/manual/template_lang.rst:545 1791msgid "Stored general program mode templates" 1792msgstr "" 1793 1794#: ../../__w/calibre/calibre/manual/template_lang.rst:547 1795msgid "" 1796":ref:`General Program Mode <general_mode>` supports saving templates and " 1797"calling those templates from another template, much like calling stored " 1798"functions. You save templates using " 1799":guilabel:`Preferences->Advanced->Template functions`. More information is " 1800"provided in that dialog. You call a template the same way you call a " 1801"function, passing positional arguments if desired. An argument can be any " 1802"expression. Examples of calling a template, assuming the stored template is " 1803"named ``foo``:" 1804msgstr "" 1805 1806#: ../../__w/calibre/calibre/manual/template_lang.rst:549 1807msgid "``foo()`` -- call the template passing no arguments." 1808msgstr "" 1809 1810#: ../../__w/calibre/calibre/manual/template_lang.rst:550 1811msgid "" 1812"``foo(a, b)`` call the template passing the values of the two variables " 1813"``a`` and ``b``." 1814msgstr "" 1815 1816#: ../../__w/calibre/calibre/manual/template_lang.rst:551 1817msgid "" 1818"``foo(if field('series') then field('series_index') else 0 fi)`` -- if the " 1819"book has a ``series`` then pass the ``series_index``, otherwise pass the " 1820"value ``0``." 1821msgstr "" 1822 1823#: ../../__w/calibre/calibre/manual/template_lang.rst:553 1824msgid "" 1825"You retrieve the arguments passed in the call to the stored template using " 1826"the ``arguments`` function. It both declares and initializes local " 1827"variables, effectively parameters. The variables are positional; they get " 1828"the value of the value given in the call in the same position. If the " 1829"corresponding parameter is not provided in the call then ``arguments`` " 1830"assigns that variable the provided default value. If there is no default " 1831"value then the variable is set to the empty string. For example, the " 1832"following ``arguments`` function declares 2 variables, ``key``, " 1833"``alternate``::" 1834msgstr "" 1835 1836#: ../../__w/calibre/calibre/manual/template_lang.rst:557 1837msgid "Examples, again assuming the stored template is named ``foo``:" 1838msgstr "" 1839 1840#: ../../__w/calibre/calibre/manual/template_lang.rst:559 1841msgid "" 1842"``foo('#myseries')`` -- argument ``key`` is assigned the value " 1843"``'myseries'`` and the argument ``alternate`` is assigned the default value " 1844"``'series'``." 1845msgstr "" 1846 1847#: ../../__w/calibre/calibre/manual/template_lang.rst:560 1848msgid "" 1849"``foo('series', '#genre')`` the variable ``key`` is assigned the value " 1850"``'series'`` and the variable ``alternate`` is assigned the value " 1851"``'#genre'``." 1852msgstr "" 1853 1854#: ../../__w/calibre/calibre/manual/template_lang.rst:561 1855msgid "" 1856"``foo()`` -- the variable ``key`` is assigned the empty string and the " 1857"variable ``alternate`` is assigned the value ``'series'``." 1858msgstr "" 1859 1860#: ../../__w/calibre/calibre/manual/template_lang.rst:563 1861msgid "" 1862"An easy way to test stored templates is using the ``Template tester`` " 1863"dialog. For ease of access give it a keyboard shortcut in " 1864":guilabel:`Preferences->Advanced->Keyboard shortcuts->Template tester`. " 1865"Giving the ``Stored templates`` dialog a shortcut will help switching more " 1866"rapidly between the tester and editing the stored template's source code." 1867msgstr "" 1868 1869#: ../../__w/calibre/calibre/manual/template_lang.rst:566 1870msgid "Providing additional information to templates" 1871msgstr "" 1872 1873#: ../../__w/calibre/calibre/manual/template_lang.rst:568 1874msgid "" 1875"A developer can choose to pass additional information to the template " 1876"processor, such as application-specific book metadata or information about " 1877"what the processor is being asked to do. A template can access this " 1878"information and use it during the evaluation." 1879msgstr "" 1880 1881#: ../../__w/calibre/calibre/manual/template_lang.rst:570 1882msgid "**Developer: how to pass additional information**" 1883msgstr "" 1884 1885#: ../../__w/calibre/calibre/manual/template_lang.rst:572 1886msgid "" 1887"The additional information is a Python dictionary containing pairs " 1888"``variable_name: variable_value`` where the values must be strings. The " 1889"template can access the dict, creating template local variables named " 1890"``variable_name`` containing the value ``variable_value``. The user cannot " 1891"change the name so it is best to use names that won't collide with other " 1892"template local variables, for example by prefixing the name with an " 1893"underscore." 1894msgstr "" 1895 1896#: ../../__w/calibre/calibre/manual/template_lang.rst:574 1897msgid "" 1898"This dict is passed to the template processor (the ``formatter``) using the " 1899"named parameter ``global_vars=your_dict``. The full method signature is::" 1900msgstr "" 1901 1902#: ../../__w/calibre/calibre/manual/template_lang.rst:582 1903msgid "**Template writer: how to access the additional information**" 1904msgstr "" 1905 1906#: ../../__w/calibre/calibre/manual/template_lang.rst:584 1907msgid "" 1908"You access the additional information (the ``globals`` dict) in a template " 1909"using the template function::" 1910msgstr "" 1911 1912#: ../../__w/calibre/calibre/manual/template_lang.rst:588 1913msgid "" 1914"where ``id`` is any legal variable name. This function checks whether the " 1915"additional information provided by the developer contains the name. If it " 1916"does then the function assigns the provided value to a template local " 1917"variable with that name. If the name is not in the additional information " 1918"and if an ``expression`` is provided, the ``expression`` is evaluated and " 1919"the result is assigned to the local variable. If neither a value nor an " 1920"expression is provided, the function assigns the empty string (``''``) to " 1921"the local variable." 1922msgstr "" 1923 1924#: ../../__w/calibre/calibre/manual/template_lang.rst:590 1925msgid "" 1926"A template can set a value in the ``globals`` dict using the template " 1927"function::" 1928msgstr "" 1929 1930#: ../../__w/calibre/calibre/manual/template_lang.rst:594 1931msgid "" 1932"This function sets the ``globals`` dict key:value pair ``id:value`` where " 1933"``value`` is the value of the template local variable ``id``. If that local " 1934"variable doesn't exist then ``value`` is set to the result of evaluating " 1935"``expression``." 1936msgstr "" 1937 1938#: ../../__w/calibre/calibre/manual/template_lang.rst:597 1939msgid "Notes on the difference between modes" 1940msgstr "" 1941 1942#: ../../__w/calibre/calibre/manual/template_lang.rst:599 1943msgid "" 1944"The three program modes, :ref:`Single Function Mode <single_mode>` (SFM), " 1945":ref:`Template Program Mode <template_mode>` (`TPM`), and :ref:`General " 1946"Program Mode <general_mode>` (`GPM`), work differently. SFM is intended to " 1947"be 'simple' so it hides a lot of programming language bits." 1948msgstr "" 1949 1950#: ../../__w/calibre/calibre/manual/template_lang.rst:601 1951msgid "Differences:" 1952msgstr "" 1953 1954#: ../../__w/calibre/calibre/manual/template_lang.rst:603 1955msgid "" 1956"In SFM the value of the column is always passed as an 'invisible' first " 1957"argument to a function included in the template." 1958msgstr "" 1959 1960#: ../../__w/calibre/calibre/manual/template_lang.rst:604 1961msgid "" 1962"SFM doesn't support the difference between variables and strings; all values" 1963" are strings." 1964msgstr "" 1965 1966#: ../../__w/calibre/calibre/manual/template_lang.rst:605 1967msgid "" 1968"The following SFM template returns either the series name or the string \"no" 1969" series\"::" 1970msgstr "" 1971 1972#: ../../__w/calibre/calibre/manual/template_lang.rst:609 1973msgid "The equivalent template in `TPM` is ::" 1974msgstr "" 1975 1976#: ../../__w/calibre/calibre/manual/template_lang.rst:613 1977msgid "The equivalent template in `GPM` is::" 1978msgstr "" 1979 1980#: ../../__w/calibre/calibre/manual/template_lang.rst:617 1981msgid "" 1982"The first argument to ``ifempty`` is the value of the field ``series``. The " 1983"second argument is the string ``no series``. In SFM the first argument, the " 1984"value of the field, is automatically passed (the invisible argument)." 1985msgstr "" 1986 1987#: ../../__w/calibre/calibre/manual/template_lang.rst:618 1988msgid "" 1989"Several template functions, for example ``booksize()`` and " 1990"``current_library_name()``, take no arguments. Because of the 'invisible " 1991"argument' you cannot use these functions in SFM." 1992msgstr "" 1993 1994#: ../../__w/calibre/calibre/manual/template_lang.rst:619 1995msgid "" 1996"Nested functions, where a function calls another function to compute an " 1997"argument, cannot be used in SFM. For example this template, intended to " 1998"return the first 5 characters of the series value uppercased, won't work in " 1999"SFM::" 2000msgstr "" 2001 2002#: ../../__w/calibre/calibre/manual/template_lang.rst:623 2003msgid "" 2004"`TPM` and `GPM` support nested functions. The above template in `TPM` would " 2005"be::" 2006msgstr "" 2007 2008#: ../../__w/calibre/calibre/manual/template_lang.rst:627 2009msgid "In `GPM` it would be::" 2010msgstr "" 2011 2012#: ../../__w/calibre/calibre/manual/template_lang.rst:631 2013msgid "" 2014"As noted in the above :ref:`Template Program Mode <template_mode>` section, " 2015"using ``{`` and ``}`` characters in `TPM` string literals can lead to errors" 2016" or unexpected results because they confuse the template processor. It tries" 2017" to treat them as template boundaries, not characters. In some but not all " 2018"cases you can replace a ``{`` with ``[[`` and a ``}`` with `]]`. Generally, " 2019"if your program contains ``{`` and ``}`` characters then you should use " 2020"`General Program Mode`." 2021msgstr "" 2022 2023#: ../../__w/calibre/calibre/manual/template_lang.rst:635 2024msgid "User-defined Python template functions" 2025msgstr "" 2026 2027#: ../../__w/calibre/calibre/manual/template_lang.rst:637 2028msgid "" 2029"You can add your own Python functions to the template processor. Such " 2030"functions can be used in any of the three template programming modes. The " 2031"functions are added by going to :guilabel:`Preferences -> Advanced -> " 2032"Template functions`. Instructions are shown in that dialog." 2033msgstr "" 2034 2035#: ../../__w/calibre/calibre/manual/template_lang.rst:640 2036msgid "Special notes for save/send templates" 2037msgstr "" 2038 2039#: ../../__w/calibre/calibre/manual/template_lang.rst:642 2040msgid "" 2041"Special processing is applied when a template is used in a `save to disk` or" 2042" `send to device` template. The values of the fields are cleaned, replacing " 2043"characters that are special to file systems with underscores, including " 2044"slashes. This means that field text cannot be used to create folders. " 2045"However, slashes are not changed in prefix or suffix strings, so slashes in " 2046"these strings will cause folders to be created. Because of this, you can " 2047"create variable-depth folder structure." 2048msgstr "" 2049 2050#: ../../__w/calibre/calibre/manual/template_lang.rst:644 2051msgid "" 2052"For example, assume we want the folder structure `series/series_index - " 2053"title`, with the caveat that if series does not exist, then the title should" 2054" be in the top folder. The template to do this is::" 2055msgstr "" 2056 2057#: ../../__w/calibre/calibre/manual/template_lang.rst:648 2058msgid "The slash and the hyphen appear only if series is not empty." 2059msgstr "" 2060 2061#: ../../__w/calibre/calibre/manual/template_lang.rst:650 2062msgid "" 2063"The lookup function lets us do even fancier processing. For example, assume " 2064"that if a book has a series, then we want the folder structure " 2065"`series/series index - title.fmt`. If the book does not have a series then " 2066"we want the folder structure `genre/author_sort/title.fmt`. If the book has " 2067"no genre then we want to use 'Unknown'. We want two completely different " 2068"paths, depending on the value of series." 2069msgstr "" 2070 2071#: ../../__w/calibre/calibre/manual/template_lang.rst:652 2072msgid "To accomplish this, we:" 2073msgstr "" 2074 2075#: ../../__w/calibre/calibre/manual/template_lang.rst:654 2076msgid "" 2077"Create a composite field (give it lookup name #aa) containing " 2078"``{series}/{series_index} - {title}``. If the series is not empty, then this" 2079" template will produce `series/series_index - title`." 2080msgstr "" 2081 2082#: ../../__w/calibre/calibre/manual/template_lang.rst:655 2083msgid "" 2084"Create a composite field (give it lookup name #bb) containing " 2085"``{#genre:ifempty(Unknown)}/{author_sort}/{title}``. This template produces " 2086"`genre/author_sort/title`, where an empty genre is replaced with `Unknown`." 2087msgstr "" 2088 2089#: ../../__w/calibre/calibre/manual/template_lang.rst:656 2090msgid "" 2091"Set the save template to ``{series:lookup(.,#aa,#bb}``. This template " 2092"chooses composite field ``#aa`` if series is not empty and composite field " 2093"``#bb`` if series is empty. We therefore have two completely different save " 2094"paths, depending on whether or not `series` is empty." 2095msgstr "" 2096 2097#: ../../__w/calibre/calibre/manual/template_lang.rst:659 2098msgid "Templates and plugboards" 2099msgstr "" 2100 2101#: ../../__w/calibre/calibre/manual/template_lang.rst:661 2102msgid "" 2103"Plugboards are used for changing the metadata written into books during " 2104"send-to-device and save-to-disk operations. A plugboard permits you to " 2105"specify a template to provide the data to write into the book's metadata. " 2106"You can use plugboards to modify the following fields: authors, author_sort," 2107" language, publisher, tags, title, title_sort. This feature helps people who" 2108" want to use different metadata in books on devices to solve sorting or " 2109"display issues." 2110msgstr "" 2111 2112#: ../../__w/calibre/calibre/manual/template_lang.rst:663 2113msgid "" 2114"When you create a plugboard, you specify the format and device for which the" 2115" plugboard is to be used. A special device is provided, ``save_to_disk``, " 2116"that is used when saving formats (as opposed to sending them to a device). " 2117"Once you have chosen the format and device, you choose the metadata fields " 2118"to change, providing templates to supply the new values. These templates are" 2119" `connected` to their destination fields, hence the name `plugboards`. You " 2120"can of course use composite columns in these templates." 2121msgstr "" 2122 2123#: ../../__w/calibre/calibre/manual/template_lang.rst:665 2124msgid "" 2125"When a plugboard might apply (Content server, save to disk, or send to " 2126"device), calibre searches the defined plugboards to choose the correct one " 2127"for the given format and device. For example, to find the appropriate " 2128"plugboard for an EPUB book being sent to an ANDROID device, calibre searches" 2129" the plugboards using the following search order:" 2130msgstr "" 2131 2132#: ../../__w/calibre/calibre/manual/template_lang.rst:669 2133msgid "" 2134"a plugboard with an exact match on format and device, e.g., ``EPUB`` and " 2135"``ANDROID``" 2136msgstr "" 2137 2138#: ../../__w/calibre/calibre/manual/template_lang.rst:670 2139msgid "" 2140"a plugboard with an exact match on format and the special ``any device`` " 2141"choice, e.g., ``EPUB`` and ``any device``" 2142msgstr "" 2143 2144#: ../../__w/calibre/calibre/manual/template_lang.rst:671 2145msgid "" 2146"a plugboard with the special ``any format`` choice and an exact match on " 2147"device, e.g., ``any format`` and ``ANDROID``" 2148msgstr "" 2149 2150#: ../../__w/calibre/calibre/manual/template_lang.rst:672 2151msgid "a plugboard with ``any format`` and ``any device``" 2152msgstr "" 2153 2154#: ../../__w/calibre/calibre/manual/template_lang.rst:674 2155msgid "" 2156"The tags and authors fields have special treatment, because both of these " 2157"fields can hold more than one item. A book can have many tags and many " 2158"authors. When you specify that one of these two fields is to be changed, the" 2159" template's result is examined to see if more than one item is there. For " 2160"tags, the result is cut apart wherever calibre finds a comma. For example, " 2161"if the template produces the value ``Thriller, Horror``, then the result " 2162"will be two tags, ``Thriller`` and ``Horror``. There is no way to put a " 2163"comma in the middle of a tag." 2164msgstr "" 2165 2166#: ../../__w/calibre/calibre/manual/template_lang.rst:677 2167msgid "" 2168"The same thing happens for authors, but using a different character for the " 2169"cut, a `&` (ampersand) instead of a comma. For example, if the template " 2170"produces the value ``Blogs, Joe&Posts, Susan``, then the book will end up " 2171"with two authors, ``Blogs, Joe`` and ``Posts, Susan``. If the template " 2172"produces the value ``Blogs, Joe;Posts, Susan``, then the book will have one " 2173"author with a rather strange name." 2174msgstr "" 2175 2176#: ../../__w/calibre/calibre/manual/template_lang.rst:679 2177msgid "" 2178"Plugboards affect the metadata written into the book when it is saved to " 2179"disk or written to the device. Plugboards do not affect the metadata used by" 2180" ``save to disk`` and ``send to device`` to create the file names. Instead, " 2181"file names are constructed using the templates entered on the appropriate " 2182"preferences window." 2183msgstr "" 2184 2185#: ../../__w/calibre/calibre/manual/template_lang.rst:682 2186msgid "Tips:" 2187msgstr "" 2188 2189#: ../../__w/calibre/calibre/manual/template_lang.rst:684 2190msgid "" 2191"Use the Template Tester to test templates. Add the tester to the context " 2192"menu for books in the library and/or give it a keyboard shortcut." 2193msgstr "" 2194 2195#: ../../__w/calibre/calibre/manual/template_lang.rst:685 2196msgid "" 2197"Templates can use other templates by referencing composite columns built " 2198"with the desired template. Alternatively, you can use Stored Templates." 2199msgstr "" 2200 2201#: ../../__w/calibre/calibre/manual/template_lang.rst:686 2202msgid "" 2203"In a plugboard, you can set a field to empty (or whatever is equivalent to " 2204"empty) by using the special template ``{}``. This template will always " 2205"evaluate to an empty string." 2206msgstr "" 2207 2208#: ../../__w/calibre/calibre/manual/template_lang.rst:687 2209msgid "" 2210"The technique described above to show numbers even if they have a zero value" 2211" works with the standard field series_index." 2212msgstr "" 2213 2214#: ../../__w/calibre/calibre/manual/template_lang.rst:692 2215msgid "Function reference" 2216msgstr "" 2217