Skip to content

Commit 448ff91

Browse files
committed
docs: wrote basic instructions for authoring a rule
1 parent 3b43861 commit 448ff91

File tree

2 files changed

+32
-0
lines changed

2 files changed

+32
-0
lines changed
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
title: Author a Rule
3+
---
4+
5+
[Harper's grammatical rules are many](../rules), but most are relatively easy to understand.
6+
Before we get into how to write a rule, it is important that we get some of the language cleared up.
7+
8+
When we refer to a Harper rule, we are talking about [an implementation of the Linter trait](https://docs.rs/harper-core/latest/harper_core/linting/trait.Linter.html).
9+
As you can see, there is an enormous amount of flexibility in this trait and a wide variety of strategies for querying the provided document.
10+
11+
## Patterns
12+
13+
For new contributors, defining a pattern and [implementing the PatternLinter trait](https://docs.rs/harper-core/latest/harper_core/linting/trait.PatternLinter.html) is the easiest way to get started.
14+
If you like to learn by example, you can make a copy of the `ThatWhich` rule and modify it to look for something else.
15+
Here's the general playbook:
16+
17+
- Start by forking the [Harper monorepo](https://github.com/Automattic/harper/fork) and create a new file under `harper-core/src/linting` called `my_rule.rs`.
18+
- Follow our [guide to get your environment setup.](./environment)
19+
- Copy in a template rule (like from `that_which.rs`).
20+
- Modify the constructor to create a pattern to look for the problematic text you have in mind.
21+
- Export your rule from the `linting module` ([which you can find here](https://github.com/Automattic/harper/blob/master/harper-core/src/linting/mod.rs))
22+
- Add your rule to the `LintGroup` [macro call](https://github.com/Automattic/harper/blob/master/harper-core/src/linting/lint_group.rs), which will aggregate its results with the other linters in Harper.
23+
- Open a PR.
24+
25+
## Querying the Document Directly
26+
27+
If you don't wish to use a Harper [Pattern](https://docs.rs/harper-core/latest/harper_core/patterns/trait.Pattern.html), you may query the `Document` directly.
28+
Make sure you read the [available methods](https://docs.rs/harper-core/latest/harper_core/struct.Document.html) available for `Document`s and for [TokenStrings](https://docs.rs/harper-core/latest/harper_core/struct.Document.html#impl-TokenStringExt-for-Document).

packages/web/vite.config.ts

+4
Original file line numberDiff line numberDiff line change
@@ -112,6 +112,10 @@ export default defineConfig({
112112
{
113113
title: 'Dictionary',
114114
to: '/docs/contributors/dictionary'
115+
},
116+
{
117+
title: 'Author a Rule',
118+
to: '/docs/contributors/author_a_rule'
115119
}
116120
]
117121
},

0 commit comments

Comments
 (0)