backpair.txt

*backpair.vim*		Go back to the inner position of the inputted pair.

Author: mityu
License: MIT License

==============================================================================
CONTENTS						*backpair-contents*

INTRODUCTION						|backpair-introduction|
REQUIREMENTS						|backpair-requirements|
FUNCTIONS						|backpair-functions|
AUTOCOMMANDS						|backpair-autocmds|
EXAMPLES						|backpair-examples|


==============================================================================
INTRODUCTION					*backpair-introduction*

|backpair.vim| is a plugin to help inserting pair then returning back to the
inner position of the pair such as `()`, `[]`, `<>`, `""`, etc.  For examples,
if you configure well, you can move like these:

			    Type )
	()|		------------->		(|)

			    Type )
	\%(\)|		------------->		\%(|\)

			    Type ]
	[[]]|		------------->		[[|]]


Note that this plugin does NOT provide any configuration and you need to write
some configurations in your .vimrc so that this plugin works well.  See
|backpair-functions| and |backpair-autocmds| for the available functions and
autocommands, and see |backpair-examples| for the example configurations.

==============================================================================
REQUIREMENTS					*backpair-requirements*

- Vim 8.2 or later
- Neovim 0.7.0 or later

==============================================================================
FUNCTIONS					*backpair-functions*

backpair#add_pair({opener}, {closer} [, {opts}])	*backpair#add_pair()*
	Register a pair.  {opener} and {closer} is a |String| with one
	character at least.  If you type {opener}, {closer} and the last
	character of {closer} sequentially in insert mode, this plugin reverts
	the type of the last character of {closer} and move the cursor to the
	position between {opener} and {closer}.
	{opts} is a |Dict| to specify some options to enable/disable the rule
	dynamically.  The available keys are:
	- enable_filetypes	(optional, |List| of |String|s)
		If the current buffer's filetype doesn't appear in this list,
		the rule will be disabled.
	- disable_filetypes	(optional, |List| of |String|s)
		If the current buffer's file type appears in this list, the
		rule will be disabled.
	- skip_if_ongoing	(optional, |List| of |String|s)
		If one element of this value exists in a list of ongoing
		rule's current input, the rule will be disabled.
	- condition		(optional, |Funcref|)
		This function should take no arguments and return boolean
		comparable value.  If this function returns falsy value, the
		rule will be disabled.  Note that this function will be
		evaluated when after user typed the last character of {closer}
		and before the typed character is inserted on buffer.

	Examples:
	- `call backpair#add_pair("[", "]")`:

			Buffer~
		-----------------------
			|
	   Type [
	----------->	[|
	   Type ]
	----------->	[]|
	   Type ]
	----------->	[|]


	- `call backpair#add_pair("\(", "\)")`:

			Buffer~
		-----------------------
			|
	   Type \
	----------->	\|
	   Type (
	----------->	\(|
	   Type \
	----------->	\(\|
	   Type )
	----------->	\(\)|
	   Type )
	----------->	\(|\)

	 `call backpair#add_pair("[", "]", #{skip_if_ongoing: ["[[]"]})`
	 `call backpair#add_pair("[[", "]]")`

			Buffer~
		-----------------------
			[[]|
	   Type ]
	----------->	[[]]|	<------ The first rule is skipped since "[[]"
					matches the input for the second rule.
	   Type ]
	----------->	[[|]]	<------ The second rule is applied.

backpair#clear_pairs()				*backpair#clear_pairs()*
	Clear all the registered pairs.

backpair#enable()					*backpair#enable()*
	Enables |backpair.vim| plugin.

backpair#disable()					*backpair#disable()*
	Disables |backpair.vim| plugin.

backpair#clear_state()				*backpair#clear_state()*
	Clear current internal state.  Useful to prohibit |backpair.vim|
	plugin to trigger any rule that return cursor back to the inner
	position of the latest pair on next type of a character.
	Example: >
	inoremap <C-f> <Cmd>call backpair#clear_state()<CR><C-g>U<right>
<

==============================================================================
AUTOCOMMANDS					*backpair-autocmds*

|backpair.vim| provides a |User| autocommand to do initial configurations.

backpair-initialize			*backpair-User-backpair-initialize*
	On the first load of |backpair.vim|.  You can do some plugin
	configurations such as to call |backpair#add_pair()|.


==============================================================================
EXAMPLES					*backpair-examples*

- Setup this plugin: >
	augroup setup-plugin-backpair
	  autocmd!
	  autocmd InsertEnter * ++once call backpair#enable()
	  autocmd User backpair-initialize ++once call s:backpair_config()
	augroup END

	function s:backpair_config() abort
	  call backpair#add_pair('(', ')')
	  call backpair#add_pair('[', ']', #{skip_if_ongoing: ['[[]']})
	  call backpair#add_pair('[[', ']]')
	  call backpair#add_pair('<', '>')
	  call backpair#add_pair('"', '"')
	  call backpair#add_pair("'", "'")
	  call backpair#add_pair('「', '」')
	endfunction
<


==============================================================================
vim:tw=78:fo=tcq2mM:ts=8:ft=help:norl