Views

Views represent a virtual, filtered perspective of a structured file. They define a series of transformation steps that extract specific, named scopes, effectively changing how the file is represented for linting purposes. By focusing only on relevant sections, Views let you control exactly what content is analyzed—and enable rules that apply only to specific parts of a file.

Each View is defined in a YAML file and consists of a series of steps that are executed in order. Each step includes the following fields:

• name: The name of the step. If no type is provided, the name is used as the only scope for the value. Otherwise, the name is used as a metascope and will be appended to the active scope – such as heading.<name>.md.
• expr: An expression that selects the data to be linted. The expression is evaluated by the active engine.
• type: The type of the data. Supported types are md, adoc, html, rst, or org.

Here’s an example of a View that extracts the title and description fields from an OpenAPI document:

yaml
Copy
engine: dasel
scopes:
  - name: title
    expr: info.title
    type: md

  - expr: info.description
    type: md

  - expr: servers.all().description
    type: md

Views are stored in <StylesPath>/config/views and can be referenced in the .vale.ini file under any syntax-specific section:

ini
Copy
[*.json]
BasedOnStyles = Vale

View = MyView

Engines

Each step in a View contains a query that is processed by Dasel (JSON, YAML, or TOML), tree-sitter (source code), or TextFSM (text).

Dasel

Dasel is a command-line tool that allows you to query and modify data structures using selectors. It works with JSON, YAML, TOML, XML, and more.

Vale uses Dasel to query structured data in files and extract the relevant content. For example, given the following JSON:

json
Copy
{
	"title": "Vale",
	"version": "3.0.0",
	"features": [
		{
			"title": "Views",
			"description": "Customize the file-processing pipeline with Views."
		},
		{
			"title": "Styles",
			"description": "Define custom linting rules with Styles."
		}
	]
}

You could use the following View to extract the name and description fields from each feature:

yaml
Copy
engine: dasel
scopes:
  # The `name` field is used as the metascope, allowing us to
  # write rules that specifically target the `title` field by
  # using the custom `feature` scope.
  - name: feature
    expr: features.all().title
    type: md

  - expr: features.all().description
    type: md

Check out the playground to experiment with Dasel queries.

Tree-sitter

Tree-sitter is a parser generator tool and an incremental parsing library. It can be used to build parsers for source code in any language.

Vale uses tree-sitter to parse source code and extract structured data. For example, given the following Python code:

python
Copy
# This a comment.
def hello(name: str) -> str:
    """
    This is a docstring.
    """
    return f"Hello, {name}!"

You could use the following View to extract all comments and function docstrings:

yaml
Copy
engine: tree-sitter
scopes:
  - name: comment
    expr: (comment)+ @comment

  - expr: |
      ((function_definition
        body: (block . (expression_statement (string) @docstring)))
      (#offset! @docstring 0 3 0 -3))

See Pattern Matching with Queries for more information.

TextFSM

Coming soon!