lib.c File Reference

Key helper functions. More...

#include "config.h"
#include <ctype.h>
#include <limits.h>
#include <stdbool.h>
#include <stdlib.h>
#include <string.h>
#include <wchar.h>
#include "mutt/lib.h"
#include "gui/lib.h"
#include "key/lib.h"
#include "menu/lib.h"

Include dependency graph for lib.c:

Go to the source code of this file.

Functions
void	mutt_keymap_free (struct Keymap **ptr)
	Free a Keymap.
struct Keymap *	alloc_keys (size_t len, keycode_t *keys)
	Allocate space for a sequence of keys.
int	parse_fkey (char *s)
	Parse a function key string.
static int	parse_keycode (const char *s)
	Parse a numeric keycode.
size_t	parsekeys (const char *str, keycode_t *d, size_t max)
	Parse a key string into key codes.
struct Keymap *	km_compare_keys (struct Keymap *k1, struct Keymap *k2, size_t *pos)
	Compare two keymaps' keyscodes and return the bigger one.
int	get_op (const struct MenuFuncOp *funcs, const char *start, size_t len)
	Get the function by its name.
const char *	mutt_get_func (const struct MenuFuncOp *funcs, int op)
	Get the name of a function.
void	escape_macro (const char *macro, struct Buffer *buf)
	Escape any special characters in a macro.
bool	is_bound (const struct KeymapList *km_list, int op)
	Does a function have a keybinding?
int	binding_sort (const void *a, const void *b, void *sdata)
	Compare two BindingInfo by their keybinding - Implements sort_t -.
int	measure_column (struct BindingInfoArray *bia, int col)
	Measure one column of a table.
int	gather_unbound (const struct MenuFuncOp *funcs, const struct KeymapList *km_menu, const struct KeymapList *km_aux, struct BindingInfoArray *bia_unbound)
	Gather info about unbound functions for one menu.
void	km_keyname (int c, struct Buffer *buf)
	Get the human name for a key.
bool	km_expand_key (struct Keymap *map, struct Buffer *buf)
	Get the key string bound to a Keymap.
void	km_expand_key_string (char *str, struct Buffer *buf)
	Get a human-readable key string.
struct Keymap *	km_find_func (enum MenuType mtype, int func)
	Find a function's mapping in a Menu.
const struct MenuFuncOp *	km_get_table (enum MenuType mtype)
	Lookup a Menu's functions.
const char *	help_lookup_function (int op, enum MenuType menu)
	Find a keybinding for an operation.
void	gather_menu (enum MenuType menu, struct BindingInfoArray *bia_bind, struct BindingInfoArray *bia_macro)
	Gather info about one menu.

Variables
const struct MenuFuncOp	OpAlias []
	Functions for the Alias Menu.
const struct MenuFuncOp	OpAttachment []
	Functions for the Attachment Menu.
const struct MenuFuncOp	OpAutocrypt []
	Functions for the Autocrypt Account.
const struct MenuFuncOp	OpBrowser []
	Functions for the file Browser Menu.
const struct MenuFuncOp	OpCompose []
	Functions for the Compose Menu.
const struct MenuFuncOp	OpEditor []
	Functions for the Editor Menu.
const struct MenuFuncOp	OpIndex []
	Functions for the Index Menu.
const struct MenuFuncOp	OpPager []
	Functions for the Pager Menu.
const struct MenuFuncOp	OpPgp []
	Functions for the Pgp Menu.
const struct MenuFuncOp	OpPostponed []
	Functions for the Postpone Menu.
const struct MenuFuncOp	OpQuery []
	Functions for the external Query Menu.
const struct MenuFuncOp	OpSmime []
	Functions for the Smime Menu.
struct Mapping	KeyNames []
	Key name lookup table.
keycode_t	AbortKey
	code of key to abort prompts, normally Ctrl-G
struct KeymapList	Keymaps [MENU_MAX]
	Array of key mappings, one for each MenuType.

Detailed Description

Key helper functions.

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 lib.c.

Function Documentation

mutt_keymap_free()

void mutt_keymap_free

(

struct Keymap **

ptr

)

Free a Keymap.

Parameters

ptr	Keymap to free

Definition at line 130 of file lib.c.

{
  if (!ptr || !*ptr)
    return;
 
  struct Keymap *km = *ptr;
  FREE(&km->macro);
  FREE(&km->desc);
  FREE(&km->keys);
 
  FREE(ptr);
}

Here is the caller graph for this function:

alloc_keys()

