0
# AST Parsing and Node Types
1

2
Complete Abstract Syntax Tree generation with specialized node types for parsing and representing Visualforce markup structures. This capability provides the foundation for all static analysis of Visualforce files.
3

4
## Capabilities
5

6
### VfParser
7

8
Main parser that converts Visualforce markup into a structured AST for analysis.
9

10
```java { .api }
11
/**
12
 * Parser for the Visualforce language
13
 * Extends JjtreeParserAdapter to create AST from Visualforce markup
14
 */
15
public final class VfParser extends JjtreeParserAdapter<ASTCompilationUnit> {
16
    /**
17
     * Create parser with Visualforce-specific configuration
18
     * @param vfProperties Configuration including Apex and Object directory paths
19
     */
20
    public VfParser(VfLanguageProperties vfProperties);
21
    
22
    /**
23
     * Parse Visualforce content into AST (protected method called by PMD framework)
24
     * @param cs Character stream of Visualforce content
25
     * @param task Parser task context
26
     * @return Root AST node with type information attached
27
     * @throws ParseException if content cannot be parsed
28
     */
29
    protected ASTCompilationUnit parseImpl(CharStream cs, ParserTask task) throws ParseException;
30
}
31
```
32

33
**Usage Example:**
34

35
```java
36
import net.sourceforge.pmd.lang.visualforce.ast.VfParser;
37
import net.sourceforge.pmd.lang.visualforce.VfLanguageProperties;
38

39
// Create parser with properties
40
VfLanguageProperties properties = new VfLanguageProperties();
41
VfParser parser = new VfParser(properties);
42

43
// Parser is typically used by PMD framework, not directly by users
44
// PMD calls parseImpl() internally during analysis
45
```
46

47
### Base AST Interfaces
48

49
Core interfaces that define the structure of Visualforce AST nodes.
50

51
```java { .api }
52
/**
53
 * Base interface for all Visualforce AST nodes
54
 * Extends JjtreeNode to integrate with PMD's AST framework
55
 */
56
public interface VfNode extends JjtreeNode<VfNode> {}
57

58
/**
59
 * Abstract base class for all concrete Visualforce AST nodes
60
 * Provides common functionality and visitor pattern integration
61
 */
62
abstract class AbstractVfNode extends AbstractJjtreeNode<AbstractVfNode, VfNode> implements VfNode {
63
    /**
64
     * Accept a Visualforce-specific visitor for AST traversal
65
     * @param visitor Visitor implementation to accept
66
     * @param data Context data passed through visitation
67
     * @return Result from visitor
68
     */
69
    protected abstract <P, R> R acceptVfVisitor(VfVisitor<? super P, ? extends R> visitor, P data);
70
    
71
    /**
72
     * Get XPath node name for this AST node type
73
     * @return String name used in XPath expressions
74
     */
75
    @Override
76
    public String getXPathNodeName();
77
}
78

79
/**
80
 * Abstract base class for AST nodes that represent data values
81
 * Implements VfTypedNode to provide type analysis capabilities
82
 */
83
abstract class AbstractVFDataNode extends AbstractVfNode implements VfTypedNode {
84
    /**
85
     * Get the resolved data type for this node's value
86
     * @return DataType representing the node's type, or null if no metadata found
87
     */
88
    @Override
89
    public DataType getDataType();
90
    
91
    /**
92
     * Set the data type for this node (used internally by type visitor)
93
     * @param dataType DataType to assign to this node
94
     */
95
    void setDataType(DataType dataType);
96
}
97
```
98

99
### Root AST Node
100

101
The top-level node representing a complete Visualforce file.
102

