Issue Matchers

Within the JSON manifest of an extension, a issueMatchers top-level key can be used to define issue matchers. The value is an object which defined key-value pairs following the following format:

"issueMatchers": {
    "my-issue-matcher": {
        "pattern": {
            "regexp": "^(?:PHP\\s+)?Parse error:\\s+(.+?)\\s+\\(([a-zA-Z0-9-_]+)\\) in ([^:]+?) on line (\\d+)$",
            "message": 1,
            "code": 2,
            "file": 3,
            "line": 4,
            "severity": "error"
        }
    }
}

Each issue matcher object is keyed with an identifier (in this case, my-issue-matcher) which is used with the IssueParser constructor API. This value must be unique within a single extension.

In this way, the JSON representation of a matcher defines everything needed to wrap issue detection up into an easily readable format.

Issue Matcher definitions

Keys within this object are:

• "pattern": defines one or more objects that are used as pattern matchers (regular expressions)
  • If one object is provided, it is the sole pattern used
  • If an array object is provided, each pattern will be matched successively (if the first fails, it matcher will stop). This allows matching more complex, multi-line output.
• "linesStartAt1": whether line numbers captured by the matcher are 1-indexed (true by default). If false, then line numbers will be assumed to be zero-indexed and are automatically incremented for display.
• "columnsStartAt1": whether column numbers captured by the matcher are 1-indexed (true by default). If false, then line numbers will be assumed to be zero-indexed and are automatically incremented for display.

Pattern definitions

An issue matcher definition may have one or more patterns.

Each pattern is defined as an object containing a regular expression (regexp) and a set of keys that map to the regex capture it represents. Keys are then defined for each “important” piece of the parsed text that is used of building issues.

• "regexp": a regular expression string defining captures for parsing
• "message": a capture number for the user-readable message that should be displayed to the user
• "line": a capture number for the line number where the issue begins
• "column": a capture number for the column number where the issue begins (optional)
• "endLine": a capture number for the line number where the issue begins (optional)
• "endColumn": a capture number for the column number where the issue begins (optional)
• "code": a capture number for the issue code, which may be a string or integer and is implementation dependent (such as T_PHP_PARSE_ERROR) (optional)
• "severity": the severity of the issue.
  • If provided with an capture number, the parser will search for case-insensitive combinations of the following strings: “warn”, “warning”, “err”, “error”
  • If provided with a string (“warning” or “error”), that severity will always be used for this matcher
  • If not provided, “warning” will be assumed
• "loop": whether the pattern should be “looped”, matching successive lines of output until the pattern no longer matches. This allows patterns to match output for a single issue that spans multiple lines.