Upcoming breaking changes

[davidgranstrom]

Hi all,

This is a tracking issue where I will post breaking changes in the upcoming version of scnvim. If you want to try it out you can follow along in #153. It starting to become pretty stable by now but changes might still occur. I will try and post here if I break something intentionally.

Overall goals of this refactor/rewrite have been to rewrite a lot of viml code to lua to ease maintainability and coding standards (and in some cases improve performance). Fix some long standing issues in the code base that has been hard to solve because of legacy code and implement some new cool features (floating post window I'm looking at you!). I hope that the new configuration system will make it easier to start using scnvim out-of-the-box and to be able to configure the system to your liking.

I will write a more definite guide on how to transition to the new lua configuration once the API has settled.

Configuration

• All global options have been removed (e.g. g:scnvim_postwin_direction etc.) these are instead declared in scnvim.setup
• All <Plug> mappings have been removed, mappings can now be defined directly in the setup function
  • No mappings are defined by default
  • It's possible to create your own mappings using the scnvim API if you don't like to define them in the setup function

Please see the default configuration for what options are available. The rewrite is still in motion, so things might change without notice.

Example for setting options with the new configuration:

local scnvim = require 'scnvim'
scnvim.setup {
   mapping = {
    ['<M-e>'] = scnvim.map.send_line({'i', 'n'}),
    ['<C-e>'] = {
      scnvim.map.send_block({'i', 'n'}),
      scnvim.map.send_selection('x'),
    },
    ['<F12>'] = scnvim.map.hard_stop({'n', 'x', 'i'}),
    ['<CR>'] = scnvim.map.postwin_toggle('n'),
    ['<M-CR>'] = scnvim.map.postwin_toggle('i'),
    ['<M-L>'] = scnvim.map.postwin_clear({'n', 'i'}),
    ['<C-k>'] = scnvim.map.show_signature({'n', 'i'}),
  },
  editor = {
    flash = {
      duration = 100,
      repeats = 2,
      hl_group = 'TermCursor',
    },
  },
}

Custom mappings

For custom mappings that relied on the viml api scnvim#sclang#send you can instead use scnvim.send

" old
nnoremap <leader>sm :call scnvim#sclang#send_silent('s.meter')<cr>
" new
nnoremap <leader>sm <cmd>lua require('scnvim').send_silent('s.meter')<cr>

API

• The viml API is gone (e.g. scnvim#sclang#send_silent) and have been replaced by equivalent lua functions
• Some functions have moved to avoid cyclic references between modules
  • utils.path_sep => path.sep
  • utils.get_scnvim_root_dir => path.get_plugin_root_dir

[davidgranstrom]

Breaking change: postwin.float now only accepts a table value

To opt-in to use a floating post window:

postwin = {
   float = {
     enabled = true,
     -- more options here.. 
   }
}

[davidgranstrom]

Breaking change: editor.flash has moved to editor.highlight.flash

  editor = {
    highlight = {
      color = 'IncSearch',
      type = 'flash',
    }
  },

type can be one of: flash, fade or none

use an entry with the type name to configure the highlight

  editor = {
    highlight = {
      color = 'IncSearch',
      type = 'flash',
      flash = {
        repeats = 4,
      }
    }
  },

[davidgranstrom]

Breaking change: The postwin.float configuration has been refactored, it is now possible to use more granular positioning and also change the default width/height.

row, col, width and height can be a number or function. The function will be evaluated when opening the post window, which makes it possible to re-position it after resizing the terminal, apply offsets etc.

Here are the new default values:

    float = {
      enabled = false,
      row = 0,
      col = function()
        return vim.o.columns
      end,
      width = 64,
      height = 14,
      config = {
        border = 'single',
      },
      callback = function(id)
        vim.api.nvim_win_set_option(id, 'winblend', 10)
      end,
    },

[davidgranstrom]

Breaking change:

mapping has been renamed to keymaps in the user config

scnvim.setup {
  keymaps = {
    ['<CR>'] = map('postwin.toggle'),
  }
}

The map helper function can take a string or a function as input.

When the input is a string it will be parsed as module.function to create the keymap. If the input is a function it will simply execute that function.

See :h scnvim-keymaps for more examples!