Skip to content

Offline, privacy-first grammar checker. Fast, open-source, Rust-powered

docs(core): added an example of pattern use

Elijah Potter0f20d8024e81
diff --git a/harper-core/src/patterns/is_not_title_case.rs b/harper-core/src/patterns/is_not_title_case.rs
index ecad0b8e8..5821159c2 100644
--- a/harper-core/src/patterns/is_not_title_case.rs
+++ b/harper-core/src/patterns/is_not_title_case.rs
@@ -2,8 +2,8 @@ use crate::{make_title_case, Dictionary, Token, TokenStringExt};
use super::Pattern;
-/// Will match full length of wrapped pattern __only if the matched
-/// text is not already title case__.
+/// Will match full length of wrapped pattern only if the matched
+/// text is not already title case.
pub struct IsNotTitleCase<D: Dictionary> {
inner: Box<dyn Pattern>,
dict: D,
diff --git a/harper-core/src/patterns/mod.rs b/harper-core/src/patterns/mod.rs
index ce2d042d4..3366f8753 100644
--- a/harper-core/src/patterns/mod.rs
+++ b/harper-core/src/patterns/mod.rs
@@ -1,3 +1,10 @@
+//! [`Pattern`]s are one of the more powerful constructs inside Harper, especially for beginners.
+//!
+//! Through the [`PatternLinter`](crate::linting::PatternLinter) trait, they make it much easier to
+//! build Harper [rules](crate::linting::Linter).
+//!
+//! See the page about [`SequencePattern`] for a concrete example of their use.
+
use std::collections::VecDeque;
use crate::{Document, Span, Token, VecExt};
@@ -127,7 +134,7 @@ where
}
}
-trait DocPattern {
+pub trait DocPattern {
fn find_all_matches_in_doc(&self, document: &Document) -> Vec<Span>;
}
diff --git a/harper-core/src/patterns/sequence_pattern.rs b/harper-core/src/patterns/sequence_pattern.rs
index c1eb7ac53..ef5386a00 100644
--- a/harper-core/src/patterns/sequence_pattern.rs
+++ b/harper-core/src/patterns/sequence_pattern.rs
@@ -6,6 +6,26 @@ use super::{NounPhrase, Pattern, RepeatingPattern, WordSet};
use crate::{CharStringExt, Lrc, Token, TokenKind};
/// A pattern that checks that a sequence of other patterns match.
+/// There are specific extension methods available, but you can also use [`Self::then`] to add
+/// arbitrary patterns.
+///
+/// ## Example
+///
+/// Let's say we wanted to locate places in a [`Document`] where an article is followed by a noun.
+/// We can do that with a `SequencePattern`.
+///
+/// ```rust
+/// use harper_core::patterns::{SequencePattern, DocPattern};
+/// use harper_core::{Document, Span};
+///
+/// let document = Document::new_markdown_default_curated("This is a test.");
+///
+/// let pattern = SequencePattern::default().then_article().then_whitespace().then_noun();
+/// let matches = pattern.find_all_matches_in_doc(&document);
+///
+/// // The pattern found that the tokens at indexes 4, 5, and 6 fit the criteria.
+/// assert_eq!(matches, vec![Span::new(4, 7)]);
+/// ```
#[derive(Default)]
pub struct SequencePattern {
token_patterns: Vec<Box<dyn Pattern>>,
@@ -60,6 +80,7 @@ impl SequencePattern {
gen_then_from_is!(adjective);
gen_then_from_is!(apostrophe);
gen_then_from_is!(hyphen);
+ gen_then_from_is!(article);
pub fn then_word_set(self, set: WordSet) -> Self {
self.then(Box::new(set))