Views
Customize the file-processing pipeline with 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 notype
is provided, the name is used as the only scope for the value. Otherwise, thename
is used as a metascope and will be appended to the active scope – such asheading.<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 aremd
,adoc
,html
,rst
, ororg
.
Here’s an example of a View that extracts the title
and description
fields from an OpenAPI document:
yamlengine: 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[*.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{ "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:
yamlengine: 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# 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:
yamlengine: 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!
On This Page