get.h File Reference

Get a key from the user. More...

#include <stdint.h>
#include "mutt/lib.h"
#include "menu/lib.h"
#include "keymap.h"

Include dependency graph for get.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	KeyEvent
	An event such as a keypress. More...
struct	KeymapMatch
	Result of Matching Keybinding. More...

Macros
#define	KEY_COUNT_MAX_DIGITS   6
	Maximum number of digits in a key count prefix, e.g. 123j
#define	KEY_SEQ_MAX_LEN   8
	Maximum number of keys in a key sequence, e.g. abc

Typedefs
typedef uint8_t	GetChFlags
typedef uint8_t	KeyGatherFlags
typedef uint8_t	MenuFuncFlags

Enumerations
enum	GetChFlag { GETCH_NONE = 0 , GETCH_IGNORE_MACRO = 1U << 0 , GETCH_NO_COUNTER = 1U << 1 , GETCH_NO_FEEDBACK = 1U << 2 }
	Flags for mutt_getch(), e.g. More...
enum	KeyGatherFlag { KEY_GATHER_NO_MATCH = 0 , KEY_GATHER_MATCH = 1U << 0 , KEY_GATHER_LONGER = 1U << 1 }
	Flags for gather_functions(), e.g. More...
enum	MenuFuncFlag { MFF_NONE = 0 , MFF_DEPRECATED = 1U << 1 }
	Menu function property flags. More...

Functions
	ARRAY_HEAD (KeyEventArray, struct KeyEvent)
	ARRAY_HEAD (KeymapMatchArray, struct KeymapMatch)
void	array_add (struct KeyEventArray *a, int ch, int op)
	Add an event to the end of the array.
struct KeyEvent *	array_pop (struct KeyEventArray *a)
	Remove an event from the array.
void	array_to_endcond (struct KeyEventArray *a)
	Clear the array until an OP_END_COND.
KeyGatherFlags	gather_functions (const struct MenuDefinition *md, const keycode_t *keys, int key_len, struct KeymapMatchArray *kma)
	Find functions whose keybindings match.
void	generic_tokenize_push_string (char *s)
	Parse and queue a 'push' command.
struct KeyEvent	km_dokey (const struct MenuDefinition *md, GetChFlags flags)
	Determine what a keypress should do.
void	km_error_key (const struct MenuDefinition *md)
	Handle an unbound key sequence.
void	mutt_flushinp (void)
	MacroEvents moved to KeyModuleData UngetKeyEvents moved to KeyModuleData.
void	mutt_flush_macro_to_endcond (void)
	Drop a macro from the input buffer.
struct KeyEvent	mutt_getch (GetChFlags flags)
	Read a character from the input buffer.
int	mutt_monitor_getch (void)
void	mutt_push_macro_event (int ch, int op)
	Add the character/operation to the macro buffer.
void	mutt_push_macro_repeated (char *macro, int count)
	Push a macro string into the input queue, optionally repeated.
void	mutt_unget_ch (int ch)
	Return a keystroke to the input buffer.
void	mutt_unget_op (int op)
	Return an operation to the input buffer.

Detailed Description

Get a key from the user.

Authors

• Richard Russon

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 get.h.

Macro Definition Documentation

KEY_COUNT_MAX_DIGITS

#define KEY_COUNT_MAX_DIGITS   6

Maximum number of digits in a key count prefix, e.g. 123j

Definition at line 46 of file get.h.

KEY_SEQ_MAX_LEN

#define KEY_SEQ_MAX_LEN   8

Maximum number of keys in a key sequence, e.g. abc

Definition at line 48 of file get.h.

Typedef Documentation

GetChFlags

typedef uint8_t GetChFlags

Definition at line 43 of file get.h.

KeyGatherFlags

typedef uint8_t KeyGatherFlags

Definition at line 59 of file get.h.

MenuFuncFlags

typedef uint8_t MenuFuncFlags

Definition at line 69 of file get.h.

Enumeration Type Documentation

GetChFlag

enum GetChFlag

Flags for mutt_getch(), e.g.

GETCH_NONE

Enumerator
GETCH_NONE	No flags are set.
GETCH_IGNORE_MACRO	Don't use MacroEvents.
GETCH_NO_COUNTER	km_dokey(): disable numeric count prefix parsing
GETCH_NO_FEEDBACK	km_dokey(): suppress key progress notifications

Definition at line 36 of file get.h.

{
  GETCH_NONE         =       0,  
  GETCH_IGNORE_MACRO = 1U << 0,  
  GETCH_NO_COUNTER   = 1U << 1,  
  GETCH_NO_FEEDBACK  = 1U << 2,  
};

KeyGatherFlag

enum KeyGatherFlag

Flags for gather_functions(), e.g.

KEY_GATHER_NO_MATCH

Enumerator
KEY_GATHER_NO_MATCH	No bindings match the search string.
KEY_GATHER_MATCH	Binding matches the search string.
KEY_GATHER_LONGER	No bindings match, but longer strings might.

Definition at line 53 of file get.h.

{
  KEY_GATHER_NO_MATCH =       0,  
  KEY_GATHER_MATCH    = 1U << 0,  
  KEY_GATHER_LONGER   = 1U << 1,  
};

MenuFuncFlag

enum MenuFuncFlag

Menu function property flags.

Enumerator
MFF_NONE	No flags are set.
MFF_DEPRECATED	Function is deprecated.

Definition at line 64 of file get.h.

{
  MFF_NONE       =       0,  
  MFF_DEPRECATED = 1U << 1,  
};

Function Documentation

ARRAY_HEAD() [1/2]

ARRAY_HEAD	(	KeyEventArray	,
		struct KeyEvent	)

ARRAY_HEAD() [2/2]

ARRAY_HEAD	(	KeymapMatchArray	,
		struct KeymapMatch	)

Here is the call graph for this function:

array_add()

void array_add	(	struct KeyEventArray *	a,
		int	ch,
		int	op )

Add an event to the end of the array.

Parameters

a	Array
ch	Character
op	Operation, e.g. OP_DELETE

Definition at line 120 of file get.c.

{
  struct KeyEvent event = { ch, op, 0 };
  ARRAY_ADD(a, event);
}

Here is the caller graph for this function:

array_pop()

struct KeyEvent * array_pop

(

struct KeyEventArray *

a

)

Remove an event from the array.

Parameters

a

Array

Return values

ptr

Event

Definition at line 102 of file get.c.

{
  if (ARRAY_EMPTY(a))
  {
    return NULL;
  }
 
  struct KeyEvent *event = ARRAY_LAST(a);
  ARRAY_SHRINK(a, 1);
  return event;
}

Here is the caller graph for this function:

array_to_endcond()

void array_to_endcond

(

struct KeyEventArray *

a

)

Clear the array until an OP_END_COND.

Parameters

a

Array

Definition at line 130 of file get.c.

{
  while (!ARRAY_EMPTY(a))
  {
    if (array_pop(a)->op == OP_END_COND)
    {
      return;
    }
  }
}

Here is the call graph for this function:

Here is the caller graph for this function:

gather_functions()

KeyGatherFlags gather_functions	(	const struct MenuDefinition *	md,
		const keycode_t *	keys,
		int	key_len,
		struct KeymapMatchArray *	kma )

Find functions whose keybindings match.

Parameters

[in]	md	Menu Definition of all valid functions
[in]	keys	User-entered key string to match
[in]	key_len	Length of key string
[out]	kma	Array for the results

Return values

flags

Results, e.g. KEY_GATHER_MATCH

Definition at line 428 of file get.c.

{
  if (!md || !keys || !kma)
    return 0;
 
  struct SubMenu **smp = NULL;
  KeyGatherFlags flags = KEY_GATHER_NO_MATCH;
 
  ARRAY_FOREACH(smp, &md->submenus)
  {
    struct Keymap *km = NULL;
 
    STAILQ_FOREACH(km, &(*smp)->keymaps, entries)
    {
      if (key_len > km->len)
        continue;
 
      bool match = true;
 
      for (int i = 0; i < key_len; i++)
      {
        if (keys[i] != km->keys[i])
        {
          match = false;
          break;
        }
      }
 
      if (match)
      {
        KeyGatherFlags fmatch = KEY_GATHER_NO_MATCH;
        if (km->len == key_len)
          fmatch = KEY_GATHER_MATCH;
        else
          fmatch = KEY_GATHER_LONGER;
 
        flags |= fmatch;
 
        struct KeymapMatch kmatch = { md->id, fmatch, km };
        ARRAY_ADD(kma, kmatch);
      }
    }
  }
 
  return flags;
}

