Writing a Grammatical Rule for Harper

Harper is a gram­mar checker that re­lies on con­crete, leg­i­ble gram­mat­i­cal rules. In do­ing so, we make Harper’s in­ner-work­ings fun­da­men­tally clear, which al­lows us to guar­an­tee pri­vacy, speed, and most im­por­tantly re­main im­par­tial.

Writing ad­di­tional rules is one of the best (and eas­i­est) ways you can con­tribute to the open source pro­ject. Sim­ple rules take just a few min­utes and of­ten don’t re­quire any un­der­stand­ing of Rust at all—a fact I only cite be­cause it is a com­mon point of con­cern.

Instead of throw­ing a wall of text in your face, I’m break­ing this “guide” of sorts into three sim­ple sec­tions. You don’t need to read all three—in fact, I would rec­om­mend against it.

The only thing you need from here is an idea of the gram­mat­i­cal rule you want to add to Harper. Don’t have one in mind? Visit our is­sue board to find a po­ten­tial rule that piques your in­ter­est.

The three paths:

1. A “phrase cor­rec­tion”. These are for the sim­plest gram­mat­i­cal rules. Use one of these in cases where se­man­tic mean­ing and con­text aren’t im­por­tant.
2. An ExprLinter. These are for more com­plex rules. Use one of these in cases where se­man­tic mean­ing or con­text are im­por­tant, and you don’t need ac­cess to in­for­ma­tion wider than clause-level. Takes a lit­tle bit to learn, but are ex­tremely pow­er­ful.
3. A plain Linter. These are of­ten used for rules that in­volve punc­tu­a­tion. It re­quires the most Rust knowl­edge but the least Harper-specific knowl­edge. I’m go­ing to hold off on writ­ing a guide for these un­til I hear a real de­sire to learn about them.

These guides will fo­cus more on the process of writ­ing a rule for Harper, not the tech­ni­cal de­tails of wiring it up. For the lat­ter, see our of­fi­cial doc­u­men­ta­tion.