# Package org.apache.lucene.search.matchhighlight

This package contains several components useful to build a highlighter on top of the `Matches` API.

`MatchRegionRetriever` can be used to retrieve hit areas for a given `Query` and one (or more) indexed documents. These hit areas can be then passed to `PassageSelector` and formatted with `PassageFormatter`.

- Interface Summary
  Interface | Description
  --- | ---
  MatchHighlighter.FieldValueHighlighter | Actual per-field highlighter.
  MatchRegionRetriever.FieldValueProvider | An abstraction that provides document values for a given field.
  MatchRegionRetriever.MatchOffsetsConsumer | A callback for accepting a single document (and its associated leaf reader, leaf document ID) and its match offset ranges, as indicated by the `Matches` interface retrieved for the query.
  OffsetsRetrievalStrategy | Determines how match offset regions are computed from `MatchesIterator`.
  OffsetsRetrievalStrategySupplier | A per-field supplier of `OffsetsRetrievalStrategy`.
  PassageAdjuster | Adjusts the range of one or more passages over a given value.

- Class Summary
  Class | Description
  --- | ---
  BreakIteratorShrinkingAdjuster | A `PassageAdjuster` that adjusts the `Passage` range to word boundaries hinted by the given `BreakIterator`.
  FieldValueHighlighters | A factory of `MatchHighlighter.FieldValueHighlighter` classes that cover typical use cases (verbatim values, highlights, abbreviations).
  MatchHighlighter | An example highlighter that combines several lower-level highlighting utilities in this package into a fully featured, ready-to-use component.
  MatchHighlighter.DocHighlights | Single document's highlights.
  MatchHighlighter.QueryOffsetRange | An `OffsetRange` of a match, together with the source query that caused it.
  MatchRegionRetriever | Utility class to compute a list of "match regions" for a given query, searcher and document(s) using `Matches` API.
  OffsetRange | A non-empty range of offset positions.
  OffsetsFromMatchIterator | This strategy retrieves offsets directly from `MatchesIterator`, if they are available, otherwise it falls back to using `OffsetsFromPositions`.
  OffsetsFromPositions | This strategy applies to fields with stored positions but no offsets.
  OffsetsFromTokens | This strategy works for fields where we know the match occurred but there are no known positions or offsets.
  OffsetsFromValues | This strategy works for fields where we know the match occurred but there are no known positions or offsets.
  Passage | A passage is a fragment of source text, scored and possibly with a list of sub-offsets (markers) to be highlighted.
  PassageFormatter | Formats a collection of passages over a given string, cleaning up and resolving restrictions concerning overlaps, allowed sub-ranges over the input string and length restrictions.
  PassageSelector | Selects fragments of text that score best for the given set of highlight markers.