언어 변경Reference for all built-in template language functions¶
Here, we document all the built-in functions available in the calibre template language. Every function is implemented as a class in python and you can click the source links to see the source code, in case the documentation is insufficient. The functions are arranged in logical groups by type.
GUI 함수¶
selected_books¶
selected_books([sorted_by, ascending]) – 현재 선택된 책들의 책 ID 목록을 선택 순서대로 반환합니다. / / 이 함수는 GUI 에서만 사용할 수 있습니다.
selected_column¶
selected_column() – 현재 선택된 셀이 들어 있는 열의 조회 이름을 반환합니다. 선택된 셀이 없으면 '' 를 반환합니다. / / 이 함수는 GUI 에서만 사용할 수 있습니다.
show_dialog¶
show_dialog(html_or_text) – HTML 또는 텍스트를 포함한 대화상자를 표시합니다. 사용자가 확인을 누르면 '1' 을, 취소를 누르면 '' 를 반환합니다. / / 이 함수는 GUI 에서만 사용할 수 있습니다.
sort_book_ids¶
sort_book_ids(book_ids, sorted_by, ascending [, sorted_by, ascending]*) – book_ids 목록을 sorted_by 로 지정한 조회 이름의 열 기준으로 ascending 이 지정하는 순서대로 정렬해 반환합니다. 여러 정렬 기준을 순서대로 지정할 수 있습니다.
width_from_pages¶
width_from_pages(value [, num_of_pages_for_max_width, logarithmic_factor, default_width]) – 주어진 페이지 수를 바탕으로 책 등줄의 너비를 ‘0’``과 ``‘1’ 사이의 비율로 반환합니다. 이 함수는 ‘책장’ 보기에서 페이지 수를 바탕으로 등줄 너비를 계산하는 데 사용됩니다. 선택적 인수는 너비 계산 방식을 제어합니다.
[목록]
URL 함수¶
encode_for_url¶
encode_for_url(value, use_plus) – use_plus 설정에 따라 URL 에 사용할 수 있게 value 를 인코딩해 반환합니다. 값은 먼저 URL 인코딩되며, 이어서 use_plus 가 0 이면 공백을 '+' 로, 아니면 %20 으로 바꿉니다..
make_url¶
make_url(path, [query_name, query_value]+) – 질의 URL을 구성하는 가장 쉬운 방법입니다. 질의할 웹 사이트와 페이지를 나타내는 path 와, 질의를 구성하는 query_name, query_value 쌍을 사용합니다. 일반적으로 query_value 는 URL 인코딩되어야 합니다. 이 함수는 항상 값을 인코딩하며 공백은 항상 '+' 기호로 바꿉니다.
query_name, query_value 쌍을 하나 이상 제공해야 합니다.
예: 저자 Niccolò Machiavelli 에 대한 Wikipedia 검색 URL을 구성하려면:
make_url('https://en.wikipedia.org/w/index.php', 'search', 'Niccolò Machiavelli')
다음이 반환됩니다:
https://en.wikipedia.org/w/index.php?search=Niccol%C3%B2+Machiavelli
사용자 지정 열의 책 상세 URL 템플릿을 작성하는 경우, 클릭한 필드의 값을 얻으려면 $item_name 또는 field('item_name') 을 사용하십시오. 예를 들어 Niccolò Machiavelli 을 클릭한 경우 다음과 같이 URL 을 만들 수 있습니다:
make_url('https://en.wikipedia.org/w/index.php', 'search', $item_name)
make_url_extended(), query_string(), encode_for_url() 함수도 참고하십시오.
make_url_extended¶
make_url_extended(...) – 이 함수는 make_url() 과 비슷하지만 URL 구성 요소를 더 세밀하게 제어할 수 있습니다. URL 의 구성 요소는 다음과 같습니다:
scheme:://authority/path?query string.
자세한 내용은 Wikipedia 의 Uniform Resource Locator 문서를 참조하십시오.
이 함수에는 두 가지 형태가 있습니다:
make_url_extended(scheme, authority, path, [query_name, query_value]+)
그리고
make_url_extended(scheme, authority, path, query_string)
이 함수는 scheme, authority, path 와 query_string 또는 질의 인수 쌍으로 만든 질의 문자열을 사용해 URL 을 구성하여 반환합니다. authority 는 비워 둘 수 있으며, calibre scheme URL 이 그 예입니다. query_string 또는 최소 하나의 query_name, query_value 쌍을 반드시 제공해야 합니다. query_string 을 제공했는데 그것이 빈 문자열이면 결과 URL 에는 질의 문자열 구간이 포함되지 않습니다.
예 1: 저자 Niccolò Machiavelli 에 대한 Wikipedia 검색 URL 구성:
make_url_extended('https', 'en.wikipedia.org', '/w/index.php', 'search', 'Niccolò Machiavelli')
다음이 반환됩니다:
https://en.wikipedia.org/w/index.php?search=Niccol%C3%B2+Machiavelli
query_string 과 함께 make_url_extended() 를 사용하는 예는 query_string() 함수를 참조하십시오.
사용자 지정 열의 책 상세 URL 템플릿을 작성하는 경우, 클릭한 필드의 값을 얻으려면 $item_name 또는 field('item_name') 을 사용하십시오. 예를 들어 Niccolò Machiavelli 을 클릭한 경우 다음과 같이 URL 을 만들 수 있습니다:
make_url_extended('https', 'en.wikipedia.org', '/w/index.php', 'search', $item_name')
make_url(), query_string(), encode_for_url() 함수도 참고하십시오.
query_string¶
query_string([query_name, query_value, how_to_encode]+) – query_name, query_value, how_to_encode 삼중항으로부터 URL 질의 문자열을 구성해 반환합니다. 질의 문자열은 query_name=query_value 형태의 항목들이 이어진 것이며, query_value 는 지정된 방식대로 URL 인코딩됩니다. 각 항목은 ``’&’``(앰퍼샌드) 문자로 구분됩니다.
how_to_encode 가 0 이면 query_value 를 인코딩하고 공백을 '+'``(플러스)로 바꿉니다. ``1 이면 query_value 를 인코딩하되 공백을 %20 으로 바꿉니다. 2 이면 query_value 를 변경하지 않고 그대로 반환합니다. 인코딩도 하지 않고 공백도 바꾸지 않습니다. query_value 를 인코딩하지 않되 공백만 바꾸고 싶다면 re($series, ' ', '%20') 와 같이 re() 함수를 사용하십시오.
이 함수는 질의 문자열 각 부분이 어떻게 구성되는지 세밀하게 제어해야 할 때 사용합니다. 그런 다음 결과 질의 문자열을 make_url_extended() 에 사용할 수 있습니다. 예:
make_url_extended(
'https', 'your_host', 'your_path',
query_string('encoded', 'Hendrik Bäßler', 0, 'unencoded', 'Hendrik Bäßler', 2))
이 경우 다음이 생성됩니다:
https://your_host/your_path?encoded=Hendrik+B%C3%A4%C3%9Fler&unencoded=Hendrik Bäßler
query_name, query_value, how_to_encode 삼중항을 하나 이상 제공해야 하며, 원하는 만큼 더 많이 지정할 수 있습니다.
반환값은 지정한 모든 항목이 포함된 URL 질의 문자열입니다. 예: name1=val1[&nameN=valN]*. 반환값에는 '?' path / query string 구분자가 포함되지 않습니다.
사용자 지정 열의 책 상세 URL 템플릿을 작성하는 경우, 클릭한 필드의 인코딩되지 않은 값을 얻으려면 $item_name 또는 field('item_name') 을 사용하십시오. 공백을 플러스로 바꿔 이미 인코딩된 값은 item_value_quoted 로, 공백을 %20 으로 바꿔 이미 인코딩된 값은 item_value_no_plus 로 사용할 수 있습니다.
make_url(), make_url_extended(), encode_for_url() 함수도 참고하십시오.
to_hex¶
to_hex(val) – 문자열 val 을 16진수로 인코딩해 반환합니다. calibre URL 을 구성할 때 유용합니다.
urls_from_identifiers¶
urls_from_identifiers(identifiers, sort_results) – identifiers 라는 콤마 구분 식별자 목록을 받아 URL 목록을 콤마로 구분해 반환합니다. 각 식별자는 id_name:id_value 형식입니다. sort_results 가 참이면 결과를 정렬합니다.
값 반복 처리¶
first_non_empty¶
first_non_empty(value [, value]*) – 비어 있지 않은 첫 번째 value 를 반환합니다. 모든 값이 비어 있으면 빈 문자열을 반환합니다. 인수 개수는 제한이 없습니다.
lookup¶
lookup(value, [ pattern, key, ]* else_key) – 패턴들을 순서대로 value 와 대조합니다. 어떤 pattern 이 일치하면 key 가 가리키는 필드 값을 반환합니다. 일치하는 패턴이 없으면 else_key 가 가리키는 필드 값을 반환합니다.
switch¶
switch(value, [patternN, valueN,]+ else_value) – 각 patternN, valueN 쌍에 대해 value 가 정규식 patternN 과 일치하는지 검사하고 일치하면 연결된 valueN 을 반환합니다. 어느 것도 일치하지 않으면 else_value 를 반환합니다.
switch_if¶
switch_if([test_expression, value_expression,]+ else_expression) – 각 test_expression, value_expression 쌍에 대해 test_expression 이 참(비어 있지 않음)인지 검사하고 참이면 value_expression 결과를 반환합니다. 어느 것도 참이 아니면 else_expression 결과를 반환합니다.
값 서식 지정¶
f_string¶
f_string(string) – Python 이 f 문자열을 해석하는 방식과 비슷하게 string 을 해석합니다. 긴 str & str 또는 strcat(a,b,c) 표현을 단순화하려는 용도입니다.
중괄호({ 와 }) 사이의 텍스트는 General Program Mode 템플릿 식이어야 합니다. 식은 식 목록일 수도 있으며, 현재 컨텍스트(현재 책과 지역 변수)에서 평가됩니다. 중괄호 밖의 텍스트는 변경 없이 그대로 전달됩니다.
예:
f_string('Here is the title: {$title}')- 현재 책의 제목으로{$title}을 치환한 문자열을 반환합니다. 예를 들어 책 제목이 20,000 Leagues Under the Sea 이면f_string()은 Here is the title: 20,000 Leagues Under the Sea 를 반환합니다.현재 날짜가 2025년 9월 18일이라고 가정하면, 다음
f_string()f_string("Today's date: the {d = today(); format_date(d, 'd')} of {format_date(d, 'MMMM')}, {format_date(d, 'yyyy')}")
은 Today’s date: the 18 of September, 2025 문자열을 반환합니다. 첫 번째
{ ... }그룹에서 식 목록(대입 후if문)을 사용해 오늘 날짜를 지역 변수에 할당하는 점에 유의하십시오.책이 Foo 라는 시리즈의 3권이고 전체가 5권이라면, 다음 템플릿
program: if $series then series_count = book_count('series:"""=' & $series & '"""', 0); return f_string("{$series}, book {$series_index} of {series_count}") fi; return 'This book is not in a series'은 Foo, book 3 of 5 를 반환합니다.
finish_formatting¶
finish_formatting(value, format, prefix, suffix) – {series_index:05.2f| - |- }``와 같은 템플릿에서와 동일한 방식으로 ``value``에 ``format, prefix 및 ``suffix``를 적용합니다. 이 함수는 복잡한 단일 함수 또는 템플릿 프로그램 모드 템플릿을 GPM 템플릿으로 쉽게 변환할 수 있도록 제공됩니다. 예를 들어, 다음 프로그램은 위의 템플릿과 동일한 출력을 생성합니다:
program: finish_formatting(field(“series_index”), “05.2f”, “ - ”, “ - ”)
또 다른 예시: 다음 템플릿의 경우:
{series:re(([^\s])[^\s]+(\s|$),\1)}{series_index:0>2s| - | - }{title}
사용법:
program:
strcat(
re(field(‘series’), ‘([^\s])[^\s]+(\s|$)’, ‘\1’),
finish_formatting(field(‘series_index’), ‘0>2s’, ‘ - ’, ‘ - ’),
field(‘title’)
)
format_date¶
format_date(value, format_string) – 날짜 문자열이어야 하는 value 를 format_string 으로 형식화해 문자열로 반환합니다. 날짜는 ISO 형식일 때 가장 안전합니다. 다른 날짜 형식을 사용하면 실제 날짜 값을 모호하지 않게 판단할 수 없어 오류가 날 수 있습니다. 또한 format_date_field() 함수가 더 빠르고 더 신뢰할 수 있다는 점에 유의하십시오.
형식 코드는 다음과 같습니다:
d :앞에 0이 없는 날짜 숫자(1~31)dd :앞에 0이 붙는 날짜 숫자(01~31)ddd :지역화된 요일 약칭dddd :지역화된 요일 전체 이름M :앞에 0이 없는 월 숫자(1~12)MM :앞에 0이 붙는 월 숫자(01~12)MMM :지역화된 월 약칭MMMM :지역화된 월 전체 이름yy :두 자리 연도(00~99)yyyy :네 자리 연도h :앞에 0이 없는 시(0~11 또는 0~23, am/pm 설정에 따라 다름)hh :앞에 0이 붙는 시(00~11 또는 00~23, am/pm 설정에 따라 다름)m :앞에 0이 없는 분(0~59)mm :앞에 0이 붙는 분(00~59)s :앞에 0이 없는 초(0~59)ss :앞에 0이 붙는 초(00~59)ap :24시간제 대신 12시간제를 사용하며,ap는 지역화된 소문자 am/pm 문자열로 바뀝니다AP :24시간제 대신 12시간제를 사용하며,AP는 지역화된 대문자 AM/PM 문자열로 바뀝니다aP :24시간제 대신 12시간제를 사용하며,aP는 지역화된 AM/PM 문자열로 바뀝니다Ap :24시간제 대신 12시간제를 사용하며,Ap는 지역화된 AM/PM 문자열로 바뀝니다iso :시간과 시간대를 포함한 날짜입니다. 이 형식만 단독으로 사용할 수 있습니다to_number :날짜와 시간을 부동소수점 숫자(timestamp)로 변환합니다from_number :부동소수점 숫자(timestamp)를 ISO 형식 날짜로 변환합니다. 다른 날짜 형식을 원하면from_number뒤에 콜론(:)과 원하는 형식 문자열을 덧붙이십시오. 예:format_date(val, 'from_number:MMM dd yyyy')
형식화하려는 날짜에 지역화된 월 이름이 들어 있으면 예상치 못한 결과가 나올 수 있습니다. 날짜 형식에 MMMM 를 포함하도록 바꾼 경우 이런 일이 생길 수 있습니다. format_date_field() 를 사용하면 이 문제를 피할 수 있습니다.
format_date_field¶
format_date_field(field_name, format_string) – field_name 필드의 값을 서식화합니다. 여기서 ``field_name``은 표준 또는 사용자 정의 날짜 필드의 조회 이름이어야 합니다. 서식 지정 코드에 대해서는 :ref:`format_date() <ff_format_date>`를 참조하십시오. 이 함수는 format_date()보다 훨씬 빠르며, 필드(열)의 값을 서식화할 때 사용해야 합니다. 또한 이 함수는 기본 날짜를 직접 처리하므로 더 안정적입니다. 계산된 날짜나 문자열 변수 내의 날짜에는 사용할 수 없습니다. 예시:
format_date_field(‘pubdate’, ‘yyyy.MM.dd’)
format_date_field(‘#date_read’, ‘MMM dd, yyyy’)
format_duration¶
format_duration(value, template, [largest_unit]) – 초 단위의 값을 주간, 일, 시간, 분, 초로 표시하는 문자열로 변환합니다. 값이 실수인 경우 가장 가까운 정수로 반올림됩니다. [ 및 ] 문자로 둘러싸인 값 선택자로 구성된 템플릿을 사용하여 값의 표시 형식을 지정할 수 있습니다. 선택자는 다음과 같습니다:
[w]: 주[d]: 일[h]: 시간[m]: 분[s]: 초
선택자 사이에 임의의 텍스트를 넣을 수 있습니다.
다음 예제에서는 2일(172,800초), 1시간(3,600초), 20초의 기간을 사용하며, 이 세 값의 합은 176,420초입니다.
format_duration(176420, ‘[d][h][m][s]’)``는 ``2d 1h 0m 20s값을 반환합니다.format_duration(176420, ‘[h][m][s]’)``는 ``49h 0m 20s값을 반환합니다.``format_duration(176420, ‘Your reading time is [d][h][m][s]’)``는 값 ``Your reading time is 49h 0m 20s``를 반환합니다.
``format_duration(176420, ‘[w][d][h][m][s]’)``는 값 ``2d 1h 0m 20s``를 반환합니다. 0주인 값은 반환되지 않는다는 점에 유의하십시오.
위 예시에서 주(week)와 같은 항목에 대해 0값을 표시하려면 대문자 선택자를 사용하십시오. 예를 들어, 다음 코드는 ``‘W’``를 사용하여 0주를 표시합니다:
``format_duration(176420, ‘[W][d][h][m][s]’)``는 ``0w 2d 1h 0m 20s``를 반환합니다.
기본적으로 값 뒤에 오는 텍스트는 선택자 뒤에 공백이 붙은 형태입니다. 이 텍스트는 원하는 대로 변경할 수 있습니다. 사용자 정의 텍스트를 포함한 선택자의 형식은 선택자 뒤에 콜론(:)을 붙이고, ‘|’ 문자로 구분된 텍스트 세그먼트를 나열하는 방식입니다. 출력에 포함하고 싶은 공백 문자는 반드시 포함해야 합니다.
하나에서 세 개의 텍스트 세그먼트를 지정할 수 있습니다.
``[w: weeks ]``와 같이 하나의 세그먼트만 지정하면, 해당 세그먼트가 모든 값에 사용됩니다.
``[w: weeks | week ]``와 같이 두 개의 세그먼트를 지정하면, 첫 번째 세그먼트는 0과 1보다 큰 값에 사용됩니다. 두 번째 세그먼트는 1에 사용됩니다.
``[w: weeks | week | weeks ]``와 같이 세 개의 세그먼트를 지정하면, 첫 번째 세그먼트는 0에, 두 번째 세그먼트는 1에, 세 번째 세그먼트는 1보다 큰 값에 사용됩니다.
두 번째 형식은 많은 언어에서 세 번째 형식과 동일합니다.
예를 들어, 다음 선택자:
[w: weeks | week | weeks ]``는 ``‘0 weeks ’,‘1 week ’또는 ``‘2 weeks ’``를 생성합니다.[w: weeks | week ]``는 ``‘0 weeks ’,‘1 week ’또는 ``‘2 weeks ’``를 생성합니다.[w: weeks ]``는 ``0 weeks ‘,1 weeks ’또는 ``2 weeks ‘``를 생성합니다.
선택적 매개변수 ``largest_unit``은 템플릿이 생성할 주, 일, 시간, 분, 초 중 가장 큰 단위를 지정합니다. 이 매개변수는 값 선택자 중 하나여야 합니다. 이는 값을 잘라내는 데 유용할 수 있습니다.
format_duration(176420, ‘[h][m][s]’, ‘d’)``는 ``49h 0m 20s 대신 ``1h 0m 20s``를 반환합니다.
format_number¶
format_number(value, template) – value``를 숫자로 해석하고, ``{0:5.2f}, {0:,d} 또는 ``${0:5,.2f}``와 같은 Python 서식 템플릿을 사용하여 해당 숫자의 서식을 지정합니다. 서식 템플릿은 위 예시와 같이 ``{0:``로 시작하고 ``}``로 끝나야 합니다. 예외: 서식 템플릿에 서식만 포함되어 있다면 앞의 “{0:”과 뒤의 “}”를 생략할 수 있습니다. 더 많은 예제는 템플릿 언어 및 파이썬 문서를 참조하십시오. 서식이 지정되지 않으면 빈 문자열을 반환합니다.
human_readable¶
human_readable(value) – value 를 숫자로 간주하고 KB, MB, GB 등의 형식으로 표현한 문자열을 반환합니다.
rating_to_stars¶
rating_to_stars(value, use_half_stars) – value 를 별(★) 문자 문자열로 반환합니다. 값은 0 에서 5 사이의 숫자여야 합니다. 사용자 지정 평점 열에서 소수 값을 반별 문자로 표현하려면 use_half_stars 를 1 로 설정하십시오.
관계 연산¶
cmp¶
cmp(value, y, lt, eq, gt) – value 와 y 를 둘 다 숫자로 변환한 뒤 비교합니다. value <# y 이면 lt, value ==# y 이면 eq, 그 외에는 gt 를 반환합니다. 보통 비교 연산자로 대체할 수 있습니다.
first_matching_cmp¶
first_matching_cmp(val, [ cmp, result, ]* else_result) – val < cmp 비교를 순서대로 수행해 처음으로 성공한 비교에 연결된 result 를 반환합니다. 일치하는 비교가 없으면 else_result 를 반환합니다.
strcmp¶
strcmp(x, y, lt, eq, gt) – x 와 y 를 대소문자 구분 없이 사전식으로 비교합니다. x < y 이면 lt, x == y 이면 eq, 그 외에는 gt 를 반환합니다. 많은 경우 비교 연산자로 대체할 수 있음
strcmpcase¶
strcmpcase(x, y, lt, eq, gt) – x 와 y 를 대소문자를 구분해 사전식으로 비교합니다. x < y 이면 lt 를, x == y 이면 eq 를, 그 외에는 gt 를 반환합니다.
참고: 이는 calibre가 기본적으로 사용하는 비교 방식이 아닙니다. 예를 들어 사전식 비교 연산자(==, >, < 등)는 이렇게 동작하지 않습니다. 이 함수는 예상치 못한 결과를 낼 수 있으므로 가능하면 strcmp() 를 사용하십시오.
기타¶
arguments¶
arguments(id[=expression] [, id[=expression]]*) – 저장된 템플릿에서 호출 시 전달된 인수를 가져오는 데 사용됩니다. 이 함수는 제공된 이름인 ``id``를 사용하여 지역 변수를 선언하고 초기화하며, 이를 실질적으로 매개변수로 만듭니다. 이 변수들은 위치 기반이며, 호출 시 해당 위치에 전달된 인수의 값을 가져옵니다. 호출 시 해당 인수가 제공되지 않으면 ``arguments()``는 해당 변수에 제공된 기본값을 할당합니다. 기본값이 없으면 변수는 빈 문자열로 설정됩니다.
assign¶
assign(id, value) – value 를 id 에 할당한 뒤 value 를 반환합니다. id 는 식이 아니라 식별자여야 합니다. 대부분의 경우 = 연산자로 대체할 수 있습니다.
globals¶
globals(id[=expression] [, id[=expression]]*) – 포맷터로 전달할 수 있는 “전역 변수”를 가져옵니다. id``는 전역 변수의 이름입니다. 이 함수는 ``id 매개변수로 전달된 전역 변수의 이름을 사용하여 로컬 변수를 선언하고 초기화합니다. 전역 변수 목록에 해당 변수가 없는 경우, 제공된 기본값을 해당 변수에 할당합니다. 기본값이 없는 경우 변수는 빈 문자열로 설정됩니다.
is_dark_mode¶
is_dark_mode() – calibre가 다크 모드로 실행 중이면 '1' 을, 아니면 ``’’``(빈 문자열)을 반환합니다. 고급 색상 및 아이콘 규칙에서 모드별 다른 색상/아이콘을 선택하는 데 사용 가능
print¶
print(a [, b]*) – 인수들을 표준 출력으로 출력합니다. calibre를 명령행(calibre-debug -g)에서 시작하지 않았다면 출력은 보이지 않습니다. print 함수는 항상 빈 문자열을 반환합니다.
set_globals¶
set_globals(id[=expression] [, id[=expression]]*) – 포매터에 전달할 수 있는 전역 / 변수 를 설정합니다. 전역 변수 이름은 전달한 id 를 사용합니다. id 의 값은 변수 값으로 사용됩니다.
날짜 함수¶
date_arithmetic¶
date_arithmetic(value, calc_spec, fmt) – calc_spec``을 사용하여 ``value``로부터 새로운 날짜를 계산합니다. 선택 사항인 ``fmt``에 따라 서식이 지정된 새로운 날짜를 반환합니다. ``fmt``가 지정되지 않으면 결과는 ISO 형식으로 반환됩니다. ``calc_spec``은 ``vW (valueWhat) 쌍을 연결하여 형성된 문자열이며, 여기서 ``v``는 음수일 수도 있는 숫자이고 W는 다음 문자 중 하나입니다:
s:date``에 ``v초를 더합니다m:date``에 ``v분을 더합니다
days_between¶
days_between(date1, date2) – date1 과 date2 사이의 일 수를 반환합니다. date1 이 date2 보다 크면 양수, 그렇지 않으면 음수입니다. 날짜를 해석할 수 없으면 빈 문자열을 반환합니다.
today¶
today() – 오늘(현재 시각)의 날짜+시간 문자열을 반환합니다. 이 값은 format_date 나 days_between 에 사용하도록 설계되었지만 일반 문자열처럼 조작할 수도 있습니다. 날짜는 ISO 형식입니다.
대소문자 변경¶
capitalize¶
capitalize(value) – value 의 첫 글자는 대문자로, 나머지는 소문자로 바꿔 반환합니다.
lowercase¶
lowercase(value) – ``value``를 소문자로 반환합니다.
titlecase¶
titlecase(value) – ``value``를 제목 형식 대소문자로 반환합니다.
uppercase¶
uppercase(value) – ``value``를 대문자로 반환합니다.
데이터베이스 함수¶
annotation_count¶
annotation_count() – 현재 책에 연결된 모든 종류의 주석(annotation) 총개수를 반환합니다. 이 함수는 GUI 와 콘텐츠 서버에서만 동작합니다.
approximate_formats¶
approximate_formats() – 책과 관련된 형식 목록을 쉼표로 구분하여 반환합니다. 이 목록은 파일 시스템이 아닌 calibre의 데이터베이스에서 가져오기 때문에, 대부분 정확하겠지만 목록의 정확성을 보장할 수는 없습니다. 반환된 형식 이름은 EPUB과 같이 항상 대문자로 표시된다는 점에 유의하십시오. approximate_formats() 함수는 formats_... 함수들보다 훨씬 빠릅니다.
이 함수는 GUI에서만 작동합니다. 디스크에 저장하거나 기기로 전송하는 템플릿에서 이 값들을 사용하려면, 사용자 정의 “다른 열로 구성된 열”을 만들고, 해당 열의 템플릿에서 이 함수를 호출한 다음, 저장/전송 템플릿에서 해당 열의 값을 사용해야 합니다.
book_count¶
book_count(query, use_vl) – query``를 검색하여 찾은 도서의 개수를 반환합니다. ``use_vl``이 ``0``(영)인 경우 가상 도서관은 무시됩니다. 이 함수와 그 동반 함수인 ``book_values()``는 템플릿 검색에서 특히 유용하며, 단 한 권의 책으로 구성된 시리즈를 찾는 것과 같이 여러 책의 정보를 결합한 검색을 지원합니다. ``allow_template_database_functions_in_composites 트윅이 True로 설정되어 있지 않으면 복합 열에서는 사용할 수 없습니다. 이 함수는 GUI에서만 사용할 수 있습니다.
예를 들어, 다음 템플릿 검색은 이 함수와 관련 함수를 사용하여 책이 단 한 권뿐인 모든 시리즈를 찾습니다:
``series_only_one_book``이라는 이름의 저장된 템플릿을 정의합니다(이름은 임의로 지정 가능). 템플릿은 다음과 같습니다:
program: vals = globals(vals=‘’); if !vals then all_series = book_values(‘series’, ‘series:true’, ‘,’, 0); for series in all_series: if book_count(‘series:=“’ & series & ‘”’, 0) == 1 then vals = list_join(‘,’, vals, ‘,’, series, ‘,’) fi rof; set_globals(vals) fi; str_in_list(vals, ‘,’, $series, 1, ‘’)템플릿이 처음 실행될 때(첫 번째 책을 확인할 때) 데이터베이스 조회 결과를
vals``라는 ``global템플릿 변수에 저장합니다. 이 결과는 이후의 책을 확인할 때 조회를 다시 수행하지 않고 사용됩니다.템플릿 검색에서 저장된 템플릿을 사용하는 방법:
template:“program: series_only_one_book()#@#:n:1”검색식에 템플릿을 직접 입력하는 대신 저장된 템플릿을 사용하면, 검색 표현식에서 따옴표를 이스케이프 처리해야 하는 문제로 인한 오류를 방지할 수 있습니다.
이 함수는 GUI 및 콘텐츠 서버에서만 사용할 수 있습니다.
book_values¶
book_values(column, query, sep, use_vl) – query``를 검색하여 찾은 도서들 중, ``column``(조회 이름) 열에 포함된 고유 값들을 ``sep``으로 구분하여 리스트로 반환합니다. ``use_vl``이 ``0``(영)인 경우 가상 도서관은 무시됩니다. 이 함수와 그 동반 함수인 ``book_count()``는 템플릿 검색에서 특히 유용하며, 단 한 권의 책으로 구성된 시리즈를 찾는 것과 같이 여러 책의 정보를 결합한 검색을 지원합니다. ``allow_template_database_functions_in_composites 트윅이 True로 설정되어 있지 않으면 복합 열에서는 사용할 수 없습니다. 이 함수는 GUI와 콘텐츠 서버에서만 사용할 수 있습니다.
extra_file_modtime¶
extra_file_modtime(file_name, format_string) – 책의 data/ 폴더에 있는 추가 파일 ``file_name``의 수정 시간을 반환합니다. 파일이 존재할 경우 해당 시간을 반환하고, 그렇지 않으면 ``-1``을 반환합니다. 수정 시간은 ``format_string``에 따라 포맷됩니다(자세한 내용은 format_date() 참조). ``format_string``이 빈 문자열인 경우, 수정 시간을 에포크(epoch) 이후 경과한 초 수를 나타내는 부동 소수점 숫자로 반환합니다. 함수 has_extra_files(), extra_file_names() 및 :ref:`extra_file_size() <ff_extra_file_size>`도 참조하십시오. 에포크는 운영 체제에 따라 다릅니다. 이 함수는 GUI 및 콘텐츠 서버에서만 사용할 수 있습니다.
Translated with DeepL.com (free version)
extra_file_names¶
extra_file_names(sep [, pattern]) – 책의 data/ 폴더에 있는 추가 파일 목록을 ``sep``으로 구분하여 반환합니다. 선택적 매개변수인 정규 표현식 ``pattern``이 지정되면, 목록은 ``pattern``과 일치하는 파일로 필터링됩니다. 패턴 일치는 대소문자를 구분하지 않습니다. 관련 함수 has_extra_files(), extra_file_modtime() 및 :ref:`extra_file_size() <ff_extra_file_size>`도 참조하십시오. 이 함수는 GUI 및 콘텐츠 서버에서만 사용할 수 있습니다.
extra_file_size¶
extra_file_size(file_name) – 책의 data/ 폴더에 file_name 추가 파일이 있으면 그 크기를 바이트 단위로 반환하고, 없으면 -1 을 반환합니다..
formats_modtimes¶
formats_modtimes(date_format_string) – 책의 각 형식에 대한 수정 시간을 나타내는, 콜론(:)으로 구분된 항목 FMT:DATE``의 쉼표(,)로 구분된 목록을 반환합니다. ``date_format_string 매개변수는 날짜의 서식 지정 방식을 지정합니다. 자세한 내용은 format_date() 함수를 참조하십시오. select() 함수를 사용하여 특정 형식의 수정 시간을 가져올 수 있습니다. EPUB과 마찬가지로 형식 이름은 항상 대문자로 표기된다는 점에 유의하십시오.
formats_path_segments¶
formats_path_segments(with_author, with_title, with_format, with_ext, sep) – calibre 라이브러리 내 책 형식의 경로 중 sep``으로 구분된 부분들을 반환합니다. 매개변수 ``sep``은 일반적으로 슬래시(‘/’``)여야 합니다. 이 함수의 용도 중 하나는 ‘디스크에 저장’ 및 ‘기기로 전송’ 템플릿에서 생성된 경로가 일관되게 축약되도록 하는 것입니다. 또 다른 용도는 장치상의 경로가 calibre 라이브러리의 경로와 일치하도록 하는 것입니다.
책 경로는 저자, 괄호 안에 Calibre 데이터베이스 ID가 포함된 제목, 그리고 형식(저자 - 제목)의 세 부분으로 구성됩니다. Calibre는 파일 이름 길이 제한으로 인해 이 세 부분 중 어느 것이든 축약할 수 있습니다. 해당 부분에 1``을 전달하여 포함할 부분을 선택할 수 있습니다. 특정 세그먼트를 제외하고 싶다면 해당 세그먼트에 ``0 또는 빈 문자열을 전달하십시오. 예를 들어, 다음 코드는 확장자를 제외한 형식 이름만 반환합니다:
formats_path_segments(0, 0, 1, 0, ‘/’)
세그먼트가 하나뿐이므로 구분자는 무시됩니다.
여러 형식(여러 확장자)이 있는 경우 확장자 중 하나가 무작위로 선택됩니다. 어떤 확장자가 사용될지 신경 쓰인다면 확장자를 제외한 경로를 가져온 다음 원하는 확장자를 추가하십시오.
예시: calibre 라이브러리에 Joe Blogs가 쓴 ‘Help’라는 제목의 epub 형식의 책이 있다고 가정해 봅시다. 이 책의 경로는 다음과 같을 것입니다.
Joe Blogs/Help - (calibre_id)/Help - Joe Blogs.epub
다음은 다양한 매개변수에 대해 반환되는 결과를 보여줍니다:
``formats_path_segments(0, 0, 1, 0, ‘/’)``는 `Help - Joe Blogs`를 반환합니다
``formats_path_segments(0, 0, 1, 1, ‘/’)``는 `Help - Joe Blogs.epub`을 반환합니다
``formats_path_segments(1, 0, 1, 1, ‘/’)``는 `Joe Blogs/Help - Joe Blogs.epub`을 반환합니다
``formats_path_segments(1, 0, 1, 0, ‘/’)``는 `Joe Blogs/Help - Joe Blogs`를 반환합니다.
``formats_path_segments(0, 1, 0, 0, ‘/’)``는 `Help - (calibre_id)`를 반환합니다.
formats_paths¶
formats_paths([separator]) – 책 형식의 전체 경로를 나타내는 FMT:PATH 형식 항목의 separator 구분 목록을 반환합니다. separator 인수는 선택 사항이며, 지정하지 않으면 쉼표가 사용됩니다.
formats_sizes¶
formats_sizes() – 책 형식의 크기를 바이트 단위로 나타내는 FMT:SIZE 형식 항목의 콤마 구분 목록을 반환합니다. 특정 형식의 크기를 얻으려면 select() 함수를 사용할 수 있습니다.
get_link¶
get_link(field_name, field_value) – 값이 field_value 인 field_name 필드의 링크를 가져옵니다. 연결된 링크가 없으면 빈 문자열을 반환합니다. 예:
다음은 태그
Fiction에 연결된 링크를 반환합니다:get_link('tags', 'Fiction')
다음 템플릿은 책에 연결된 모든 태그의 링크를
value:link, ...형식의 목록으로 만듭니다:program: ans = ''; for t in $tags: l = get_link('tags', t); if l then ans = list_join(', ', ans, ',', t & ':' & get_link('tags', t), ',') fi rof; ans
이 함수는 GUI 와 콘텐츠 서버에서만 동작합니다.
get_note¶
get_note(field_name, field_value, plain_text) – 값이 field_value``인 ``field_name 필드의 노트를 가져옵니다. plain_text``가 비어 있으면 이미지를 포함한 노트의 HTML을 반환합니다. ``plain_text``가 ``1``(또는 ``‘1’)이면 노트의 일반 텍스트를 반환합니다. 노트가 존재하지 않는 경우, 두 경우 모두 빈 문자열을 반환합니다. 예시:
Fiction 태그에 연결된 노트의 HTML을 반환합니다:
program: get_note(‘tags’, ‘Fiction’, ‘’)작가 `Isaac Asimov`에게 연결된 노트의 일반 텍스트를 반환합니다:
program: get_note(‘authors’, ‘Isaac Asimov’, 1)
이 함수는 GUI와 콘텐츠 서버에서만 작동합니다.
Translated with DeepL.com (free version)
has_extra_files¶
has_extra_files([pattern]) – returns the count of extra files, otherwise the empty string. If the optional parameter pattern (a regular expression) is supplied then the list is filtered to files that match pattern before the files are counted. The pattern match is case insensitive. See also the functions extra_file_names(), extra_file_size() and extra_file_modtime(). This function can be used only in the GUI and the content server.
has_note¶
has_note(field_name, field_value). 필드에 메모가 있는지 확인합니다. 이 함수에는 두 가지 변형이 있습니다:
``field_value``가 ``‘’``(빈 문자열)이 아닌 경우, 필드 ``field_name``의 값 ``field_value``에 메모가 있으면 ``‘1’``을 반환하고, 그렇지 않으면 ``‘’``을 반환합니다.
예시: ``has_note(‘tags’, ‘Fiction’)``는 태그 ``fiction``에 메모가 첨부되어 있으면 ``‘1’``을 반환하고, 그렇지 않으면 ``‘’``을 반환합니다.
``field_value``가 ``‘’``인 경우, 필드 ``field_name``에 메모가 있는 값들의 리스트를 반환합니다. 필드 내 어떤 항목에도 메모가 없으면 ``‘’``를 반환합니다. 이 변형은 특정 값이 아닌, 필드 내 어떤 값에라도 메모가 있는 경우 열 아이콘을 표시하는 데 유용합니다.
예시: ``has_note(‘authors’, ‘’)``는 메모가 있는 저자의 목록을 반환하며, 메모가 있는 저자가 없으면 ``‘’``를 반환합니다.
이 함수의 반환 값인 목록의 길이와 ``field_name``에 포함된 값들의 목록 길이를 비교하여, ``field_name``의 모든 값에 메모가 있는지 확인할 수 있습니다. 예시:
list_count(has_note(‘authors’, ‘’), ‘&’) ==# list_count_field(‘authors’)
이 함수는 GUI와 콘텐츠 서버에서만 작동합니다.
Translated with DeepL.com (free version)
reading_progress¶
reading_progress(book_id, [user, output_fmt, which, fmt]) – returns the reading progress, in the specified output format.The user parameter defaults to match any user. Use the value local to match reading progress in the calibre e-book viewer. Use _ to match reading progress for anonymous users of the Content server viewer. Any other value matches the corresponding username as used in the Content server.
The output_fmt parameter controls the format of the text returned by this function. It takes any of the following values:
page_count- the default, outputspages read / total pages. If page counting is not enabled outputs percent read instead.percent- outputs percent readpercent_number- outputs percent read as a number without the trailing percent sign, useful for sorting.pos_frac- outputs a fraction between zero and one.
The which parameter controls how the specific reading progress record for the specified user is selected. There can be more than one record if no user is specified or if the book has been read in multiple formats or on multiple devices. It accepts two values:
most_recent- the progress of the most recent reader of the book (the default value)furthest- the furthest progress of all matching records
The fmt parameter controls which book format is used. The default is to return records for all formats, the specific record is then selected by the which parameter.
Some examples:
{id:reading_progress()} -- the reading progress as pages read / total pages
for the most recent reading session of this book
{id:reading_progress(,percent)} -- same as above, but as a percentage
{id:reading_progress(,pos_frac,furthest)} -- same as above, but as a fraction and using the
furthest progress on this book.
{id:reading_progress(bob,pos_frac,furthest,EPUB)} -- for the user "bob" and the "EPUB" format.
메타데이터에서 값 가져오기¶
booksize¶
booksize() – calibre size 필드 값을 반환합니다. 책에 형식이 없으면 ‘’ 를 반환합니다. / / 이 함수는 GUI 에서만 동작합니다. 이 값을 디스크에 저장 또는 장치로 보내기에 사용하려면 저장된 템플릿이나 다른 데이터 소스를 사용하기
connected_device_name¶
connected_device_name(storage_location_key) – 장치가 연결되어 있으면 장치 이름을, 아니면 빈 문자열을 반환합니다. 장치의 각 저장 위치는 고유한 장치 이름을 가질 수 있습니다. storage_location_key 는 해당 저장 위치를 지정합니다.
connected_device_uuid¶
connected_device_uuid(storage_location_key) – 장치가 연결되어 있으면 장치 uuid(고유 ID)를, 아니면 빈 문자열을 반환합니다. 장치의 각 저장 위치는 서로 다른 uuid 를 가집니다.
current_library_name¶
current_library_name() – 현재 calibre 라이브러리 경로의 마지막 이름을 반환합니다.
current_library_path¶
current_library_path() – 현재 calibre 라이브러리의 전체 경로를 반환합니다.
current_virtual_library_name¶
current_virtual_library_name() – 현재 가상 라이브러리가 있으면 그 이름을, 없으면 빈 문자열을 반환합니다. 라이브러리 이름의 대소문자는 유지됩니다. 예[CODEprogram: current_virtual_library_name([/CODE이 함수는 GUI 에서만 동작합니다.
field¶
field(lookup_name) – 조회 이름이 lookup_name 인 메타데이터 필드 값을 반환합니다. 함수 대신 $ 접두사를 사용할 수도 있습니다. 예: $tags.
has_cover¶
has_cover() – 책에 표지가 있으면 'Yes' 를, 없으면 빈 문자열을 반환합니다.
is_marked¶
is_marked() – 책이 calibre에서 marked 상태인지 확인합니다. 표시되어 있으면 'true'``(소문자) 또는 이름 있는 표시의 콤마 구분 목록을 반환합니다. 표시되지 않았으면 ``'' 를 반환합니다.
language_codes¶
language_codes(lang_strings) – lang_strings 로 전달된 언어 이름의 언어 코드 를 반환합니다. 문자열은 현재 로캘의 언어여야 합니다. lang_strings 는 콤마 구분 목록입니다.
language_strings¶
language_strings(value, localize) – value 로 전달된 언어 코드의 언어 이름을 반환합니다(이름과 코드는 여기 참조). 예: {languages:language_strings()}. localize 가 0 이면 영어 이름을, 0 이 아니면 현재 로캘 언어의 이름을 반환합니다. lang_codes 는 콤마 구분 목록입니다.
ondevice¶
ondevice() – ``ondevice``가 설정되어 있으면 문자열 ``‘Yes’``를 반환하고, 그렇지 않으면 빈 문자열을 반환합니다. 이 함수는 GUI에서만 작동합니다. 디스크에 저장하거나 기기로 전송하는 템플릿에서 이 값을 사용하려면 사용자 정의 “다른 열로 구성된 열”을 생성하고, 해당 열의 템플릿에서 이 함수를 호출한 다음, 저장/전송 템플릿에서 해당 열의 값을 사용해야 합니다.
raw_field¶
raw_field(lookup_name [, optional_default]) – 형식 적용 없이 lookup_name 이 가리키는 메타데이터 필드 값을 반환합니다. 필드가 없으면 선택적 두 번째 인수 optional_default 를 평가해 반환합니다.
raw_list¶
raw_list(lookup_name, separator) – 형식 지정이나 정렬을 적용하지 않고 lookup_name 이 가리키는 메타데이터 목록을 반환하며 항목은 separator 로 구분합니다.
series_sort¶
series_sort() – 시리즈 정렬 값을 반환합니다.
user_categories¶
user_categories() – 이 책이 포함된 사용자 카테고리의 쉼표로 구분된 목록을 반환합니다. 이 함수는 GUI 환경에서만 작동합니다. 디스크 저장 또는 기기 전송 템플릿에서 이 값들을 사용하려면, `다른 열을 기반으로 생성된 열`을 직접 만들어 해당 열의 템플릿에서 이 함수를 호출한 다음, 그 열의 값을 저장/전송 템플릿에서 사용해야 합니다
virtual_libraries¶
virtual_libraries() – 이 책을 포함하는 가상 라이브러리의 쉼표로 구분된 목록을 반환합니다. 이 함수는 GUI 환경에서만 작동합니다. 디스크에 저장하거나 기기로 전송하는 템플릿에서 이 값들을 사용하려면, `다른 열을 기반으로 생성된 열`을 직접 만들어 해당 열의 템플릿에서 이 함수를 호출한 다음, 저장/전송 템플릿에서 해당 열의 값을 사용해야 합니다.
목록 조작¶
list_count¶
list_count(value, separator) – 값을 separator 로 구분된 항목 목록으로 해석하고 그 개수를 반환합니다. 대부분의 목록은 쉼표를 구분자로 사용하지만 authors 는 & 를 사용
list_count_field¶
list_count_field(lookup_name)– 조회 이름이 lookup_name 인 필드의 항목 수를 반환합니다. 해당 필드는 authors 나 tags 처럼 다중 값 필드여야 하며, 그렇지 않으면 예외가 발생합니다.
list_count_matching¶
list_count_matching(value, pattern, separator) – value 를 separator 로 구분된 항목 목록으로 해석하고 정규식 pattern 과 일치하는 항목 수를 반환합니다.
list_difference¶
list_difference(list1, list2, separator) – 대소문자를 구분하지 않는 비교를 사용해 list1 에서 list2 에 있는 항목을 제거한 목록을 반환합니다..
list_equals¶
list_equals(list1, sep1, list2, sep2, yes_val, no_val) – list1 과 list2 에 동일한 항목이 들어 있으면 yes_val 을, 아니면 no_val 을 반환합니다. 각 목록은 각각 sep1 과 sep2 로 분리해 항목을 구합니다.
list_intersection¶
list_intersection(list1, list2, separator) – 대소문자를 구분하지 않는 비교를 사용해 list1 과 list2 에 공통으로 있는 항목만 남긴 목록을 반환합니다..
list_join¶
list_join(with_separator, list1, separator1 [, list2, separator2]*) – 소스 목록 (list1 등)의 항목들을 ``with_separator``를 사용하여 결과 목록의 항목들 사이에 연결하여 만든 목록을 반환합니다. 각 소스 ``list[123…]``의 항목들은 해당 ``separator[123…]``로 구분됩니다. 리스트에는 값이 하나도 없을 수 있습니다. ``publisher``와 같이 단일 값을 가지는 필드, 즉 사실상 항목이 하나뿐인 리스트일 수도 있습니다. 중복 항목은 대소문자를 구분하지 않는 비교를 통해 제거됩니다. 항목들은 소스 리스트에 나타나는 순서대로 반환됩니다. 목록의 항목들이 대소문자만 다를 경우 마지막 항목이 사용됩니다. 모든 구분자는 한 글자 이상일 수 있습니다.
예시:
program:
list_join(‘#@#’, $authors, ‘&’, $tags, ‘,’)
다음과 같이 이전 list_join 호출의 결과에 대해 ``list_join``을 사용할 수 있습니다:
program:
a = list_join(‘#@#’, $authors, ‘&’, $tags, ‘,’);
b = list_join(‘#@#’, a, ‘#@#’, $#genre, ‘,’, $#people, ‘&’, ‘some value’, ‘,’)
표현식을 사용하여 목록을 생성할 수 있습니다. 예를 들어, ``authors``와 ``#genre``에 대한 항목을 원하지만, 장르를 “Genre: ”라는 단어 뒤에 장르의 첫 글자를 붙인 형태로 변경하고 싶다고 가정해 봅시다. 즉, “Fiction”이라는 장르는 “Genre: F”가 됩니다. 다음 코드가 이를 수행합니다:
program:
list_join('#@#', $authors, '&', list_re($#genre, ',', '^(.).*$', 'Genre: \1'), ',')
list_re¶
list_re(src_list, separator, include_re, opt_replace) – 먼저 src_list 를 separator 문자로 나눠 목록을 만든 뒤 각 항목이 include_re 와 일치하는지 검사해 새 목록을 만듭니다. opt_replace 를 지정하면 일치한 항목에 치환을 적용합니다.
list_re_group¶
list_re_group(src_list, separator, include_re, search_re [,template_for_group]*) – list_re() 와 비슷하지만 치환은 선택 사항이 아닙니다. 치환 시 re_group(item, search_re, template ...) 를 사용합니다.
list_remove_duplicates¶
list_remove_duplicates(list, separator) – list 에서 중복 항목을 제거한 목록을 반환합니다. 항목이 대소문자만 다르면 마지막 항목이 남습니다. 항목 구분자는 separator 입니다.
list_sort¶
list_sort(value, direction, separator) – 대소문자를 구분하지 않는 사전식 정렬로 value 를 정렬해 반환합니다. direction 이 0 이면 오름차순, 그 외에는 내림차순입니다.
list_split¶
list_split(list_val, sep, id_prefix) – ``sep``을 사용하여 ``list_val``을 개별 값으로 분할한 다음, 각 값을 ``id_prefix_N``이라는 이름의 지역 변수에 할당합니다. 여기서 N은 목록 내 해당 값의 위치입니다. 첫 번째 항목의 위치는 0(영)입니다. 이 함수는 목록의 마지막 요소를 반환합니다.
예시:
list_split(‘one:two:foo’, ‘:’, ‘var’)
이는 다음 코드와 동일합니다:
var_0 = ‘one’
var_1 = ‘two’
var_2 = ‘foo’
list_union¶
list_union(list1, list2, separator) – list1 과 list2 의 항목을 합쳐 새 목록을 만들고 대소문자를 구분하지 않는 비교로 중복 항목을 제거합니다. 대소문자만 다른 경우 마지막 값을 사용
range¶
range(start, stop, step, limit) – 매개변수 start, stop, step``으로 지정된 범위를 순환하며 생성된 숫자 목록을 반환하며, 최대 길이는 ``limit``입니다. 생성되는 첫 번째 값은 'start'입니다. 이후의 값들은 ``next_v = current_v + step``으로 계산됩니다. 루프는 ``step``이 양수일 경우 ``next_v < stop``인 동안, 그렇지 않을 경우 ``next_v > stop``인 동안 계속됩니다. ``step``이 양수일 때 ``start >= stop 조건을 만족하지 못하면 빈 리스트가 생성됩니다. limit``은 리스트의 최대 길이를 설정하며, 기본값은 1000입니다. 매개변수 ``start, step, limit``은 선택 사항입니다. 인수를 하나만 사용하여 ``range()``를 호출하면 ``stop``이 지정됩니다. 인수를 두 개 사용하면 ``start``와 ``stop``이 지정됩니다. 인수를 세 개 사용하면 ``start, stop, step``이 지정됩니다. 인수를 네 개 사용하면 ``start, stop, step, ``limit``이 지정됩니다.
예시:
range(5) -> ‘0, 1, 2, 3, 4’
range(0, 5) -> ‘0, 1, 2, 3, 4’
range(-1, 5) -> '-1, 0, 1, 2, 3, 4'
range(1, 5) -> ‘1, 2, 3, 4’
range(1, 5, 2) -> ‘1, 3’
range(1, 5, 2, 5) -> ‘1, 3’
range(1, 5, 2, 1) -> error(limit exceeded)
subitems¶
subitems(value, start_index, end_index) – 이 함수는 장르와 같은 태그 형태의 계층적 항목 목록을 분할합니다. 이 함수는 ``value``를 쉼표로 구분된 태그 형태의 항목 목록으로 해석하며, 각 항목은 마침표로 구분된 목록입니다. 이 함수는 각 항목에서 ``start_index``부터 ``end_index``까지의 구성 요소를 추출한 후, 그 결과를 다시 합쳐서 새로운 목록을 반환합니다. 중복 항목은 제거됩니다. 점으로 구분된 목록의 첫 번째 하위 항목의 인덱스는 0입니다. 인덱스가 음수인 경우 목록의 끝에서부터 카운트합니다. 특별한 경우로, ``end_index``가 0인 경우 목록의 길이로 간주합니다.
예시:
sublist¶
sublist(value, start_index, end_index, separator) – value 를 separator 로 구분된 항목 목록으로 해석하고, start_index 부터 end_index 까지의 항목으로 이루어진 새 목록을 반환합니다. 첫 번째 항목의 번호는 0입니다. 인덱스가 음수이면 목록의 끝에서부터 셉니다. 특별히 end_index 가 0이면 목록 길이로 간주합니다.
태그 열(쉼표로 구분)이 “A, B, C” 라고 가정하면 예시는 다음과 같습니다:
{tags:sublist(0,1,\,)}는 “A” 를 반환합니다.{tags:sublist(-1,0,\,)}는 “C” 를 반환합니다.{tags:sublist(0,-1,\,)}는 “A, B” 를 반환합니다.
목록 조회¶
identifier_in_list¶
identifier_in_list(val, id_name [, found_val, not_found_val]) – val``을 쉼표로 구분된 식별자 목록으로 처리합니다. 식별자는 ``id_name:value 형식을 갖습니다. id_name 매개변수는 검색할 id_name 텍스트로, id_name 또는 id_name:regexp 중 하나입니다. 첫 번째 경우는 해당 id_name과 일치하는 식별자가 있으면 일치합니다. 두 번째 경우는 id_name이 식별자와 일치하고 정규 표현식(regexp)이 식별자의 값과 일치하면 일치합니다. found_val``과 ``not_found_val``이 제공된 경우, 일치하는 항목이 있으면 ``found_val``을 반환하고, 그렇지 않으면 ``not_found_val``을 반환합니다. ``found_val``과 ``not_found_val``이 제공되지 않은 경우, 일치하는 항목이 있으면 ``identifier:value 쌍을 반환하고, 그렇지 않으면 빈 문자열(‘’)을 반환합니다.
list_contains¶
list_contains(value, separator, [ pattern, found_val, ]* not_found_val) – value 를 separator 로 구분된 항목 목록으로 해석하고 각 항목을 정규식 pattern 과 비교합니다. 어떤 항목이라도 일치하면 해당 found_val 을 반환하고, 일치하는 것이 없으면 not_found_val 을 반환
list_item¶
list_item(value, index, separator) – value 를 separator 로 구분된 항목 목록으로 해석하여 index 번째 항목을 반환합니다. 첫 항목의 인덱스는 0 이고 마지막 항목은 -1 입니다.
select¶
select(value, key) – value 를 각 항목이 id:id_value 형식인 콤마 구분 목록( calibre identifier 형식 )으로 해석합니다. 함수는 key 와 일치하는 첫 쌍을 찾아 그 값을 반환합니다.
str_in_list¶
str_in_list(value, separator, [ string, found_val, ]+ not_found_val) – value``를 ``separator``로 구분된 항목들의 리스트로 해석한 다음, ``string``을 리스트 내의 각 값과 비교합니다. 여기서 ``string``은 정규 표현식이 아닙니다. ``string``이 어떤 항목과도 일치하면(대소문자 구분 없이) 해당 ``found_val``을 반환합니다. ``string``에 ``separators``가 포함되어 있다면, 이 또한 리스트로 간주되어 각 하위 값이 검사됩니다. ``string``과 ``found_value 쌍은 원하는 만큼 반복될 수 있으며, 이는 문자열의 값에 따라 서로 다른 값을 반환할 수 있게 합니다. 일치하는 문자열이 없으면 ``not_found_value``가 반환됩니다. 문자열은 순서대로 검사되며, 첫 번째 일치 항목이 반환됩니다.
문자열 조작¶
character¶
character(character_name) – character_name 으로 지정한 문자를 반환합니다. 예를 들어 character('newline') 는 줄바꿈 문자('')를 반환합니다. 지원되는 이름에는 newline 등이 있습니다.
check_yes_no¶
check_yes_no(field_name, is_undefined, is_false, is_true) – 조회 이름이 field_name 인 예/아니오 필드의 값이 매개변수로 지정한 값 중 하나인지 검사하고 일치하면 'Yes' 를, 일치하지 않으면 빈 문자열을 반환합니다. 검사하려는 조건에 따라 is_undefined, is_false, is_true 를 1(숫자)로 설정하고, 검사하지 않을 조건은 0으로 설정하십시오.
예: check_yes_no("#bool", 1, 0, 1) 은 예/아니오 필드 #bool 이 True 이거나 정의되지 않은 경우(True 도 False 도 아님) 'Yes' 를 반환합니다.
is_undefined, is_false, is_true 중 둘 이상을 동시에 1로 설정할 수 있습니다.
contains¶
contains(value, pattern, text_if_match, text_if_not_match) – 값이 정규식 pattern 과 일치하는지 검사합니다. 일치하면 text_if_match 를, 그렇지 않으면 text_if_not_match 를 반환합니다.
field_exists¶
field_exists(lookup_name) – 조회 이름이 lookup_name 인 필드(열)가 존재하는지 확인하고, 존재하면 '1' 을, 없으면 빈 문자열을 반환합니다.
ifempty¶
ifempty(value, text_if_empty) – value 가 비어 있지 않으면 그 값을 반환하고, 비어 있으면 text_if_empty 를 반환합니다.
re¶
re(value, pattern, replacement) – 정규식을 적용한 뒤의 value 를 반환합니다. 값 안의 pattern 에 해당하는 모든 부분을 replacement 로 바꿉니다. 템플릿 언어의 정규식은 기본적으로 대소문자를 구분하지 않습니다.
re_group¶
re_group(value, pattern [, template_for_group]*) – 정규 표현식 pattern``을 ``value``에 적용하고, 일치하는 각 인스턴스를 해당 템플릿이 반환하는 값으로 대체하여 생성된 문자열을 반환합니다. `템플릿 프로그램 모드 <https://manual.calibre-ebook.com/template_lang.html#more-complex-programs-in-template-expressions-template-program-mode>`_에서는 ``template 및 eval 함수와 마찬가지로 { 대신 [[``를, ``} 대신 ``]]``를 사용합니다.
다음 예제는 두 개 이상의 단어로 구성된 시리즈를 찾아 첫 번째 단어를 대문자로 변환합니다:
program: re_group(field(‘series’), “(\S* )(.*)”, “{$:uppercase()}”, “{$}”)'}
shorten¶
shorten(value, left_chars, middle_text, right_chars) – value``의 앞부분에서 ``left_chars 개를 잘라내고, 그 뒤에 middle_text``를 삽입한 후, ``value``의 끝부분에서 ``right_chars 개를 더한, ``value``의 축약된 버전을 반환합니다. ``left_chars``와 ``right_chars``는 음수가 아닌 정수여야 합니다.
예시: 길이가 최대 15자 이내인 제목을 표시하고 싶다고 가정해 봅시다. 이를 수행하는 템플릿 중 하나는 {title:shorten(9,-,5)}``입니다. 제목이 `Ancient English Laws inthe Times of Ivanhoe`인 책의 경우, 결과는 `Ancient E-anhoe`가 됩니다. 즉, 제목의 처음 9자, ``-, 그리고 마지막 5자가 나열됩니다. 값의 길이가 left chars + right chars + ``middle text``의 길이보다 짧다면, 값은 변경되지 않은 채로 반환됩니다. 예를 들어, 제목 `TheDome`은 변경되지 않습니다.
strcat¶
strcat(a [, b]*) – 모든 인수를 이어 붙여 만든 문자열을 반환합니다. 인수 개수는 제한이 없습니다. 대부분의 경우 이 함수 대신 & 연산자를 사용할 수 있습니다.
strcat_max¶
strcat_max(max, string1 [, prefix2, string2]*) – 인수들을 이어 붙여 만든 문자열을 반환합니다. 반환값은 string1 으로 시작합니다. 이후 prefix, string 쌍에서 만든 문자열은 전체 길이가 max 를 넘지 않을 때만 추가됩니다.
strlen¶
strlen(value) – 문자열 ``value``의 길이를 반환합니다.
substr¶
substr(value, start, end) – value 의 start 번째 문자부터 end 번째 문자까지를 반환합니다. 첫 문자의 인덱스는 0 입니다. end 가 음수이면 문자열 끝에서부터의 위치를 뜻합니다.
swap_around_articles¶
swap_around_articles(value, separator) – ``value``의 연결사를 문장 끝으로 옮기고 세미콜론으로 구분하여 반환합니다. ``value``는 리스트일 수 있으며, 이 경우 리스트의 각 항목이 처리됩니다. ``value``가 리스트인 경우 반드시 ``separator``를 지정해야 합니다. ``separator``를 지정하지 않거나 구분자로 빈 문자열을 지정하면, ``value``는 리스트가 아닌 단일 값으로 처리됩니다. 여기서 `articles`는 calibre가 ``title_sort``를 생성할 때 사용하는 항목들을 의미합니다.
swap_around_comma¶
swap_around_comma(value) – B, A 형식의 value 를 받아 A B 를 반환합니다. 성, 이름 형식(LN, FN)의 이름을 이름 성(FN LN) 형식으로 바꿀 때 유용합니다. value 에 쉼표가 없으면 값을 그대로 반환합니다.
test¶
test(value, text_if_not_empty, text_if_empty) – 값이 비어 있지 않으면 text_if_not_empty 를, 비어 있으면 text_if_empty 를 반환합니다.
transliterate¶
transliterate(value) – value 의 단어 소리를 근사해 라틴 문자 알파벳 문자열로 반환합니다. 예를 들어 value 가 Фёдор Миха́йлович Достоевский 이면 이 함수는 Fiodor Mikhailovich Dostoievskii 을 반환합니다.
불리언¶
and¶
and(value [, value]*) – 모든 값이 비어 있지 않으면 문자열 ‘1’``을 반환하고, 그렇지 않으면 빈 문자열을 반환합니다. 값의 개수는 제한이 없습니다. 대부분의 경우 이 함수 대신 ``&& 연산자를 사용할 수 있습니다. and()``를 ``&&``로 대체하지 말아야 할 한 가지 이유는, 단락 평가(short-circuiting)로 인해 부수 효과로 결과가 달라질 수 있는 경우입니다. 예를 들어, ``and(a=‘’,b=5)``는 항상 두 할당 모두를 수행하지만, ``&& 연산자는 두 번째 할당을 수행하지 않습니다.
not¶
not(value) – 값이 비어 있으면 문자열 '1' 을, 그렇지 않으면 빈 문자열을 반환합니다. 보통 단항 not(!) 연산자로 대체할 수 있습니다.
or¶
or(value [, value]*) – 값 중 하나라도 비어 있지 않으면 문자열 '1' 을, 모두 비어 있으면 빈 문자열을 반환합니다. 인수 개수는 제한이 없습니다. 보통 || 연산자로 대체할 수 있습니다.
산술¶
add¶
add(x [, y]*) – 인수들의 합을 반환합니다. 인수 중 숫자가 아닌 값이 있으면 예외를 발생시킵니다. 대부분의 경우 + 연산자로 대체할 수 있습니다.
ceiling¶
ceiling(value) – value 이상인 가장 작은 정수를 반환합니다. value 가 숫자가 아니면 예외를 발생시킵니다.
divide¶
divide(x, y) – x / y 를 반환합니다. x 또는 y 가 숫자가 아니면 예외를 발생시킵니다. 보통 / 연산자로 대체할 수 있습니다.
floor¶
floor(value) – value 이하인 가장 큰 정수를 반환합니다. value 가 숫자가 아니면 예외를 발생시킵니다.
fractional_part¶
fractional_part(value) – 값의 소수점 이하 부분을 반환합니다. 예를 들어 fractional_part(3.14) 는 0.14 를 반환합니다. value 가 숫자가 아니면 예외를 발생시킵니다.
mod¶
mod(value, y) – value / y 의 나머지에 대해 floor 를 적용한 값을 반환합니다. value 또는 y 가 숫자가 아니면 예외를 발생시킵니다.
multiply¶
multiply(x [, y]*) – 인수들의 곱을 반환합니다. 인수 중 숫자가 아닌 값이 있으면 예외를 발생시킵니다. 보통 * 연산자로 대체할 수 있습니다.
round¶
round(value) – value 에 가장 가까운 정수를 반환합니다. value 가 숫자가 아니면 예외를 발생시킵니다.
subtract¶
subtract(x, y) – x - y 를 반환합니다. x 또는 y 가 숫자가 아니면 예외를 발생시킵니다. 보통 - 연산자로 대체할 수 있습니다.
재귀¶
eval¶
eval(string) – 문자열을 프로그램으로 평가하고 지역 변수를 전달합니다. 이를 통해 템플릿 처리기를 사용해 지역 변수로부터 복잡한 결과를 만들 수 있습니다. Template Program Mode 에서는 템플릿이 평가되기 전에 { 와 } 가 해석되므로 각각 [[ 와 ]] 를 사용해야 하며, 자동으로 변환됩니다. 또한 Template Program Mode 를 사용할 때는 이 함수의 인수 안에서 접두사/접미사(|prefix|suffix 구문)를 사용할 수 없습니다.
template¶
template(x) – x 를 템플릿으로 평가합니다. 평가는 자체 컨텍스트에서 수행되므로 호출자와 템플릿 평가 사이에 변수는 공유되지 않습니다. General Program Mode 를 사용하지 않을 때는 { 와 } 가 특별한 문자이므로 각각 [[ 와 ]] 를 사용해야 하며, 자동으로 변환됩니다. 예를 들어 template('[[title_sort]]') 는 템플릿 {title_sort} 를 평가해 그 값을 반환합니다. 또한 Template Program Mode 를 사용할 때는 이 함수의 인수 안에서 접두사/접미사(|prefix|suffix 구문)를 사용할 수 없습니다.
API of the Metadata objects¶
The python implementation of the template functions is passed in a Metadata object. Knowing it’s API is useful if you want to define your own template functions.
- class calibre.ebooks.metadata.book.base.Metadata(title, authors=('알 수 없음',), other=None, template_cache=None, formatter=None)[소스]¶
A class representing all the metadata for a book. The various standard metadata fields are available as attributes of this object. You can also stick arbitrary attributes onto this object.
Metadata from custom columns should be accessed via the get() method, passing in the lookup name for the column, for example: “#mytags”.
Use the
is_null()method to test if a field is null.This object also has functions to format fields into strings.
The list of standard metadata fields grows with time is in
STANDARD_METADATA_FIELDS.Please keep the method based API of this class to a minimum. Every method becomes a reserved field name.
- is_null(field)[소스]¶
Return True if the value of field is null in this object. ‘null’ means it is unknown or evaluates to False. So a title of _(‘Unknown’) is null or a language of ‘und’ is null.
Be careful with numeric fields since this will return True for zero as well as None.
Also returns True if the field does not exist.
- deepcopy(class_generator=<function Metadata.<lambda>>)[소스]¶
Do not use this method unless you know what you are doing, if you want to create a simple clone of this object, use
deepcopy_metadata()instead. Class_generator must be a function that returns an instance of Metadata or a subclass of it.
- get_identifiers()[소스]¶
Return a copy of the identifiers dictionary. The dict is small, and the penalty for using a reference where a copy is needed is large. Also, we don’t want any manipulations of the returned dict to show up in the book.
- set_identifiers(identifiers)[소스]¶
Set all identifiers. Note that if you previously set ISBN, calling this method will delete it.
- all_non_none_fields()[소스]¶
Return a dictionary containing all non-None metadata fields, including the custom ones.
- get_standard_metadata(field, make_copy)[소스]¶
return field metadata from the field if it is there. Otherwise return None. field is the key name, not the label. Return a copy if requested, just in case the user wants to change values in the dict.
- get_all_standard_metadata(make_copy)[소스]¶
return a dict containing all the standard field metadata associated with the book.
- get_all_user_metadata(make_copy)[소스]¶
return a dict containing all the custom field metadata associated with the book.
- get_user_metadata(field, make_copy)[소스]¶
return field metadata from the object if it is there. Otherwise return None. field is the key name, not the label. Return a copy if requested, just in case the user wants to change values in the dict.
- set_all_user_metadata(metadata)[소스]¶
store custom field metadata into the object. Field is the key name not the label
- set_user_metadata(field, metadata)[소스]¶
store custom field metadata for one column into the object. Field is the key name not the label
- remove_stale_user_metadata(other_mi)[소스]¶
Remove user metadata keys (custom column keys) if they don’t exist in ‘other_mi’, which must be a metadata object
- template_to_attribute(other, ops)[소스]¶
Takes a list [(src,dest), (src,dest)], evaluates the template in the context of other, then copies the result to self[dest]. This is on a best-efforts basis. Some assignments can make no sense.
- calibre.ebooks.metadata.book.base.STANDARD_METADATA_FIELDS¶
The set of standard metadata fields.
'''
All fields must have a NULL value represented as None for simple types,
an empty list/dictionary for complex types and (None, None) for cover_data
'''
SOCIAL_METADATA_FIELDS = frozenset((
'tags', # Ordered list
'rating', # A floating point number between 0 and 10
'comments', # A simple HTML enabled string
'series', # A simple string
'series_index', # A floating point number
# Of the form { scheme1:value1, scheme2:value2}
# For example: {'isbn':'123456789', 'doi':'xxxx', ... }
'identifiers',
))
'''
The list of names that convert to identifiers when in get and set.
'''
TOP_LEVEL_IDENTIFIERS = frozenset((
'isbn',
))
PUBLICATION_METADATA_FIELDS = frozenset((
'title', # title must never be None. Should be _('Unknown')
# Pseudo field that can be set, but if not set is auto generated
# from title and languages
'title_sort',
'authors', # Ordered list. Must never be None, can be [_('Unknown')]
'author_sort_map', # Map of sort strings for each author
# Pseudo field that can be set, but if not set is auto generated
# from authors and languages
'author_sort',
'book_producer',
'timestamp', # Dates and times must be timezone aware
'pubdate',
'last_modified',
'rights',
# So far only known publication type is periodical:calibre
# If None, means book
'publication_type',
'uuid', # A UUID usually of type 4
'languages', # ordered list of languages in this publication
'publisher', # Simple string, no special semantics
# Absolute path to image file encoded in filesystem_encoding
'cover',
# Of the form (format, data) where format is, e.g. 'jpeg', 'png', 'gif'...
'cover_data',
# Either thumbnail data, or an object with the attribute
# image_path which is the path to an image file, encoded
# in filesystem_encoding
'thumbnail',
))
BOOK_STRUCTURE_FIELDS = frozenset((
# These are used by code, Null values are None.
'toc', 'spine', 'guide', 'manifest',
))
USER_METADATA_FIELDS = frozenset((
# A dict of dicts similar to field_metadata. Each field description dict
# also contains a value field with the key #value#.
'user_metadata',
))
DEVICE_METADATA_FIELDS = frozenset((
'device_collections', # Ordered list of strings
'lpath', # Unicode, / separated
'size', # In bytes
'mime', # Mimetype of the book file being represented
))
CALIBRE_METADATA_FIELDS = frozenset((
'application_id', # An application id, currently set to the db_id.
'db_id', # the calibre primary key of the item.
'formats', # list of formats (extensions) for this book
# a dict of user category names, where the value is a list of item names
# from the book that are in that category
'user_categories',
# a dict of items to associated hyperlink
'link_maps',
# Calculated page count, null values are None or 0. -1 is no countable
# formats. -2 is error processing formats, -3 is DRMed.
'pages',
))
ALL_METADATA_FIELDS = SOCIAL_METADATA_FIELDS.union(
PUBLICATION_METADATA_FIELDS).union(
BOOK_STRUCTURE_FIELDS).union(
USER_METADATA_FIELDS).union(
DEVICE_METADATA_FIELDS).union(
CALIBRE_METADATA_FIELDS)
# All fields except custom fields
STANDARD_METADATA_FIELDS = SOCIAL_METADATA_FIELDS.union(
PUBLICATION_METADATA_FIELDS).union(
BOOK_STRUCTURE_FIELDS).union(
DEVICE_METADATA_FIELDS).union(
CALIBRE_METADATA_FIELDS)
# Metadata fields that smart update must do special processing to copy.
SC_FIELDS_NOT_COPIED = frozenset(('title', 'title_sort', 'authors',
'author_sort', 'author_sort_map',
'cover_data', 'tags', 'languages',
'identifiers'))
# Metadata fields that smart update should copy only if the source is not None
SC_FIELDS_COPY_NOT_NULL = frozenset(('device_collections', 'lpath', 'size', 'comments', 'thumbnail'))
# Metadata fields that smart update should copy without special handling
SC_COPYABLE_FIELDS = SOCIAL_METADATA_FIELDS.union(
PUBLICATION_METADATA_FIELDS).union(
BOOK_STRUCTURE_FIELDS).union(
DEVICE_METADATA_FIELDS).union(
CALIBRE_METADATA_FIELDS) - \
SC_FIELDS_NOT_COPIED.union(
SC_FIELDS_COPY_NOT_NULL)
SERIALIZABLE_FIELDS = SOCIAL_METADATA_FIELDS.union(
USER_METADATA_FIELDS).union(
PUBLICATION_METADATA_FIELDS).union(
CALIBRE_METADATA_FIELDS).union(
DEVICE_METADATA_FIELDS) - \
frozenset(('device_collections', 'formats',
'cover_data'))
# these are rebuilt when needed