sponsor Vim development Vim logo Vim Book Ad

MapToSideEffects : Create mappings to function side effects

 script karma  Rating -1/3, Downloaded by 541  Comments, bugs, improvements  Vim wiki

created by
Alexey Muranov
 
script type
utility
 
description
This plugin helps to fool Vim into mapping key sequences in Normal,
Visual/Select, and Operator-pending modes to function side effects.

## User interface (API)

This plugins supports 4 *kinds* of *actions*:

* `Idempotent` -- actions that take no arguments and cannot be
  meaningfully repeated more than once,
* `Repeatable` -- actions that take no arguments but can be
  meaningfully repeated a number of times,
* `WithCount`  -- actions that take a `count`-type argument,
* `WithCount1` -- actions that take a `count1`-type argument.

*Action* here means a *VimL* function called for its side effects.

### Registering actions and creating mappings

The following functions create mappings of a key sequence of the form
`<Plug>(<name>)` to the side effects of the given action in requested
modes.

* `mapToSideEffects#SetUpIdempotent(action[, options])`
  -- set up a mapping of a key sequence of the form `<Plug>(<name>)` to
  the side effects of a user provided `Idempotent` action, return the
  generated ID number,

* `mapToSideEffects#SetUpRepeatable(action[, options])`
  -- set up a mapping of a key sequence of the form `<Plug>(<name>)` to
  the side effects of a user provided `Repeatable` action, return the
  generated ID number,

* `mapToSideEffects#SetUpWithCount(action[, options])`
  -- set up a mapping of a key sequence of the form `<Plug>(<name>)` to
  the side effects of a user provided `WithCount` action, return the
  generated ID number,

* `mapToSideEffects#SetUpWithCount1(action[, options])`
  -- set up a mapping of a key sequence of the form `<Plug>(<name>)` to
  the side effects of a user provided `WithCount1` action, return the
  generated ID number,

The optional `options` argument of these functions must be a
dictionary which can contain two keys: `'modes'` and `'name'`.

The `modes` option, if provided, has to be a string containing only
letters `n`, `v`, `x`, `s`, `o`.  If it is omitted, it is assumed to be
`'nvo'`.

The `name` option, if provided, has to be a string matching the regex
`'^[-_.:[:alnum:]]\{1,45}$'` and not beginning with `MapToSideEffects-`
in any character case, and the user must ensure that the key sequence
`<Plug>(<name>)` has not yet been used as a mapping source.  If the
`name` option is omitted, the `name` is taken to be
`'MapToSideEffects-<id>'`, where `<id>` is the generated numerical ID.

Name collisions may be avoided as follows, for example:

(a) start names with "`<PluginName>-`" in plugins and with a dash "`-`"
  in user scripts, or

(b) do not provide custom names, use automatic names of the form
  "`MapToSideEffects-<id>`."

### Unregistering actions and removing mappings

The following functions unregister one or several previously registered
actions and clear the corresponding mappings.

* `mapToSideEffects#ClearOne(id)`
  -- remove the mapping and the data associated with the given ID number,

* `mapToSideEffects#ClearOneByName(name)`
  -- remove the mapping and the data associated with the given name,

* `mapToSideEffects#ClearMultiple(ids)`
  -- remove the mappings and the data associated with the given ID
  numbers,

* `mapToSideEffects#ClearMultipleByNames(names)`
  -- remove the mappings and the data associated with the given names,

The following function removes all the plugin's data and clears the
corresponding mappings.

* `mapToSideEffects#Reset()`
  -- remove all mappings and all data.

## Usage

Suppose one wishes to use the key sequence `<leader>ekf` in *Normal*,
*Visual*, and *Operator-pending* modes to perform the motion to the
nearest "end of a keyword," as defined by the pattern `'\>'` in *Vim*, in
the forward direction and taking into account the `[count]` prefix.
Using this plugin, this can be achieved as follows, for example.

1. Define a function `s:ToEndOfKeywordForward` with desired side effects
  that takes a positive integer argument `count1`:

      function s:ToEndOfKeywordForward(count1)
        let l:count1 = a:count1
        while l:count1 > 0
          call search('\>', 'W')
          let l:count1 -= 1
        endwhile
      endfunction


2. Creates a mapping of `<Plug>(-GoToEndOfKeywordForward)` to the side
  effects of `s:ToEndOfKeywordForward` function in *Normal*, *Visual*,
  and *Operator-pending* modes:

      call mapToSideEffects#SetUpWithCount1(
            \   function('s:ToEndOfKeywordForward'),
            \   {'name' : '-GoToEndOfKeywordForward', 'modes' : 'nxo'} )


3. Create desired custom mappings to `<Plug>(-GoToEndOfKeywordForward)`:

      nmap <leader>ekf <Plug>(-GoToEndOfKeywordForward)
      xmap <leader>ekf <Plug>(-GoToEndOfKeywordForward)
      omap <leader>ekf <Plug>(-GoToEndOfKeywordForward)


GitHub page: https://github.com/alexeymuranov/vim-MapToSideEffects
 
install details
Install normally.
 

rate this script Life Changing Helpful Unfulfilling 
script versions (upload new version)

Click on the package to download.

package script version date Vim version user release notes
MapToSideEffects-0.1.0.tar.gz 0.1.0 2015-05-01 7.4 Alexey Muranov Fix typos in comments and README
ip used for rating: 3.236.50.252

If you have questions or remarks about this site, visit the vimonline development pages. Please use this site responsibly.
Questions about Vim should go to the maillist. Help Bram help Uganda.
   
OSDN