Skip to content

Processor API Reference

The TextProcessor class is the core engine of gtext.

TextProcessor

gtext.processor.TextProcessor 

TextProcessor(extensions: Optional[List[BaseExtension]] = None)

Main processor for transforming text files with extensions.

The TextProcessor reads .gtext files, applies registered extensions, and outputs the transformed content.

Parameters:

Name Type Description Default
extensions Optional[List[BaseExtension]]

List of extension instances to use. If None, uses default extensions.

 None
Example

processor = TextProcessor() result = processor.process_file("document.md.gtext") print(result)

Initialize the processor with extensions.

Source code in gtext/processor.py 
26
27
28
29
30
31
32
def __init__(self, extensions: Optional[List[BaseExtension]] = None):
    """Initialize the processor with extensions."""
    if extensions is None:
        # Default extensions
        self.extensions = [IncludeExtension()]
    else:
        self.extensions = extensions

add_extension 

add_extension(extension: BaseExtension) -> None

Add an extension to the processor.

Parameters:

Name Type Description Default
extension BaseExtension

Extension instance to add

 required
Source code in gtext/processor.py 
105
106
107
108
109
110
111
def add_extension(self, extension: BaseExtension) -> None:
    """Add an extension to the processor.

    Args:
        extension: Extension instance to add
    """
    self.extensions.append(extension)

process_file 

process_file(input_path: str | Path, output_path: Optional[str | Path] = None) -> str

Process a .gtext file and optionally write output.

Parameters:

Name Type Description Default
input_path str | Path

Path to the .gtext source file

 required
output_path Optional[str | Path]

Optional output path. If None and input ends with .gtext, auto-detects output by stripping .gtext extension.

 None

Returns:

Type Description
str

The processed content as a string

Raises:

Type Description
FileNotFoundError

If input file doesn't exist
Source code in gtext/processor.py 
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
def process_file(self, input_path: str | Path, output_path: Optional[str | Path] = None) -> str:
    """Process a .gtext file and optionally write output.

    Args:
        input_path: Path to the .gtext source file
        output_path: Optional output path. If None and input ends with .gtext,
                    auto-detects output by stripping .gtext extension.

    Returns:
        The processed content as a string

    Raises:
        FileNotFoundError: If input file doesn't exist
    """
    input_path = Path(input_path)

    if not input_path.exists():
        raise FileNotFoundError(f"Input file not found: {input_path}")

    # Read source content
    content = input_path.read_text(encoding="utf-8")

    # Process with extensions
    processed = self.process_string(content, context={"input_path": input_path})

    # Write output if requested
    if output_path:
        output_path = Path(output_path)
        output_path.write_text(processed, encoding="utf-8")
    elif str(input_path).endswith(".gtext"):
        # Auto-detect output path
        output_path = Path(str(input_path)[:-6])  # Strip .gtext
        output_path.write_text(processed, encoding="utf-8")

    return processed

process_string 

process_string(content: str, context: Optional[Dict] = None) -> str

Process a string with all registered extensions.

Parameters:

Name Type Description Default
content str

The text content to process

 required
context Optional[Dict]

Optional context dict passed to extensions

 None

Returns:

Type Description
str

The processed content
Source code in gtext/processor.py 
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
def process_string(self, content: str, context: Optional[Dict] = None) -> str:
    """Process a string with all registered extensions.

    Args:
        content: The text content to process
        context: Optional context dict passed to extensions

    Returns:
        The processed content
    """
    if context is None:
        context = {}

    # Remove gtext metadata comments before processing
    content = self._remove_metadata_comments(content)

    result = content
    for extension in self.extensions:
        result = extension.process(result, context)

    return result

Usage Examples

Basic Usage

from gtext import TextProcessor

processor = TextProcessor()
result = processor.process_file("document.md.gtext")

Custom Extensions

from gtext import TextProcessor
from gtext.extensions import IncludeExtension

processor = TextProcessor(extensions=[
    IncludeExtension(),
    # Add custom extensions
])

Process String

from gtext import TextProcessor

processor = TextProcessor()
content = "# Hello World"
result = processor.process_string(content)

With Context

from pathlib import Path
from gtext import TextProcessor

processor = TextProcessor()
context = {"input_path": Path("source.gtext")}
result = processor.process_string(content, context=context)

Add Extension Dynamically

from gtext import TextProcessor
from my_extension import MyExtension

processor = TextProcessor()
processor.add_extension(MyExtension())
result = processor.process_file("document.gtext")