mini-move.txt

*mini.move* Move any selection in any direction
*MiniMove*

MIT License Copyright (c) 2023 Evgeni Chasnovski

==============================================================================

Features:
- Works in two modes:
    - Visual mode. Select text (charwise with |v|, linewise with |V|, and
      blockwise with |CTRL-V|) and press customizable mapping to move in
      all four directions (left, right, down, up). It keeps Visual mode.
    - Normal mode. Press customizable mapping to move current line in all
      four directions (left, right, down, up).
    - Special handling of linewise movement:
        - Vertical movement gets reindented with |=|.
        - Horizontal movement is improved indent/dedent with |>| / |<|.
        - Cursor moves along with selection.

- Provides both mappings and Lua functions for motions. See
  |MiniMove.move_selection()| and |MiniMove.move_line()|.

- Respects |v:count|. Movement mappings can be preceded by a number which
  multiplies command effect.

- All consecutive moves (regardless of direction) can be undone by a single |u|.

- Respects preferred column for vertical movement. It will vertically move
  selection as how cursor is moving (not strictly vertically if target
  column is not present in target line).

Notes:
- Doesn't allow moving selection outside of current lines (by design).

# Setup ~

This module needs a setup with `require('mini.move').setup({})` (replace
`{}` with your `config` table). It will create global Lua table `MiniMove`
which you can use for scripting or manually (with `:lua MiniMove.*`).

See |MiniMove.config| for available config settings.

You can override runtime config settings (but not `config.mappings`) locally
to buffer inside `vim.b.minimove_config` which should have same structure
as `MiniMove.config`. See |mini.nvim-buffer-local-config| for more details.

# Comparisons ~

- 'matze/vim-move':
    - Doesn't support vertical movement of charwise and blockwise selections.
      While 'mini.move' does.
    - Doesn't support horizontal movement of current line in favor of
      horizontal movement of current character. While 'mini.move' supports
      horizontal movement of current line and doesn't support such movement
      of current character.
    - Has extra functionality for certain moves (like move by half page).
      While 'mini.move' does not (by design).
- 'booperlv/nvim-gomove':
    - Doesn't support movement in charwise visual selection.
      While 'mini.move' does.
    - Has extra functionality beyond moving text, like duplication.
      While 'mini.move' concentrates only on moving functionality.

# Disabling ~

To disable, set `vim.g.minimove_disable` (globally) or `vim.b.minimove_disable`
(for a buffer) to `true`. Considering high number of different scenarios
and customization intentions, writing exact rules for disabling module's
functionality is left to user. See |mini.nvim-disabling-recipes| for common
recipes.

------------------------------------------------------------------------------
                                                              *MiniMove.setup()*
                           `MiniMove.setup`({config})
Module setup

Parameters ~
{config} `(table|nil)` Module config table. See |MiniMove.config|.

Usage ~
>lua
  require('mini.move').setup() -- use default config
  -- OR
  require('mini.move').setup({}) -- replace {} with your config table
<
------------------------------------------------------------------------------
                                                               *MiniMove.config*
                               `MiniMove.config`
Module config

Default values:
>lua
  MiniMove.config = {
    -- Module mappings. Use `''` (empty string) to disable one.
    mappings = {
      -- Move visual selection in Visual mode. Defaults are Alt (Meta) + hjkl.
      left = '<M-h>',
      right = '<M-l>',
      down = '<M-j>',
      up = '<M-k>',

      -- Move current line in Normal mode
      line_left = '<M-h>',
      line_right = '<M-l>',
      line_down = '<M-j>',
      line_up = '<M-k>',
    },

    -- Options which control moving behavior
    options = {
      -- Automatically reindent selection during linewise vertical move
      reindent_linewise = true,
    },
  }
<
# Mappings ~

Other possible choices of mappings: >lua

  -- `HJKL` for moving visual selection (overrides H, L, J in Visual mode)
  require('mini.move').setup({
    mappings = {
      left  = 'H',
      right = 'L',
      down  = 'J',
      up    = 'K',
    }
  })

  -- Shift + arrows
  require('mini.move').setup({
    mappings = {
      left  = '<S-left>',
      right = '<S-right>',
      down  = '<S-down>',
      up    = '<S-up>',

      line_left  = '<S-left>',
      line_right = '<S-right>',
      line_down  = '<S-down>',
      line_up    = '<S-up>',
    }
  })
<
------------------------------------------------------------------------------
                                                     *MiniMove.move_selection()*
                 `MiniMove.move_selection`({direction}, {opts})
Move visually selected region in any direction within present lines

Main function powering visual selection move in Visual mode.

Notes:
- Vertical movement in linewise mode is followed up by reindent with |v_=|.
- Horizontal movement in linewise mode is same as |v_<| and |v_>|.

Parameters ~
{direction} `(string)` One of "left", "down", "up", "right".
{opts} `(table|nil)` Options. Same structure as `options` in |MiniMove.config|
  (with its values as defaults) plus these allowed extra fields:
  - <n_times> (number) - number of times to try to make a move.
    Default: |v:count1|.

------------------------------------------------------------------------------
                                                          *MiniMove.move_line()*
                   `MiniMove.move_line`({direction}, {opts})
Move current line in any direction

Main function powering current line move in Normal mode.

Notes:
- Vertical movement is followed up by reindent with |v_=|.
- Horizontal movement is almost the same as |<<| and |>>| with a different
  handling of |v:count| (multiplies shift effect instead of modifying that
  number of lines).

Parameters ~
{direction} `(string)` One of "left", "down", "up", "right".
{opts} `(table|nil)` Options. Same structure as `options` in |MiniMove.config|
  (with its values as defaults) plus these allowed extra fields:
  - <n_times> (number) - number of times to try to make a move.
    Default: |v:count1|.


 vim:tw=78:ts=8:noet:ft=help:norl: