# Luakit Documentation / Modules / lousy.bind

# Module `lousy.bind`

lousy.bind library

Key, buffer and command binding functions.

## Functions

### lousy.bind.parse_mods (mods, remove_shift)

Parse a table of modifier keys into a string.

#### Parameters

- mods
  Type: table
  The table of modifier keys.
- remove_shift
  Type: boolean
  Optional
  Default: `false`
  Remove the shift key from the modifier table.

#### Return Values

- string
  A string of key names, separated by hyphens (-).

### lousy.bind.match_any (object, binds, args)

Match any 'any' bindings in a given table of bindings.

The bindings' callback functions are called in the order that they occur in the given table of bindings. If any callback function returns a value other than `false`, then matching stops and this function immediately returns `true`. Otherwise, if the callback returns `false`, matching continues.

#### Parameters

- object
  Type: any type
  An object passed through to any 'any' bindings called.
- binds
  Type: table
  A table of bindings to search.
- args
  Type: table
  A table of arguments passed through to any 'any' bindings called.

#### Return Values

- boolean
  `true` if an 'any' binding was ran successfully.

### lousy.bind.match_key (object, binds, mods, key, args)

Match any key binding in a given table of bindings.

The bindings' callback functions are called in the order that they occur in the given table of bindings. If any callback function returns a value other than `false`, then matching stops and this function immediately returns `true`. Otherwise, if the callback returns `false`, matching continues.

#### Parameters

- object
  Type: any type
  An object passed through to any key bindings called.
- binds
  Type: table
  A table of bindings to search.
- mods
  Type: string
  The string of modifier keys.
- key
  Type: string
  The key name.
- args
  Type: table
  A table of arguments passed through to any key bindings called.

#### Return Values

- boolean
  `true` if a key binding was ran successfully.

### lousy.bind.match_but (object, binds, mods, button, args)

Match any button binding in a given table of bindings.

The bindings' callback functions are called in the order that they occur in the given table of bindings. If any callback function returns a value other than `false`, then matching stops and this function immediately returns `true`. Otherwise, if the callback returns `false`, matching continues.

#### Parameters

- object
  Type: any type
  An object passed through to any key bindings called.
- binds
  Type: table
  A table of bindings to search.
- mods
  Type: string
  The table of modifier keys.
- button
  Type: string
  The button name.
- args
  Type: table
  A table of arguments passed through to any button bindings called.

#### Return Values

- boolean
  `true` if a key binding was ran successfully.

### lousy.bind.match_buf (object, binds, buffer, args)

Try and match a buffer binding in a given table of bindings and call that bindings callback function.

#### Parameters

- object
  Type: any type
  The first argument of the bind callback function.
- binds
  Type: table
  The table of binds in which to check for a match.
- buffer
  Type: string
  The buffer string to match.
- args
  Type: table
  The bind options/state/metadata table which is applied over the opts table given when the bind was created.

#### Return Values

- boolean
  `true` if a binding was matched and called.
- boolean
  `true` if a partial match exists.

### lousy.bind.match_cmd (object, binds, buffer, args)

Try and match a command or buffer binding in a given table of bindings and call that bindings callback function.

#### Parameters

- object
  Type: any type
  The first argument of the bind callback function.
- binds
  Type: table
  The table of binds in which to check for a match.
- buffer
  Type: string
  The buffer string to match.
- args
  Type: table
  The bind options/state/metadata table which is applied over the opts table given when the bind was created.

#### Return Values

- boolean
  `true` if either type of binding was matched and called.

### lousy.bind.hit (object, binds, mods, key, args)

Attempt to match either a key or buffer binding and execute it. This function is also responsible for performing operations on the buffer when necessary and the buffer is enabled.

When matching key bindings, this function ignores the case of `key`, and uses the presence of the Shift modifier to determine which bindings should be matched.

#### Parameters

- object
  Type: any type
  The first argument of the bind callback function.
- binds
  Type: table
  The table of binds in which to check for a match.
- mods
  Type: {string}
  The modifiers to match.
- key
  Type: string
  The key name to match.
- args
  Type: table
  The bind options/state/metadata table which is applied over the opts table given when the bind was created.

#### Return Values

- boolean
  `true` if a key or buffer binding was matched or if a key was added to the buffer.
- string
  The new buffer truncated to 10 characters (if you need more buffer then use the input bar for whatever you are doing). If no buffer binding could be matched, the returned buffer will be the empty string.

### lousy.bind.bind_to_string (b)

Produce a string describing the action that triggers a given binding. For example, a binding for the down-arrow key would produce `"<Down>"`.

#### Parameters

- b
  Type: table
  The binding.

#### Return Values

- string
  The binding description string.

### lousy.bind.add_bind (binds, bind, action, opts)

Bind a trigger to an action, adding the resulting binding to an array of bindings.

#### Parameters

- binds
  Type: table
  The array of bindings to add the new binding to.
- bind
  Type: string
  The trigger that will activate the action associated with this bind.
- action
  Type: table
  The action that will be activated.
- opts
  Type: table
  Optional
  A table of bind-time options that will be passed to the action when it is activated.

### lousy.bind.remove_bind (binds, bind)

Remove any binding with a specific trigger from the given array of bindings.

#### Parameters

- binds
  Type: table
  The array of bindings to remove the named binding from.
- bind
  Type: string
  The trigger to unbind.

#### Return Values

- table
  The associated action of the binding that was removed, or `nil` if not found.
- table
  The options of the binding that was removed, or `nil` if not found.

### lousy.bind.remap_bind (binds, new, old, keep)

Remap a binding from a given trigger to a new trigger, optionally keeping the original binding. In both cases, the new binding will have the same options as the original binding.

#### Parameters

- binds
  Type: table
  The array of bindings to remap within.
- new
  Type: string
  The new trigger to map from.
- old
  Type: string
  The existing trigger to remap.
- keep
  Type: boolean
  Optional
  Default: `false`
  Retain the existing binding.

## Properties

### lousy.bind.ignore_mask

Type: any type
Read-write
Set of modifiers to ignore.

### lousy.bind.map

Type: any type
Read-write
A table that contains mappings for key names.

### lousy.bind.mod_map

Type: any type
Read-write
A table that contains mappings for modifier names.

## Attribution

#### Copyright

- 2010 Mason Larobina