103
```java { .api }
104
/**
105
 * Root node of the AST representing a complete Visualforce file
106
 * Implements RootNode to serve as the AST entry point
107
 */
108
public final class ASTCompilationUnit extends AbstractVfNode implements RootNode {
109
    /**
110
     * Get AST metadata and parsing information
111
     * @return AstInfo containing task context and root reference
112
     */
113
    @Override
114
    public AstInfo<ASTCompilationUnit> getAstInfo();
115
    
116
    /**
117
     * Internal method to attach parser task information (used by parser)
118
     * @param task Parser task context
119
     * @return This compilation unit with task info attached
120
     */
121
    ASTCompilationUnit makeTaskInfo(ParserTask task);
122
    
123
    /**
124
     * Accept Visualforce visitor
125
     * @param visitor Visitor to accept
126
     * @param data Context data
127
     * @return Visitor result
128
     */
129
    @Override
130
    protected <P, R> R acceptVfVisitor(VfVisitor<? super P, ? extends R> visitor, P data);
131
}
132
```
133

134
### Element Nodes
135

136
AST nodes representing XML/HTML elements and their components in Visualforce markup.
137

138
```java { .api }
139
/**
140
 * Represents XML/HTML elements in Visualforce markup
141
 * Examples: <apex:page>, <c:customComponent>, <div>
142
 */
143
public final class ASTElement extends AbstractVfNode {
144
    /**
145
     * Check if element has namespace prefix (e.g., "apex:" in "apex:page")
146
     * @return true if element name contains namespace prefix
147
     */
148
    public boolean isHasNamespacePrefix();
149
    
150
    /**
151
     * Get the namespace prefix part of element name
152
     * @return String before first colon, or null if no namespace
153
     */
154
    public String getNamespacePrefix();
155
    
156
    /**
157
     * Get the local name part of element (after namespace prefix)
158
     * @return String after first colon, or full name if no namespace
159
     */
160
    public String getLocalName();
161
    
162
    /**
163
     * Get complete element name including namespace
164
     * @return Full element name as it appears in markup
165
     */
166
    public String getName();
167
    
168
    /**
169
     * Check if element is self-closing (e.g., <apex:input />)
170
     * @return true if element uses empty tag syntax
171
     */
172
    public boolean isEmpty();
173
    
174
    /**
175
     * Check if element is unclosed (missing end tag)
176
     * @return true if parser could not find proper closing tag
177
     */
178
    public boolean isUnclosed();
179
}
180

181
/**
182
 * Represents element attributes in Visualforce markup
183
 * Examples: rendered="{!condition}", value="{!account.name}"
184
 */
185
public final class ASTAttribute extends AbstractVfNode {
186
    /**
187
     * Get attribute name
188
     * @return Attribute name string
189
     */
190
    public String getName();
191
}
192

193
/**
194
 * Represents attribute values, including literal values and expressions
195
 */
196
public final class ASTAttributeValue extends AbstractVfNode {
197
    /**
198
     * Get the literal value of the attribute
199
     * @return String value or null for expression values
200
     */
201
    public String getValue();
202
}
203
```
204

205
### Expression Nodes
206

207
AST nodes for Visualforce Expression Language (EL) constructs.
208

