README

TextBridge4D

🔄 A powerful text format conversion library for Delphi and Lazarus

Overview • Features • Installation • Quick Start • Formats • Architecture • API • Playground • Extending • FAQ

🇧🇷 Português (Brasil)

📖 Overview

TextBridge4D is a versatile text format conversion library that uses an Abstract Syntax Tree (AST) to seamlessly convert between different markup formats. The AST-based approach ensures accurate and lossless conversions while providing an extensible architecture for adding new formats.

Why TextBridge4D?

• 🌳 AST-Based: Uses a tree structure for accurate format conversion
• 🔌 Plugin Architecture: Easily add new formats without modifying core code
• 🎯 Simple API: One-line conversions with the fluent interface
• 📦 Zero Dependencies: Pure Pascal implementation
• 🔙 Legacy Support: Compatible with Delphi 6+ and Lazarus/FreePascal
• 🎮 Interactive Playground: Full demo application included for testing and visualization

Project Structure

TextBridge4D/
????????? src/                            # Library source code
???   ????????? TextBridge4D.pas            # Main library unit (Core API + AST)
???   ????????? TextBridge4D.Interfaces.pas # Interface definitions
???   ????????? TextBridge4D.Base.pas       # Abstract base classes & utilities
???   ????????? TextBridge4D.Enums.pas      # Enumerations & constants
???   ????????? TextBridge4D.BBCode.pas     # BBCode format implementation
???   ????????? TextBridge4D.HTML.pas       # HTML format implementation
???   ????????? TextBridge4D.Markdown.pas   # Markdown format implementation
???   ????????? TextBridge4D.RichText.pas   # RTF format implementation
???   ????????? TextBridge4D.PlainText.pas  # Plain text format implementation
????????? playground/                     # Demo application
???   ????????? DemoPlayground.dpr          # Project file
???   ????????? uMain.pas                   # Main form with interactive conversion
????????? README.md                       # English documentation
????????? README.pt-BR.md                 # Portuguese documentation

✨ Features

📦 Installation

Manual Installation

1. Clone or download this repository:

git clone https://github.com/weslleycapelari/TextBridge4D.git

2. Add the src folder to your project's search path:
   • Delphi: Project → Options → Delphi Compiler → Search Path
   • Lazarus: Project → Project Options → Compiler Options → Paths → Other unit files
3. Add the desired units to your uses clause:

uses
  TextBridge4D,           // Main library (required)
  TextBridge4D.BBCode,    // BBCode support
  TextBridge4D.HTML,      // HTML support
  TextBridge4D.Markdown,  // Markdown support
  TextBridge4D.RichText,  // RTF support
  TextBridge4D.PlainText; // Plain text support

Boss (Delphi Package Manager)

boss install github.com/weslleycapelari/TextBridge4D

🚀 Quick Start

Basic Conversion

The simplest way to convert text between formats:

uses
  TextBridge4D, TextBridge4D.BBCode, TextBridge4D.HTML;

var
  LResult: String;
begin
  // Convert BBCode to HTML
  LResult := TTextBridge4D.Convert('[b]Hello[/b] [i]World[/i]', ttBBCode, ttHTML);
  // Result: <strong>Hello</strong> <em>World</em>
  
  // Convert Markdown to BBCode
  LResult := TTextBridge4D.Convert('**Bold** and _Italic_', ttMarkdown, ttBBCode);
  // Result: [b]Bold[/b] and [i]Italic[/i]
end;

Fluent Interface

For more control, use the fluent interface:

var
  LBridge: TTextBridge4D;
  LResult: String;
begin
  LBridge := TTextBridge4D.New
    .Parse('[b]Welcome[/b] to [color=red]TextBridge4D[/color]', ttBBCode);
  
  LResult := LBridge.Render(ttHTML);
  // Result: <strong>Welcome</strong> to <span style="color:red;">TextBridge4D</span>
  
  LResult := LBridge.Render(ttMarkdown);
  // Result: **Welcome** to TextBridge4D
  
  LBridge.Free;
end;

Building Documents Programmatically

Create formatted documents using the AST directly:

var
  LDoc: TTextBridge4D;
  LParagraph: TTextBridge4D;
  LResult: String;
begin
  LDoc := TTextBridge4D.New;
  try
    // Add a paragraph with formatted text
    LParagraph := LDoc.AddChild(ntParagraph);
    LParagraph.AddChild(ntBold).AddChild(ntText, 'Important: ');
    LParagraph.AddChild(ntText, 'This is a ');
    LParagraph.AddChild(ntItalic).AddChild(ntText, 'demonstration');
    
    // Add a link
    with LDoc.AddChild(ntLink) do
    begin
      SetAttribute('href', 'https://github.com');
      AddChild(ntText, 'Visit GitHub');
    end;
    
    // Render to different formats
    LResult := LDoc.Render(ttHTML);
    // <p><strong>Important: </strong>This is a <em>demonstration</em></p>
    // <a href="https://github.com">Visit GitHub</a>
    
  finally
    LDoc.Free;
  end;
end;

📄 Supported Formats

BBCode

Forum-style markup language using square brackets.

HTML

Standard web markup language.

text

through

text

| | List |<ul><li>item</li></ul>or<ol><li>item</li></ol>` |

Markdown

Lightweight markup language for plain text formatting.

Rich Text Format (RTF)

Document format used by word processors.

⚠️ Note: RTF parsing is limited. The current implementation returns raw text. Full RTF parsing requires a complete state machine and may be added in future versions.

Plain Text

Extracts text content without any formatting.

🏗️ Architecture & Design

Core Components

1. AST (Abstract Syntax Tree)
   • Central data structure for all conversions
   • Each node (TTextBridge4D) represents a document element
   • Supports hierarchical nesting of elements
   • Type-safe node list (TBNodeList) with automatic memory management
2. Interface-Based Format System
   • All formatters implement ITextBridgeFormat interface
   • Formatters registered at initialization via RegisterFormat
   • Dynamic format lookup using GetFormat(TBTextType)
   • Thread-safe registration mechanism
3. Two-Phase Conversion
   • Phase 1 (Parse): Format A → AST
   • Phase 2 (Render): AST → Format B
   • AST can be rendered to multiple formats without re-parsing
   • Enables format-agnostic processing of documents

Design Patterns Used

• Abstract Factory: Format registration and creation
• Template Method: TTextBridgeFormatBase defines parsing/rendering structure
• Facade: TTextBridge4D provides simple interface to complex system
• Composite: AST nodes form tree structure
• Strategy: Different formatters implement same interface

Compatibility Features

• Delphi 6+ Support: No modern features required
• Lazarus/FreePascal: Full compatibility with FPC mode
• No Dependencies: Pure RTL implementation
• Memory Safe: Automatic cleanup via TObjectList ownership
• String Builder: Custom implementation for older Delphi versions

Performance Characteristics

• Parsing: O(n) where n = input length
• Rendering: O(m) where m = AST node count
• Memory: O(m) for AST storage
• Reusability: Parse once, render multiple times

📚 API Reference

TTextBridge4D (Main Class)

Class Methods

Instance Methods

Properties

TBNodeType (Node Types)

TBNodeType = (
  ntRoot,           // Document root
  ntText,           // Plain text content
  ntParagraph,      // Paragraph block
  ntBold,           // Bold formatting
  ntItalic,         // Italic formatting
  ntUnderline,      // Underline formatting
  ntStrike,         // Strikethrough
  ntLink,           // Hyperlink (href attribute)
  ntImage,          // Image (src, alt attributes)
  ntColor,          // Text color (color attribute)
  ntSize,           // Font size (size attribute)
  ntFont,           // Font family (face attribute)
  ntList,           // List container (ordered attribute)
  ntListItem,       // List item
  ntCode,           // Code block
  ntQuote,          // Block quote
  ntHeader,         // Header (level attribute: 1-6)
  ntLineBreak,      // Line break
  ntHorizontalRule  // Horizontal line
);

TBTextType (Format Types)

TBTextType = (
  ttUnknown,    // Unknown format
  ttBBCode,     // BBCode format
  ttHTML,       // HTML format
  ttMarkdown,   // Markdown format
  ttRichText,   // RTF format
  ttPlainText   // Plain text
);

🔧 Extending TextBridge4D

Creating a Custom Format Handler

To add support for a new format, create a class that inherits from TTextBridgeFormatBase:

unit TextBridge4D.CustomFormat;

interface

uses
  TextBridge4D.Enums,
  TextBridge4D.Interfaces,
  TextBridge4D,
  TextBridge4D.Base;

type
  TTextBridgeCustomFormat = class(TTextBridgeFormatBase)
  protected
    function DoParse(const AText: String): TTextBridge4D; override;
    function DoRender(ARoot: TTextBridge4D): String; override;
  public
    function GetFormatType: TBTextType; override;
    function GetFormatName: String; override;
  end;

implementation

function TTextBridgeCustomFormat.GetFormatType: TBTextType;
begin
  Result := ttCustom; // Add to TBTextType enum
end;

function TTextBridgeCustomFormat.GetFormatName: String;
begin
  Result := 'Custom';
end;

function TTextBridgeCustomFormat.DoParse(const AText: String): TTextBridge4D;
begin
  Result := TTextBridge4D.New;
  // Implement parsing logic
  // Build AST from input text
end;

function TTextBridgeCustomFormat.DoRender(ARoot: TTextBridge4D): String;
begin
  // Implement rendering logic
  // Traverse AST and generate output
end;

initialization
  TTextBridge4D.RegisterFormat(TTextBridgeCustomFormat.Create);

end.

Tips for Implementation

1. Parsing: Build the AST by creating nodes for each formatting element
2. Rendering: Traverse the AST recursively, outputting the appropriate syntax
3. Attributes: Use SetAttribute/HasAttribute for element properties
4. Self-Closing: Handle elements like images and line breaks specially

🎮 Demo Application (Playground)

The project includes a complete interactive demonstration application located in the playground folder. This application allows you to:

Features

• Real-time Conversion: Convert text between any supported formats instantly
• AST Visualization: View the generated Abstract Syntax Tree structure
• Multiple Output Views:
  • Raw code output
  • Rich text preview (for RTF)
  • HTML preview in browser
  • AST tree structure
• Performance Metrics: See parsing time, rendering time, and conversion speed
• Example Templates: Pre-loaded examples for testing different features
• Auto-convert: Optional automatic conversion as you type
• Format Swapping: Quickly swap input and output formats

Running the Playground

1. Open playground/DemoPlayground.dpr in Delphi
2. Compile and run the application
3. Select input and output formats
4. Type or paste text in the input area
5. Click "Convert" or enable auto-convert
6. View results in different tabs

Using the Playground for Testing

The playground is an invaluable tool for:

• Testing new format implementations
• Debugging parser issues by viewing the AST
• Understanding how different formats are converted
• Measuring performance with different document sizes
• Creating examples for documentation

🧪 Examples

Convert Forum Post to Email (BBCode → HTML)

var
  LPost: String;
  LEmail: String;
begin
  LPost := '[b]Announcement[/b]'#13#10 +
           'Please check the [url=https://example.com]new features[/url].'#13#10 +
           '[quote]This is amazing![/quote]';
           
  LEmail := TTextBridge4D.Convert(LPost, ttBBCode, ttHTML);
end;

Convert README to Forum (Markdown → BBCode)

var
  LReadme: String;
  LForum: String;
begin
  LReadme := '# Project Title'#13#10 +
             '**Features:**'#13#10 +
             '- Feature 1'#13#10 +
             '- Feature 2';
             
  LForum := TTextBridge4D.Convert(LReadme, ttMarkdown, ttBBCode);
end;

Extract Plain Text for Search Index

var
  LHtml: String;
  LSearchText: String;
begin
  LHtml := '<h1>Welcome</h1><p>This is <strong>important</strong> content.</p>';
  
  LSearchText := TTextBridge4D.Convert(LHtml, ttHTML, ttPlainText);
  // Result: Welcome This is important content.
end;

❓ FAQ (Frequently Asked Questions)

Q: Can I convert directly from BBCode to HTML without understanding AST?

A: Yes! Simply use TTextBridge4D.Convert('[b]text[/b]', ttBBCode, ttHTML). The AST is handled internally.

Q: Is TextBridge4D thread-safe?

A: Format registration is thread-safe, but AST instances should not be shared between threads. Create separate instances per thread.

Q: Can I extend TextBridge4D with custom formats?

A: Absolutely! Create a class inheriting from TTextBridgeFormatBase, implement the required methods, and register it with RegisterFormat.

Q: Why doesn't RTF parsing work fully?

A: Full RTF parsing requires a complex state machine. The current implementation extracts text content. Full support is planned for future versions.

Q: How do I handle errors during conversion?

A: Wrap conversion calls in try-except blocks and catch ETextBridgeParseError for parsing errors and ETextBridgeRenderError for rendering errors.

Q: Can I preserve custom attributes when converting?

A: Yes, custom attributes are preserved in the AST. However, they may be lost when rendering to formats that don't support them.

Q: Does TextBridge4D support Unicode?

A: Yes, full Unicode support is available. All string handling uses Delphi's native string type.

Q: How do I contribute to the project?

A: Fork the repository, make your changes following the coding standards, and submit a pull request. See the Contributing section for details.

�️ Roadmap

Planned features for future releases:

• Full RTF Parsing: Complete RTF document parser with state machine
• Extended Markdown: GitHub-flavored Markdown support (tables, task lists)
• XML/DOCX Support: Microsoft Word document format
• LaTeX Output: Mathematical and scientific document support
• Streaming Parser: Handle large documents with limited memory
• Validation Framework: Configurable validation rules for AST
• CSS Styling: Advanced HTML styling support
• Performance Optimizations: Faster parsing for large documents
• Unit Tests: Comprehensive test coverage
• CI/CD Integration: Automated testing and release pipeline

�💡 Use Cases

TextBridge4D is perfect for:

• Forum Systems: Convert between BBCode (for storage) and HTML (for display)
• Content Management: Store content in one format, display in multiple formats
• Documentation Tools: Convert Markdown documentation to HTML or RTF
• Email Systems: Convert rich forum posts or HTML to plain text
• Text Editors: Allow users to import/export content in different formats
• Search Indexing: Extract plain text from formatted documents
• Cross-Platform Content: Share formatted content between different systems
• API Responses: Convert stored markup to client's preferred format

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For detailed guidelines, see CONTRIBUTING.md.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Coding Standards

• Use English for all documentation and comments
• Follow naming conventions (see CONTRIBUTING.md for details)
• Target Delphi 6+ compatibility
• Include comprehensive documentation
• Test with the playground application

For more information, see our Contributing Guide.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

📌 Version History

For a complete list of changes and version history, see CHANGELOG.md.

Version 2.1.0 (2026-01-14) - CRITICAL BUG FIXES

• CRITICAL: Fixed memory corruption in AddChild method when moving nodes between parents
• CRITICAL: Fixed HTML parser failure with '>' character inside quoted attributes
• Added ExtractChild method for safe node removal without destruction
• Added FindTagClose function with quote-aware state machine for HTML parsing
• Improved ExtractAttribute to validate whole words and handle spaces/entities
• Added Sniff method for auto-detection of text formats with confidence scoring
• Added DetectFormat class method for automatic format detection
• All formatters now support format auto-detection (BBCode, HTML, Markdown, RTF, PlainText)

Version 2.0.0 (2026-01-14)

• Complete refactoring with improved English documentation
• Enhanced naming conventions following best practices
• Added comprehensive XML documentation comments
• Improved Delphi 6+ and Lazarus/FreePascal compatibility
• Added interactive playground application with AST visualization
• Added HTML format support with full parsing capabilities
• Performance improvements and better error handling
• Complete test suite with example templates

Version 1.0.0 (2026-01-01)

• Initial release
• Core AST-based conversion engine
• BBCode, Markdown, RTF, and PlainText support
• Basic HTML rendering (parse-only)
• Interface-based format registration system

�👤 Author

Weslley Capelari

• GitHub: @weslleycapelari

🙏 Acknowledgments

• Inspired by the need for cross-format text conversion in Delphi applications
• Thanks to the Delphi and Lazarus communities

Made with ❤️ for the Delphi community