Here is the caller graph for this function:

generic_tokenize_push_string()

void generic_tokenize_push_string

(

char *

s

)

Parse and queue a 'push' command.

Parameters

s	String to push into the key queue

Parses s for <function> syntax and adds the whole sequence the macro buffer.

Definition at line 352 of file get.c.

{
  struct KeyModuleData *mod_data = neomutt_get_module_data(NeoMutt, MODULE_ID_KEY);
  char *pp = NULL;
  char *p = s + mutt_str_len(s) - 1;
  size_t l;
  int i;
  int op = OP_NULL;
 
  while (p >= s)
  {
    /* if we see something like "<PageUp>", look to see if it is a real
     * function name and return the corresponding value */
    if (*p == '>')
    {
      for (pp = p - 1; pp >= s && *pp != '<'; pp--)
        ; // do nothing
 
      if (pp >= s)
      {
        i = parse_fkey(pp);
        if (i > 0)
        {
          mutt_push_macro_event(KEY_F(i), 0);
          p = pp - 1;
          continue;
        }
 
        l = p - pp + 1;
        for (i = 0; mod_data->key_names[i].name; i++)
        {
          if (mutt_istrn_equal(pp, mod_data->key_names[i].name, l))
            break;
        }
        if (mod_data->key_names[i].name)
        {
          /* found a match */
          mutt_push_macro_event(mod_data->key_names[i].value, 0);
          p = pp - 1;
          continue;
        }
 
        /* See if it is a valid command
         * skip the '<' and the '>' when comparing */
        struct Buffer *buf = buf_pool_get();
        buf_strcpy_n(buf, pp + 1, l - 2);
 
        for (enum MenuType j = 0; j < MENU_MAX; j++)
        {
          op = km_get_op_menu(j, buf_string(buf));
          if (op != OP_NULL)
            break;
        }
 
        buf_pool_release(&buf);
 
        if (op != OP_NULL)
        {
          mutt_push_macro_event(0, op);
          p = pp - 1;
          continue;
        }
      }
    }
    mutt_push_macro_event((unsigned char) *p--, 0); /* independent 8 bits chars */
  }
}

Here is the call graph for this function:

Here is the caller graph for this function:

km_dokey()

struct KeyEvent km_dokey	(	const struct MenuDefinition *	md,
		GetChFlags	flags )

Determine what a keypress should do.

Parameters

md	Menu Definition
flags	Flags, e.g. GETCH_IGNORE_MACRO

Return values

ptr

Event

Definition at line 519 of file get.c.

{
  struct KeyEvent event = { 0, OP_NULL, 0 };
  enum DokeyState state = DKS_START;
  int count = 0;
  int count_digits = 0;
  int key_len = 0;
  struct Keymap *pending_exact = NULL;
  bool feedback_active = false;
  keycode_t keys[KEY_SEQ_MAX_LEN] = { 0 };
 
  const short c_key_timeout_idle = cs_subset_number(NeoMutt->sub, "key_timeout_idle");
  const short c_key_timeout_progress = cs_subset_number(NeoMutt->sub, "key_timeout_partial");
 
  if (!md)
    return event;
 
  for (int n = 0; n < MaxKeyLoop; n++)
  {
    const int timeout_ms = (state == DKS_START) ? c_key_timeout_idle : c_key_timeout_progress;
    event = mutt_getch_timeout(flags, timeout_ms);
 
    // abort, timeout, repaint
    if (event.op < OP_NULL)
    {
      if (event.op == OP_TIMEOUT)
      {
        if ((state == DKS_NEED_MORE) && pending_exact)
        {
          if (pending_exact->op != OP_MACRO)
          {
            key_progress_notify(md, count, keys, key_len, flags);
            key_progress_notify(md, 0, NULL, 0, flags);
            return (struct KeyEvent) { 0, pending_exact->op, count };
          }
 
          if (flags & GETCH_IGNORE_MACRO)
          {
            key_progress_notify(md, 0, NULL, 0, flags);
            return (struct KeyEvent) { 0, OP_NULL, 0 };
          }
 
          mutt_push_macro_repeated(pending_exact->macro, count_digits > 0 ? count : 0);
          state = DKS_START;
          count = 0;
          count_digits = 0;
          key_len = 0;
          pending_exact = NULL;
          memset(keys, 0, sizeof(keys));
          feedback_active = false;
          key_progress_notify(md, 0, NULL, 0, flags);
          continue;
        }
      }
 
      if (feedback_active || (state != DKS_START))
      {
        key_progress_notify(md, 0, NULL, 0, flags);
      }
      mutt_debug(LL_DEBUG3, "KEY: getch() %s\n", opcodes_get_name(event.op));
      return event;
    }
 
    // macro op pushed into queue (e.g. from `exec`)
    if (event.op > OP_NULL)
    {
      if (feedback_active || (state != DKS_START))
      {
        key_progress_notify(md, 0, NULL, 0, flags);
      }
      // Apply any count digits that arrived ahead of this op
      // (e.g. "5<next-entry>" inside a macro body),
      // preserving an explicit count already attached to the event.
      if ((event.count == 0) && (count_digits > 0))
        event.count = count;
      return event;
    }
 
    mutt_debug(LL_DEBUG3, "KEY: getch() '%c'\n", isprint(event.ch) ? event.ch : '?');
 
    // Check if digit keys have explicit bindings before using them as a counter
    if (!(flags & GETCH_NO_COUNTER) && (state != DKS_NEED_MORE) &&
        (event.ch >= '0') && (event.ch <= '9'))
    {
      keycode_t digit_key = event.ch;
      struct KeymapMatchArray digit_kma = ARRAY_HEAD_INITIALIZER;
      KeyGatherFlags digit_kgf = gather_functions(md, &digit_key, 1, &digit_kma);
      bool digit_bound = (digit_kgf & KEY_GATHER_MATCH);
      ARRAY_FREE(&digit_kma);
 
      if (!digit_bound)
      {
        if (count_digits >= KEY_COUNT_MAX_DIGITS)
        {
          key_progress_notify(md, count, keys, key_len, flags);
          key_progress_notify(md, 0, NULL, 0, flags);
          return (struct KeyEvent) { event.ch, OP_NULL, 0 };
        }
 
        const int digit = event.ch - '0';
        if ((count > (INT_MAX / 10)) ||
            ((count == (INT_MAX / 10)) && (digit > (INT_MAX % 10))))
        {
          key_progress_notify(md, count, keys, key_len, flags);
          key_progress_notify(md, 0, NULL, 0, flags);
          return (struct KeyEvent) { event.ch, OP_NULL, 0 };
        }
 
        count = (count * 10) + digit;
        count_digits++;
        state = DKS_COUNTER;
        feedback_active = true;
        key_progress_notify(md, count, keys, key_len, flags);
        continue;
      }
    }
 
    if (key_len >= KEY_SEQ_MAX_LEN)
    {
      key_progress_notify(md, count, keys, key_len, flags);
      key_progress_notify(md, 0, NULL, 0, flags);
      return (struct KeyEvent) { event.ch, OP_NULL, 0 };
    }
 
    keys[key_len] = event.ch;
    key_len++;
 
    struct KeymapMatchArray kma = ARRAY_HEAD_INITIALIZER;
    KeyGatherFlags kgf = gather_functions(md, keys, key_len, &kma);
 
    mutt_debug(LL_DEBUG3, "KEY: flags = %x\n", kgf);
 
    bool has_exact = false;
    bool has_longer = false;
    pending_exact = NULL;
 
    struct KeymapMatch *kmatch = NULL;
    ARRAY_FOREACH(kmatch, &kma)
    {
      if (kmatch->flags == KEY_GATHER_MATCH)
      {
        has_exact = true;
        if (!pending_exact)
          pending_exact = kmatch->keymap;
      }
      else if (kmatch->flags == KEY_GATHER_LONGER)
      {
        has_longer = true;
      }
    }
 
    if (!has_exact && !has_longer)
    {
      key_progress_notify(md, count, keys, key_len, flags);
      key_progress_notify(md, 0, NULL, 0, flags);
      mutt_debug(LL_DEBUG3, "KEY: FAIL1: ('%c', %s)\n",
                 isprint(event.ch) ? event.ch : '?', opcodes_get_name(event.op));
      ARRAY_FREE(&kma);
      return event;
    }
 
    if (has_exact && has_longer)
    {
      state = DKS_NEED_MORE;
      feedback_active = true;
      key_progress_notify(md, count, keys, key_len, flags);
      ARRAY_FREE(&kma);
      continue;
    }
 
    if (!has_exact && has_longer)
    {
      state = DKS_NEED_MORE;
      feedback_active = true;
      key_progress_notify(md, count, keys, key_len, flags);
      ARRAY_FREE(&kma);
      continue;
    }
 
    if (has_exact && pending_exact)
    {
      struct Keymap *map = pending_exact;
 
      if (map->op != OP_MACRO)
      {
        key_progress_notify(md, count, keys, key_len, flags);
        key_progress_notify(md, 0, NULL, 0, flags);
        mutt_debug(LL_DEBUG3, "KEY: SUCCESS: ('%c', %s)\n",
                   isprint(event.ch) ? event.ch : '?', opcodes_get_name(map->op));
        ARRAY_FREE(&kma);
        return (struct KeyEvent) { event.ch, map->op, count_digits > 0 ? count : 0 };
      }
 
      /* #GETCH_IGNORE_MACRO turns off processing the MacroEvents buffer
       * in mutt_getch().  Generating new macro events during that time would
       * result in undesired behavior once the option is turned off.
       *
       * Originally this returned -1, however that results in an unbuffered
       * username or password prompt being aborted.  Returning OP_NULL allows
       * mw_get_field() to display the keybinding pressed instead.
       *
       * It may be unexpected for a macro's keybinding to be returned,
       * but less so than aborting the prompt.  */
      if (flags & GETCH_IGNORE_MACRO)
      {
        key_progress_notify(md, 0, NULL, 0, flags);
        ARRAY_FREE(&kma);
        return (struct KeyEvent) { event.ch, OP_NULL, 0 };
      }
 
      mutt_push_macro_repeated(map->macro, count_digits > 0 ? count : 0);
      state = DKS_START;
      count = 0;
      count_digits = 0;
      key_len = 0;
      pending_exact = NULL;
      memset(keys, 0, sizeof(keys));
      feedback_active = false;
      key_progress_notify(md, 0, NULL, 0, flags);
      ARRAY_FREE(&kma);
      continue;
    }
 
    ARRAY_FREE(&kma);
  }
 
  key_progress_notify(md, 0, NULL, 0, flags);
  mutt_flushinp();
  mutt_error(_("Macro loop detected"));
  return (struct KeyEvent) { '\0', OP_ABORT, 0 };
}