struct Keymap * alloc_keys	(	size_t	len,
		keycode_t *	keys
	)

Allocate space for a sequence of keys.

Parameters

len	Number of keys
keys	Array of keys

Return values

ptr	Sequence of keys

Definition at line 149 of file lib.c.

{
  struct Keymap *p = MUTT_MEM_CALLOC(1, struct Keymap);
  p->len = len;
  p->keys = MUTT_MEM_CALLOC(len, keycode_t);
  memcpy(p->keys, keys, len * sizeof(keycode_t));
  return p;
}

Here is the caller graph for this function:

parse_fkey()

int parse_fkey

(

char *

s

)

Parse a function key string.

Parameters

s	String to parse

Return values

num	Number of the key

Given "<f8>", it will return 8.

Definition at line 165 of file lib.c.

{
  char *t = NULL;
  int n = 0;
 
  if ((s[0] != '<') || (tolower(s[1]) != 'f'))
    return -1;
 
  for (t = s + 2; *t && isdigit((unsigned char) *t); t++)
  {
    n *= 10;
    n += *t - '0';
  }
 
  if (*t != '>')
    return -1;
  return n;
}

Here is the caller graph for this function:

parse_keycode()

static int parse_keycode ( const char *  s )

static

Parse a numeric keycode.

Parameters

s	String to parse

Return values

num	Number of the key

This function parses the string <NNN> and uses the octal value as the key to bind.

Definition at line 192 of file lib.c.

{
  char *end_char = NULL;
  long int result = strtol(s + 1, &end_char, 8);
  /* allow trailing whitespace, eg.  < 1001 > */
  while (isspace(*end_char))
    end_char++;
  /* negative keycodes don't make sense, also detect overflow */
  if ((*end_char != '>') || (result < 0) || (result == LONG_MAX))
  {
    return -1;
  }
 
  return result;
}

Here is the caller graph for this function:

parsekeys()

size_t parsekeys	(	const char *	str,
		keycode_t *	d,
		size_t	max
	)

Parse a key string into key codes.

Parameters

str	Key string
d	Array for key codes
max	Maximum length of key sequence

Return values

num	Length of key sequence

Definition at line 215 of file lib.c.

{
  int n;
  size_t len = max;
  char buf[128] = { 0 };
  char c;
  char *t = NULL;
 
  mutt_str_copy(buf, str, sizeof(buf));
  char *s = buf;
 
  while (*s && len)
  {
    *d = '\0';
    if ((*s == '<') && (t = strchr(s, '>')))
    {
      t++;
      c = *t;
      *t = '\0';
 
      n = mutt_map_get_value(s, KeyNames);
      if (n != -1)
      {
        s = t;
        *d = n;
      }
      else if ((n = parse_fkey(s)) > 0)
      {
        s = t;
        *d = KEY_F(n);
      }
      else if ((n = parse_keycode(s)) > 0)
      {
        s = t;
        *d = n;
      }
 
      *t = c;
    }
 
    if (!*d)
    {
      *d = (unsigned char) *s;
      s++;
    }
    d++;
    len--;
  }
 
  return max - len;
}

Here is the call graph for this function:

Here is the caller graph for this function:

km_compare_keys()

struct Keymap * km_compare_keys	(	struct Keymap *	k1,
		struct Keymap *	k2,
		size_t *	pos
	)

Compare two keymaps' keyscodes and return the bigger one.

Parameters

k1	first keymap to compare
k2	second keymap to compare
pos	position where the two keycodes differ

Return values

ptr	Keymap with a bigger ASCII keycode

Definition at line 274 of file lib.c.

{
  *pos = 0;
 
  while (*pos < k1->len && *pos < k2->len)
  {
    if (k1->keys[*pos] < k2->keys[*pos])
      return k2;
    else if (k1->keys[*pos] > k2->keys[*pos])
      return k1;
    else
      *pos = *pos + 1;
  }
 
  return NULL;
}

Here is the caller graph for this function:

get_op()

int get_op	(	const struct MenuFuncOp *	funcs,
		const char *	start,
		size_t	len
	)

Get the function by its name.

Parameters

funcs	Functions table
start	Name of function to find
len	Length of string to match

Return values

num	Operation, e.g. OP_DELETE

Definition at line 298 of file lib.c.

{
  for (int i = 0; funcs[i].name; i++)
  {
    if (mutt_istrn_equal(start, funcs[i].name, len) && (mutt_str_len(funcs[i].name) == len))
    {
      return funcs[i].op;
    }
  }
 
  return OP_NULL;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_get_func()

const char * mutt_get_func	(	const struct MenuFuncOp *	funcs,
		int	op
	)

Get the name of a function.

Parameters

funcs	Functions table
op	Operation, e.g. OP_DELETE

Return values

ptr	Name of function
NULL	Operation not found

Note

This returns a static string.

Definition at line 320 of file lib.c.

{
  for (int i = 0; funcs[i].name; i++)
  {
    if (funcs[i].op == op)
      return funcs[i].name;
  }
 
  return NULL;
}

Here is the caller graph for this function:

escape_macro()

void escape_macro	(	const char *	macro,
		struct Buffer *	buf
	)

Escape any special characters in a macro.

Parameters

[in]	macro	Macro string
[out]	buf	Buffer for the result

Replace characters, such as <Enter> with the literal "\n"

Definition at line 338 of file lib.c.

{
  wchar_t wc = 0;
  size_t k;
  size_t len = mutt_str_len(macro);
  mbstate_t mbstate1 = { 0 };
  mbstate_t mbstate2 = { 0 };
 
  for (; (len > 0) && (k = mbrtowc(&wc, macro, MB_LEN_MAX, &mbstate1)); macro += k, len -= k)
  {
    if ((k == ICONV_ILLEGAL_SEQ) || (k == ICONV_BUF_TOO_SMALL))
    {
      if (k == ICONV_ILLEGAL_SEQ)
        memset(&mbstate1, 0, sizeof(mbstate1));
      k = (k == ICONV_ILLEGAL_SEQ) ? 1 : len;
      wc = ReplacementChar;
    }
 
    const int w = wcwidth(wc);
    if (IsWPrint(wc) && (w >= 0))
    {
      char tmp[MB_LEN_MAX * 2] = { 0 };
      if (wcrtomb(tmp, wc, &mbstate2) != ICONV_ILLEGAL_SEQ)
      {
        buf_addstr(buf, tmp);
      }
    }
    else if ((wc < 0x20) || (wc == 0x7f))
    {
      if (wc == '\033') // Escape
        buf_addstr(buf, "\\e");
      else if (wc == '\n')
        buf_addstr(buf, "\\n");
      else if (wc == '\r')
        buf_addstr(buf, "\\r");
      else if (wc == '\t')
        buf_addstr(buf, "\\t");
      else
        buf_add_printf(buf, "^%c", (char) ((wc + '@') & 0x7f));
    }
    else
    {
      buf_addch(buf, '?');
    }
  }
}

Here is the call graph for this function:

Here is the caller graph for this function:

is_bound()

bool is_bound	(	const struct KeymapList *	km_list,
		int	op
	)

Does a function have a keybinding?

Parameters

km_list	Keymap to examine
op	Operation, e.g. OP_DELETE

Return values

true	A key is bound to that operation

Definition at line 391 of file lib.c.

{
  struct Keymap *map = NULL;
  STAILQ_FOREACH(map, km_list, entries)
  {
    if (map->op == op)
      return true;
  }
  return false;
}

Here is the caller graph for this function:

measure_column()

int measure_column	(	struct BindingInfoArray *	bia,
		int	col
	)

Measure one column of a table.

Parameters

bia	Array of binding info
col	Column to measure

Return values

num	Width of widest column

Definition at line 419 of file lib.c.

{
  int max_width = 0;
 
  struct BindingInfo *bi = NULL;
  ARRAY_FOREACH(bi, bia)
  {
    const int col_width = mutt_strwidth(bi->a[col]);
    max_width = MAX(max_width, col_width);
  }
 
  return max_width;
}

Here is the call graph for this function:

Here is the caller graph for this function:

gather_unbound()

int gather_unbound	(	const struct MenuFuncOp *	funcs,
		const struct KeymapList *	km_menu,
		const struct KeymapList *	km_aux,
		struct BindingInfoArray *	bia_unbound
	)

Gather info about unbound functions for one menu.

Parameters

funcs	List of functions
km_menu	Keymaps for the menu
km_aux	Keymaps for generic
bia_unbound	Unbound functions

Return values

num	Number of unbound functions

Definition at line 441 of file lib.c.

{
  for (int i = 0; funcs[i].name; i++)
  {
    if (!is_bound(km_menu, funcs[i].op) &&
        (!km_aux || !is_bound(km_aux, funcs[i].op)))
    {
      struct BindingInfo bi = { 0 };
      bi.a[0] = NULL;
      bi.a[1] = funcs[i].name;
      bi.a[2] = _(opcodes_get_description(funcs[i].op));
      ARRAY_ADD(bia_unbound, bi);
    }
  }
 
  return ARRAY_SIZE(bia_unbound);
}

Here is the call graph for this function:

Here is the caller graph for this function:

km_keyname()

void km_keyname	(	int	c,
		struct Buffer *	buf
	)

Get the human name for a key.

Parameters

[in]	c	Key code
[out]	buf	Buffer for the result

Definition at line 465 of file lib.c.

{
  const char *name = mutt_map_get_name(c, KeyNames);
  if (name)
  {
    buf_addstr(buf, name);
    return;
  }
 
  if ((c < 256) && (c > -128) && iscntrl((unsigned char) c))
  {
    if (c < 0)
      c += 256;
 
    if (c < 128)
    {
      buf_addch(buf, '^');
      buf_addch(buf, (c + '@') & 0x7f);
    }
    else
    {
      buf_add_printf(buf, "\\%d%d%d", c >> 6, (c >> 3) & 7, c & 7);
    }
  }
  else if ((c >= KEY_F0) && (c < KEY_F(256))) /* this maximum is just a guess */
  {
    buf_add_printf(buf, "<F%d>", c - KEY_F0);
  }
  else if ((c < 256) && (c >= -128) && IsPrint(c))
  {
    buf_add_printf(buf, "%c", (unsigned char) c);
  }
  else
  {
    buf_add_printf(buf, "<%ho>", (unsigned short) c);
  }
}

Here is the call graph for this function:

Here is the caller graph for this function:

km_expand_key()

bool km_expand_key	(	struct Keymap *	map,
		struct Buffer *	buf
	)

Get the key string bound to a Keymap.

Parameters

[in]	map	Keybinding map
[out]	buf	Buffer for the result

Return values

true

Success

Definition at line 509 of file lib.c.

{
  if (!map || !buf)
    return false;
 
  for (int i = 0; i < map->len; i++)
  {
    km_keyname(map->keys[i], buf);
  }
 
  return true;
}

Here is the call graph for this function:

Here is the caller graph for this function:

km_expand_key_string()

void km_expand_key_string	(	char *	str,
		struct Buffer *	buf
	)

Get a human-readable key string.

Parameters

[in]	str	Raw key string
[out]	buf	Buffer for the key string

Definition at line 527 of file lib.c.

{
  for (; *str; str++)
  {
    km_keyname(*str, buf);
  }
}

Here is the call graph for this function:

Here is the caller graph for this function:

km_find_func()

struct Keymap * km_find_func	(	enum MenuType	mtype,
		int	func
	)

Find a function's mapping in a Menu.

Parameters

mtype	Menu type, e.g. MENU_PAGER
func	Function, e.g. OP_DELETE

Return values

ptr	Keymap for the function

Definition at line 541 of file lib.c.

{
  struct Keymap *np = NULL;
  STAILQ_FOREACH(np, &Keymaps[mtype], entries)
  {
    if (np->op == func)
      break;
  }
  return np;
}

Here is the caller graph for this function:

km_get_table()

const struct MenuFuncOp * km_get_table

(

enum MenuType

mtype

)

Lookup a Menu's functions.

Parameters

mtype

Menu type, e.g. MENU_EDITOR

Return values

ptr	Array of functions

Definition at line 557 of file lib.c.

{
  switch (mtype)
  {
    case MENU_ALIAS:
      return OpAlias;
    case MENU_ATTACHMENT:
      return OpAttachment;
#ifdef USE_AUTOCRYPT
    case MENU_AUTOCRYPT:
      return OpAutocrypt;
#endif
    case MENU_COMPOSE:
      return OpCompose;
    case MENU_DIALOG:
      return OpDialog;
    case MENU_EDITOR:
      return OpEditor;
    case MENU_FOLDER:
      return OpBrowser;
    case MENU_GENERIC:
      return OpGeneric;
    case MENU_INDEX:
      return OpIndex;
    case MENU_PAGER:
      return OpPager;
    case MENU_PGP:
      return OpPgp;
    case MENU_POSTPONED:
      return OpPostponed;
    case MENU_QUERY:
      return OpQuery;
    case MENU_SMIME:
      return OpSmime;
    default:
      return NULL;
  }
}

Here is the caller graph for this function:

help_lookup_function()

const char * help_lookup_function	(	int	op,
		enum MenuType	menu
	)

Find a keybinding for an operation.

Parameters

op	Operation, e.g. OP_DELETE
menu	Current Menu, e.g. MENU_PAGER

Return values

str	Key binding
NULL	No key binding found

Definition at line 603 of file lib.c.

{
  if ((menu != MENU_PAGER) && (menu != MENU_EDITOR) && (menu != MENU_GENERIC))
  {
    /* first look in the generic map for the function */
    const char *fn_name = mutt_get_func(OpGeneric, op);
    if (fn_name)
      return fn_name;
  }
 
  const struct MenuFuncOp *funcs = km_get_table(menu);
 
  return mutt_get_func(funcs, op);
}

Here is the call graph for this function:

Here is the caller graph for this function:

gather_menu()

void gather_menu	(	enum MenuType	menu,
		struct BindingInfoArray *	bia_bind,
		struct BindingInfoArray *	bia_macro
	)

Gather info about one menu.

Parameters

menu	Menu type
bia_bind	Array for bind results (may be NULL)
bia_macro	Array for macro results (may be NULL)

Definition at line 624 of file lib.c.

{
  struct Buffer *key_binding = buf_pool_get();
  struct Buffer *macro = buf_pool_get();
 
  struct Keymap *map = NULL;
  STAILQ_FOREACH(map, &Keymaps[menu], entries)
  {
    struct BindingInfo bi = { 0 };
 
    buf_reset(key_binding);
    km_expand_key(map, key_binding);
 
    if (map->op == OP_MACRO)
    {
      if (!bia_macro || (map->op == OP_NULL))
        continue;
 
      buf_reset(macro);
      escape_macro(map->macro, macro);
      bi.a[0] = buf_strdup(key_binding);
      bi.a[1] = buf_strdup(macro);
      bi.a[2] = map->desc;
      ARRAY_ADD(bia_macro, bi);
    }
    else
    {
      if (!bia_bind)
        continue;
 
      if (map->op == OP_NULL)
      {
        bi.a[0] = buf_strdup(key_binding);
        bi.a[1] = "noop";
        ARRAY_ADD(bia_bind, bi);
        continue;
      }
 
      bi.a[0] = buf_strdup(key_binding);
      bi.a[1] = help_lookup_function(map->op, menu);
      bi.a[2] = _(opcodes_get_description(map->op));
      ARRAY_ADD(bia_bind, bi);
    }
  }
 
  buf_pool_release(&key_binding);
  buf_pool_release(&macro);
}

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

OpAlias

const struct MenuFuncOp OpAlias[]

extern

Functions for the Alias Menu.

Definition at line 60 of file functions.c.

OpAttachment

const struct MenuFuncOp OpAttachment[]

extern

Functions for the Attachment Menu.

Definition at line 62 of file functions.c.

OpAutocrypt

const struct MenuFuncOp OpAutocrypt[]

extern

Functions for the Autocrypt Account.

Definition at line 54 of file functions.c.

OpBrowser

const struct MenuFuncOp OpBrowser[]

extern

Functions for the file Browser Menu.

Definition at line 72 of file functions.c.

OpCompose

const struct MenuFuncOp OpCompose[]

extern

Functions for the Compose Menu.

Definition at line 87 of file functions.c.

OpEditor

const struct MenuFuncOp OpEditor[]

extern

Functions for the Editor Menu.

Definition at line 53 of file functions.c.

OpIndex

const struct MenuFuncOp OpIndex[]

extern

Functions for the Index Menu.

Definition at line 90 of file functions.c.

OpPager

const struct MenuFuncOp OpPager[]

extern

Functions for the Pager Menu.

Definition at line 71 of file functions.c.

OpPgp

const struct MenuFuncOp OpPgp[]

extern

Functions for the Pgp Menu.

Definition at line 42 of file functions.c.

OpPostponed

const struct MenuFuncOp OpPostponed[]

extern

Functions for the Postpone Menu.

Definition at line 52 of file functions.c.

OpQuery

const struct MenuFuncOp OpQuery[]

extern

Functions for the external Query Menu.

Definition at line 76 of file functions.c.

OpSmime

const struct MenuFuncOp OpSmime[]

extern

Functions for the Smime Menu.

Definition at line 52 of file functions.c.

KeyNames

struct Mapping KeyNames[]

Key name lookup table.

Definition at line 59 of file lib.c.

AbortKey

keycode_t AbortKey

code of key to abort prompts, normally Ctrl-G

key to abort edits etc, normally Ctrl-G

Definition at line 121 of file lib.c.

Keymaps

struct KeymapList Keymaps[MENU_MAX]

Array of key mappings, one for each MenuType.

Array of Keymap keybindings, one for each Menu.

Definition at line 124 of file lib.c.