FLM Fragment: flm.flmfragment

FLM fragment: a compiled piece of FLM-formatted text.

An FLMFragment represents a piece of FLM source text that has been parsed into a node tree. Fragments can be rendered standalone (if parsed with standalone_mode=True) or within a document context for cross-reference resolution, consistent numbering, and footnotes.

Create fragments via make_fragment().

The FLMFragment class

class flm.flmfragment.FLMFragment(flm_text, environment, *, is_block_level=None, resource_info=None, standalone_mode=False, tolerant_parsing=False, what='(unknown)', silent=False, parsing_mode=None, input_lineno_colno_offsets=None, _flm_text_if_loading_nodes=None)

A fragment of FLM-formatted code.

Usually you should avoid manually creating FLMFragment instances. Rather, use the environment objects’s flm.flmenvironment.FLMEnvironment.make_fragment() method.

A FLM fragment is intended to later be inserted in a document so that it can be rendered into the desired output format (HTML, plain text). If the fragment is standalone (standalone_mode=True), then some FLM features are disabled (typically, for instance, cross-references) and the fragment can be rendered directly on its own without inserting it in a document, see render_standalone().

The environment argument should be a FLMEnvironment instance used to parse this fragment.

Parameters:

  • flm_text – The FLM source text to parse, or a pre-parsed LatexNodeList.

  • environment – The FLMEnvironment used to parse this fragment.

  • is_block_level – Whether to parse as block-level (True), inline (False), or auto-detect (None, the default).

  • standalone_mode – If True, disables features that require a document context (e.g., cross-references). Enables the use of render_standalone().

  • what – A short description for error messages (e.g., 'abstract').

The argument resource_info can be set to any custom object that can help locate resources called by FLM text. For instance, a includegraphics{} call might wish to look for graphics in the same filesystem folder as a file that contained the FLM code; the resource_info object can be used to store the filesystem folder of the FLM code forming this fragment.

render(render_context, **kwargs)

Render this fragment within a document render context.

This method is typically called inside the render callback passed to render().

Parameters:

render_context – The FLMRenderContext (typically a FLMDocumentRenderContext).

Returns:

The rendered output string.

render_standalone(fragment_renderer)

Render this fragment in standalone mode (without a document context).

The fragment must have been parsed with standalone_mode=True. Features that require a document context (e.g., cross-references, footnotes) are not available in standalone mode.

Parameters:

fragment_renderer – A FragmentRenderer instance.

Returns:

The rendered output string.

Raises:

ValueError – If the fragment was not parsed in standalone mode.

classmethod parse(flm_text, environment, *, standalone_mode=False, tolerant_parsing=None, is_block_level=None, parsing_mode=None, resource_info=None, what=None, input_lineno_colno_offsets=None)

Parse FLM source text into a walker and node list without creating an FLMFragment instance.

This low-level classmethod creates an FLMLatexWalker via the environment and parses the full input. It is used internally by __init__ and can be called directly when only the raw parse result is needed.

Parameters:

  • flm_text – The FLM source string.

  • environment – The FLMEnvironment.

  • standalone_mode – If True, parse in standalone mode.

  • tolerant_parsing – If True, handle parse errors leniently.

  • is_block_level – Block-level mode (True/False/None).

  • parsing_mode – Optional named parsing mode string.

  • resource_info – Resource locator object.

  • what – Description for error messages.

  • input_lineno_colno_offsets – Line/column offset dictionary.

Returns:

A tuple (latex_walker, nodes) where latex_walker is the FLMLatexWalker instance and nodes is the parsed LatexNodeList.

start_node_visitor(node_visitor)

Start a node visitor traversal on this fragment’s parsed node tree.

Calls node_visitor.start() with the fragment’s root LatexNodeList.

Parameters:

node_visitor – A node visitor object implementing a start(nodes) method.

is_empty()

Return True if the fragment’s source text is empty or whitespace-only.

Return type:

bool

whitespace_stripped()

Return a new FLMFragment with leading and trailing whitespace removed from the source text.

get_first_paragraph()

Returns a new FLMFragment object that contains all material comprising the first paragraph in the present fragment.

truncate_to(chars, min_chars=None, truncation_marker=' …')

Return a new FLMFragment truncated to approximately chars characters.

The truncation is performed at the node level, attempting to break at word boundaries.

Parameters:

  • chars – Target maximum number of characters.

  • min_chars – Minimum number of characters to include even if truncation would otherwise stop earlier.

  • truncation_marker – String appended at the truncation point (default: ' …').

Returns:

A new FLMFragment with truncated content.