NeoMutt  2023-05-17-56-ga67199
Teaching an old dog new tricks
DOXYGEN
query.h File Reference

Notmuch query functions. More...

#include <stddef.h>
#include <stdbool.h>
+ Include dependency graph for query.h:
+ This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Enumerations

enum  NmQueryType { NM_QUERY_TYPE_MESGS = 1 , NM_QUERY_TYPE_THREADS , NM_QUERY_TYPE_UNKNOWN }
 Notmuch Query Types. More...
 
enum  NmWindowQueryRc { NM_WINDOW_QUERY_SUCCESS = 1 , NM_WINDOW_QUERY_INVALID_TIMEBASE , NM_WINDOW_QUERY_INVALID_DURATION }
 Return codes for nm_windowed_query_from_query() More...
 

Functions

enum NmQueryType nm_parse_type_from_query (char *buf, enum NmQueryType fallback)
 Parse a query type out of a query. More...
 
enum NmQueryType nm_string_to_query_type (const char *str)
 Lookup a query type. More...
 
enum NmQueryType nm_string_to_query_type_mapper (const char *str)
 Lookup a query type. More...
 
const char * nm_query_type_to_string (enum NmQueryType query_type)
 Turn a query type into a string. More...
 
enum NmWindowQueryRc nm_windowed_query_from_query (char *buf, size_t buflen, const bool force_enable, const short duration, const short current_pos, const char *current_search, const char *timebase, const char *or_terms)
 Windows buf with notmuch date: search term. More...
 
bool nm_query_window_check_timebase (const char *timebase)
 Checks if a given timebase string is valid. More...
 

Detailed Description

Notmuch query functions.

Authors
  • Austin Ray

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

Definition in file query.h.

Enumeration Type Documentation

◆ NmQueryType

Notmuch Query Types.

Read whole-thread or matching messages only?

Enumerator
NM_QUERY_TYPE_MESGS 

Default: Messages only.

NM_QUERY_TYPE_THREADS 

Whole threads.

NM_QUERY_TYPE_UNKNOWN 

Unknown query type. Error in notmuch query.

Definition at line 34 of file query.h.

35{
39};
@ NM_QUERY_TYPE_UNKNOWN
Unknown query type. Error in notmuch query.
Definition: query.h:38
@ NM_QUERY_TYPE_THREADS
Whole threads.
Definition: query.h:37
@ NM_QUERY_TYPE_MESGS
Default: Messages only.
Definition: query.h:36

◆ NmWindowQueryRc

Return codes for nm_windowed_query_from_query()

Enumerator
NM_WINDOW_QUERY_SUCCESS 

Query was successful.

NM_WINDOW_QUERY_INVALID_TIMEBASE 

Invalid timebase.

NM_WINDOW_QUERY_INVALID_DURATION 

Invalid duration.

Definition at line 44 of file query.h.

45{
49};
@ NM_WINDOW_QUERY_SUCCESS
Query was successful.
Definition: query.h:46
@ NM_WINDOW_QUERY_INVALID_DURATION
Invalid duration.
Definition: query.h:48
@ NM_WINDOW_QUERY_INVALID_TIMEBASE
Invalid timebase.
Definition: query.h:47

Function Documentation

◆ nm_parse_type_from_query()

enum NmQueryType nm_parse_type_from_query ( char *  buf,
enum NmQueryType  fallback 
)

Parse a query type out of a query.

Parameters
bufBuffer for URL
fallbackFallback query type if buf doesn't contain a type= statement
Return values
enumNmQueryType, Notmuch query type

If a user writes a query for a vfolder and includes a type= statement, that type= will be encoded, which Notmuch will treat as part of the query= statement. This method will remove the type= and return its corresponding NmQueryType representation.

Definition at line 48 of file query.c.

