or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

ast-nodes.mdbuiltin-rules.mdindex.mdlanguage-integration.mdparsing.mdrule-development.md
tile.json

tessl/maven-net-sourceforge-pmd--pmd-vm

PMD language module for static analysis of Apache Velocity Template Language (VTL) files

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/net.sourceforge.pmd/pmd-vm@6.55.x

To install, run

npx @tessl/cli install tessl/maven-net-sourceforge-pmd--pmd-vm@6.55.0

index.mddocs/

PMD Velocity Module

PMD Velocity Module (pmd-vm) is a specialized language module within the PMD static analysis framework that provides comprehensive support for Apache Velocity Template Language (VTL) analysis. It implements a complete parser and rule engine for Velocity templates, enabling developers to apply static analysis rules to template files and identify issues such as unused macro parameters, parameter reassignment violations, excessive template length, inline JavaScript/CSS usage, and other template-specific code quality concerns.

Package Information

  • Package Name: pmd-vm
  • Package Type: Maven module
  • Language: Java (implementation), supports Apache Velocity Template Language (VTL)
  • Installation: Maven dependency net.sourceforge.pmd:pmd-vm:6.55.0
  • License: BSD-style

Core Imports

import net.sourceforge.pmd.lang.vm.VmLanguageModule;
import net.sourceforge.pmd.lang.vm.VmHandler;
import net.sourceforge.pmd.lang.vm.rule.AbstractVmRule;
import net.sourceforge.pmd.lang.vm.ast.VmNode;
import net.sourceforge.pmd.lang.vm.ast.VmParserVisitorAdapter;

Basic Usage

Language Module Registration

// PMD automatically registers language modules via VmLanguageModule
VmLanguageModule vmModule = new VmLanguageModule();
// Module provides NAME="VM" and TERSE_NAME="vm" constants

Creating Custom Rules

import net.sourceforge.pmd.lang.vm.rule.AbstractVmRule;
import net.sourceforge.pmd.lang.vm.ast.ASTReference;
import net.sourceforge.pmd.lang.vm.ast.VmNode;

public class CustomVelocityRule extends AbstractVmRule {
    
    @Override
    public Object visit(ASTReference node, Object data) {
        // Analyze Velocity references ($variable)
        String refName = node.getRootString();
        if (shouldReportViolation(refName)) {
            addViolation(data, node, "Custom rule violation: " + refName);
        }
        return super.visit(node, data);
    }
    
    private boolean shouldReportViolation(String refName) {
        // Custom logic for rule violation detection
        return refName != null && refName.startsWith("temp");
    }
}

AST Traversal and Analysis

import net.sourceforge.pmd.lang.vm.ast.VmParserVisitorAdapter;
import net.sourceforge.pmd.lang.vm.ast.ASTDirective;
import net.sourceforge.pmd.lang.vm.ast.ASTMethod;

public class VelocityAnalyzer extends VmParserVisitorAdapter {
    
    @Override
    public Object visit(ASTDirective node, Object data) {
        // Analyze Velocity directives (#if, #foreach, etc.)
        System.out.println("Found directive at line " + node.getLine());
        return super.visit(node, data);
    }
    
    @Override
    public Object visit(ASTMethod node, Object data) {
        // Analyze method calls in templates
        System.out.println("Found method call");
        return super.visit(node, data);
    }
}

Architecture

PMD Velocity Module is structured around several key components:

  • Language Module System: Integration with PMD's multi-language architecture via VmLanguageModule
  • Parser Framework: JavaCC-generated parser for Velocity syntax with token management
  • AST Node Hierarchy: 40+ specialized node types representing different Velocity constructs
  • Rule Framework: Base classes and visitor patterns for implementing static analysis rules
  • Built-in Rules: Production-ready rules for common Velocity template issues
  • Visitor Pattern: Standardized traversal mechanism for AST analysis

Capabilities

Language Module Integration

Core integration with PMD framework providing language registration, parsing coordination, and rule violation handling.

public class VmLanguageModule extends BaseLanguageModule {
    public static final String NAME = "VM";
    public static final String TERSE_NAME = "vm";
    public VmLanguageModule();
}

public class VmHandler extends AbstractLanguageVersionHandler {
    public RuleViolationFactory getRuleViolationFactory();
    public Parser getParser(ParserOptions parserOptions);
    public VisitorStarter getDumpFacade(Writer writer, String prefix, boolean recurse);
}

Language Module Integration

AST Node Framework

Complete Abstract Syntax Tree representation of Velocity templates with 40+ specialized node types for expressions, directives, references, and control structures.

public interface VmNode extends Node {
    Object jjtAccept(VmParserVisitor visitor, Object data);
    @Deprecated
    Object childrenAccept(VmParserVisitor visitor, Object data);
    VmNode getChild(int index);
    VmNode getParent();
    Iterable<? extends VmNode> children();
}

