pymigaguide

pymigaguide.markdown

pymigaguide.model

GuideMetadata Objects

class GuideMetadata(BaseModel)

database

@DATABASE

author

@AUTHOR

version

@$VER: …

copyright

@(c) …

index_node

@INDEX (global)

help_node

@HELP (global)

font_name

@FONT name size (global)

wordwrap

@WORDWRAP

smartwrap

@SMARTWRAP

tab_width

@TAB n

width_hint

@WIDTH

height_hint

@HEIGHT

onopen_script

@ONOPEN (global)

onclose_script

@ONCLOSE (global)

macros

@MACRO name expansion (global)

NodeAttributes Objects

class NodeAttributes(BaseModel)

title

@TITLE or @NODE “title”

toc

@TOC

next

@NEXT

prev

@PREV

index

@INDEX (node-local)

help

@HELP (node-local)

font_name

@FONT (node-local)

proportional

@PROPORTIONAL

wordwrap

@WORDWRAP

smartwrap

@SMARTWRAP

tab_width

@TAB

onopen_script

@ONOPEN (node-local)

onclose_script

@ONCLOSE (node-local)

keywords

@KEYWORDS

macros

@MACRO (node-local)

embeds

@EMBED path(s)

extras

stash unknowns

GuideNode Objects

class GuideNode(BaseModel)

content

Flattened inline stream

Link Objects

class Link(BaseModel)

target_file

“file.guide” or other file (e.g., image)

target_node

“NODE” or dummy “main” when linking to non-guide

line

optional line number

Action Objects

class Action(BaseModel)

kind

“SYSTEM”, “RX”, “RXS”, “BEEP”, “CLOSE”, “QUIT”

value

command/script, or None for BEEP/CLOSE/QUIT

StyleToggle Objects

class StyleToggle(BaseModel)

style

“bold”, “italic”, “underline”, “code”

ColorChange Objects

class ColorChange(BaseModel)

fg

named color, or “APEN:"

bg

named color, or “BPEN:"

AlignChange Objects

class AlignChange(BaseModel)

align

“left”, “center”, “right”

IndentChange Objects

class IndentChange(BaseModel)

lindent

set left indent (spaces)

pari

set paragraph initial indent

pard

reset paragraph settings

TabsChange Objects

class TabsChange(BaseModel)

tab

literal tab insertion

Break Objects

class Break(BaseModel)

kind

“line” or “paragraph”

UnknownInline Objects

class UnknownInline(BaseModel)

raw

raw command text inside @{ … }

pymigaguide.cli

detect_and_decode

def detect_and_decode(data: bytes) -> tuple[str, str]

Detect encoding with chardet and decode to a Python str (UTF-8 internally). Returns (text, detected_encoding).

pymigaguide.writer.markdown

fence_backticks

def fence_backticks(s: str) -> str

Wrap s in a backtick fence that doesn’t conflict with backticks inside s. Uses inline-style by default (not code blocks).

MarkdownOptions Objects

@dataclass
class MarkdownOptions()

heading_level

heading per node

file_suffix

links to other guides

tab_spaces

how many spaces for @{TAB}

paragraph_blank_lines

blank lines for PAR

line_break

soft line break (we just use newline)

underline_html

use for underline

include_node_title

emit H1/H2… title at top of node

MarkdownRenderer Objects

class MarkdownRenderer()

render_document

def render_document(doc: GuideDocument) -> Dict[str, str]

Returns a dict: { node_name: markdown }

pymigaguide.writer.html

HtmlRenderer Objects

class HtmlRenderer()

render_document

def render_document(doc: GuideDocument) -> Dict[str, str]

Returns a dict: { node_name: html }

pymigaguide.writer.json

dump_json

def dump_json(doc: GuideDocument) -> str

Pydantic v2 uses model_dump_json; v1 uses .json(). Support both without caring which is installed.

pymigaguide.writer.txt

TxtRenderer Objects

class TxtRenderer()

render_document

def render_document(doc: GuideDocument) -> Dict[str, str]

Returns a dict: { node_name: text }

pymigaguide.parser

AmigaGuideParser Objects

class AmigaGuideParser()

Pragmatic AmigaGuide parser:

• Parses global directives, nodes, and inline @{…} commands.
• Preserves unknown inline commands as UnknownInline.
• Does not execute macros; it records global/node macro definitions.

pymigaguide.regex

ESCAPED_AT_RE

\@ => literal @

ESCAPED_BS_RE

\ => literal \

pymigaguide.app

pymigaguide.widgets.flowtext

FlowOptions Objects

@dataclass
class FlowOptions()

word_wrap

AmigaGuide WORDWRAP (soft wrap at width)

smart_wrap

SMARTWRAP (single \n treated as space)

default_tab

@TAB n default

underline_html

honor underline (as underline style)

show_unknown_inline

render unknowns visibly (debug)

LinkActivated Objects

class LinkActivated(Message)

Posted by FlowText when a link is clicked.

FlowText Objects

class FlowText(Widget)

Render AmigaGuide Inline items faithfully enough for TUI:

• Styles: bold/italic/underline
• Colors: FG/BG by name; APEN/BPEN best-effort
• Breaks: LINE, PAR
• Tabs: @{TAB} with default/custom tab stops
• Links: clickable labels (emit LinkActivated)
• Actions: rendered as plain labels (no execution)

Notes:

• Alignment (JLEFT/JCENTER/JRIGHT) is applied per paragraph.
• CODE mode as a strict “no wrap” inline is not supported per-run in Rich; we treat it as a style toggle (monospace effect is up to your theme) and

• TODO - we can segment paragraphs to no-wrap blocks later.

  • SMARTWRAP: single newlines turn into spaces unless an explicit @{LINE} or paragraph boundary is encountered.

pymigaguide.widgets.guidetoolbar

GuideToolbar Objects

class GuideToolbar(Horizontal)

Top navigation bar for AmigaGuide docs.

NavRequested Objects

class NavRequested(Message)

Emitted when a toolbar button requests navigation.

pymigaguide.widgets

pymigaguide.widgets.guideview

GuideView Objects

class GuideView(Container)

High-level viewer: holds a Markdown widget, manages navigation/history, and resolves links between nodes (and across files later).

goto

def goto(file: Optional[str], node: Optional[str],
         line: Optional[int]) -> None

Navigate to (file,node). If file is None or .guide is current, use current doc. node may be a slug; map to actual node name if possible.

on_guide_toolbar_nav_requested

def on_guide_toolbar_nav_requested(message: GuideToolbar.NavRequested) -> None

Handle navigation requests from the toolbar.

on_markdown_link_clicked

def on_markdown_link_clicked(event: Markdown.LinkClicked) -> None

Intercept Markdown links and navigate within guides.