A builder for creating a Formatter. More...

Public Member Functions
	__init__ (self)
	Initialize the formatter builder.

None	append_line (self, str line)
	Append a line to the format.

None	append_multiline_str (self, str lines)
	Appends a multiline string to the format, preserving the first line's leading whitespaces and remove any common leading whitespaces from subsequent lines.

None	append_str (self, str string)
	Append a string to the format without any post-processing.

ChoiceExtractor	choose (self, *Extractor\|str extractors, str capture_name=None)
	Create a choice extractor.

Extractor	extractor (self, typing.Callable[[str], Extractor] create_extractor)
	Create a custom extractor.

JsonExtractor	json (self, typing.Type[Schema]\|collections.abc.Sequence schema, *, str capture_name=None)
	Create a JSON extractor.

RegexExtractor	regex (self, str regex, *, str capture_name=None)
	Create a regex extractor.

RegexComplementExtractor	regex_complement (self, str regex, *, str capture_name=None)
	Create a regex complement extractor.

Extractor	str (self, *, typing.Union[str, list[str]] stop=None, typing.Optional[str] capture_name=None)
	Create a string extractor.

Extractor	substr (self, str string, *, str capture_name=None, bool extract_empty_substring=False)
	Create a substring extractor.

Formatter	build (self, kbnf.Vocabulary vocabulary, typing.Callable[[list[int]], str] decode, kbnf.Config engine_config=None)
	Build a formatter from the builder.

Protected Member Functions
	_assert_capture_name_valid (self, str capture_name)

str	_create_nonterminal (self, str name)

None	_add_capture_name (self, NonterminalExtractor extractor)

	_add_extractor (self, str extractor_type, typing.Callable[[str], Extractor] create_extractor)

Protected Attributes
	_counter

	_main_rule

	_rules

	_capture_names

	_nonterminal_to_extractor

	_extractors

	_instance_id

Static Protected Attributes
int	_formatter_builder_counter

Detailed Description

A builder for creating a Formatter.

Definition at line 274 of file formatter.py.

Constructor & Destructor Documentation

◆ init()

formatron.formatter.FormatterBuilder.__init__ ( self )

Initialize the formatter builder.

Definition at line 283 of file formatter.py.

Member Function Documentation

◆ _add_capture_name()

None formatron.formatter.FormatterBuilder._add_capture_name	(		self,
		NonterminalExtractor	extractor )

protected

Definition at line 369 of file formatter.py.

◆ _add_extractor()

formatron.formatter.FormatterBuilder._add_extractor	(		self,
		str	extractor_type,
		typing.Callable[[str], Extractor]	create_extractor )

protected

Definition at line 395 of file formatter.py.

◆ _assert_capture_name_valid()

formatron.formatter.FormatterBuilder._assert_capture_name_valid	(		self,
		str	capture_name )

protected

Definition at line 294 of file formatter.py.

◆ _create_nonterminal()

str formatron.formatter.FormatterBuilder._create_nonterminal	(		self,
		str	name )

protected

Definition at line 364 of file formatter.py.

◆ append_line()

None formatron.formatter.FormatterBuilder.append_line	(		self,
		str	line )

Append a line to the format.

Specifically, a newline character is appended to the input.

   Note that if you need a literal `$`, you need to escape it by adding a backslash: `\\$`.

Definition at line 305 of file formatter.py.

◆ append_multiline_str()

None formatron.formatter.FormatterBuilder.append_multiline_str	(		self,
		str	lines )

Appends a multiline string to the format, preserving the first line's leading whitespaces and remove any common leading whitespaces from subsequent lines.

Note that tabs and spaces are both treated as whitespace, but they are not equal: the lines " hello" and "\\thello" are considered to have no common leading whitespace.

Entirely blank lines are normalized to a newline character.

Note that if you need a literal $, you need to escape it by adding a backslash: \\$.

Definition at line 319 of file formatter.py.

◆ append_str()

None formatron.formatter.FormatterBuilder.append_str	(		self,
		str	string )

Append a string to the format without any post-processing.

   Note that if you need a literal `$`, you need to escape it by adding a backslash: `\\$`.

Definition at line 328 of file formatter.py.

◆ build()

Formatter formatron.formatter.FormatterBuilder.build	(		self,
		kbnf.Vocabulary	vocabulary,
		typing.Callable[[list[int]], str]	decode,
		kbnf.Config	engine_config = None )

Build a formatter from the builder.

The builder will not be consumed and can be used again.

Parameters

vocabulary	The KBNF engine vocabulary for the formatter.
decode	The callback to decode the token IDs to a string.
engine_config	The KBNF engine configuration.

Returns: The formatter.

Definition at line 519 of file formatter.py.

◆ choose()

ChoiceExtractor formatron.formatter.FormatterBuilder.choose	(		self,
		*Extractor \| str	extractors,
		str	capture_name = None )

Create a choice extractor.

   Check out the ChoiceExtractor docs for more details.

Parameters

extractors	The extractors to choose from.
capture_name	The capture name of the extractor, or `None` if the extractor does not capture.

Returns: The choice extractor.

Definition at line 385 of file formatter.py.

◆ extractor()

Extractor formatron.formatter.FormatterBuilder.extractor	(		self,
		typing.Callable[[str], Extractor]	create_extractor )

Create a custom extractor.

Parameters

create_extractor callable with signature (extractor_nonterminal: str)->Extractor that create the extractor. extractor_nonterminal is the auto-generated nonterminal reference for the extractor.

Definition at line 411 of file formatter.py.

◆ json()

JsonExtractor formatron.formatter.FormatterBuilder.json	(		self,
		typing.Type[Schema]\|collections.abc.Sequence	schema,
		*	,
		str	capture_name = None )

Create a JSON extractor.

Check out the JsonExtractor docs for more details.

Parameters

schema	The schema for extraction.
capture_name	The capture name of the extractor, or `None` if the extractor does not capture.

Returns: The JSON extractor.

Definition at line 423 of file formatter.py.

◆ regex()

RegexExtractor formatron.formatter.FormatterBuilder.regex	(		self,
		str	regex,
		*	,
		str	capture_name = None )

Create a regex extractor.

   Check out the RegexExtractor docs for more details.

Parameters

regex	The regular expression for extraction.
capture_name	The capture name of the extractor, or `None` if the extractor does not capture.

Returns: The regex extractor.

Definition at line 449 of file formatter.py.

◆ regex_complement()

RegexComplementExtractor formatron.formatter.FormatterBuilder.regex_complement	(		self,
		str	regex,
		*	,
		str	capture_name = None )

Create a regex complement extractor.

This is roughly equivalent to 'extract a string that does not match the given regex anywhere'.

   Check out the RegexComplementExtractor docs for more details.

Parameters

regex	The regular expression for extraction.
capture_name	The capture name of the extractor, or `None` if the extractor does not capture.

Returns: The regex complement extractor.

Definition at line 464 of file formatter.py.

◆ str()

Extractor formatron.formatter.FormatterBuilder.str	(		self,
		*	,
		typing.Union[str, list[str]]	stop = None,
		typing.Optional[str]	capture_name = None )

Create a string extractor.

   The extractor will extract all text until(inclusive) one of the stop strings is encountered.

Parameters

stop	The strings for the extractors to stop at. They will be included in text generation and extraction.
capture_name	The capture name of the extractor, or `None` if the extractor does not capture.

Returns: The string extractor.

Definition at line 479 of file formatter.py.

◆ substr()

Extractor formatron.formatter.FormatterBuilder.substr	(		self,
		str	string,
		*	,
		str	capture_name = None,
		bool	extract_empty_substring = False )

Create a substring extractor.

   The extractor will extract a substring of the input string.

Parameters

string	The string to extract.
capture_name	The capture name of the extractor, or `None` if the extractor does not capture.
extract_empty_substring	Whether to extract an empty substring as a valid substring.

Returns: The substring extractor.

Definition at line 502 of file formatter.py.

Member Data Documentation

◆ _capture_names

formatron.formatter.FormatterBuilder._capture_names

protected

Definition at line 287 of file formatter.py.

◆ _counter

formatron.formatter.FormatterBuilder._counter

protected

Definition at line 284 of file formatter.py.

◆ _extractors

formatron.formatter.FormatterBuilder._extractors

protected

Definition at line 289 of file formatter.py.

◆ _formatter_builder_counter

int formatron.formatter.FormatterBuilder._formatter_builder_counter

staticprotected

Definition at line 278 of file formatter.py.

◆ _instance_id

formatron.formatter.FormatterBuilder._instance_id

protected

Definition at line 290 of file formatter.py.

◆ _main_rule

formatron.formatter.FormatterBuilder._main_rule

protected

Definition at line 285 of file formatter.py.

◆ _nonterminal_to_extractor

formatron.formatter.FormatterBuilder._nonterminal_to_extractor

protected

Definition at line 288 of file formatter.py.

◆ _rules

formatron.formatter.FormatterBuilder._rules

protected

Definition at line 286 of file formatter.py.

The documentation for this class was generated from the following file:

src/formatron/formatter.py

Public Member Functions

Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __init__()

Member Function Documentation

◆ _add_capture_name()

◆ _add_extractor()

◆ _assert_capture_name_valid()

◆ _create_nonterminal()

◆ append_line()

◆ append_multiline_str()

◆ append_str()

◆ build()

◆ choose()

◆ extractor()

◆ json()

◆ regex()

◆ regex_complement()

◆ str()

◆ substr()

Member Data Documentation

◆ _capture_names

◆ _counter

◆ _extractors

◆ _formatter_builder_counter

◆ _instance_id

◆ _main_rule

◆ _nonterminal_to_extractor

◆ _rules

◆ init()