0
# Debugging and Utilities
1

2
Utility functions for debugging, AST inspection, and format conversion. These tools help with development, testing, and understanding the structure of parsed documents.
3

4
## Capabilities
5

6
### AST Export Functions
7

8
Functions for converting AST nodes to different representations for debugging and serialization purposes.
9

10
```python { .api }
11
def dumpAST(obj, ind=0, topnode=False):
12
    """
13
    Print a pretty-printed representation of an AST to console.
14
    
15
    Args:
16
        obj (Node): AST node to print
17
        ind (int): Current indentation level (used internally for recursion)
18
        topnode (bool): Whether this is the top-level node (used internally)
19
    
20
    Returns:
21
        None: Prints directly to console
22
    """
23

24
def dumpJSON(obj):
25
    """
26
    Convert an AST to JSON string representation.
27
    
28
    Args:
29
        obj (Node): AST node to convert
30
        
31
    Returns:
32
        str: JSON representation of the AST
33
    """
34
```
35

36
### Node Utility Functions
37

38
Helper functions for working with AST nodes and determining their properties.
39

40
```python { .api }
41
def is_container(node):
42
    """
43
    Check if a node type can contain child nodes.
44
    
45
    Args:
46
        node (Node): Node to check
47
        
48
    Returns:
49
        bool: True if the node can have children, False otherwise
50
    """
51
```
52

53
## Usage Examples
54

55
### Pretty-Print AST Structure
56

57
```python
58
from commonmark import Parser, dumpAST
59

60
parser = Parser()
61
markdown = """
62
# Title
63

64
Some text with **bold** and *italic* formatting.
65

66
- List item 1
67
- List item 2
68
"""
69

70
ast = parser.parse(markdown)
71
dumpAST(ast)
72
# Output: Hierarchical representation of the AST structure
73
```
74

75
### JSON Serialization
76

77
```python
78
from commonmark import Parser, dumpJSON
79
import json
80

81
parser = Parser()
82
markdown = "# Hello\n*World*"
83
ast = parser.parse(markdown)
84

85
json_string = dumpJSON(ast)
86
print(json_string)
87

88
# Parse back to Python dict for manipulation
89
ast_dict = json.loads(json_string)
90
print(f"Root node type: {ast_dict[0]['type']}")
91
```
92

93
### Node Type Checking
94

95
```python
96
from commonmark import Parser
97
from commonmark.node import is_container
98

99
parser = Parser()
100
ast = parser.parse("# Title\n\nParagraph text")
101

102
# Walk through nodes and check if they can contain children
103
walker = ast.walker()
104
event = walker.nxt()
105
while event:
106
    node, entering = event['node'], event['entering']
107
    if entering:
108
        can_contain = is_container(node)
109
        print(f"{node.t}: {'container' if can_contain else 'leaf'}")
110
    event = walker.nxt()
111
```
112

113
### Debugging Complex Documents
114

115
```python
116
from commonmark import Parser, dumpAST, dumpJSON
117

118
parser = Parser()
119
complex_markdown = """
120
# Main Title
121

122
## Subsection
123

124
Here's a paragraph with **bold**, *italic*, and `code` text.
125

126
```python
127
def hello():
128
    print("Hello, world!")
129
```
130

131
- List item with [link](http://example.com)
132
- Another item
133

134
> This is a blockquote
135
> with multiple lines.
136
"""
137

138
ast = parser.parse(complex_markdown)
139

140
print("=== AST Structure ===")
141
dumpAST(ast)
142

143
print("\n=== JSON Representation ===")
144
json_repr = dumpJSON(ast)
145
print(json_repr[:200] + "..." if len(json_repr) > 200 else json_repr)
146
```
147
148
### Analyzing Node Properties
149

150
```python
151
from commonmark import Parser
152
from commonmark.node import is_container
153

154
parser = Parser()
155
ast = parser.parse("""
156
# Title
157

158
Paragraph with **bold** text.
159

160
- Item 1
161
- Item 2
162
""")
163

164
def analyze_node(node, depth=0):
165
    indent = "  " * depth
166
    print(f"{indent}{node.t}")
167
    
168
    if hasattr(node, 'literal') and node.literal:
169
        print(f"{indent}  literal: '{node.literal}'")
170
    
171
    if is_container(node):
172
        print(f"{indent}  (container)")
173
        child = node.first_child
174
        while child:
175
            analyze_node(child, depth + 1)
176
            child = child.nxt
177
    else:
178
        print(f"{indent}  (leaf)")
179

180
analyze_node(ast)
181
```
182

183
## Common Node Types
184

185
When debugging AST structures, you'll encounter these common node types:
186

187
- `document`: Root node of the document
188
- `paragraph`: Paragraph block
189
- `heading`: Header (h1-h6)
190
- `text`: Plain text content
191
- `strong`: Bold text
192
- `emph`: Italic text
193
- `code`: Inline code
194
- `code_block`: Code block
195
- `list`: Ordered or unordered list
196
- `item`: List item
197
- `link`: Hyperlink
198
- `image`: Image
199
- `block_quote`: Blockquote
200
- `thematic_break`: Horizontal rule
201
- `html_inline`: Inline HTML
202
- `html_block`: Block-level HTML