all2md.parsers.bbcode

BBCode to AST converter.

This module provides conversion from BBCode (Bulletin Board Code) markup to AST representation. It enables parsing legacy bulletin board and forum content into the unified all2md AST structure for archival and conversion purposes.

BBCode is a lightweight markup language used by many bulletin board systems and forums in the early web. This parser supports comprehensive BBCode tags including vendor-specific extensions commonly found in popular forum software.

class all2md.parsers.bbcode.BBCodeTag

Bases: object

Represents a parsed BBCode tag.

Parameters:

  • name (str) – Tag name (e.g., ‘b’, ‘url’, ‘quote’)

  • is_closing (bool) – Whether this is a closing tag

  • value (str or None) – Tag attribute value (e.g., URL in [url=http://example.com])

  • position (int) – Character position in source text

name: str
is_closing: bool
value: str | None
position: int
__init__(name: str, is_closing: bool, value: str | None, position: int) → None
class all2md.parsers.bbcode.BBCodeParser

Bases: BaseParser

Convert BBCode markup to AST representation.

This parser handles comprehensive BBCode tags including core formatting, links, images, lists, tables, quotes, code blocks, and vendor-specific extensions commonly found in bulletin board systems.

Supported BBCode tags include: - Formatting: [b], [i], [u], [s], [sup], [sub] - Links: [url], [url=…], [email], [email=…] - Images: [img], [img=WIDTHxHEIGHT] - Quotes: [quote], [quote=author] - Code: [code], [code=language] - Lists: [list], [list=1], [*] - Tables: [table], [tr], [td], [th] - Styling: [color=…], [size=…], [font=…] - Alignment: [center], [left], [right] - Media: [youtube], [video] - Special: [spoiler], [hr]

Parameters:

  • options (BBCodeParserOptions or None, default = None) – Parser configuration options

  • progress_callback (ProgressCallback or None, default = None) – Optional callback for progress updates

Examples

Basic parsing:

>>> parser = BBCodeParser()
>>> doc = parser.parse("[b]Bold[/b] and [i]italic[/i] text")

With options:

>>> options = BBCodeParserOptions(strict_mode=True)
>>> parser = BBCodeParser(options)
>>> doc = parser.parse(bbcode_text)

Initialize the BBCode parser with options and progress callback.

TAG_PATTERN = re.compile('\\[(/?)(\\w+)(?:=([^\\]]+))?\\]', re.IGNORECASE)
BLOCK_TAGS = {'center', 'code', 'hr', 'left', 'list', 'quote', 'right', 'spoiler', 'table', 'video', 'youtube'}
HEADING_TAGS = {'h1', 'h2', 'h3', 'h4', 'h5', 'h6'}
SELF_CLOSING_TAGS = {'*', 'br', 'hr'}
__init__(options: BBCodeParserOptions | None = None, progress_callback: Callable[[ProgressEvent], None] | None = None)

Initialize the BBCode parser with options and progress callback.

options: BBCodeParserOptions
parse(input_data: str | Path | IO[bytes] | bytes) → Document

Parse BBCode input into AST Document.

Parameters:

input_data (str, Path, IO[bytes], or bytes) – BBCode input to parse. Can be: - File path (str or Path) - File-like object in binary mode - Raw BBCode bytes - BBCode string

Returns:

AST document node

Return type:

Document

Raises:

ParsingError – If parsing fails in strict mode

extract_metadata(document: Any) → DocumentMetadata

Extract metadata from BBCode document.

BBCode doesn’t have standard metadata fields, but we can try to extract basic information like title from the first heading if present.

Parameters:

document (Any) – Document content (BBCode string)

Returns:

Extracted metadata

Return type:

DocumentMetadata