# machakann/vim-sandwich

Fetching contributors…
Cannot retrieve contributors at this time
471 lines (388 sloc) 15.8 KB
 *sandwich.txt* Last change:21-Aug-2017. The set of operator and textobject plugins to edit sandwiched textobjects. Author : machakann License : NYSL license Japanese English (Unofficial) Requirement: Vim 7.4 or higher |+reltime| feature (optional) |+float| feature (optional) ============================================================================== CONTENTS *sandwich-contents* QUICK START |sandwich-quick-start| INTRODUCTION |sandwich-introduction| KEYMAPPINGS |sandwich-keymappings| CONFIGURATION |sandwich-configuration| MAGICCHARACTERS |sandwich-magiccharacters| FILETYPE RECIPES |sandwich-filetype-recipes| MISCELLANEOUS |sandwich-miscellaneous| Introduce vim-surround keymappings ============================================================================== QUICK START *sandwich-quick-start* *sandwich.vim* is the set of operator and textobject plugins to add/delete/replace surroundings of a sandwiched textobject, like (foo), "bar". add~ Press sa{motion/textobject}{addition}. For example, saiw( makes foo to (foo). delete~ Press sdb or sd{deletion}. For example, sdb or sd( makes (foo) to foo. sdb searchs a set of surrounding automatically. replace~ Press srb{addition} or sr{deletion}{addition}. For example, srb" or sr(" makes (foo) to "foo". That's all. Now you already know enough about sandwich.vim. If you want more, read following descriptions and each help for operator/textobject, |operator-sandwich| and |textobj-sandwich|. ============================================================================== INTRODUCTION *sandwich-introduction* This plugin provides functions to add/delete/replace surroundings of sandwiched texts. These functions are implemented genuinely by utilizing operator/textobject framework. Their action can be repeated by |.| command without any dependency. It consists of two parts, |operator-sandwich| and |textobj-sandwich|. These two cooperate gracefully to realize the functionality. However, at the same time, each of them are independent, thus they could work with any other operators/textobjects. |operator-sandwich| gives three kinds of operators, |(operator-sandwich-add)|, |(operator-sandwich-delete)|, |(operator-sandwich-replace)|. These operators edit sandwiched text. |textobj-sandwich| gives four kinds of textobjects, |(textobj-sandwich-auto-i)|, |(textobj-sandwich-auto-a)|, |(textobj-sandwich-query-i)|, |(textobj-sandwich-query-a)|. These textobjects search and select sandwiched text. ============================================================================== KEYMAPPINGS *sandwich-keymappings* This plugin defines the following keymappings. function default keymappings -------------------------------------------------------------------------- add sa{motion/textobject}{addition} (normal and visual mode) delete sd (visual mode) sdb (normal mode) sd{deletion} (normal mode) replace sr{addition} (visual mode) srb{addition} (normal mode) sr{deletion}{addition} (normal mode) textobjct ib (operator-pending and visual mode) ab (operator-pending and visual mode) is (operator-pending and visual mode) as (operator-pending and visual mode) -------------------------------------------------------------------------- NOTE: To prevent unintended operation, the following setting is strongly recommended to add to your vimrc. > nmap s xmap s < |s| could be easily replaced by |c|l| commands. The detailed breakdown is described below. * |operator-sandwich| |(operator-sandwich-add)| which is a operator to add surroundings is mapped to the key sequences sa. This is valid in both normal and visual modes. |(operator-sandwich-delete)| which is a operator to delete surroundings is mapped to the key sequences sd in visual mode. If the both ends of the selected region are the same characters or the set of registered surroundings, then it deletes them. |(operator-sandwich-replace)| which is a operator to replace surroundings is mapped to the key sequences sr in visual mode. If the both ends of the selected region are the same characters or the set of registered surroundings, then it replaces them. * |textobj-sandwich| |(textobj-sandwich-auto-i)| and |(textobj-sandwich-auto-a)| which are the textobjects to search and select a sandwiched text automatically are mapped to the key sequences ib and ab. They are valid in both operator-pending mode and visual mode. ib selects the text inside the surroundings. ab selects the text including surroundings. |(textobj-sandwich-query-i)| and |(textobj-sandwich-query-a)| which are the textobjects to search and select a sandwiched text depending on user input are mapped to the key sequences is and as. They are valid in both operator-pending mode and visual mode. is selects the text inside the surroundings. as selects the text including surroundings. In addition to the above, the key sequences sd, sdb, sr and srb in normal mode is used by compound mappings of |operator-sandwich| and |textobj-sandwich|. Each of them are the short-hand mappings as following keysequences. sd > (operator-sandwich-delete)(textobj-sandwich-query-a) < sdb > (operator-sandwich-delete)(textobj-sandwich-auto-a) < sr > (operator-sandwich-replace)(textobj-sandwich-query-a) < srb > (operator-sandwich-replace)(textobj-sandwich-auto-a) < This is just for convenience, since these textobjects perfectly fills up the working condition of these operators. Users only have to assign surroundings as listed above. If you don't like the short-hands, define g:sandwich_no_default_key_mappings in your vimrc. > let g:sandwich_no_default_key_mappings = 1 < NOTE: In fact, these compound keymappings have one more key sequence |(operator-sandwich-release-count)| in between the two key sequences. It is a tiny trick for the [count] handling. For example the key sequences 2sdb is identical to: > (operator-sandwich-delete)2(textobj-sandwich-auto-a) < It searches the second closest sandwiched text and deletes them. > # : cursor [bar(foo)baz] ---> bar(foo)baz < ============================================================================== CONFIGURATION *sandwich-configuration* A set of surroundings and options for it is called "recipe". Each recipe is a dictionary and the |list|s of recipes determines the operator's behavior and textobject's behavior. |g:sandwich#default_recipes| is one of the |list|s of recipes. This is shared to be used by |operator-sandwich| and |textobj-sandwich| since it is convenient in many cases. If |g:sandwich#recipes| is defined by user, it is employed alternatively. The default recipes |g:sandwich#default_recipes| can be checked by |:echo| command. > :echo g:sandwich#default_recipes < Besides them, |g:operator#sandwich#recipes| and |g:textobj#sandwich#recipes| can be used. They are used only by |operator-sandwich| and |textobj-sandwich| respectively. About the contents of a recipe, please see |operator-sandwich-configuration| and |textobj-sandwich-configuration|. g:sandwich#recipes *g:sandwich#recipes* This is one of the lists of recipes which is referred from both |operator-sandwich| and |textobj-sandwich|. If this list does not exist, |g:sandwich#default_recipes| is used. *b:sandwich_recipes* If |b:sandwich_recipes| exists, it would be used instead of |g:sandwich#recipes|. This is buffer local, thus it might be convenient to manage too many filetype-specific recipes. g:sandwich#default_recipes *g:sandwich#default_recipes* This is a list of recipes which is prepared in default. If |g:sandwich#recipes| exists, it will be used instead. This variable is locked usually, but it can be copied when you declare |g:sandwich#recipes| if you need. > :let g:sandwich#recipes = deepcopy(g:sandwich#default_recipes) < Notes on default recipes~ (, ) [, ] {, } <, > Both open/close braces behave as same. For example, sa(iw and sa)iw result in the same text. > foo -> (foo) < sd( and sd) do the opposite, but it would be checked if their syntax are matched. ------------------------------------------------------------------------------ ' " Wrap a text by quotes. > foo -> 'foo' < When deleting a pair of quotes, 'quoteescape' option is considered. The pair of quotes are searched only in a same line. The target quotes should have same syntax. ------------------------------------------------------------------------------  When deleting a pair of spaces, successive spaces are deleted at a time. ------------------------------------------------------------------------------ t, T f, F i, I See |sandwich-magiccharacters|. ============================================================================== MAGICCHARACTERS *sandwich-magiccharacters* Sandwich.vim requests user to input keys for determination of {addtion}/{deletion}. Usually it is something like ( for () pair or " for "" pair, but there is several functional inputs for cumbersome editings. It might be helpful for your work, give it a try! f~ F~ Press saiwf to surround a word by function. After inputting f key, user would be requested to input function name and press , then the target textobject would be surrounded by parenthesis with the function name. key completes function names from the current buffer in input. > arg -- saiwffunc --> func(arg) < The key sequence sdf, conversely, deletes function surrounding. > func(arg) -- sdf --> arg < In case of nested functions, sdf deletes the function under the cursor while sdF deletes the function surrounding. > cursor is on 'func2': func1(func2(arg)) -- sdf --> func1(arg) -- sdF --> func2(arg) < i~ I~ It realizes to define Instant surroundings. saiwi ask user for inputting former and latter surroundings. For example, saiwifoobar makes a word surrounded by foo and bar. key completes words from the current buffer, just simply. On the other hand sdi deletes arbitrary surroundings. For example, sdifoobar makes foowordbar to word, the inputs would be interpreted as regular expressions. This is useful when a lot of targets are there because the action could be repeated by |.| command. sd{textobj}I, sdI reuse the last inputs. t~ T~ The inputs t and T support to edit HTML style tags. saiwt ask user to input a name of element, then a textobject would be surrounded by the tag. saiwT works as same. > word -- saiwtp -->

word

< sdt deletes the nearest tag surroundings. sdT works as same. >

word

-- sdt --> word < t and T works differently only when replacing surroundings. srtt replaces only the name of element, does not touch attributes. srTT replaces the whole body of tags. ============================================================================== FILETYPE RECIPES *sandwich-filetype-recipes* Sandwich.vim has filetype specific settings. They will be available when 'filetype' option was set to a certain value. User settings are not overwrittern by them, use only the recipes helpful for you. These recipes are written in ftplugin/{filetype}/sandwich.vim. If you don't want vim to load these files, set g:sandwich_no_{filetype}_ftplugin as true in advance. For example, add the following line to your vimrc in case you don't need tex specific recipes. > let g:sandwich_no_tex_ftplugin = 1 < ------------------------------------------------------------------------------ plaintex~ tex~ > Surroundings Input “{text}” u" „{text}“ U" ug u, «{text}» u< uf {text}' l' l {text}'' l" "{text}"' L" ,,{text} l, <<{text}>> l< \{{text}\} \{ ${text}$ $\left({text}\right) m( \left[{text}\right] m[ \left|{text}\right| m| \left\{{text}\right\} m{ \left\langle {text}\right\rangle m< < The surroundings its input starting from 'm' could be removed/replaced by a input ma, for example press sdma. > \big({text}\big) M( \big[{text}\big] M[ \big|{text}\big| M| \big\{{text}\big\} M{ \big\langle {text}\big\rangle M< \begingroup{text}\endgroup gr \gr \toprule{text}\bottomrule tr br \tr \br \{input}{{text}} c < This recipe asks user to input a string and then {input} is substituted by the input string. > \begin{{input}}{text}\end{{input}} e < This recipe asks user to input a string and then {input} is substituted by the input string. Use to complete {input}, the completion items are loaded from g:sandwich#filetype#tex#environments (or b:sandwich#filetype#tex#environments if exists). ------------------------------------------------------------------------------ ============================================================================== MISCELLANEOUS *sandwich-miscellaneous* Introduce vim-surround keymappings~ If you want to use with vim-surround (vim script #1697) keymappings, add the following line to your vimrc. > runtime macros/sandwich/keymap/surround.vim < NOTE: Unlike surround.vim, the inputs ( and ) behave as same. If you want the spaces inside braces with ( input, add the lines. > runtime macros/sandwich/keymap/surround.vim let g:sandwich#recipes += [ \ {'buns': ['{ ', ' }'], 'nesting': 1, 'match_syntax': 1, \ 'kind': ['add', 'replace'], 'action': ['add'], 'input': ['{']}, \ \ {'buns': ['[ ', ' ]'], 'nesting': 1, 'match_syntax': 1, \ 'kind': ['add', 'replace'], 'action': ['add'], 'input': ['[']}, \ \ {'buns': ['( ', ' )'], 'nesting': 1, 'match_syntax': 1, \ 'kind': ['add', 'replace'], 'action': ['add'], 'input': ['(']}, \ \ {'buns': ['{\s*', '\s*}'], 'nesting': 1, 'regex': 1, \ 'match_syntax': 1, 'kind': ['delete', 'replace', 'textobj'], \ 'action': ['delete'], 'input': ['{']}, \ \ {'buns': ['\[\s*', '\s*$'], 'nesting': 1, 'regex': 1, \ 'match_syntax': 1, 'kind': ['delete', 'replace', 'textobj'], \ 'action': ['delete'], 'input': ['[']}, \ \ {'buns': ['(\s*', '\s*)'], 'nesting': 1, 'regex': 1, \ 'match_syntax': 1, 'kind': ['delete', 'replace', 'textobj'], \ 'action': ['delete'], 'input': ['(']}, \ ] < ys, yss, yS, ds, cs in normal mode and S in visual mode are available. Not in vim-surround but dss and css are also available, these are similar as ds and cs` but determine deleted/replaced texts automatically. See the file directly for detail. Additionally, vim-sandwich provides several textobjects. They would also be helpful, give it a try! * Textobjects to select a text surrounded by braket or same characters user input. |(textobj-sandwich-query-i)|, |(textobj-sandwich-query-a)| > xmap is (textobj-sandwich-query-i) xmap as (textobj-sandwich-query-a) omap is (textobj-sandwich-query-i) omap as (textobj-sandwich-query-a) < * Textobjects to select the nearest surrounded text automatically. |(textobj-sandwich-auto-i)|, |(textobj-sandwich-auto-a)|. > xmap iss (textobj-sandwich-auto-i) xmap ass (textobj-sandwich-auto-a) omap iss (textobj-sandwich-auto-i) omap ass (textobj-sandwich-auto-a) < * Textobjects to select a text surrounded by same characters user input. |(textobj-sandwich-literal-query-i)|, |(textobj-sandwich-literal-query-a)| > xmap im (textobj-sandwich-literal-query-i) xmap am (textobj-sandwich-literal-query-a) omap im (textobj-sandwich-literal-query-i) omap am (textobj-sandwich-literal-query-a) < ============================================================================== vim:tw=78:ts=8:ft=help:norl:noet: