query.h File Reference

Notmuch query functions. More...

#include <stdbool.h>
#include <stddef.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_UNKNOWN = 0 , NM_QUERY_TYPE_MESSAGES , NM_QUERY_TYPE_THREADS }
	Notmuch Query Types. More...
enum	NmTimebase {   NMTB_UNKNOWN = 0 , NMTB_HOUR , NMTB_DAY , NMTB_WEEK ,   NMTB_MONTH , NMTB_YEAR }
	Time periods for notmuch windowed queries. 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.
enum NmQueryType	nm_string_to_query_type (const char *str)
	Lookup a query type.
enum NmQueryType	nm_string_to_query_type_mapper (const char *str)
	Lookup a query type.
const char *	nm_query_type_to_string (enum NmQueryType query_type)
	Turn a query type into a string.
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, enum NmTimebase timebase, const char *or_terms)
	Windows buf with notmuch date: search term.

Variables
const struct EnumDef	NmQueryWindowTimebaseDef
	Data for the $nm_query_window_timebase enumeration.
const struct EnumDef	NmQueryTypeDef
	Data for the $nm_query_type enumeration.

Detailed Description

Notmuch query functions.

Authors

• Austin Ray

Copyright

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version.

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

enum NmQueryType

Notmuch Query Types.

Read whole-thread or matching messages only?

Enumerator
NM_QUERY_TYPE_UNKNOWN	Unknown query type. Error in notmuch query.
NM_QUERY_TYPE_MESSAGES	Default: Messages only.
NM_QUERY_TYPE_THREADS	Whole threads.

Definition at line 36 of file query.h.

{
  NM_QUERY_TYPE_UNKNOWN = 0,  
  NM_QUERY_TYPE_MESSAGES,     
  NM_QUERY_TYPE_THREADS,      
};

NmTimebase

enum NmTimebase

Time periods for notmuch windowed queries.

Enumerator
NMTB_UNKNOWN	Unknown timebase.
NMTB_HOUR	Hours.
NMTB_DAY	Days.
NMTB_WEEK	Weeks.
NMTB_MONTH	Months.
NMTB_YEAR	Years.

Definition at line 46 of file query.h.

{
  NMTB_UNKNOWN = 0, 
  NMTB_HOUR,        
  NMTB_DAY,         
  NMTB_WEEK,        
  NMTB_MONTH,       
  NMTB_YEAR,        
};

NmWindowQueryRc

enum 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 59 of file query.h.

{
  NM_WINDOW_QUERY_SUCCESS = 1,      
  NM_WINDOW_QUERY_INVALID_TIMEBASE, 
  NM_WINDOW_QUERY_INVALID_DURATION  
};

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

buf	Buffer for URL
fallback	Fallback query type if buf doesn't contain a type= statement

Return values

enum	NmQueryType, 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 90 of file query.c.

{
  enum NmQueryType query_type = fallback;
 
  if (!buf)
    return query_type;
 
  size_t buflen = mutt_str_len(buf);
  const char *message_ptr = mutt_istrn_rfind(buf, buflen, "type=messages");
  const char *thread_ptr = mutt_istrn_rfind(buf, buflen, "type=threads");
 
  // No valid type statement found.
  if (!message_ptr && !thread_ptr)
    return query_type;
 
  // Determine the last valid "type=" statement.
  if ((!message_ptr && thread_ptr) || (thread_ptr > message_ptr))
  {
    query_type = NM_QUERY_TYPE_THREADS;
  }
  else
  {
    query_type = NM_QUERY_TYPE_MESSAGES;
  }
 
  // Clean-up any valid "type=" statements.
  // The six variations of how "type=" could appear.
  const char *variants[6] = { "&type=threads", "&type=messages",
                              "type=threads&", "type=messages&",
                              "type=threads",  "type=messages" };
  int variants_size = countof(variants);
 
  for (int i = 0; i < variants_size; i++)
  {
    mutt_istr_remall(buf, variants[i]);
  }
 
  return query_type;
}

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

str	String to lookup

Return values

enum	NmQueryType, e.g. NM_QUERY_TYPE_MESSAGES

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

Definition at line 150 of file query.c.

{
  enum NmQueryType query_type = nm_string_to_query_type_mapper(str);
 
  if (query_type == NM_QUERY_TYPE_UNKNOWN)
  {
    mutt_error(_("failed to parse notmuch query type: %s"), NONULL(str));
    return NM_QUERY_TYPE_MESSAGES;
  }
 
  return query_type;
}

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

str	String to lookup

Return values

num	Query type
NM_QUERY_TYPE_UNKNOWN	on error

Definition at line 169 of file query.c.

{
  int query_type = mutt_map_get_value(str, NmQueryTypeMethods);
  return (query_type < 0) ? NM_QUERY_TYPE_UNKNOWN : query_type;
}

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_type

Query type

Return values

ptr

String

Note

This is a static string and must not be freed.

Definition at line 137 of file query.c.

{
  const char *name = mutt_map_get_name(query_type, NmQueryTypeMethods);
  return name ? name : "messages";
}

Here is the call graph for this function:

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 enum NmTimebase	timebase,
		const char *	or_terms )

Windows buf with notmuch date: search term.

Parameters

[out]	buf	allocated string buffer to receive the modified search query
[in]	buflen	allocated maximum size of the buf string buffer
[in]	force_enable	Enables windowing for duration=0
[in]	duration	Duration of time between beginning and end for notmuch date search term
[in]	cur_pos	Current position of vfolder window
[in]	cur_search	Current notmuch search
[in]	timebase	Timebase for date: search term
[in]	or_terms	Additional notmuch search terms

Return values

NM_WINDOW_QUERY_SUCCESS	Prepended buf with date: search term
NM_WINDOW_QUERY_INVALID_DURATION	Duration out-of-range for search term. buf not prepended with date:
NM_WINDOW_QUERY_INVALID_TIMEBASE	Timebase 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 220 of file query.c.

{
  // if the duration is a non positive integer, disable the window unless the
  // user explicitly enables windowed queries.
  if (!force_enable && (duration <= 0))
  {
    return NM_WINDOW_QUERY_INVALID_DURATION;
  }
 
  int beg = duration * (cur_pos + 1);
  int end = duration * cur_pos;
 
  // If the duration is 0, we want to generate a query spanning a single timebase.
  // For example, `date:1month..1month` spans the previous month.
  if ((duration == 0) && (cur_pos != 0))
  {
    end = cur_pos;
    beg = end;
  }
 
  const char *timebase_str = mutt_map_get_name(timebase, NmTimebaseMethods);
  if (!timebase_str)
  {
    return NM_WINDOW_QUERY_INVALID_TIMEBASE;
  }
 
  size_t length = 0;
  if (end == 0)
  {
    // Open-ended date allows mail from the future.
    // This may occur is the sender's time settings are off.
    length = snprintf(buf, buflen, "date:%d%s..", beg, timebase_str);
  }
  else
  {
    length = snprintf(buf, buflen, "date:%d%s..%d%s", beg, timebase_str, end, timebase_str);
  }
 
  if (!mutt_str_equal(or_terms, ""))
  {
    char *date_part = mutt_str_dup(buf);
    length = snprintf(buf, buflen, "(%s or (%s))", date_part, or_terms);
    FREE(&date_part);
  }
 
  // Add current search to window query.
  snprintf(buf + length, buflen - length, " and %s", cur_search);
 
  return NM_WINDOW_QUERY_SUCCESS;
}

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

NmQueryWindowTimebaseDef

const struct EnumDef NmQueryWindowTimebaseDef

extern

Data for the $nm_query_window_timebase enumeration.

Definition at line 73 of file query.c.

                                                {
  "nm_query_window_timebase",
  5,
  (struct Mapping *) &NmTimebaseMethods,
};

NmQueryTypeDef

const struct EnumDef NmQueryTypeDef

extern

Data for the $nm_query_type enumeration.

Definition at line 52 of file query.c.

                                      {
  "nm_query_type",
  2,
  (struct Mapping *) &NmQueryTypeMethods,
};