<h1>Writing an Expression Rule for Harper</h1>
This is part three in a three-part series.
<a href="./writing_a_grammatical_rule_for_harper">Go to part one.</a>
Expression rules (or more commonly, <code>ExprLinter</code>s) are Harper rules that use declarative expressions to find and fix grammatical errors.
They're halfway between a "phrase correction" and manually implementing <code>Linter</code>.
Make sure you properly <a href="https://writewithharper.com/docs/contributors/environment">set up your environment</a>.
Before we get started, let's take a look at the <code>ExprLinter</code> trait.
Here's what it looks like at the time of writing this post.
<pre><code class="hljs language-rust">/// A trait that searches for tokens that fulfil [`Expr`]s in a [`Document`].
///
/// Makes use of [`TokenStringExt::iter_chunks`] to avoid matching across sentence or clause
/// boundaries.
#[blanket(derive(Box))]
pub trait ExprLinter: LSend {
 /// A simple getter for the expression you want Harper to search for.
 fn expr(&#x26;self) -> &#x26;dyn Expr;
 /// If any portions of a [`Document`] match [`Self::expr`], they are passed through [`ExprLinter::match_to_lint`] to be
 /// transformed into a [`Lint`] for editor consumption.
 ///
 /// This function may return `None` to elect _not_ to produce a lint.
 fn match_to_lint(&#x26;self, matched_tokens: &#x26;[Token], source: &#x26;[char]) -> Option&#x3C;Lint>;
 /// A user-facing description of what kinds of grammatical errors this rule looks for.
 /// It is usually shown in settings menus.
 fn description(&#x26;self) -> &#x26;str;
}
</code></pre>
The structure of the trait reveals some of the behind-the-scenes work Harper is doing for you.
There are three phases:
<ol>
<li>You provide Harper an <code>Expr</code>.
It will iterate through the document, looking for token sequences that match your expression.</li>
<li>Any and all matches are passed to <code>match_to_lint</code>.
From there, you can perform optional additional validation to confirm that the tokens really do represent a grammatical error.
If so, return <code>None</code>.
Otherwise, return a <code>Lint</code> with any suggestions that may fix the problem.</li>
<li>Harper will handle everything else. It will show UI, reformat text, and settings menus to the user.
It will also perform aggressive caching on the first two steps, so any modifications to the document have a negligible performance impact.</li>
</ol>
<h2>Let's Get Started</h2>
Now that we've reviewed the essentials, let's implement an <code>ExprLinter</code>.
Before we can write a single line of code, we need a grammatical rule of interest.
I'm going to pay a visit to the Harper <a href="https://github.com/Automattic/harper/issues?q=is%3Aissue%20state%3Aopen%20label%3Aenhancement%20label%3Aharper-core%20label%3Alinting">issue board</a>.
After looking through a few options, I think <a href="https://github.com/Automattic/harper/issues/1513">#1513</a> is a good candidate.
We are looking for missing prepositions between an adjective and a subject.
To get started, we'll create a file under <code>harper-core/src/linting</code> called <code>missing_preposition.rs</code> and add it to the parent Rust module.
I'll paste the template into the file:
<pre><code class="hljs language-rust">pub struct MissingPreposition {
 expr: Box&#x3C;dyn Expr>,
}

impl Default for MissingPreposition {
 fn default() -> Self {
 let expr = todo!();

 Self {
 expr: Box::new(expr),
 }
 }
}


impl ExprLinter for MissingPreposition {
 fn expr(&#x26;self) -> &#x26;dyn Expr {
 self.expr.as_ref()
 }

 fn match_to_lint(&#x26;self, matched_tokens: &#x26;[Token], _source: &#x26;[char]) -> Option&#x3C;Lint> {
 unimplemented!()
 }

 fn description(&#x26;self) -> &#x26;'static str {
 unimplemented!()
 }
}
</code></pre>
I like to start by building out a few test cases before working on the actual code.
We get some for free from the GitHub issue:
<pre><code class="hljs language-rust">#[test]
fn fixes_issue_1513() {
 assert_lint_count(
 "The city is famous its beaches.",
 MissingPreposition::default(),
 1,
 );
 assert_lint_count(
 "The students are interested learning.",
 MissingPreposition::default(),
 1,
 );
}
</code></pre>
Obviously, these tests will fail if we try to run <code>cargo test</code>, but at this point you should do so anyway to make sure your toolchain is working.
<h2>Writing our Expression</h2>
The heart of this grammatical rule is the <code>Expr</code> (pronounced expression).
There are a number of ways to go about making one of these.
The simplest (and most common by far) is to put together a <a href="https://docs.rs/harper-core/latest/harper_core/expr/struct.SequenceExpr.html"><code>SequenceExpr</code></a>.
In our case, we're looking for missing prepositions between an adjective and a noun.
A good expression to start with could look like:
<pre><code class="hljs language-rust">impl Default for MissingPreposition {
 fn default() -> Self {
 let expr = SequenceExpr::default()
 .then(UPOSSet::new(&#x26;[UPOS::ADJ]))
 .t_ws()
 .then(UPOSSet::new(&#x26;[UPOS::NOUN, UPOS::PRON, UPOS::PROPN]));

 Self {
 expr: Box::new(expr),
 }
 }
}
</code></pre>
We're using a <code>UPOSSet</code> here, which is another kind of <code>Expr</code> that looks for specific parts of speech.
The name derives from the <a href="https://universaldependencies.org/u/pos/index.html">Universal Dependencies tag system</a>.
Any tokens tagged with any of the options we've provided to the <code>UPOSSet</code> will match.
However, it's easy to create an example that this expression matches against, but doesn't contain a grammatical error.
We call this a false positive.
Let's write one and add it to our test suite.
<pre><code class="hljs language-rust">#[test]
fn allows_terrible_stuff() {
 assert_no_lints(
 "Either it was terrible stuff or the whiskey distorted things.",
 MissingPreposition::default(),
 );
}
</code></pre>
From here, you should use your brain to continuously refine the expression into something that
maintains a low false-positive rate while remaining useful.
Here's what I settled on:
<pre><code class="hljs language-rust">impl Default for MissingPreposition {
 fn default() -> Self {
 let expr = SequenceExpr::default()
 .then(
 AnchorStart.or(SequenceExpr::default()
 .then(UPOSSet::new(&#x26;[UPOS::DET]))
 .t_ws()),
 )
 .then(UPOSSet::new(&#x26;[UPOS::NOUN, UPOS::PRON, UPOS::PROPN]))
 .t_ws()
 .then(UPOSSet::new(&#x26;[UPOS::AUX]))
 .t_ws()
 .then(UPOSSet::new(&#x26;[UPOS::ADJ]))
 .t_ws()
 .then(UPOSSet::new(&#x26;[UPOS::NOUN, UPOS::PRON, UPOS::PROPN]))
 .then_optional(AnyPattern)
 .then_optional(AnyPattern);

 Self {
 expr: Box::new(expr),
 }
 }
}
</code></pre>
Now that we have an effective expression as a base, let's fill out the remaining fields.
I found checking for an adposition reduced the false-positive rate, and it was easiest to add it to the <code>match_to_lint</code> function.
<pre><code class="hljs language-rust">impl ExprLinter for MissingPreposition {
 fn expr(&#x26;self) -> &#x26;dyn Expr {
 self.expr.as_ref()
 }

 fn match_to_lint(&#x26;self, matched_tokens: &#x26;[Token], _source: &#x26;[char]) -> Option&#x3C;Lint> {
 if matched_tokens.last()?.kind.is_upos(UPOS::ADP) {
 return None;
 }

 Some({
 Lint {
 span: matched_tokens[2..4].span()?,
 lint_kind: LintKind::Miscellaneous,
 suggestions: vec![],
 message: "You may be missing a preposition here.".to_owned(),
 priority: 31,
 }
 })
 }

 fn description(&#x26;self) -> &#x26;'static str {
 "Locates potentially missing prepositions."
 }
}
</code></pre>
That's it!
We've written our rule.
Don't forget to <a href="https://writewithharper.com/docs/contributors/author-a-rule#Register-Your-Rule">register your rule</a> and add some more tests before opening PR.
Make sure you take a look at the <a href="https://github.com/Automattic/harper/pull/1530">pull request</a> to see the finished rule.

This article guides contributors on writing a Harper expression-based rule. It covers defining the rule's expression, writing test cases, and implementing the `match_to_lint` function for user suggestions.

This article guides contributors on writing a Harper expression-based rule. It covers defining the rule's expression, writing test cases, and implementing the <code>match_to_lint</code> function for user suggestions.

Writing an Expression Rule for Harper

Back in my day, we used math for autocomplete.

Back in my day, we used math for autocomplete.

Markov Chains Are the Original Language Models

<h1>Harper for Firefox</h1>
<img src="/images/harper_chrome_ext.png" alt="The Harper Firefox Extension">
There's a great deal of overlap between those who use Harper and those who use Firefox.
Foremost, they both value privacy.
Which is why I'm so thrilled to say that Harper has an official plugin for Firefox.
While there has been an unofficial one for <a href="./harper_for_firefox_through_spellbolt">a while now</a>, this is the one that fully deserves the Harper label. It's ours, through and through.
It's still early days, so if you run into problems, feel free to open <a href="https://github.com/Automattic/harper/issues/new/choose">an issue</a>.
If you'd like to install it, pay us a visit on the <a href="https://addons.mozilla.org/en-US/firefox/addon/private-grammar-checker-harper/">Firefox Add-on Store</a>.

There's a great deal of overlap between those who use Harper and those who use Firefox.

There's a great deal of overlap between those who use Harper and those who use Firefox.

Harper for Firefox

for_the_love_of_iframes

<h1>For The Love of <code>iframe</code>s.</h1>
I adore a good <code>iframe</code>.
They're so elegant as a web component.
Just expose an endpoint, say <a href="https://writewithharper.com/editor?initialText=This%20is%20an%20interactive%20buffer%20you%20can%20use%20to%20to%20check%20your%20work"><code>https://writewithharper.com/editor</code></a>, set it up to accept some query parameters and get it hosted.
Now you can access this web-component from any page that has a loose enough Content Security Policy.
For me, that means my <a href="https://elijahpotter.dev/articles/the_simplest_neovim_markdown_setup">school assignments</a> and other assorted documentation.
It also means that I can avoid setting up a complex build system for MDX, while still being able to include interactive components.
The example from earlier:
<pre><code class="hljs language-html">&#x3C;iframe
 src="https://writewithharper.com/editor?initialText=See, we can now embed the the Harper editor%0Arght into this document!%0A%0AIt's a little too easy."
 width="100%"
 height="400px"
 style="border-radius:10px;border:0px"
>&#x3C;/iframe>
</code></pre>
One major caveat though: when we pass our arguments to the component through the query URL, this gets sent to the component's server as well.
I certainly trust the Harper website's server, since I maintain it and the code is <a href="https://github.com/elijah-potter/harper/tree/master/packages/web">open source</a>, but that isn't always the case.
<iframe src="https://writewithharper.com/editor?initialText=See, we can now embed the the Harper editor%0Arght into this document!%0A%0AIt's a little too easy." width="100%" height="400px" style="border-radius:10px;border:0px" ></iframe>
You should also probably avoid doing this too much.
Most browsers spawn a whole new process for every <code>iframe</code>, so if you want things to stay snappy it is best to limit yourself to just one (maybe two) per page.

Chronically underrated, chronically over-prescribed

Chronically underrated, chronically over-prescribed

Elijah Potter

For The Love of `iframe`s.

Other Stuff

Writing an Expression Rule for Harper

Markov Chains Are the Original Language Models

Harper for Firefox

Elijah Potter

For The Love of iframes.

Other Stuff

Writing an Expression Rule for Harper

Markov Chains Are the Original Language Models

Harper for Firefox

For The Love of `iframe`s.