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