Here is the call graph for this function:

Here is the caller graph for this function:

km_error_key()

void km_error_key

(

const struct MenuDefinition *

md

)

Handle an unbound key sequence.

Parameters

md	Menu Definition

Definition at line 328 of file get.c.

{
  if (!md)
    return;
 
  struct Keymap *key = km_find_func(md, OP_HELP);
  if (!key)
  {
    mutt_error(_("Key is not bound"));
    return;
  }
 
  struct Buffer *buf = buf_pool_get();
  keymap_expand_key(key, buf);
  mutt_error(_("Key is not bound.  Press '%s' for help."), buf_string(buf));
  buf_pool_release(&buf);
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_flushinp()

void mutt_flushinp

(

void

)

MacroEvents moved to KeyModuleData UngetKeyEvents moved to KeyModuleData.

Empty all the keyboard buffers

Definition at line 81 of file get.c.

{
  struct KeyModuleData *mod_data = neomutt_get_module_data(NeoMutt, MODULE_ID_KEY);
  const size_t unget_count = ARRAY_SIZE(&mod_data->unget_key_events);
  const size_t macro_count = ARRAY_SIZE(&mod_data->macro_events);
  ARRAY_SHRINK(&mod_data->unget_key_events, ARRAY_SIZE(&mod_data->unget_key_events));
  ARRAY_SHRINK(&mod_data->macro_events, ARRAY_SIZE(&mod_data->macro_events));
 
  if ((unget_count + macro_count) > 0)
  {
    mutt_debug(LL_DEBUG1, "Flushed %zu queued key events (%zu unget, %zu macro)\n",
               unget_count + macro_count, unget_count, macro_count);
  }
  flushinp();
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_flush_macro_to_endcond()

void mutt_flush_macro_to_endcond

(

void

)

Drop a macro from the input buffer.

All the macro text is deleted until an OP_END_COND command, or the buffer is empty.

Definition at line 185 of file get.c.

{
  struct KeyModuleData *mod_data = neomutt_get_module_data(NeoMutt, MODULE_ID_KEY);
  array_to_endcond(&mod_data->macro_events);
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_getch()

struct KeyEvent mutt_getch

(

GetChFlags

flags

)

Read a character from the input buffer.

Parameters

flags

Flags, e.g. GETCH_IGNORE_MACRO

Return values

obj	KeyEvent to process

The priority for reading events is:

1. UngetKeyEvents buffer
2. MacroEvents buffer
3. Keyboard

This function can return:

• Abort { 0, OP_ABORT, 0 }
• Repaint { 0, OP_REPAINT, 0 }
• Timeout { 0, OP_TIMEOUT, 0 }

Definition at line 319 of file get.c.

{
  return mutt_getch_timeout(flags, 1000);
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_monitor_getch()

int mutt_monitor_getch

(

void

)

mutt_push_macro_event()

void mutt_push_macro_event	(	int	ch,
		int	op )

Add the character/operation to the macro buffer.

Parameters

ch	Character to add
op	Operation to add

Adds the ch/op to the macro buffer. This should be used for macros, push, and exec commands only.

Definition at line 173 of file get.c.

{
  struct KeyModuleData *mod_data = neomutt_get_module_data(NeoMutt, MODULE_ID_KEY);
  array_add(&mod_data->macro_events, ch, op);
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_push_macro_repeated()

void mutt_push_macro_repeated	(	char *	macro,
		int	count )

Push a macro string into the input queue, optionally repeated.

Parameters

macro	Macro string to expand
count	Number of times to repeat (0 or 1 means once)

The repeat count is clamped to $macro_repeat_max to bound queue growth.

Definition at line 60 of file get.c.

{
  int repeat = (count > 0) ? count : 1;
 
  const short c_macro_repeat_max = cs_subset_number(NeoMutt->sub, "macro_repeat_max");
  if ((c_macro_repeat_max > 0) && (repeat > c_macro_repeat_max))
    repeat = c_macro_repeat_max;
 
  for (int i = 0; i < repeat; i++)
    generic_tokenize_push_string(macro);
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_unget_ch()

void mutt_unget_ch

(

int

ch

)

Return a keystroke to the input buffer.

Parameters

ch

Key press

This puts events into the UngetKeyEvents buffer

Definition at line 147 of file get.c.

{
  struct KeyModuleData *mod_data = neomutt_get_module_data(NeoMutt, MODULE_ID_KEY);
  array_add(&mod_data->unget_key_events, ch, OP_NULL);
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_unget_op()

void mutt_unget_op

(

int

op

)

Return an operation to the input buffer.

Parameters

op	Operation, e.g. OP_DELETE

This puts events into the UngetKeyEvents buffer

Definition at line 159 of file get.c.

{
  struct KeyModuleData *mod_data = neomutt_get_module_data(NeoMutt, MODULE_ID_KEY);
  array_add(&mod_data->unget_key_events, 0, op);
}

Here is the call graph for this function:

Here is the caller graph for this function: