<page xmlns="http://projectmallard.org/1.0/"
      xmlns:ui="http://projectmallard.org/ui/1.0/"
      xmlns:its="http://www.w3.org/2005/11/its"
      type="topic" style="tip"
      id="gtg-search-syntax">

  <info>
    <link type="guide" xref="index#gtg-search" group="second"/>
    <link type="seealso" xref="gtg-search"/>

    <revision pkgversion="0.1.0" version="0.1.0" date="2012-07-03" status="candidate" />
    <revision pkgversion="0.4.0" date="2020-05-12" status="candidate" />

    <credit type="author copyright">
      <name>Bertrand Rousseau</name>
      <email>bertrand.rousseau@gmail.com</email>
      <years>2012</years>
    </credit>
     <credit type="editor copyright">
      <name>Danielle Vansia</name>
      <email>daniellevansia@gmail.com</email>
      <years>2020</years>
    </credit>
  </info>

  <title><app>GTG</app> Search Syntax</title>

<p>When performing a search request, you can also use special keywords to help refine your results. The table below describes this syntax. This functionality allows you to more efficiently view tasks based on specific criteria and prioritize tasks that are immediately due.</p>

<table rules="rows" frame="top bottom" ui:expanded="true">
<title><app>GTG</app> Search Keywords</title>
  <thead>
    <tr>
      <td><p><em style="strong">Search Query</em></p></td>
      <td><p><em style="strong">Search Result</em></p></td>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><p><code>word</code></p></td>
      <td><p>Tasks that contain a single word.</p></td>
    </tr>
    <tr>
      <td><p><code>"text"</code></p></td>
      <td><p>Tasks that contain everything inside of the quotes. You can include multiple words, special characters, and spaces in this search.
</p></td>
    </tr>
    <tr>
      <td><p><code>@tag</code></p></td>
      <td><p>Tasks with this tag.</p></td>
    </tr>
    <tr>
      <td><p><code>!notag</code></p></td>
      <td><p>Tasks without tags.</p></td>
    </tr>
    <tr>
      <td><p><code>!before [date]</code></p></td>
      <td>
        <p>Tasks that need to be completed before the input date.</p>
        <p>See the note below for the <code>[date]</code> element's format.</p>
      </td>
    </tr>
    <tr>
      <td><p><code>!after [date]</code></p></td>
      <td>
        <p>Tasks that you can wait to complete until after the input date. These tasks either have a start date that is after the input date or do not have a start date set and are due after the input date.</p>
        <p>See the note below for the <code>[date]</code> element's format.</p>
      </td>
    </tr>
    <tr>
      <td><p><code>!today</code></p></td>
      <td><p>Tasks that are due today.</p></td>
    </tr>
    <tr>
      <td><p><code>!tomorrow</code></p></td>
      <td><p>Tasks that are due tomorrow.</p></td>
    </tr>
    <tr>
      <td><p><code>!nodate</code></p></td>
      <td><p>Tasks without a set due date.</p></td>
    </tr>
    <tr>
      <td><p><code>!now</code></p></td>
      <td><p>Tasks with due date defined as "now."</p></td>
    </tr>
    <tr>
      <td><p><code>!soon</code></p></td>
      <td><p>Tasks with due date defined as "soon."</p></td>
    </tr>
    <tr>
      <td><p><code>!someday</code></p></td>
      <td><p>Tasks with due date defined as "someday."</p></td>
    </tr>
    <tr>
      <td><p><code>!not [query]</code></p></td>
      <td><p>Tasks that do not include the next part of the query.</p></td>
    </tr>
    <tr>
      <td><p><code>[query] !or [query]</code></p></td>
      <td><p>Tasks with one of the specified elements in the query.</p></td>
    </tr>
  </tbody>
</table>

<note style="tip"><title>Date Format</title><p><code>[date]</code> can be formatted in a number of ways using <app>GTG's</app> natural date parsing syntax. Dates can be literal (for example, "2020-04-20") or "fuzzy" (for example, "someday"). See <link xref="gtg-date-parsing">Using the Date and Keyword Parsing Syntax</link> for details.</p></note>

<p>The search feature behaves like it adds an implicit, logical <em>AND</em> between each element (unless the <code>!or</code> operator is used). The results include tasks that match all elements of the query.</p>

<section id="searchexamples">
<title>Search Query Examples</title>
<table rules="rows" frame="top bottom" ui:expanded="true">
<title>Examples</title>
  <thead>
    <tr>
      <td><p><em style="strong">Search Input</em></p></td>
      <td><p><em style="strong">Search Result</em></p></td>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><p><em style="strong"><code>!tomorrow !or !today</code></em></p></td>
      <td><p>Tasks that are due today or tomorrow.</p></td>
    </tr>
    <tr>
      <td><p><em style="strong"><code>@gtg @writing</code></em></p></td>
      <td><p>Tasks with both the <em style="strong"><code>@gtg</code></em> and <em style="strong"><code>@writing</code></em> tags.</p></td>
    </tr>
    <tr>
      <td><p><em style="strong"><code>@gtg !before 2020-03-01</code></em></p></td>
      <td><p>Tasks that are due before March 1, 2020, and have the <em style="strong"><code>@gtg</code></em> tag.</p></td>
    </tr>
    <tr>
      <td><p><em style="strong"><code>buy @errands</code></em></p></td>
      <td><p>Tasks that include the word <em style="strong"><code>buy</code></em> in the task title or description and contain the <em style="strong"><code>@errands</code></em> tag.</p></td>
    </tr>
    <tr>
      <td><p><em style="strong"><code>!not buy @errands</code></em></p></td>
      <td><p>Tasks that contain the <em style="strong"><code>@errands</code></em> tag but do not contain the word <em style="strong"><code>buy</code></em> in the task title or description.</p></td>
    </tr>
  </tbody>
</table>
</section>
</page>
