/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/**
* The calculus of spans.
*
* <p>A span is a <code><doc,startPosition,endPosition></code> tuple that is enumerated by
* class {@link org.apache.lucene.search.spans.Spans Spans}.
* </p>
*
* <p>The following span query operators are implemented:
*
* <ul>
*
* <li>A {@link org.apache.lucene.search.spans.SpanTermQuery SpanTermQuery} matches all spans
* containing a particular {@link org.apache.lucene.index.Term Term}.
* This should not be used for terms that are indexed at position Integer.MAX_VALUE.
* </li>
*
* <li> A {@link org.apache.lucene.search.spans.SpanNearQuery SpanNearQuery} matches spans
* which occur near one another, and can be used to implement things like
* phrase search (when constructed from {@link org.apache.lucene.search.spans.SpanTermQuery}s)
* and inter-phrase proximity (when constructed from other {@link org.apache.lucene.search.spans.SpanNearQuery}s).</li>
*
* <li> A {@link org.apache.lucene.search.spans.SpanWithinQuery SpanWithinQuery} matches spans
* which occur inside of another spans. </li>
*
* <li> A {@link org.apache.lucene.search.spans.SpanContainingQuery SpanContainingQuery} matches spans
* which contain another spans. </li>
*
* <li>A {@link org.apache.lucene.search.spans.SpanOrQuery SpanOrQuery} merges spans from a
* number of other {@link org.apache.lucene.search.spans.SpanQuery}s.</li>
*
* <li>A {@link org.apache.lucene.search.spans.SpanNotQuery SpanNotQuery} removes spans
* matching one {@link org.apache.lucene.search.spans.SpanQuery SpanQuery} which overlap (or comes
* near) another. This can be used, e.g., to implement within-paragraph
* search.</li>
*
* <li>A {@link org.apache.lucene.search.spans.SpanFirstQuery SpanFirstQuery} matches spans
* matching <code>q</code> whose end position is less than
* <code>n</code>. This can be used to constrain matches to the first
* part of the document.</li>
*
* <li>A {@link org.apache.lucene.search.spans.SpanPositionRangeQuery SpanPositionRangeQuery} is
* a more general form of SpanFirstQuery that can constrain matches to arbitrary portions of the document.</li>
*
* </ul>
*
* In all cases, output spans are minimally inclusive. In other words, a
* span formed by matching a span in x and y starts at the lesser of the
* two starts and ends at the greater of the two ends.
*
* <p>For example, a span query which matches "John Kerry" within ten
* words of "George Bush" within the first 100 words of the document
* could be constructed with:
* <pre class="prettyprint">
* SpanQuery john = new SpanTermQuery(new Term("content", "john"));
* SpanQuery kerry = new SpanTermQuery(new Term("content", "kerry"));
* SpanQuery george = new SpanTermQuery(new Term("content", "george"));
* SpanQuery bush = new SpanTermQuery(new Term("content", "bush"));
*
* SpanQuery johnKerry =
* new SpanNearQuery(new SpanQuery[] {john, kerry}, 0, true);
*
* SpanQuery georgeBush =
* new SpanNearQuery(new SpanQuery[] {george, bush}, 0, true);
*
* SpanQuery johnKerryNearGeorgeBush =
* new SpanNearQuery(new SpanQuery[] {johnKerry, georgeBush}, 10, false);
*
* SpanQuery johnKerryNearGeorgeBushAtStart =
* new SpanFirstQuery(johnKerryNearGeorgeBush, 100);
* </pre>
*
* <p>Span queries may be freely intermixed with other Lucene queries.
* So, for example, the above query can be restricted to documents which
* also use the word "iraq" with:
*
* <pre class="prettyprint">
* Query query = new BooleanQuery();
* query.add(johnKerryNearGeorgeBushAtStart, true, false);
* query.add(new TermQuery("content", "iraq"), true, false);
* </pre>
*/
package org.apache.lucene.search.spans;