mirror of
https://github.com/kovidgoyal/calibre.git
synced 2025-07-08 02:34:06 -04:00
Merge branch 'master' of https://github.com/cbhaley/calibre
This commit is contained in:
Kovid Goyal
commit
681c50ed08
@ -174,53 +174,53 @@ Notes on calling functions in Single Function Mode:
|
||||
|
||||
Functions are documented in :ref:`template_functions_reference`. The documentation tells you what arguments the functions require and what the functions do. For example, here is the documentation of the :ref:`ff_ifempty` function.
|
||||
|
||||
:ffdoc:`ifempty`
|
||||
* :ffdoc:`ifempty`
|
||||
|
||||
You see that the function requires two arguments, ``value`` and ``text_if_empty``. However, because we are using Single Function Mode, we omit the ``value`` argument, passing only ``text_if_empty``. For example, this template::
|
||||
|
||||
{tags:ifempty(No tags on this book)}
|
||||
|
||||
shows the tags for a book if it has any. If it has no tags then it show `No tags on this book`.
|
||||
shows the tags for a book, if any. If it has no tags then it show `No tags on this book`.
|
||||
|
||||
The following functions are usable in Single Function Mode because their first parameter is ``value``.
|
||||
|
||||
* :ref:`ff_capitalize`
|
||||
* :ref:`ff_ceiling`
|
||||
* :ref:`ff_cmp`
|
||||
* :ref:`ff_contains`
|
||||
* :ref:`ff_date_arithmetic`
|
||||
* :ref:`ff_floor`
|
||||
* :ref:`ff_format_date`
|
||||
* :ref:`ff_format_number`
|
||||
* :ref:`ff_fractional_part`
|
||||
* :ref:`ff_human_readable`
|
||||
* :ref:`ff_ifempty`
|
||||
* :ref:`ff_language_strings`
|
||||
* :ref:`ff_list_contains`
|
||||
* :ref:`ff_list_count`
|
||||
* :ref:`ff_list_count_matching`
|
||||
* :ref:`ff_list_item`
|
||||
* :ref:`ff_list_sort`
|
||||
* :ref:`ff_lookup`
|
||||
* :ref:`ff_lowercase`
|
||||
* :ref:`ff_mod`
|
||||
* :ref:`ff_rating_to_stars`
|
||||
* :ref:`ff_re`
|
||||
* :ref:`ff_re_group`
|
||||
* :ref:`ff_round`
|
||||
* :ref:`ff_select`
|
||||
* :ref:`ff_shorten`
|
||||
* :ref:`ff_str_in_list`
|
||||
* :ref:`ff_subitems`
|
||||
* :ref:`ff_sublist`
|
||||
* :ref:`ff_substr`
|
||||
* :ref:`ff_swap_around_articles`
|
||||
* :ref:`ff_swap_around_comma`
|
||||
* :ref:`ff_switch`
|
||||
* :ref:`ff_test`
|
||||
* :ref:`ff_titlecase`
|
||||
* :ref:`ff_transliterate`
|
||||
* :ref:`ff_uppercase`
|
||||
* :ffsum:`ff_capitalize`
|
||||
* :ffsum:`ff_ceiling`
|
||||
* :ffsum:`ff_cmp`
|
||||
* :ffsum:`ff_contains`
|
||||
* :ffsum:`ff_date_arithmetic`
|
||||
* :ffsum:`ff_floor`
|
||||
* :ffsum:`ff_format_date`
|
||||
* :ffsum:`ff_format_number`
|
||||
* :ffsum:`ff_fractional_part`
|
||||
* :ffsum:`ff_human_readable`
|
||||
* :ffsum:`ff_ifempty`
|
||||
* :ffsum:`ff_language_strings`
|
||||
* :ffsum:`ff_list_contains`
|
||||
* :ffsum:`ff_list_count`
|
||||
* :ffsum:`ff_list_count_matching`
|
||||
* :ffsum:`ff_list_item`
|
||||
* :ffsum:`ff_list_sort`
|
||||
* :ffsum:`ff_lookup`
|
||||
* :ffsum:`ff_lowercase`
|
||||
* :ffsum:`ff_mod`
|
||||
* :ffsum:`ff_rating_to_stars`
|
||||
* :ffsum:`ff_re`
|
||||
* :ffsum:`ff_re_group`
|
||||
* :ffsum:`ff_round`
|
||||
* :ffsum:`ff_select`
|
||||
* :ffsum:`ff_shorten`
|
||||
* :ffsum:`ff_str_in_list`
|
||||
* :ffsum:`ff_subitems`
|
||||
* :ffsum:`ff_sublist`
|
||||
* :ffsum:`ff_substr`
|
||||
* :ffsum:`ff_swap_around_articles`
|
||||
* :ffsum:`ff_swap_around_comma`
|
||||
* :ffsum:`ff_switch`
|
||||
* :ffsum:`ff_test`
|
||||
* :ffsum:`ff_titlecase`
|
||||
* :ffsum:`ff_transliterate`
|
||||
* :ffsum:`ff_uppercase`
|
||||
|
||||
**Using functions and formatting in the same template**
|
||||
|
||||
@ -405,7 +405,7 @@ Example: This template computes an approximate duration in years, months, and da
|
||||
|
||||
**Relational operators**
|
||||
|
||||
Relational operators return ``'1'`` if the comparison is true, otherwise the empty string ('').
|
||||
Relational operators return ``'1'`` if the comparison is true, otherwise the empty string (``''``).
|
||||
|
||||
There are two forms of relational operators: string comparisons and numeric comparisons.
|
||||
|
||||
@ -418,17 +418,16 @@ The numeric comparison operators are ``==#``, ``!=#``, ``<#``, ``<=#``, ``>#``,
|
||||
|
||||
Examples:
|
||||
|
||||
* ``program: field('series') == 'foo'`` returns ``'1'`` if the book's series is 'foo', otherwise ``''``.
|
||||
* ``program: field('series') == 'foo'`` returns ``'1'`` if the book's series is `foo`, otherwise ``''``.
|
||||
* ``program: 'f.o' in field('series')`` returns ``'1'`` if the book's series matches the regular expression ``f.o`` (e.g., `foo`, `Off Onyx`, etc.), otherwise ``''``.
|
||||
* ``program: 'science' inlist $#genre`` returns ``'1'`` if any of the values retrieved from the book's genres match the regular expression ``science``, e.g., `Science`, `History of Science`, `Science Fiction` etc., otherwise ``''``.
|
||||
* ``program: '^science$' inlist $#genre`` returns ``'1'`` if any of the book's genres exactly match the regular expression ``^science$``, e.g., `Science`, otherwise ``''``. The genres `History of Science` and `Science Fiction` don't match.
|
||||
* ``program: 'asimov' inlist $authors`` returns ``'1'`` if any author matches the regular expression ``asimov``, e.g., `Asimov, Isaac` or `Isaac Asimov`, otherwise ``''``.
|
||||
* ``program: 'asimov' inlist_field 'authors'`` returns ``'1'`` if any author matches the regular expression ``asimov``, e.g., `Asimov, Isaac` or `Isaac Asimov`, otherwise ``''``.
|
||||
* ``program: 'asimov$' inlist_field 'authors'`` returns ``'1'`` if any author matches the regular expression ``asimov$``, e.g., `Isaac Asimov`, otherwise ``''``. It doesn't match `Asimov, Isaac` because of the ``$`` anchor in the regular expression.
|
||||
* ``program: if field('series') != 'foo' then 'bar' else 'mumble' fi`` returns ``'bar'`` if the book's series is not ``foo``. Otherwise it returns ``'mumble'``.
|
||||
* ``program: if field('series') != 'foo' then 'bar' else 'mumble' fi`` returns ``'bar'`` if the book's series is not ``foo``. Otherwise it returns ``'mumble'``.
|
||||
* ``program: if field('series') == 'foo' || field('series') == '1632' then 'yes' else 'no' fi`` returns ``'yes'`` if series is either ``'foo'`` or ``'1632'``, otherwise ``'no'``.
|
||||
* ``program: if '^(foo|1632)$' in field('series') then 'yes' else 'no' fi`` returns ``'yes'`` if series is either ``'foo'`` or ``'1632'``, otherwise ``'no'``.
|
||||
* ``program: if field('series') != 'foo' then 'bar' else 'mumble' fi`` returns ``'bar'`` if the book's series is not `foo`. Otherwise it returns ``'mumble'``.
|
||||
* ``program: if field('series') == 'foo' || field('series') == '1632' then 'yes' else 'no' fi`` returns ``'yes'`` if series is either `foo` or `1632`, otherwise ``'no'``.
|
||||
* ``program: if '^(foo|1632)$' in field('series') then 'yes' else 'no' fi`` returns ``'yes'`` if series is either `foo` or `1632`, otherwise ``'no'``.
|
||||
* ``program: if 11 > 2 then 'yes' else 'no' fi`` returns ``'no'`` because the ``>`` operator does a lexical comparison.
|
||||
* ``program: if 11 ># 2 then 'yes' else 'no' fi`` returns ``'yes'`` because the ``>#`` operator does a numeric comparison.
|
||||
|
||||
@ -452,13 +451,18 @@ More complex programs in template expressions - Template Program Mode
|
||||
Example: assume you want a template to show the series for a book if it has one, otherwise show
|
||||
the value of a custom field #genre. You cannot do this in the :ref:`Single Function Mode <single_mode>` because you cannot make reference to another metadata field within a template expression. In `TPM` you can, as the following expression demonstrates::
|
||||
|
||||
{#series:'ifempty($, field('#genre'))'}
|
||||
{series_index:0>7.1f:'ifempty($, -5)'}
|
||||
|
||||
The example shows several things:
|
||||
|
||||
* `TPM` is used if the expression begins with ``:'`` and ends with ``'}``. Anything else is assumed to be in :ref:`Single Function Mode <single_mode>`.
|
||||
* Functions must be given all their arguments. There is no default value. For example, the standard built-in functions must be given the initial parameter ``value``.
|
||||
* The variable ``$`` is usable as the ``input`` argument and stands for the value of the field named in the template, ``#series`` in this case.
|
||||
|
||||
If the template contains a prefix and suffix, the expression ends with ``'|`` where the ``|`` is the delimiter for the prefix. Example::
|
||||
|
||||
{series_index:0>7.1f:'ifempty($, -5)'|prefix | suffix}
|
||||
|
||||
* Functions must be given all their arguments. For example, the standard built-in functions must be given the initial parameter ``value``.
|
||||
* The variable ``$`` is usable as the ``value`` argument and stands for the value of the field named in the template, ``series_index`` in this case.
|
||||
* white space is ignored and can be used anywhere within the expression.
|
||||
* constant strings are enclosed in matching quotes, either ``'`` or ``"``.
|
||||
|
||||
|
||||
@ -45,7 +45,8 @@ from calibre import sanitize_file_name
|
||||
from calibre.constants import config_dir, iswindows
|
||||
from calibre.ebooks.metadata.book.base import Metadata
|
||||
from calibre.ebooks.metadata.book.formatter import SafeFormat
|
||||
from calibre.gui2 import choose_files, choose_save_file, error_dialog, gprefs, pixmap_to_data, question_dialog, safe_open_url
|
||||
from calibre.gui2 import (choose_files, choose_save_file, error_dialog, gprefs, info_dialog,
|
||||
pixmap_to_data, question_dialog, safe_open_url)
|
||||
from calibre.gui2.dialogs.template_dialog_ui import Ui_TemplateDialog
|
||||
from calibre.gui2.dialogs.template_general_info import GeneralInformationDialog
|
||||
from calibre.gui2.widgets2 import Dialog, HTMLDisplay
|
||||
@ -68,6 +69,8 @@ class DocViewer(Dialog):
|
||||
self.builtins = builtins
|
||||
self.function_type_string = function_type_string_method
|
||||
self.last_operation = None
|
||||
self.last_function = None
|
||||
self.back_stack = []
|
||||
super().__init__(title=_('Template function documentation'), name='template_editor_doc_viewer_dialog',
|
||||
default_buttons=QDialogButtonBox.StandardButton.Close, parent=parent)
|
||||
|
||||
@ -82,7 +85,7 @@ class DocViewer(Dialog):
|
||||
e = self.doc_viewer_widget = HTMLDisplay(self)
|
||||
if iswindows:
|
||||
e.setDefaultStyleSheet('pre { font-family: "Segoe UI Mono", "Consolas", monospace; }')
|
||||
e.anchor_clicked.connect(safe_open_url)
|
||||
e.anchor_clicked.connect(self.url_clicked)
|
||||
l.addWidget(e)
|
||||
bl = QHBoxLayout()
|
||||
l.addLayout(bl)
|
||||
@ -91,10 +94,41 @@ class DocViewer(Dialog):
|
||||
cb.stateChanged.connect(self.english_cb_state_changed)
|
||||
bl.addWidget(cb)
|
||||
bl.addWidget(self.bb)
|
||||
|
||||
b = self.back_button = self.bb.addButton(_('&Back'), QDialogButtonBox.ButtonRole.ActionRole)
|
||||
b.clicked.connect(self.back)
|
||||
b.setToolTip((_('Displays the previously viewed function')))
|
||||
b.setEnabled(False)
|
||||
|
||||
b = self.bb.addButton(_('Show &all functions'), QDialogButtonBox.ButtonRole.ActionRole)
|
||||
b.clicked.connect(self.show_all_functions)
|
||||
b.setToolTip((_('Shows a list of all built-in functions in alphabetic order')))
|
||||
|
||||
def back(self):
|
||||
if not self.back_stack:
|
||||
info_dialog(self, _('Go back'), _('No function to go back to'), show=True)
|
||||
else:
|
||||
place = self.back_stack.pop()
|
||||
if not self.back_stack:
|
||||
self.back_button.setEnabled(False)
|
||||
if isinstance(place, int):
|
||||
self.show_all_functions()
|
||||
self.doc_viewer_widget.verticalScrollBar().setSliderPosition(place)
|
||||
else:
|
||||
self.show_function(place)
|
||||
|
||||
def url_clicked(self, qurl):
|
||||
if qurl.scheme().startswith('http'):
|
||||
safe_open_url(qurl)
|
||||
else:
|
||||
if self.last_function is not None:
|
||||
self.back_stack.append(self.last_function)
|
||||
self.back_button.setEnabled(True)
|
||||
else:
|
||||
self.back_stack.append(self.doc_viewer_widget.verticalScrollBar().sliderPosition())
|
||||
self.back_button.setEnabled(True)
|
||||
self.show_function(qurl.path())
|
||||
|
||||
def english_cb_state_changed(self):
|
||||
if self.last_operation is not None:
|
||||
self.last_operation()
|
||||
@ -113,10 +147,14 @@ class DocViewer(Dialog):
|
||||
if fname not in self.builtins or not bif.doc:
|
||||
self.set_html(self.header_line(fname) + ('No documentation provided'))
|
||||
else:
|
||||
self.last_function = fname
|
||||
self.set_html(self.header_line(fname) +
|
||||
self.ffml.document_to_html(self.get_doc(bif), fname))
|
||||
|
||||
def show_all_functions(self):
|
||||
self.back_button.setEnabled(False)
|
||||
self.back_stack = []
|
||||
self.last_function = None
|
||||
self.last_operation = self.show_all_functions
|
||||
result = []
|
||||
a = result.append
|
||||
@ -127,7 +165,10 @@ class DocViewer(Dialog):
|
||||
if not doc:
|
||||
a(_('No documentation provided'))
|
||||
else:
|
||||
a(self.ffml.document_to_html(doc.strip(), name))
|
||||
html = self.ffml.document_to_html(doc.strip(), name)
|
||||
paren = html.find('(')
|
||||
html = f'<a href="ffdoc:{name}">{name}</a>{html[paren:]}'
|
||||
a(html)
|
||||
except Exception:
|
||||
print('Exception in', name)
|
||||
raise
|
||||
@ -541,6 +582,8 @@ class TemplateDialog(QDialog, Ui_TemplateDialog):
|
||||
self.doc_viewer = None
|
||||
self.current_function_name = None
|
||||
self.documentation.setReadOnly(True)
|
||||
self.documentation.setOpenLinks(False)
|
||||
self.documentation.anchorClicked.connect(self.url_clicked)
|
||||
self.source_code.setReadOnly(True)
|
||||
self.doc_button.clicked.connect(self.open_documentation_viewer)
|
||||
self.general_info_button.clicked.connect(self.open_general_info_dialog)
|
||||
@ -569,7 +612,7 @@ class TemplateDialog(QDialog, Ui_TemplateDialog):
|
||||
except:
|
||||
self.builtin_source_dict = {}
|
||||
|
||||
func_names = sorted(self.all_functions)
|
||||
self.function_names = func_names = sorted(self.all_functions)
|
||||
self.function.clear()
|
||||
self.function.addItem('')
|
||||
for f in func_names:
|
||||
@ -603,6 +646,15 @@ class TemplateDialog(QDialog, Ui_TemplateDialog):
|
||||
# Now geometry
|
||||
self.restore_geometry(gprefs, self.geometry_string('template_editor_dialog_geometry'))
|
||||
|
||||
def url_clicked(self, qurl):
|
||||
if qurl.scheme().startswith('http'):
|
||||
safe_open_url(qurl)
|
||||
elif qurl.scheme() == 'ffdoc':
|
||||
name = qurl.path()
|
||||
if name in self.function_names:
|
||||
dex = self.function_names.index(name)
|
||||
self.function.setCurrentIndex(dex+1)
|
||||
|
||||
def open_documentation_viewer(self):
|
||||
if self.doc_viewer is None:
|
||||
dv = self.doc_viewer = DocViewer(self.ffml, self.all_functions,
|
||||
|
||||
@ -768,9 +768,6 @@ Selecting a function will show only that function's documentation</string>
|
||||
</item>
|
||||
<item row="3" column="1">
|
||||
<widget class="QTextBrowser" name="documentation">
|
||||
<property name="openExternalLinks">
|
||||
<bool>true</bool>
|
||||
</property>
|
||||
<property name="maximumSize">
|
||||
<size>
|
||||
<width>16777215</width>
|
||||
|
||||
@ -116,6 +116,13 @@ program:
|
||||
\[/CODE]
|
||||
\[/LIST]
|
||||
[/CODE]
|
||||
[*]End of summary marker. A summary is generated from the first characters of
|
||||
the documentation. The summary includes text up to a \[/] tag. There is no
|
||||
opening tag because the summary starts at the first character. If there is
|
||||
no \[/] tag then all the document is used for the summary. The \[/] tag
|
||||
is not replaced with white space or any other character.
|
||||
[*]Escaped character: precede the character with a backslash. This is useful
|
||||
to escape tags. For example to make the \[CODE] tag not a tag, use \\\[CODE].
|
||||
|
||||
[*]HTML output contains no CSS and does not start with a tag such as <DIV> or <P>.
|
||||
[/LIST]
|
||||
|
||||
@ -14,16 +14,18 @@ class NodeKinds(IntEnum):
|
||||
DOCUMENT = -1
|
||||
BLANK_LINE = -2
|
||||
BOLD_TEXT = -3
|
||||
CODE_TEXT = -4
|
||||
CODE_BLOCK = -5
|
||||
END_LIST = -6
|
||||
GUI_LABEL = -7
|
||||
ITALIC_TEXT = -8
|
||||
LIST = -9
|
||||
LIST_ITEM = -10
|
||||
REF = -11
|
||||
TEXT = -12
|
||||
URL = -13
|
||||
CHARACTER = -4
|
||||
CODE_TEXT = -5
|
||||
CODE_BLOCK = -6
|
||||
END_LIST = -7
|
||||
GUI_LABEL = -8
|
||||
ITALIC_TEXT = -9
|
||||
LIST = -10
|
||||
LIST_ITEM = -11
|
||||
REF = -12
|
||||
END_SUMMARY = -13
|
||||
TEXT = -14
|
||||
URL = -15
|
||||
|
||||
|
||||
class Node:
|
||||
@ -42,7 +44,7 @@ class Node:
|
||||
return self._children
|
||||
|
||||
def text(self):
|
||||
return self._text.replace('\\', '')
|
||||
return self._text
|
||||
|
||||
def escaped_text(self):
|
||||
return prepare_string_for_xml(self.text())
|
||||
@ -61,6 +63,13 @@ class BoldTextNode(Node):
|
||||
self._text = text
|
||||
|
||||
|
||||
class CharacterNode(Node):
|
||||
|
||||
def __init__(self, character):
|
||||
super().__init__(NodeKinds.CHARACTER)
|
||||
self._text = character
|
||||
|
||||
|
||||
class CodeBlock(Node):
|
||||
|
||||
def __init__(self, code_text):
|
||||
@ -82,6 +91,12 @@ class DocumentNode(Node):
|
||||
self._children = []
|
||||
|
||||
|
||||
class EndSummaryNode(Node):
|
||||
|
||||
def __init__(self):
|
||||
super().__init__(NodeKinds.END_SUMMARY)
|
||||
|
||||
|
||||
class GuiLabelNode(Node):
|
||||
|
||||
def __init__(self, text):
|
||||
@ -202,6 +217,12 @@ class FFMLProcessor:
|
||||
[/CODE]
|
||||
[/LIST]
|
||||
|
||||
- end of summary marker. A summary is generated from the first characters of
|
||||
the documentation. The summary includes text up to a \[/] tag. There is no
|
||||
opening tag because the summary starts at the first character. If there is
|
||||
no \[/] tag then all the document is used for the summary. The \[/] tag
|
||||
is not replaced with white space or any other character.
|
||||
|
||||
- escaped character: precede the character with a backslash. This is useful
|
||||
to escape tags. For example to make the [CODE] tag not a tag, use \[CODE].
|
||||
|
||||
@ -241,7 +262,7 @@ class FFMLProcessor:
|
||||
:param indent: The indent level of the tree. The outermost root should
|
||||
have an indent of zero.
|
||||
"""
|
||||
if node.node_kind() in (NodeKinds.TEXT, NodeKinds.CODE_TEXT,
|
||||
if node.node_kind() in (NodeKinds.TEXT, NodeKinds.CODE_TEXT, NodeKinds.CHARACTER,
|
||||
NodeKinds.CODE_BLOCK, NodeKinds.ITALIC_TEXT,
|
||||
NodeKinds.GUI_LABEL, NodeKinds.BOLD_TEXT):
|
||||
print(f'{" " * indent}{node.node_kind().name}:{node.text()}')
|
||||
@ -288,10 +309,14 @@ class FFMLProcessor:
|
||||
result += f'<b>{tree.escaped_text()}</b>'
|
||||
elif tree.node_kind() == NodeKinds.BLANK_LINE:
|
||||
result += '\n<br>\n<br>\n'
|
||||
elif tree.node_kind() == NodeKinds.CHARACTER:
|
||||
result += tree.text()
|
||||
elif tree.node_kind() == NodeKinds.CODE_TEXT:
|
||||
result += f'<code>{tree.escaped_text()}</code>'
|
||||
elif tree.node_kind() == NodeKinds.CODE_BLOCK:
|
||||
result += f'<pre style="margin-left:2em"><code>{tree.escaped_text().rstrip()}</code></pre>'
|
||||
elif tree.node_kind() == NodeKinds.END_SUMMARY:
|
||||
pass
|
||||
elif tree.node_kind() == NodeKinds.GUI_LABEL:
|
||||
result += f'<span style="font-family: Sans-Serif">{tree.escaped_text()}</span>'
|
||||
elif tree.node_kind() == NodeKinds.ITALIC_TEXT:
|
||||
@ -300,16 +325,16 @@ class FFMLProcessor:
|
||||
result += '\n<ul>\n'
|
||||
for child in tree.children():
|
||||
result += '<li>\n'
|
||||
result += self.tree_to_html(child, depth+1)
|
||||
result += self.tree_to_html(child, depth=depth+1)
|
||||
result += '</li>\n'
|
||||
result += '</ul>\n'
|
||||
elif tree.node_kind() == NodeKinds.REF:
|
||||
result += f'<code>{tree.escaped_text()}()</code>'
|
||||
result += f'<a href="ffdoc:{tree.text()}">{tree.text()}</a></a>'
|
||||
elif tree.node_kind() == NodeKinds.URL:
|
||||
result += f'<a href="{tree.escaped_url()}">{tree.escaped_label()}</a>'
|
||||
elif tree.node_kind() in (NodeKinds.DOCUMENT, NodeKinds.LIST_ITEM):
|
||||
for child in tree.children():
|
||||
result += self.tree_to_html(child, depth+1)
|
||||
result += self.tree_to_html(child, depth=depth+1)
|
||||
return result
|
||||
|
||||
def document_to_html(self, document, name):
|
||||
@ -327,6 +352,29 @@ class FFMLProcessor:
|
||||
tree = self.parse_document(document, name)
|
||||
return self.tree_to_html(tree, 0)
|
||||
|
||||
def document_to_summary_html(self, document, name):
|
||||
"""
|
||||
Given a document in the Formatter Function Markup Language (FFML), return
|
||||
that document's summary in HTML format.
|
||||
|
||||
:param document: the text in FFML.
|
||||
:param name: the name of the document, used during error
|
||||
processing. It is usually the name of the function.
|
||||
|
||||
:return: a string containing the HTML
|
||||
|
||||
"""
|
||||
document = document.strip()
|
||||
sum_tag = document.find('[/]')
|
||||
if sum_tag > 0:
|
||||
document = document[0:sum_tag]
|
||||
fname = document[0:document.find('(')].lstrip('`')
|
||||
tree = self.parse_document(document, name)
|
||||
result = self.tree_to_html(tree, depth=0)
|
||||
paren = result.find('(')
|
||||
result = f'<a href="ffdoc:{fname}">{fname}</a>{result[paren:]}'
|
||||
return result
|
||||
|
||||
def tree_to_rst(self, tree, indent, result=None):
|
||||
"""
|
||||
Given a Formatter Function Markup Language (FFML) parse tree, return
|
||||
@ -356,6 +404,8 @@ class FFMLProcessor:
|
||||
result += '\n\n'
|
||||
elif tree.node_kind() == NodeKinds.BOLD_TEXT:
|
||||
indent_text(f'**{tree.text()}**')
|
||||
elif tree.node_kind() == NodeKinds.CHARACTER:
|
||||
result += tree.text()
|
||||
elif tree.node_kind() == NodeKinds.CODE_BLOCK:
|
||||
result += f"\n\n{' ' * indent}::\n\n"
|
||||
for line in tree.text().strip().split('\n'):
|
||||
@ -363,6 +413,8 @@ class FFMLProcessor:
|
||||
result += '\n'
|
||||
elif tree.node_kind() == NodeKinds.CODE_TEXT:
|
||||
indent_text(f'``{tree.text()}``')
|
||||
elif tree.node_kind() == NodeKinds.END_SUMMARY:
|
||||
pass
|
||||
elif tree.node_kind() == NodeKinds.GUI_LABEL:
|
||||
indent_text(f':guilabel:`{tree.text()}`')
|
||||
elif tree.node_kind() == NodeKinds.ITALIC_TEXT:
|
||||
@ -371,7 +423,7 @@ class FFMLProcessor:
|
||||
result += '\n\n'
|
||||
for child in tree.children():
|
||||
result += f"{' ' * (indent)}* "
|
||||
result = self.tree_to_rst(child, indent+1, result)
|
||||
result = self.tree_to_rst(child, indent+1, result=result)
|
||||
result += '\n'
|
||||
result += '\n'
|
||||
elif tree.node_kind() == NodeKinds.REF:
|
||||
@ -384,7 +436,7 @@ class FFMLProcessor:
|
||||
indent_text(f'`{tree.label()} <{tree.url()}>`_')
|
||||
elif tree.node_kind() in (NodeKinds.DOCUMENT, NodeKinds.LIST_ITEM):
|
||||
for child in tree.children():
|
||||
result = self.tree_to_rst(child, indent, result)
|
||||
result = self.tree_to_rst(child, indent, result=result)
|
||||
return result
|
||||
|
||||
def document_to_rst(self, document, name, indent=0, prefix=None):
|
||||
@ -410,19 +462,51 @@ class FFMLProcessor:
|
||||
doc = prefix + doc.lstrip(' ' * indent)
|
||||
return doc
|
||||
|
||||
def document_to_summary_rst(self, document, name, indent=0, prefix=None):
|
||||
"""
|
||||
Given a document in the Formatter Function Markup Language (FFML), return
|
||||
that document's summary in RST (sphinx reStructuredText) format.
|
||||
|
||||
:param document: the text in FFML.
|
||||
:param name: the name of the document, used during error
|
||||
processing. It is usually the name of the function.
|
||||
:param indent: the indenting level of the items in the tree. This is
|
||||
usually zero, but can be greater than zero if you want
|
||||
the RST output indented.
|
||||
:param prefix: string. if supplied, this string replaces the indent
|
||||
on the first line of the output. This permits specifying
|
||||
an RST block, for example a bullet list
|
||||
|
||||
:return: a string containing the RST text
|
||||
|
||||
"""
|
||||
document = document.strip()
|
||||
sum_tag = document.find('[/]')
|
||||
if sum_tag > 0:
|
||||
document = document[0:sum_tag]
|
||||
fname = document[0:document.find('(')].lstrip('`')
|
||||
doc = self.tree_to_rst(self.parse_document(document, name), indent)
|
||||
lparen = doc.find('(')
|
||||
doc = f':ref:`ff_{fname}`\\ ``{doc[lparen:]}'
|
||||
if prefix is not None:
|
||||
doc = prefix + doc.lstrip(' ' * indent)
|
||||
return doc
|
||||
|
||||
# ============== Internal methods =================
|
||||
|
||||
keywords = {'``': NodeKinds.CODE_TEXT, # must be before '`'
|
||||
'`': NodeKinds.ITALIC_TEXT,
|
||||
'[B]': NodeKinds.BOLD_TEXT,
|
||||
'[CODE]': NodeKinds.CODE_BLOCK,
|
||||
'[/]': NodeKinds.END_SUMMARY,
|
||||
':guilabel:': NodeKinds.GUI_LABEL,
|
||||
'[LIST]': NodeKinds.LIST,
|
||||
'[/LIST]': NodeKinds.END_LIST,
|
||||
':ref:': NodeKinds.REF,
|
||||
'[URL': NodeKinds.URL,
|
||||
'[*]': NodeKinds.LIST_ITEM,
|
||||
'\n\n': NodeKinds.BLANK_LINE
|
||||
'\n\n': NodeKinds.BLANK_LINE,
|
||||
'\\': NodeKinds.CHARACTER
|
||||
}
|
||||
|
||||
def __init__(self):
|
||||
@ -437,8 +521,6 @@ class FFMLProcessor:
|
||||
p = self.input.find(for_what, self.input_pos)
|
||||
if p < 0:
|
||||
return -1
|
||||
while p > 0 and self.input[p-1] == '\\':
|
||||
p = self.input.find(for_what, p+1)
|
||||
return -1 if p < 0 else p - self.input_pos
|
||||
|
||||
def move_pos(self, to_where):
|
||||
@ -486,6 +568,12 @@ class FFMLProcessor:
|
||||
self.move_pos(end + len('[/B]'))
|
||||
return node
|
||||
|
||||
def get_character(self):
|
||||
self.move_pos(1)
|
||||
node = CharacterNode(self.text_to(1))
|
||||
self.move_pos(1)
|
||||
return node
|
||||
|
||||
def get_code_block(self):
|
||||
self.move_pos(len('[CODE]'))
|
||||
if self.text_to(1) == '\n':
|
||||
@ -583,10 +671,15 @@ class FFMLProcessor:
|
||||
self.move_pos(2)
|
||||
elif p == NodeKinds.BOLD_TEXT:
|
||||
parent.add_child(self.get_bold_text())
|
||||
elif p == NodeKinds.CHARACTER:
|
||||
parent.add_child(self.get_character())
|
||||
elif p == NodeKinds.CODE_TEXT:
|
||||
parent.add_child(self.get_code_text())
|
||||
elif p == NodeKinds.CODE_BLOCK:
|
||||
parent.add_child(self.get_code_block())
|
||||
elif p == NodeKinds.END_SUMMARY:
|
||||
parent.add_child(EndSummaryNode())
|
||||
self.move_pos(3)
|
||||
elif p == NodeKinds.GUI_LABEL:
|
||||
parent.add_child(self.get_gui_label())
|
||||
elif p == NodeKinds.ITALIC_TEXT:
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
Loading…
x
Reference in New Issue
Block a user