Extract the duplicated version into a script-local variable and improve the instructions a bit.
System-info: Ubuntu 20.04.6 LTS, x86_64
Platform-info: Vim 9.1.1029
This allows plugins to assert a compatible ingo-library version and handle a missing dependency gracefully.
There had been user complaints (latest in https://github.com/inkarkat/vim-mark/issues/46) that it's difficult to recognize what needs to be done when the library is missing.
Most users do figure it out eventually (it's documented and the issue templates highlight this as well), but still creates friction. I hope that this is a low-boilerplate solution that's working well for both producer (me) and consumers.
I'd rather have this solved declaratively by package managers, but apparently nothing of that sort has materialized, likely because plugins with dependencies are still rare.
System-info: Ubuntu 20.04.6 LTS, x86_64
Platform-info: Vim 9.1.602
Only split the fragment into collections and other elements if the [ character actually is a special character in the source magicness.
With \V, everything (except the backslash) is taken literally; we must not do translation of collections then.
Closes#3
And there's a general escaping issue with literal insertion; e.g. <C-R> may be interpreted etc.
I could instead paste the expression register, but that would clobber that (and the correct positioning may be tricky).
Leverage the :substitute that is done for the a:isKeepSpace branch, and substitute with a literal NUL character (this can be inserted robustly), then use the same :substitute command to replace it with the literal separator.
With a:isKeepSpace = 1. This might a little bit faster, but it definitely makes the join independent from 'formatoptions' from "j" (remove a comment leader) - "B" and "M" are about spaces around multibyte characters, which doesn't apply to space-constant joining via :join!.
The only use is by my AdvancedSorters.vim, which needs a neutral join (and unjoin) that does not modify the text at all.
It also uses the special join character <Nul>, which can only be inserted literally via <C-V><C-J> in insert mode; now that we're using :substitute we need to explicitly translate that into the ^@ character.
We could use \V...\m, but our own on-demand escaper gives shorter and more developer-friendly regular expressions.
All callers agree that it's a magic pattern, and there's also no documentation that says otherwise.
Instead of returning -1; only <Esc> or Ctrl-C abort. This results in better usability as accidental mistypes or fat-fingerings don't abort the whole command.
This needs to be used in place of string() when embedding a String in the right-hand side of a mapping; the existing ingo#escape#command#mapescape() would just convert to <CR>, which would still break the mapping when executed. The right way to use it is:
execute printf('map <F12> :call Foo(%s)<CR>', ingo#escape#command#mapescape(string(expr)))
This can be disabled via a:options.isAllowDigraphs = 0. The query functions for register, mark, substitute confirm, history recall, and confirmed filter disallow that as it's not needed.
Ingo Karkat