public class VmParserVisitorAdapter implements VmParserVisitor {
    // Default implementations for all visit methods
    public Object visit(VmNode node, Object data);
    public Object visit(ASTReference node, Object data);
    public Object visit(ASTDirective node, Object data);
    // ... 40+ visit methods
}

AST Node Framework

Rule Development Framework

Base classes and utilities for creating custom static analysis rules for Velocity templates.

public abstract class AbstractVmRule extends AbstractRule 
    implements VmParserVisitor, ImmutableLanguage {
    public void apply(List<? extends Node> nodes, RuleContext ctx);
    protected void visitAll(List<? extends Node> nodes, RuleContext ctx);
    // All VmParserVisitor methods available for override
}

public abstract class AbstractStatisticalVmRule extends AbstractVmRule {
    // Base class for statistical rules (complexity, length, etc.)
}

Rule Development Framework

Built-in Static Analysis Rules

Production-ready rules for detecting common issues in Velocity templates including best practices, design problems, and error-prone patterns.

// Best Practices Rules
public class AvoidReassigningParametersRule extends AbstractVmRule;
public class UnusedMacroParameterRule extends AbstractVmRule;

// Design Rules  
public class ExcessiveTemplateLengthRule extends AbstractStatisticalVmRule;
public class AvoidDeeplyNestedIfStmtsRule extends AbstractStatisticalVmRule;
public class CollapsibleIfStatementsRule extends AbstractVmRule;
public class NoInlineJavaScriptRule extends AbstractVmRule;

// Error-Prone Rules
public class EmptyIfStmtRule extends AbstractVmRule;
public class EmptyForeachStmtRule extends AbstractVmRule;

Built-in Rules

Template Parsing and Token Management

Low-level parsing capabilities for Velocity template syntax with comprehensive error handling.

@Deprecated
@InternalApi
public class VmParser extends AbstractParser {
    public TokenManager createTokenManager(Reader source);
    public Node parse(String fileName, Reader source) throws ParseException;
    public Map<Integer, String> getSuppressMap();
}

@Deprecated  
@InternalApi
public class VmTokenManager implements TokenManager {
    public Token getNextToken();
    public void setFileName(String fileName);
}

Parsing and Token Management

Types

Core Interfaces

public interface VmParserVisitor {
    Object visit(VmNode node, Object data);
    Object visit(ASTReference node, Object data);
    Object visit(ASTDirective node, Object data);
    Object visit(ASTMethod node, Object data);
    Object visit(ASTAddNode node, Object data);
    Object visit(ASTSubtractNode node, Object data);
    Object visit(ASTMulNode node, Object data);
    Object visit(ASTDivNode node, Object data);
    Object visit(ASTModNode node, Object data);
    Object visit(ASTOrNode node, Object data);
    Object visit(ASTAndNode node, Object data);
    Object visit(ASTEQNode node, Object data);
    Object visit(ASTNENode node, Object data);
    Object visit(ASTLTNode node, Object data);
    Object visit(ASTGTNode node, Object data);
    Object visit(ASTLENode node, Object data);
    Object visit(ASTGENode node, Object data);
    Object visit(ASTNotNode node, Object data);
    Object visit(ASTIfStatement node, Object data);
    Object visit(ASTElseStatement node, Object data);
    Object visit(ASTElseIfStatement node, Object data);
    Object visit(ASTForeachStatement node, Object data);
    Object visit(ASTSetDirective node, Object data);
    Object visit(ASTBlock node, Object data);
    Object visit(ASTExpression node, Object data);
    Object visit(ASTAssignment node, Object data);
    Object visit(ASTMap node, Object data);
    Object visit(ASTObjectArray node, Object data);
    Object visit(ASTIntegerRange node, Object data);
    Object visit(ASTIndex node, Object data);
    Object visit(ASTText node, Object data);
    Object visit(ASTTextblock node, Object data);
    Object visit(ASTComment node, Object data);
    Object visit(ASTFloatingPointLiteral node, Object data);
    Object visit(ASTIntegerLiteral node, Object data);
    Object visit(ASTStringLiteral node, Object data);
    Object visit(ASTIdentifier node, Object data);
    Object visit(ASTWord node, Object data);
    Object visit(ASTTrue node, Object data);
    Object visit(ASTFalse node, Object data);
    Object visit(ASTEscape node, Object data);
    Object visit(ASTEscapedDirective node, Object data);
    Object visit(ASTprocess node, Object data);
}

Exception Types

@Deprecated
public class TemplateParseException extends ParseException {
    public TemplateParseException(String message);
    public TemplateParseException(String message, String templateName, int lineNumber, int columnNumber);
    public String getTemplateName();
    public int getLineNumber();
    public int getColumnNumber();
}

public class MacroParseException extends ParseException {
    // Macro-specific parse exceptions
}

public class TokenMgrError {
    // Token manager error handling
}