209
```java { .api }
210
/**
211
 * Represents Expression Language expressions in Visualforce
212
 * Examples: {!account.name}, {!IF(condition, 'yes', 'no')}
213
 */
214
public final class ASTElExpression extends AbstractVfNode {
215
    /**
216
     * Accept Visualforce visitor
217
     * @param visitor Visitor to accept  
218
     * @param data Context data
219
     * @return Visitor result
220
     */
221
    @Override
222
    protected <P, R> R acceptVfVisitor(VfVisitor<? super P, ? extends R> visitor, P data);
223
}
224

225
/**
226
 * Represents general expressions within EL contexts
227
 * Provides advanced parsing of complex expressions with data node analysis
228
 */
229
public final class ASTExpression extends AbstractVfNode {
230
    /**
231
     * Maps strings from Visualforce page to terminal AST nodes (ASTIdentifier or ASTLiteral)
232
     * that the strings represent. The terminal node represents the type of data displayed.
233
     * 
234
     * Examples:
235
     * - {!MyValue} returns Map<ASTIdentifier, "MyValue">
236
     * - {!MyObject__c.Text__c} returns Map<ASTIdentifier, "MyObject__c.Text__c">
237
     * 
238
     * @return Map of terminal nodes to their string representations
239
     * @throws DataNodeStateException if expression contains unsupported syntax
240
     */
241
    public Map<VfTypedNode, String> getDataNodes() throws DataNodeStateException;
242
    
243
    /**
244
     * Exception thrown when identifiers in expression can't be successfully parsed
245
     * Occurs with unsupported syntax like array notation: MyObject__c['Text__c']
246
     */
247
    public static final class DataNodeStateException extends Exception {}
248
}
249

250
/**
251
 * Represents dot notation expressions for property access
252
 * Examples: account.name, user.profile.name
253
 */
254
public final class ASTDotExpression extends AbstractVfNode {}
255

256
/**
257
 * Represents negation expressions
258
 * Examples: !condition, !account.isActive
259
 */
260
public final class ASTNegationExpression extends AbstractVfNode {}
261

262
/**
263
 * Represents identifiers in expressions
264
 * Examples: account, condition, customObject
265
 * Implements VfTypedNode for type analysis support
266
 */
267
public final class ASTIdentifier extends AbstractVFDataNode {}
268

269
/**
270
 * Represents literal values in expressions
271
 * Examples: 'string literal', 123, true
272
 * Implements VfTypedNode for type analysis support
273
 */
274
public final class ASTLiteral extends AbstractVFDataNode {}
275

276
/**
277
 * Represents function arguments in expressions
278
 * Examples: arguments in IF(condition, 'true', 'false')
279
 */
280
public final class ASTArguments extends AbstractVfNode {}
281
```
282

283
### Content and Text Nodes
284

285
AST nodes for textual content within Visualforce markup.
286

287
```java { .api }
288
/**
289
 * Represents text content within elements
290
 */
291
public final class ASTText extends AbstractVfNode {}
292

293
/**
294
 * Represents CDATA sections in markup
295
 */
296
public final class ASTCData extends AbstractVfNode {}
297

298
/**
299
 * Represents general content within elements (container for text and child elements)
300
 */
301
public final class ASTContent extends AbstractVfNode {}
302

303
/**
304
 * Represents HTML script blocks within Visualforce pages
305
 */
306
public final class ASTHtmlScript extends AbstractVfNode {}
307
```
308

309
### Document Structure Nodes
310

311
AST nodes for document-level constructs.
312

313
```java { .api }
314
/**
315
 * Represents XML declarations at the start of documents
316
 */
317
public final class ASTDeclaration extends AbstractVfNode {}
318

319
/**
320
 * Represents DOCTYPE declarations
321
 */
322
public final class ASTDoctypeDeclaration extends AbstractVfNode {}
323

324
/**
325
 * Represents external ID in DOCTYPE declarations
326
 */
327
public final class ASTDoctypeExternalId extends AbstractVfNode {}
328
```
329

330
**Usage Example:**
331

332
```java
333
import net.sourceforge.pmd.lang.visualforce.ast.*;
334

335
// Example of traversing AST nodes (typically done in rules or visitors)
336
public class ExampleVisitor extends VfVisitorBase<Void, Void> {
337
    @Override
338
    public Void visit(ASTElement element, Void data) {
339
        // Check for specific Visualforce elements
340
        if ("apex:page".equals(element.getName())) {
341
            System.out.println("Found apex:page element");
342
            
343
            if (element.isHasNamespacePrefix()) {
344
                System.out.println("Namespace: " + element.getNamespacePrefix());
345
                System.out.println("Local name: " + element.getLocalName());
346
            }
347
        }
348
        
349
        // Visit child nodes
350
        return super.visit(element, data);
351
    }
352
    
353
    @Override
354
    public Void visit(ASTElExpression expression, Void data) {
355
        System.out.println("Found EL expression");
356
        // Process expression content
357
        return super.visit(expression, data);
358
    }
359
}
360
```
361

362
## Visitor Pattern Integration
363

364
All AST nodes support the visitor pattern through the `VfVisitor` interface, enabling systematic traversal and analysis of the Visualforce AST structure. The visitor pattern is the primary mechanism for implementing PMD rules and other analysis tools.