49{
50 enum NmQueryType query_type = fallback;
51
52 if (!buf)
53 return query_type;
54
55 size_t buf_len = mutt_str_len(buf);
56 const char *message_ptr = mutt_istrn_rfind(buf, buf_len, "type=messages");
57 const char *thread_ptr = mutt_istrn_rfind(buf, buf_len, "type=threads");
58
59 // No valid type statement found.
60 if (!message_ptr && !thread_ptr)
61 return query_type;
62
63 // Determine the last valid "type=" statement.
64 if ((!message_ptr && thread_ptr) || (thread_ptr > message_ptr))
65 {
66 query_type = NM_QUERY_TYPE_THREADS;
67 }
68 else
69 {
70 query_type = NM_QUERY_TYPE_MESGS;
71 }
72
73 // Clean-up any valid "type=" statements.
74 // The six variations of how "type=" could appear.
75 const char *variants[6] = { "&type=threads", "&type=messages",
76 "type=threads&", "type=messages&",
77 "type=threads", "type=messages" };
78 int variants_size = mutt_array_size(variants);
79
80 for (int i = 0; i < variants_size; i++)
81 {
82 mutt_istr_remall(buf, variants[i]);
83 }
84
85 return query_type;
86}
size_t buf_len(const struct Buffer *buf)
Calculate the length of a Buffer.
Definition: buffer.c:460
#define mutt_array_size(x)
Definition: memory.h:36
const char * mutt_istrn_rfind(const char *haystack, size_t haystack_length, const char *needle)
Find last instance of a substring, ignoring case.
Definition: string.c:541
int mutt_istr_remall(char *str, const char *target)
Remove all occurrences of substring, ignoring case.
Definition: string.c:964
size_t mutt_str_len(const char *a)
Calculate the length of a string, safely.
Definition: string.c:568
NmQueryType
Notmuch Query Types.
Definition: query.h:35
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ nm_string_to_query_type()

enum NmQueryType nm_string_to_query_type ( const char *  str)

Lookup a query type.

Parameters
strString to lookup
Return values
enumNmQueryType, e.g. NM_QUERY_TYPE_MESGS

If there's an unknown query type, default to NM_QUERY_TYPE_MESGS.

Definition at line 109 of file query.c.

110{
111 enum NmQueryType query_type = nm_string_to_query_type_mapper(str);
112
113 if (query_type == NM_QUERY_TYPE_UNKNOWN)
114 {
115 mutt_error(_("failed to parse notmuch query type: %s"), NONULL(str));
116 return NM_QUERY_TYPE_MESGS;
117 }
118
119 return query_type;
120}
#define mutt_error(...)
Definition: logging2.h:90
#define _(a)
Definition: message.h:28
enum NmQueryType nm_string_to_query_type_mapper(const char *str)
Lookup a query type.
Definition: query.c:128
#define NONULL(x)
Definition: string2.h:37
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ nm_string_to_query_type_mapper()

enum NmQueryType nm_string_to_query_type_mapper ( const char *  str)

Lookup a query type.

Parameters
strString to lookup
Return values
numQuery type
NM_QUERY_TYPE_UNKNOWNon error

Definition at line 128 of file query.c.

129{
130 if (mutt_str_equal(str, "threads"))
132 if (mutt_str_equal(str, "messages"))
133 return NM_QUERY_TYPE_MESGS;
134
136}
bool mutt_str_equal(const char *a, const char *b)
Compare two strings.
Definition: string.c:798
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ nm_query_type_to_string()

const char * nm_query_type_to_string ( enum NmQueryType  query_type)

Turn a query type into a string.

Parameters
query_typeQuery type
Return values
ptrString
Note
This is a static string and must not be freed.

Definition at line 95 of file query.c.

96{
97 if (query_type == NM_QUERY_TYPE_THREADS)
98 return "threads";
99 return "messages";
100}
+ Here is the caller graph for this function:

◆ nm_windowed_query_from_query()

enum NmWindowQueryRc nm_windowed_query_from_query ( char *  buf,
size_t  buflen,
const bool  force_enable,
const short  duration,
const short  cur_pos,
const char *  cur_search,
const char *  timebase,
const char *  or_terms 
)

Windows buf with notmuch date: search term.

Parameters
[out]bufallocated string buffer to receive the modified search query
[in]buflenallocated maximum size of the buf string buffer
[in]force_enableEnables windowing for duration=0
[in]durationDuration of time between beginning and end for notmuch date search term
[in]cur_posCurrent position of vfolder window
[in]cur_searchCurrent notmuch search
[in]timebaseTimebase for date: search term. Must be: hour, day, week, month, or year
[in]or_termsAdditional notmuch search terms
Return values
NM_WINDOW_QUERY_SUCCESSPrepended buf with date: search term
NM_WINDOW_QUERY_INVALID_DURATIONDuration out-of-range for search term. buf not prepended with date:
NM_WINDOW_QUERY_INVALID_TIMEBASETimebase isn't one of hour, day, week, month, or year

This is where the magic of windowed queries happens. Taking a vfolder search query string as parameter, it will use the following two user settings:

  • duration and
  • timebase

to amend given vfolder search window. Then using a third parameter:

  • cur_pos

it will generate a proper notmuch date: parameter. For example, given a duration of 2, a timebase set to week and a position defaulting to 0, it will prepend to the 'tag:inbox' notmuch search query the following string:

  • query: tag:inbox
  • buf: date:2week..now and tag:inbox

If the position is set to 4, with duration=3 and timebase=month:

  • query: tag:archived
  • buf: date:12month..9month and tag:archived

The window won't be applied:

  • If the duration of the search query is set to 0 this function will be disabled unless a user explicitly enables windowed queries. This returns NM_WINDOW_QUERY_INVALID_DURATION
  • If the timebase is invalid, it will return NM_WINDOW_QUERY_INVALID_TIMEBASE

Definition at line 205 of file query.c.

208{
209 // if the duration is a non positive integer, disable the window unless the
210 // user explicitly enables windowed queries.
211 if (!force_enable && (duration <= 0))
212 {
214 }
215
216 int beg = duration * (cur_pos + 1);
217 int end = duration * cur_pos;
218
219 // If the duration is 0, we want to generate a query spanning a single timebase.
220 // For example, `date:1month..1month` spans the previous month.
221 if ((duration == 0) && (cur_pos != 0))
222 {
223 end = cur_pos;
224 beg = end;
225 }
226
227 if (!nm_query_window_check_timebase(timebase))
228 {
230 }
231
232 size_t length = 0;
233 if (end == 0)
234 {
235 // Open-ended date allows mail from the future.
236 // This may occur is the sender's time settings are off.
237 length = snprintf(buf, buflen, "date:%d%s..", beg, timebase);
238 }
239 else
240 {
241 length = snprintf(buf, buflen, "date:%d%s..%d%s", beg, timebase, end, timebase);
242 }
243
244 if (!mutt_str_equal(or_terms, ""))
245 {
246 char *date_part = mutt_str_dup(buf);
247 length = snprintf(buf, buflen, "(%s or (%s))", date_part, or_terms);
248 FREE(&date_part);
249 }
250
251 // Add current search to window query.
252 snprintf(buf + length, buflen - length, " and %s", cur_search);
253
255}
#define FREE(x)
Definition: memory.h:43
char * mutt_str_dup(const char *str)
Copy a string, safely.
Definition: string.c:251
bool nm_query_window_check_timebase(const char *timebase)
Checks if a given timebase string is valid.
Definition: query.c:148
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ nm_query_window_check_timebase()

bool nm_query_window_check_timebase ( const char *  timebase)

Checks if a given timebase string is valid.

Parameters
[in]timebasestring containing a time base
Return values
trueThe given time base is valid

This function returns whether a given timebase string is valid or not, which is used to validate the user settable configuration setting:

nm_query_window_timebase

Definition at line 148 of file query.c.

149{
150 if ((mutt_str_equal(timebase, "hour")) || (mutt_str_equal(timebase, "day")) ||
151 (mutt_str_equal(timebase, "week")) ||
152 (mutt_str_equal(timebase, "month")) || (mutt_str_equal(timebase, "year")))
153 {
154 return true;
155 }
156 return false;
157}
+ Here is the call graph for this function:
+ Here is the caller graph for this function: