My dotfiles. Period.

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369
  1. *lh-vim-lib.txt* Vim common libraries (v3.1.0)
  2. For Vim version 7+ Last change: $Date: 2012-04-10 10:00:00 +0200 (mar 10 avr 2012) $
  3. By Luc Hermitte
  4. hermitte {at} free {dot} fr
  5. ==============================================================================
  6. CONTENTS *lhvl-contents* {{{1
  7. |lhvl-presentation| Presentation
  8. |lhvl-functions| Functions
  9. |add-local-help| Instructions on installing this help file
  10. ------------------------------------------------------------------------------
  11. PRESENTATION *lhvl-presentation* {{{1
  12. |lh-vim-lib| is a library that defines some common VimL functions I use in my
  13. various plugins and ftplugins.
  14. This library has been conceived as a suite of |autoload| plugins, and a few
  15. |macros| plugins. As such, it requires Vim 7+.
  16. ==============================================================================
  17. FUNCTIONS *lhvl-functions* {{{1
  18. {{{2Functions list~
  19. Miscellanous functions: |lhvl#misc|
  20. - |lh#askvim#exe()|
  21. - |lh#common#check_deps()|
  22. - |lh#common#error_msg()|
  23. - |lh#common#warning_msg()|
  24. - |lh#common#echomsg_multilines()|
  25. - |lh#encoding#iconv()|
  26. - |lh#encoding#strlen()|
  27. - |lh#encoding#strpart()|
  28. - |lh#event#register_for_one_execution_at()|
  29. - |lh#option#get()|
  30. - |lh#option#get_non_empty()|
  31. - |lh#position#char_at_mark()|
  32. - |lh#position#char_at_pos()|
  33. - |lh#position#is_before()|
  34. - |lh#visual#selection()|
  35. - |lh#visual#cut()|
  36. Functors related functions: |lhvl#function|
  37. - |lh#function#bind()|
  38. - |lh#function#execute()|
  39. - |lh#function#prepare()|
  40. Lists related functions: |lhvl#list|
  41. - |lh#list#accumulate()|
  42. - |lh#list#at()|
  43. - |lh#list#copy_if()|
  44. - |lh#list#equal_range()|,
  45. - |lh#list#Find_if()| and |lh#list#find_if()|
  46. - |lh#list#intersect()|
  47. - |lh#list#lower_bound()| and |lh#list#upper_bound()|
  48. - |lh#list#match()|
  49. - |lh#list#matches()|
  50. - |lh#list#not_found()|
  51. - |lh#list#remove()|
  52. - |lh#list#subset()|
  53. - |lh#list#Transform()| and |lh#list#transform()|
  54. - |lh#list#transform_if()|
  55. - |lh#list#unique_sort()| and |lh#list#unique_sort2()|
  56. Graphs related functions: |lhvl#graph|
  57. - |lh#graph#tsort#depth()|
  58. - |lh#graph#tsort#breadth()|
  59. Paths related functions: |lhvl#path|
  60. - |lh#path#common()|
  61. - |lh#path#depth()|
  62. - |lh#path#glob_as_list()|
  63. - |lh#path#is_absolute_path()|
  64. - |lh#path#is_url()|
  65. - |lh#path#select_one()|
  66. - |lh#path#simplify()|
  67. - |lh#path#strip_common()|
  68. - |lh#path#strip_start()|
  69. - |lh#path#to_dirname()|
  70. - |lh#path#to_relative()|
  71. - |lh#path#relative_to()|
  72. - |lh#path#to_regex()|
  73. Commands related functions: |lhvl#command|
  74. - |lh#command#new()| (alpha version)
  75. - |lh#command#Fargs2String()| (alpha version)
  76. - |lh#command#complete()| (alpha version)
  77. Menus related functions: |lhvl#menu|
  78. - |lh#menu#def_toggle_item()|
  79. - |lh#menu#text()|
  80. - |lh#menu#make()|
  81. - |lh#menu#IVN_make()|
  82. - |lh#menu#is_in_visual_mode()|
  83. - |lh#menu#map_all()|
  84. - |lh#askvim#menu()| (beta version)
  85. Buffers related functions: |lhvl#buffer|
  86. - |lh#buffer#list()|
  87. - |lh#buffer#find()|
  88. - |lh#buffer#jump()|
  89. - |lh#buffer#scratch()|
  90. - |lh#buffer#dialog#| functions for building interactive dialogs
  91. - |lh#buffer#dialog#new()|
  92. - |lh#buffer#dialog#add_help()|
  93. - |lh#buffer#dialog#select()|
  94. - |lh#buffer#dialog#quit()|
  95. - |lh#buffer#dialog#update()|
  96. Syntax related functions: |lhvl#syntax|
  97. - |lh#syntax#name_at()|
  98. - |lh#syntax#name_at_mark()|
  99. - |lh#syntax#skip()|
  100. - |lh#syntax#skip_at()|
  101. - |lh#syntax#skip_at_mark()|
  102. - |lh#syntax#list_raw()|
  103. - |lh#syntax#list()|
  104. Completion related functions |lhvl#completion|
  105. }}}2
  106. ------------------------------------------------------------------------------
  107. MISCELLANOUS FUNCTIONS *lhvl#misc* {{{2
  108. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  109. *lh#common#echomsgMultilines()* {{{3
  110. lh#common#echomsgMultilines()({text}) (*deprecated*)~
  111. *lh#common#echomsg_multilines()*
  112. lh#common#echomsg_multilines()({text})~
  113. @param {text} Message to display on several lines
  114. @return Nothing
  115. This function executes |:echomsg| as many times as required as there are lines
  116. in the original {text}.
  117. This is a workaround |:echomsg| that is unable to handle correctly multi-lines
  118. messages.
  119. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  120. *lh#common#ErrorMsg()* {{{3
  121. lh#common#ErrorMsg({text}) (*deprecated*)~
  122. *lh#common#error_msg()*
  123. lh#common#error_msg({text})~
  124. @param {text} Error message to display
  125. @return Nothing
  126. This function displays an error message in a |confirm()| box if gvim is being
  127. used, or as a standard vim error message through |:echoerr| otherwise.
  128. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  129. *lh#common#WarningMsg()* {{{3
  130. lh#common#WarningMsg({text}) (*deprecated*)~
  131. *lh#common#warning_msg()*
  132. lh#common#warning_msg({text})~
  133. @param {text} Error message to display
  134. @return Nothing
  135. This function displays a warning message highlighted with |WarningMsg| syntax.
  136. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  137. *lh#common#CheckDeps()* {{{3
  138. lh#common#CheckDeps({symbol},{file},{path},{requester}) (*deprecated*)~
  139. *lh#common#check_deps()*
  140. lh#common#check_deps({symbol},{file},{path},{requester})~
  141. @param {symbol} Symbol required, see |exists()| for symbol format.
  142. @param {file} File in which the symbol is expected to be defined
  143. @param {path} Path where the file can be found
  144. @param {requester} Name of the script in need of this symbol
  145. @return 0/1 whether the {symbol} exists
  146. Checks if {symbol} exists in vim. If not, this function first tries
  147. to |:source| the {file} in which the {symbol} is expected to be defined. If the
  148. {symbol} is still not defined, an error message is issued (with
  149. |lh#common#error_msg()|, and 0 is returned.
  150. Example: >
  151. if
  152. \ !lh#common#check_deps('*Cpp_CurrentScope',
  153. \ 'cpp_FindContextClass.vim', 'ftplugin/cpp/',
  154. \ 'cpp#GotoFunctionImpl.vim')
  155. \ || !lh#common#check_deps(':CheckOptions',
  156. \ 'cpp_options-commands.vim', 'ftplugin/cpp/',
  157. \ 'cpp#GotoFunctionImpl.vim')
  158. let &cpo=s:cpo_save
  159. finish
  160. endif
  161. Note: Since the introduction of |autoload| plugins in Vim 7, this function has
  162. lost most of its interrest.
  163. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  164. *lh#option#Get()* {{{3
  165. lh#option#Get({name},{default}[,{scopes}]) (*deprecated*)~
  166. *lh#option#get()*
  167. lh#option#get({name},{default}[,{scopes}])~
  168. @param {name} Name of the option to fetch
  169. @param {default} Default value in case the option is not defined
  170. @param {scopes} Vim scopes in which the options must be searched,
  171. default="bg".
  172. @return b:{name} if it exists, or g:{name} if it exists, or
  173. {default} otherwise.
  174. @see For development oriented options, |lh-dev| provides a
  175. dedicated function: |lh#dev#option#get()|.
  176. This function fetches the value of an user defined option (not Vim |options|).
  177. The option can be either a |global-variable|, a |buffer-variable|, or even
  178. a|window-variable|.
  179. The order of the variables checked can be specified through the optional
  180. argument {scopes}. By default, buffer-local options have the priority over
  181. global options.
  182. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  183. *lh#option#GetNonEmpty()* {{{3
  184. lh#option#GetNonEmpty({name},{default}[,{scopes}]) (*deprecated*)~
  185. *lh#option#get_non_empty()*
  186. lh#option#get_non_empty({name},{default}[,{scopes}])~
  187. @param {name} Name of the option to fetch
  188. @param {default} Default value in case the option is not defined, nor empty
  189. @param {scopes} Vim scopes in which the options must be searched,
  190. default="bg".
  191. @return b:{name} If it exists, of g:{name} if it exists, or {default}
  192. otherwise.
  193. This function works exactly like |lh#option#get()| except that a defined
  194. variable with an empty value will be ignored as well.
  195. An |expr-string| will be considered empty if its |strlen()| is 0, an
  196. |expr-number| when it values 0, |Lists| and |Dictionaries| when their |len()|
  197. is 0.
  198. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  199. *lh#askvim#Exe()* {{{3
  200. lh#askvim#Exe({command}) (*deprecated*)~
  201. *lh#askvim#exe()*
  202. lh#askvim#exe({command})~
  203. @param {command} Command to execute from vim.
  204. @return What the command echoes while executed.
  205. @note This function encapsultates |redir| without altering any
  206. register.
  207. Some information aren't directly accessible (yet) through vim API
  208. (|functions|). However, they can be obtained by executing some commands, and
  209. redirecting the result of these commands.
  210. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  211. *lh#askvim#menu()* {{{3
  212. lh#askvim#menu({menuid},{modes})~
  213. @param {menuid} Menu identifier.
  214. @param {modes} List of modes
  215. @return Information related to the {menuid}
  216. @todo Still bugged
  217. This function provides a way to obtain information related to a menu entry in
  218. Vim.
  219. The format of the result being «to be stabilized»
  220. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  221. *lh#position#IsBefore()* {{{3
  222. lh#position#IsBefore({lhs_pos},{rhs_pos}) (*deprecated*)~
  223. *lh#position#is_before()*
  224. lh#position#is_before({lhs_pos},{rhs_pos})~
  225. @param[in] Positions as those returned from |getpos()|
  226. @return Whether {lhs_pos} is before {rhs_pos}
  227. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  228. *lh#position#CharAtMark()* {{{3
  229. lh#position#CharAtMark({mark}) (*deprecated*)~
  230. *lh#position#char_at_mark()*
  231. lh#position#char_at_mark({mark})~
  232. @return The character at a given |mark|.
  233. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  234. *lh#position#CharAtPos()* {{{3
  235. lh#position#CharAtPos({pos}) (*deprecated*)~
  236. *lh#position#char_at_pos()* {{{3
  237. lh#position#char_at_pos({pos})~
  238. @return The character at a position (see |getpos()|).
  239. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  240. *lh#visual#selection()* {{{3
  241. lh#visual#selection()~
  242. @return The current visual selection
  243. @post |registers| are not altered by this function
  244. *lh#visual#cut()* {{{3
  245. lh#visual#cut()~
  246. @return The current visual selection
  247. @post |registers| are not altered by this function ;
  248. selection is deleted.
  249. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  250. *lh#event#RegisterForOneExecutionAt()* {{{3
  251. lh#event#RegisterForOneExecutionAt({event}, {cmd}, {group}) (*deprecated*)~
  252. *lh#event#register_for_one_execution_at()*
  253. lh#event#register_for_one_execution_at({event}, {cmd}, {group})~
  254. Registers a command to be executed once (and only once) when {event} is
  255. triggered on the current file.
  256. @param {event} Event that will trigger the execution of {cmd}|autocmd-events|
  257. @param {cmd} |expression-command| to execute
  258. @param {group} |autocmd-groups| under which the internal autocommand will be
  259. registered.
  260. @todo possibility to specify the file pattern
  261. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  262. *lh#encoding#iconv()* {{{3
  263. lh#encoding#iconv({expr}, {from}, {to})~
  264. This function just calls |iconv()| with the same arguments. The only
  265. difference is that it return {expr} when we know that |iconv()| will return an
  266. empty string.
  267. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  268. *lh#encoding#strlen()* {{{3
  269. lh#encoding#strlen({mb_string})~
  270. This function returns the length of the multi-bytes string.
  271. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  272. *lh#encoding#at()* {{{3
  273. lh#encoding#at({mb_string}, {i})~
  274. Returns the i-th character in a multi-bytes string.
  275. @param {i} 0-indexed offset.
  276. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  277. *lh#encoding#strpart()* {{{3
  278. lh#encoding#strpart({mb_string}, {position}, {length})~
  279. Returns {length} extracted characters from {position} in a multi-bytes string.
  280. @param {position} 0-indexed offset.
  281. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  282. *lh#float#max()* *lh#float#min()* {{{3
  283. *lh#float#arg_max()* *lh#float#arg_min()*
  284. lh#float#min({list})~
  285. lh#float#arg_min({list})~
  286. lh#float#min({list})~
  287. lh#float#arg_min({list})~
  288. Returns The minimum, /arg-minimum, /maximum, /arg-maximum of a |List| of
  289. |expr-float|.
  290. ------------------------------------------------------------------------------
  291. FUNCTORS RELATED FUNCTIONS *lhvl#function* {{{2
  292. This sub-library helps defining functors-like variables, and execute them.
  293. NB: C++ developpers may be already familiar with boost.bind
  294. (/std(::tr1)::bind) function that inspired by feature.
  295. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  296. *lhvl#functor* {{{3
  297. A functor is implemented as a |Dictionary| that has the following fields:
  298. - {execute} is the |Funcref| that will be actually executed by
  299. |lh#function#execute()|. Its only argument is a |List| of
  300. arguments for {function}.
  301. - {function} that identifies the function to execute,
  302. internals: it could be either a |Funcref|or a |expr-string|, or
  303. whatever is compatible with the {execute} |FuncRef| field.
  304. - {args} will contain the binded arguments as defined by
  305. |lh#function#bind()|. If you attach a {execute} function of your
  306. own to a functor, you don't need to fill "args".
  307. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  308. *lh#function#bind()* {{{3
  309. lh#function#bind({fn} [, {arguments} ...])~
  310. This function creates a new |lhvl#functor| based on a given function {fn}, and
  311. where some arguments are binded to the ones from {arguments}.
  312. The result is a new function-like data having for parameter v:1_, v:2_, ...
  313. that were specified in |lh#function#bind()| {arguments} list.
  314. Examples:~
  315. See tests/lh/function.vim
  316. Let's suppose Print(...) a VimL variadic function that echoes the arguments it
  317. receives, i.e. >
  318. call Print(1,2,"text", ['foo', 'bar'])
  319. will echo: >
  320. 1 ## 2 ## 'text' ## ['foo', 'bar']
  321. * Binding a |FuncRef|:~
  322. and reverse the arguments given to it when it will be executed >
  323. >:let func = lh#function#bind(function('Print'), 'v:3_', 'v:2_', 'v:1_')
  324. >:echo lh#function#execute(func, 1, 'two', [3])
  325. [3] ## 'two' ## 1
  326. * Binding a named function:~
  327. the new function has 3 parameters and calls the named function with its 3rd
  328. parameter, 42, its second and its first parameters as arguments. >
  329. >:let func = lh#function#bind('Print', 'v:3_', 42, 'v:2_', 'v:1_')
  330. >:echo lh#function#execute(func, 1, 'two', [3])
  331. [3] ## 42 ## 'two' ## 1
  332. < NB: if exists('*'.func_name) is false, then the string is considered to be
  333. an expression that will be evaluated as specified in the next use case.
  334. * Binding an expression:~
  335. This time more complex on-the-fly computations on the |lhvl#functor|
  336. parameters can be accomplished >
  337. >:let func = lh#function#bind('Print(len(v:3_), 42, v:2_, v:1_)')
  338. >:echo lh#function#execute(func, 1, 'two', [1,2,3])
  339. 3 ## 42 ## 'two' ## 1
  340. < NB: func["args"] is defined, but empty, and unused.
  341. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  342. *lh#function#execute()* {{{3
  343. lh#function#execute({functor} [, {arguments} ...])~
  344. While |lh#function#bind()| defines a |lhvl#functor| that can be stored and
  345. used later, |lh#function#execute()| directly executes the {functor} received.
  346. Different kind of {functors} are accepted:
  347. - |FuncRef|, and function names, where arguments are |lh#function#execute()|
  348. ones ;
  349. - |expr-string|, where "v:{pos}_" strings are binded on-the-fly to {arguments} ;
  350. - |lhvl#functor|, that will be given {arguments} as arguments.
  351. Examples:~
  352. See tests/lh/function.vim
  353. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  354. *lh#function#prepare()* {{{3
  355. lh#function#prepare({function}, {arguments} ...)~
  356. This function expands all the elements from the {arguments} |List|, and
  357. prepares a |expr-string| that once evaluated will call the n-ary {function}
  358. with the n-{arguments}.
  359. The evaluation is meant to be done with |eval()|.
  360. >
  361. >:let call = lh#function#prepare('Print', [1,2,"foo"])
  362. >:echo eval(call)
  363. 1 ## 2 ## 'foo'
  364. ------------------------------------------------------------------------------
  365. LISTS RELATED FUNCTIONS *lhvl#list* {{{2
  366. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  367. *lh#list#Match()* {{{3
  368. lh#list#Match({list},{pattern}[, {start-pos}]) (*deprecated*)~
  369. *lh#list#match()*
  370. lh#list#match({list},{pattern}[, {start-pos}])~
  371. @param {list} |List|
  372. @param {pattern} |expr-string|
  373. @param {start-pos} First index to check
  374. @return The lowest index, >= {start-pos}, in |List| {list} where
  375. the item matches {pattern}.
  376. @return -1 if no item matches {pattern}.
  377. @see |index()|, |match()|
  378. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  379. *lh#list#matches()* {{{3
  380. lh#list#match({list},{pattern}[, {start-pos}])~
  381. @param {list} |List|
  382. @param {pattern} |expr-string|
  383. @param {start-pos} First index to check
  384. @return The |List| of indices, >= {start-pos}, in |List| {list} where
  385. the item matches {pattern}.
  386. @return [] if no item matches {pattern}.
  387. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  388. *lh#list#find_if()* *lh#list#Find_if()* {{{3
  389. lh#list#Find_if({list},{string-predicate} [, {pred-parameters}][, {start-pos}])~
  390. lh#list#find_if({list},{functor-predicate} [, {pred-parameters}][, {start-pos}])~
  391. @param {list} |List|
  392. @param {*-predicate} Predicate to evaluate
  393. @param {pred-parameters}] |List| of Parameters to bind to special arguments in
  394. the {predicate}.
  395. @param {start-pos} First index to check
  396. @return The lowest index, >= {start-pos}, in |List| {list}
  397. where the {predicate} evals to true.
  398. @return -1 if no item matches {pattern}.
  399. @see |index()|, |eval()|
  400. The {string-predicate} recognizes some special arguments:
  401. - |v:val| is substituted with the current element being evaluated in the list
  402. - *v:1_* *v:2_* , ..., are substituted with the i-th elements from
  403. {pred-parameters}.
  404. NB: the "v:\d\+_" are 1-indexed while {pred-parameters} is indeed seen as
  405. 0-indexed by Vim.
  406. This particular feature permits to pass any type of variable to the
  407. predicate: a |expr-string|, a |List|, a |Dictionary|, ...
  408. e.g.: >
  409. :let b = { 'min': 12, 'max': 42 }
  410. :let l = [ 1, 5, 48, 25, 5, 28, 6]
  411. :let i = lh#list#Find_if(l, 'v:val>v:1_.min && v:val<v:1_.max && v:val%v:2_==0', [b, 2] )
  412. :echo l[i]
  413. 28
  414. The {functor-predicate} is a |lhvl#function|. The same example can be
  415. rewritten as: >
  416. :let l = [ 1, 5, 48, 25, 5, 28, 6]
  417. :let i = lh#list#find_if(l, 'v:1_>12 && v:1_<42 && v:1_%2==0')
  418. :echo l[i]
  419. 28
  420. NB: Expect the Find_if() version to be replaced with the find_if() one.
  421. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  422. *lh#list#lower_bound()* *lh#list#upper_bound()* {{{3
  423. *lh#list#equal_range()*
  424. lh#list#lower_bound({list}, {value} [, {first}][, {last}])~
  425. lh#list#upper_bound({list}, {value} [, {first}][, {last}])~
  426. lh#list#equal_range({list}, {value} [, {first}][, {last}])~
  427. @param {list} Sorted |List|
  428. @param {value} Value to search
  429. @param {first} First index to check
  430. @param {last} Last+1 index to check
  431. @return The lowest index, >= {first} and < {last}, in |List| {list}
  432. such as the index is <= first {value} occurrence, in lower_bound case
  433. such as the index is > last {value} occurrence, in upper_bound case
  434. @return -1 if no item matches {pattern}.
  435. @return the pair [lower_bound(), upper_bound()] in equal_range() case
  436. @see C++ STL eponym algorithms.
  437. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  438. *lh#list#not_found()* {{{3
  439. lh#list#not_found({range})~
  440. Returns whether the {range} is empty. This function can be used to check
  441. |lh#list#equal_range()| functions results
  442. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  443. *lh#list#unique_sort()* *lh#list#unique_sort2()* {{{3
  444. lh#list#unique_sort({list} [, {cmp}])~
  445. lh#list#unique_sort2({list} [, {cmp}])~
  446. @param[in] {list} |List| to sort
  447. @param {cmp} |Funcref| or function name that acts as a compare predicate.
  448. It seems to be required in order to not compare number with
  449. a lexicographic order (with vim 7.1-156)
  450. @return A new |List| sorted with no element repeated
  451. @todo support an optional {equal} predicate to use in the /unique/ making
  452. process.
  453. The difference between the two functions is the following:
  454. - unique_sort() stores all the elements in a |Dictionary|, then sort the values
  455. stored in the dictionary ;
  456. - unique_sort2() sorts all the elements from the initial |List|, and then
  457. keeps only the elements that appear once.
  458. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  459. *lh#list#Transform()* {{{3
  460. lh#list#Transform({input},{output},{action})~
  461. @param[in] {input} Input |List| to transform
  462. @param[out] {output} Output |List| where the transformed elements will be
  463. appended.
  464. @param {action} Stringified action to apply on each element from {input}.
  465. The string "v:val" will always be replaced with the
  466. element currently transformed.
  467. @return {output}
  468. This function is actually returning >
  469. extend(a:output, map(copy(a:input), a:action))
  470. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  471. *lh#list#transform()* {{{3
  472. lh#list#transform({input},{output},{action})~
  473. @param[in] {input} Input |List| to transform
  474. @param[out] {output} Output |List| where the transformed elements will be
  475. appended.
  476. @param {action}|lhvl#functor| action to apply on each element from
  477. {input}.
  478. @return {output}
  479. This function is equivalent to (|lh#list#Transform()|) >
  480. extend(a:output, map(copy(a:input), a:action))
  481. except the action is not a string but a |lhvl#functor|.
  482. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  483. *lh#list#transform_if()* {{{3
  484. lh#list#transform_if({input},{output},{action},{predicate})~
  485. @param[in] {input} Input |List| to transform
  486. @param[out] {output} Output |List| where the transformed elements will be
  487. appended.
  488. @param {action}|lhvl#functor| action to apply on each element from
  489. {input} that verifies the {predicate}.
  490. @param {predicate} Boolean |lhvl#functor| tested on each element before
  491. transforming it.
  492. @return {output}
  493. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  494. *lh#list#copy_if()* {{{3
  495. lh#list#copy_if({input},{output},{predicate})~
  496. Appends in {output} the elements from {input} that verifies the {predicate}.
  497. @param[in] {input} Input |List| to transform
  498. @param[out] {output} Output |List| where the elements that verify the
  499. {predicate} will be appended.
  500. @param {predicate} Boolean |lhvl#functor| tested on each element.
  501. @return {output}
  502. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  503. *lh#list#accumulate()* {{{3
  504. lh#list#accumulate({input},{transformation},{accumulator})~
  505. Accumulates the transformed elements from {input}.
  506. @param[in] {input} Input |List| to transform
  507. @param {transformation}|lhvl#functor| applied on each element from {input}.
  508. @param {accumulator}|lhvl#functor| taking the list of tranformaed elements
  509. as input
  510. @return the result of {accumulator}
  511. Examples: >
  512. :let strings = [ 'foo', 'bar', 'toto' ]
  513. :echo eval(lh#list#accumulate(strings, 'strlen', 'join(v:1_, "+")'))
  514. 10
  515. :let l = [ 1, 2, 'foo', ['bar']]
  516. :echo lh#list#accumulate(l, 'string', 'join(v:1_, "##")')
  517. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  518. *lh#list#subset()* {{{3
  519. lh#list#subset({input},{indices})~
  520. Returns a subset slice of the {input} list.
  521. @param[in] {input} Input |List| from which element will be extracted
  522. @param[in] {indices}|List| of indices to extract
  523. @return a |List| of the elements from {input} indexed by the {indices}
  524. Example: >
  525. :let l = [ 1, 25, 5, 48, 25, 5, 28, 6]
  526. :let indices = [ 0, 5, 7, 3 ]
  527. :echo lh#list#subset(l, indices)
  528. [ 1, 5, 6, 48 ]
  529. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  530. *lh#list#remove()* {{{3
  531. lh#list#remove({input},{indices})~
  532. Returns a subset slice of the {input} list trimmed of elements.
  533. @param[in,out] {input} Input |List| from which element will be removed
  534. @param[in] {indices}|List| of indices to remove
  535. @return a |List| of the elements from {input} not indexed by the {indices}
  536. @pre {indices} MUST be sorted
  537. Example: >
  538. :let l = [ 1, 25, 5, 48, 25, 5, 28, 6]
  539. :let indices = [ 0, 3, 5, 7 ]
  540. :echo lh#list#remove(l, indices)
  541. [ 25, 5, 25, 28 ]
  542. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  543. *lh#list#intersect()* {{{3
  544. lh#list#intersect({list1},{list2})~
  545. Returns the elements present in both input lists.
  546. @param[in] {list1}|List|
  547. @param[in] {list2}|List|
  548. @return a |List| of the elements in both {list1} and {list2}, the elements are
  549. kepts in the same order as in {list1}
  550. @note the algorithm is in O(len({list1})*len({list2}))
  551. Example: >
  552. :let l1 = [ 1, 25, 7, 48, 26, 5, 28, 6]
  553. :let l2 = [ 3, 8, 7, 25, 6 ]
  554. :echo lh#list#intersect(l1, l2)
  555. [ 25, 7, 6 ]
  556. ------------------------------------------------------------------------------
  557. GRAPHS RELATED FUNCTIONS *lhvl#graph* {{{2
  558. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  559. *lh#graph#tsort#depth()* {{{3
  560. *lh#graph#tsort#breadth()* {{{3
  561. lh#graph#tsort#depth({dag}, {start-nodes})~
  562. lh#graph#tsort#breadth({dag}, {start-nodes})~
  563. These two functions implement a topological sort on the Direct Acyclic Graph.
  564. - depth() is a recursive implementation of a depth-first search.
  565. - breadth() is a non recursive implementation of a breadth-first search.
  566. @param {dag} is a direct acyclic graph defined either:
  567. - as a |Dictionnary| that associates to each node, the |List| of
  568. all its successors
  569. - or as a /fetch/ |function()| that returns the |List| of the
  570. successors of a given node -- works only with depth() which
  571. takes care of not calling this function more than once for each
  572. given node.
  573. @param {start-nodes} is a |List| of start nodes with no incoming edge
  574. @throw "Tsort: cyclic graph detected:" if {dag} is not a DAG.
  575. @see http://en.wikipedia.org/wiki/Topological_sort
  576. @since Version 2.1.0
  577. @test tests/lh/topological-sort.vim
  578. ------------------------------------------------------------------------------
  579. PATHS RELATED FUNCTIONS *lhvl#path* {{{2
  580. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  581. *lh#path#depth()* {{{3
  582. lh#path#depth({dirname})~
  583. Returns the depth of a directory name.
  584. @param {dirname} Pathname to simplify
  585. @return the depth of the simplified directory name, i.e.
  586. lh#path#depth("bar/b2/../../foo/") returns 1
  587. @todo However, it is not able to return depth of negative paths like
  588. "../../foo/". I still need to decide whether the function should return
  589. -1 or 3.
  590. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  591. *lh#path#dirname()* {{{3
  592. lh#path#dirname({dirname})~
  593. Ensures the returned directory name ends with a '/' or a '\'.
  594. @todo On windows, it should take 'shellslash' into account to decide the
  595. character to append.
  596. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  597. *lh#path#Simplify()* {{{3
  598. lh#path#Simplify({pathname}) (*deprecated*)~
  599. *lh#path#simplify()*
  600. lh#path#simplify({pathname} [{make_relative_to_pwd])~
  601. Simplifies a path by getting rid of useless '../' and './'.
  602. @param {pathname} Pathname to simplify
  603. @param {make_relative_to_pwd} The {pathname} is made relative to pwd when set
  604. @return the simplified pathname
  605. This function works like |simplify()|, except that it also strips the leading
  606. "./".
  607. Note: when vim is compiled for unix, it seems unable to |simplify()| paths
  608. containing "..\". (It likelly works this way when vim is compiled without
  609. 'shellslash' support)
  610. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  611. *lh#path#common()* {{{3
  612. lh#path#common({pathnames})~
  613. @param[in] {pathnames} |List| of pathnames to analyse
  614. @return the common leading path between all {pathnames}
  615. e.g.: >
  616. :echo lh#path#common(['foo/bar/file','foo/file', 'foo/foo/file'])
  617. echoes >
  618. foo/
  619. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  620. *lh#path#StripCommon()* {{{3
  621. lh#path#StripCommon({pathnames}) (*deprecated*)~
  622. *lh#path#strip_common()*
  623. lh#path#strip_common({pathnames})~
  624. @param[in,out] {pathnames} |List| of pathnames to simplify
  625. @return the simplified pathnames
  626. This function strips all pathnames from their common leading part. The
  627. compuation of the common leading part is ensured by |lh#path#common()|
  628. thank.
  629. e.g.: >
  630. :echo lh#path#strip_common(['foo/bar/file','foo/file', 'foo/foo/file'])
  631. echoes >
  632. ['bar/file','file', 'foo/file']
  633. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  634. *lh#path#StripStart()* {{{3
  635. lh#path#StripStart({pathname}, {pathslist}) (*deprecated*)~
  636. *lh#path#strip_start()*
  637. lh#path#strip_start({pathname}, {pathslist})~
  638. @param[in] {pathname} name to simplify
  639. @param[in] {pathslist} list of pathname (can be a |string| of pathnames
  640. separated by ",", of a |List|).
  641. Strips {pathname} from any path from {pathslist}.
  642. e.g.: >
  643. :echo lh#path#strip_start($HOME.'/.vim/template/bar.template',
  644. \ ['/home/foo/.vim', '/usr/local/share/vim/'])
  645. :echo lh#path#strip_start($HOME.'/.vim/template/bar.template',&rtp)
  646. echoes >
  647. template/bar.template
  648. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  649. *lh#path#IsAbsolutePath()* {{{3
  650. lh#path#IsAbsolutePath({path}) (*deprecated*)~
  651. *lh#path#is_absolute_path()*
  652. lh#path#is_absolute_path({path})~
  653. @return {path} Path to test
  654. @return whether the path is an absolute path
  655. @note Supports Unix absolute paths, Windows absolute paths, and UNC paths
  656. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  657. *lh#path#IsURL()* {{{3
  658. lh#path#IsURL({path}) (*deprecated*)~
  659. *lh#path#is_url()*
  660. lh#path#is_url({path})~
  661. @return {path} Path to test
  662. @return whether the path is an URL
  663. @note Supports http(s)://, (s)ftp://, dav://, fetch://, file://, rcp://,
  664. rsynch://, scp://
  665. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  666. *lh#path#SelectOne()* {{{3
  667. lh#path#SelectOne({pathnames},{prompt}) (*deprecated*)~
  668. *lh#path#select_one()*
  669. lh#path#select_one({pathnames},{prompt})~
  670. @param[in] {pathnames} |List| of pathname
  671. @param {prompt} Prompt for the dialog box
  672. @return "" if len({pathnames}) == 0
  673. @return {pathnames}[0] if len({pathnames}) == 1
  674. @return the selected pathname otherwise
  675. Asks the end-user to choose a pathname among a list of pathnames.
  676. The pathnames displayed will be simplified thanks to |lh#path#strip_common()|
  677. -- the pathname returned is the "full" original pathname matching the
  678. simplified pathname selected.
  679. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  680. *lh#path#ToRelative()* {{{3
  681. lh#path#ToRelative({pathname}) (*deprecated*)~
  682. *lh#path#to_relative()*
  683. lh#path#to_relative({pathname})~
  684. @param {pathname} Pathname to convert
  685. @return the simplified {pathname} in its relative form as it would be seen
  686. from the current directory.
  687. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  688. *lh#path#relative_to()* {{{3
  689. lh#path#relative_to({from}, {to})~
  690. Returns the relative directory that indentifies {to} from {from} location.
  691. @param {from} origin directory
  692. @param {to} destination directory
  693. @return the simplified pathname {to} in its relative form as it would be seen
  694. from the {from} directory.
  695. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  696. *lh#path#GlobAsList()* {{{3
  697. lh#path#GlobAsList({pathslist}, {expr}) (*deprecated*)~
  698. *lh#path#glob_as_list()*
  699. lh#path#glob_as_list({pathslist}, {expr} [,{must_sort}])~
  700. @param[in] {pathslist} list (|List|, or comma separated list) of paths where
  701. to search.
  702. @param[in] {expr} glob expression of the files to search.
  703. @param[in] {mustSort} tells whether the results shall be sorted per
  704. {pathslist}, default: true.
  705. @return |globpath()|'s result, but formatted as a list of matching pathnames.
  706. In case {expr} is a |List|, |globpath()| is applied on each expression in
  707. {expr}.
  708. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  709. *lh#path#find()* {{{3
  710. lh#path#find({pathslist}, {regex})~
  711. @param[in] {pathslist} List of paths which can be received as a |List| or as a
  712. string made of coma separated paths.
  713. @return the path that matches the given {regex}
  714. e.g.: >
  715. let expected_win = $HOME . '/vimfiles'
  716. let expected_nix = $HOME . '/.vim'
  717. let what = lh#path#to_regex($HOME.'/').'\(vimfiles\|.vim\)'
  718. let z = lh#path#find(&rtp,what)
  719. if has('win16')||has('win32')||has('win64')
  720. Assert z == expected_win
  721. else
  722. Assert z == expected_nix
  723. endif
  724. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  725. *lh#path#to_regex()* {{{3
  726. lh#path#to_regex({pathname})~
  727. Transforms the {pathname} to separate each node-name by the string '[/\\]'
  728. The rationale behind this function is to build system independant regex
  729. pattern to use on pathnames as sometimes pathnames are built by appending
  730. '/stuff/like/this' without taking 'shellslash' into account.
  731. e.g.: >
  732. echo lh#path#to_regex('/home/luc/').'\(vimfiles\|.vim\)'
  733. echoes >
  734. [/\\]home[/\\]luc[/\\]\(vimfiles\|.vim\)
  735. ------------------------------------------------------------------------------
  736. MENUS RELATED FUNCTIONS *lhvl#menu* {{{2
  737. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  738. *lh#menu#def_toggle_item()* {{{3
  739. lh#menu#def_toggle_item({Data})~
  740. @param[in,out] {Data} Definition of a |menu| item.
  741. This function defines a |menu| entry that will be associated to a
  742. |global-variable| whose values can be cycled and explored from the menu. This
  743. global variable can be seen as an enumerate whose value can be cyclically
  744. updated through a menu.
  745. {Data} is a |Dictionary| whose keys are:
  746. - "variable": name of the |global-variable| to bind to the menu entry
  747. Mandatory.
  748. - "values": associated values of string or integers (|List|)
  749. Mandatory.
  750. - "menu": describes where the menu entry must be placed (|Dictionary|)
  751. - "priority": complete priority of the entry (see |sub-menu-priority|)
  752. - "name": complete name of the entry -- ampersand (&) can be used to define
  753. shortcut keys
  754. Mandatory.
  755. - "idx_crt_value": index of the current value for the option (|expr-number|)
  756. This is also an internal variable that will be automatically updated to
  757. keep the index of the current value of the "variable" in "values".
  758. Optional ; default value is 1, or the associated index of the initial value
  759. of the variable (in "values") before the function call.
  760. - "texts": texts to display according to the variable value (|List|)
  761. Optional, "values" will be used by default. This option is to be used to
  762. distinguish the short encoded value, from the long self explanatory name.
  763. - "hook": |function| to call, or command to |:execute| when the value of the
  764. variable is toggled through toggle-menu ; default: none.
  765. - "actions": list of functions to call, or commands to execute when the value
  766. of the variable is toggled through toggle-menu. There shall be one action
  767. per possible value when defined ; default: empty list
  768. Warning:
  769. If the variable is changed by hand without using the menu, then the menu
  770. and the variable will be out of synch. Unless the command |lhvl-:Toggle|
  771. is used to change the value of the options (and keep the menu
  772. synchronized).
  773. Examples:
  774. See tests/lh/test-toggle-menu.vim
  775. *lhvl-:Toggle*
  776. :Toggle {variable-name} [{text-value}]~
  777. @param {variable-name}
  778. must be a |global-variable| name used as "variable" in the
  779. definition of a toggable menu item thanks to
  780. |lh#menu#def_toggle_item()|.
  781. @param {text-value}
  782. when specified, :Toggle directly sets the variable to the value
  783. associated to {text-value}.
  784. This command supports autocompletion on the {variable-name}, and on
  785. {text-value}.
  786. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  787. *lh#menu#text()* {{{3
  788. lh#menu#text({text})~
  789. @param[in] {text} Text to send to |:menu| commands
  790. @return a text to be used in menus where "\" and spaces have been escaped.
  791. This helper function transforms a regular text into a text that can be
  792. directly used with |:menu| commands.
  793. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  794. *lh#menu#make()* {{{3
  795. option: *[gb]:want_buffermenu_or_global_disable*
  796. If Michael Geddes's |buffer-menu| plugin is installed, this option tells
  797. whether we want to take advantage of it to define menus or to ignore it.
  798. lh#menu#make({modes}, {menu-priority}, {menu-text}, {key-binding}, [<buffer>,] {action})~
  799. Creates a menu entry and its associated mappings for several modes at once.
  800. @param[in] {modes} Vim modes the menus and maps will be provided for
  801. @param[in] {menu-priority} |sub-menu-priority| for the new menu entry
  802. @param[in] {menu-text} Name of the new menu entry
  803. @param[in] {key-binding} Sequence of keys to execute the associated action
  804. @param[in] "<buffer>" If the string "<buffer>" is provided, then the
  805. associated mapping will be a |map-<buffer>|, and
  806. the menu will be available to the current buffer
  807. only. See |[gb]:want_buffermenu_or_global_disable|
  808. When "<buffer>" is set, the call to lh#menu#make()
  809. must be done in the buffer-zone from a |ftplugin|,
  810. or from a |local_vimrc|.
  811. @param[in] {action} Action to execute when {key-binding} is typed, or
  812. when the menu entry is selected.
  813. @todo support select ('s') and visual-not-select ('x') modes
  814. First example:~
  815. The following call will add the menu "LaTeX.Run LaTeX once <C-L><C-O>", with
  816. the priority (placement) 50.305, for the NORMAL, INSERT and COMMAND modes. The
  817. action associated first saves all the changed buffers and then invokes LaTeX.
  818. The same action is also binded to <C-L><C-O> for the same modes, with the
  819. nuance that the maps will be local to the buffer.
  820. >
  821. call lh#menu#make("nic", '50.305', '&LaTeX.Run LaTeX &once', "<C-L><C-O>",
  822. \ '<buffer>', ":wa<CR>:call TKMakeDVIfile(1)<CR>")
  823. Second example:~
  824. This example demonstrates an hidden, but useful, behavior: if the mode is the
  825. visual one, then the register v is filled with the text of the visual area.
  826. This text can then be used in the function called. Here, it will be proposed
  827. as a default name for the section to insert:
  828. >
  829. function! TKinsertSec()
  830. " ...
  831. if (strlen(@v) != 0) && (visualmode() == 'v')
  832. let SecName = input("name of ".SecType.": ", @v)
  833. else
  834. let SecName = input("name of ".SecType.": ")
  835. endif
  836. " ...
  837. endfunction
  838. call lh#menu#make("vnic", '50.360.100', '&LaTeX.&Insert.&Section',
  839. \ "<C-L><C-S>", '<buffer>', ":call TKinsertSec()<CR>")
  840. We have to be cautious to one little thing, there is a side effect: the visual
  841. mode vanishes when we enter the function. If you don't want this to happen,
  842. use the non-existant command: |:VCall|.
  843. Third example:~
  844. If it is known that a function will be called only under |VISUAL-mode|, and
  845. that we don't want of the previous behavior, we can explicitly invoke the
  846. function with |:VCall| -- command that doesn't actually exist. Check
  847. lh-tex/ftplugin/tex/tex-set.vim |s:MapMenu4Env| for such an example.
  848. Fourth thing: actually, lh#menu#make() is not restricted to commands. The
  849. action can be anything that could come at the right hand side of any |:map| or
  850. |:menu| action. But this time, you have to be cautious with the modes you
  851. dedicate your map to. I won't give any related example ; this is the
  852. underlying approach in |lh#menu#IVN_make()|.
  853. *lh#menu#make()_modes*
  854. Implementation details:~
  855. The actual creation of the mappings is delegated to |lh#menu#map_all()|.
  856. If the {action} to execute doesn't start with ':', it is left untransformed,
  857. otherwise it is adapted depending on each {mode}:
  858. - INSERT-mode: each recognized |:command| call is prepended with |i_CTRL-O|
  859. - NORMAL-mode: the {action} is used as it is
  860. - VISUAL-mode: ":Vcall" is replaced by "\<cr>gV", otherwise the selection is
  861. recorded into @v register, the {action} command is executed after a
  862. |v_CTRL-C|, and eventually @v is cleared.
  863. The use is @v is deprecated, rely instead on |lh#menu#is_in_visual_mode()|
  864. and on |lh#selection#visual()|.
  865. - COMMAND-mode: the {action} is prepended with |c_CTRL-C|.
  866. Examples:
  867. See tests/lh/test-menu-map.vim
  868. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  869. *lh#menu#IVN_make()* {{{3
  870. Mappings & menus inserting text~
  871. lh#menu#IVN_make(<priority>, {text}, {key}, {IM-action}, {VM-action}, {NM-action} [, {nore-IM}, {nore-VM}, {nore-NM}])~
  872. lh#menu#IVN_MenuMake() accepts three different actions for the three modes:
  873. INSERT, VISUAL and NORMAL. The mappings defined will be relative to the
  874. current buffer -- this function is addressed to ftplugins writers. The last
  875. arguments specify whether the inner mappings and abbreviations embedded within
  876. the actions should be expanded or not ; i.e. are we defining
  877. «noremaps/noremenus» ?
  878. You will find very simple examples of what could be done at the end of
  879. menu-map.vim. Instead, I'll show here an extract of my TeX ftplugin: it
  880. defines complex functions that will help to define very simply the different
  881. mappings I use. You could find another variation on this theme in
  882. ftplugin/html/html_set.vim.
  883. >
  884. :MapMenu 50.370.300 &LaTeX.&Fonts.&Emphasize ]em emph
  885. call <SID>MapMenu4Env("50.370.200", '&LaTeX.&Environments.&itemize',
  886. \ ']ei', 'itemize', '\item ')
  887. The first command binds ]em to \emph{} for the three different modes. In
  888. INSERT mode, the cursor is positioned between the curly brackets, and a marker
  889. is added after the closing bracket -- cf. my bracketing system. In VISUAL
  890. mode, the curly brackets are added around the visual area. In NORMAL mode, the
  891. area is considered to be the current word.
  892. The second call binds for the three modes: ]ei to:
  893. >
  894. \begin{itemize}
  895. \item
  896. \end{itemize}
  897. The definition of the different functions and commands involved just follows.
  898. >
  899. command -nargs=1 -buffer MapMenu :call <SID>MapMenu(<f-args>)
  900. function! s:MapMenu(code,text,binding, tex_cmd, ...)
  901. let _2visual = (a:0 > 0) ? a:1 : "viw"
  902. " If the tex_cmd starts with an alphabetic character, then suppose the
  903. " command must begin with a '\'.
  904. let texc = ((a:tex_cmd[0] =~ '\a') ? '\' : "") . a:tex_cmd
  905. call lh#menu#IVN_make(a:code, a:text.' -- ' . texc .'{}', a:binding,
  906. \ texc.'{',
  907. \ '<ESC>`>a}<ESC>`<i' . texc . '{<ESC>%l',
  908. \ ( (_2visual=='0') ? "" : _2visual.a:binding),
  909. \ 0, 1, 0)
  910. endfunction
  911. " a function and its map to close a "}", and that works whatever the
  912. " activation states of the brackets and marking features are.
  913. function! s:Close()
  914. if strlen(maparg('{')) == 0 | exe "normal a} \<esc>"
  915. elseif exists("b:usemarks") && (b:usemarks==1) | exe "normal ¡jump! "
  916. else | exe "normal a "
  917. endif
  918. endfunction
  919. imap <buffer> ¡close! <c-o>:call <SID>Close()<cr>
  920. function! s:MapMenu4Env(code,text,binding, tex_env, middle, ...)
  921. let _2visual = (a:0 > 0) ? a:1 : "vip"
  922. let b = "'" . '\begin{' . a:tex_env . '}' . "'"
  923. let e = "'" . '\end{' . a:tex_env . '}' . "'"
  924. call IVN_MenuMake(a:code, a:text, a:binding,
  925. \ '\begin{'.a:tex_env.'¡close!<CR>'.a:middle.' <CR>\end{'.a:tex_env.'}<C-F><esc>ks',
  926. \ ':VCall MapAroundVisualLines('.b. ',' .e.',1,1)',
  927. \ _2visual.a:binding,
  928. \ 0, 1, 0)
  929. endfunction
  930. Examples:
  931. See tests/lh/test-menu-map.vim
  932. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  933. *lh#menu#is_in_visual_mode()* {{{3
  934. lh#menu#is_in_visual_mode()~
  935. @return a boolean that tells whether the {action} used in
  936. |lh#menu#is_in_visual_mode()| has been invoked from the VISUAL-mode.
  937. NB: this function deprecates the test on @v.
  938. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  939. *lh#menu#map_all()* {{{3
  940. lh#menu#map_all({map-type}[, {map-args...}])~
  941. This function is a helper function that defines several mappings at once as
  942. |:amenu| would do.
  943. @param {map-type} String of the form "[aincv]*(nore)?map" that tells the
  944. mode on which mappings should be defined, and whether
  945. the mappings shall be |:noremap|.
  946. @param {map-args...} Rest of the parameters that defines the mapping
  947. The action to execute will be corrected depending on the current mode. See
  948. |lh#menu#make()_modes| for more details.
  949. ------------------------------------------------------------------------------
  950. COMMANDS RELATED FUNCTIONS *lhvl#command* {{{2
  951. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  952. *lh#command#new()* {{{3
  953. Highly Experimental.
  954. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  955. *lh#command#Fargs2String()* {{{3
  956. lh#command#Fargs2String({aList})~
  957. @param[in,out] aList list of params from <f-args>
  958. @see tests/lh/test-Fargs2String.vim
  959. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  960. *lh#command#complete()* {{{3
  961. lh#command#complete({argLead}, {cmdLine}, {cursorPos})~
  962. Under developpement
  963. ------------------------------------------------------------------------------
  964. BUFFERS RELATED FUNCTIONS *lhvl#buffer* {{{2
  965. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  966. *lh#buffer#list()* {{{3
  967. lh#buffer#list()~
  968. @return The |List| of |buflisted| buffers.
  969. e.g.: >
  970. echo lh#list#transform(lh#buffer#list(), [], "bufname")
  971. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  972. *lh#buffer#Find()* {{{3
  973. lh#buffer#Find({filename}) (*deprecated*)~
  974. *lh#buffer#find()*
  975. lh#buffer#find({filename})~
  976. Searchs for a window where the buffer is opened.
  977. @param {filename}
  978. @return The number of the first window found, in which {filename} is opened.
  979. If {filename} is opened in a window, jump to this window. Otherwise, return
  980. -1.
  981. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  982. *lh#buffer#Jump()* {{{3
  983. lh#buffer#Jump({filename}, {cmd}) (*deprecated*)~
  984. *lh#buffer#jump()*
  985. lh#buffer#jump({filename}, {cmd})~
  986. Jumps to the window where the buffer is opened, or open the buffer in a new
  987. windows if none match.
  988. @param {filename}
  989. @param {cmd}
  990. @return Nothing.
  991. If {filename} is opened in a window, jump to this window.
  992. Otherwise, execute {cmd} with {filename} as a parameter. Typical values for
  993. the command will be "sp" or "vsp". (see |:split|, |:vsplit|).
  994. N.B.: While it is not the rationale behind this function, other commands that
  995. does not open the buffer may be used in the {cmd} parameter.
  996. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  997. *lh#buffer#Scratch()* {{{3
  998. lh#buffer#Scratch({bname},{where}) (*deprecated*)~
  999. *scratch* *lh#buffer#scratch()*
  1000. lh#buffer#scratch({bname},{where})~
  1001. Split-opens a new scratch buffer.
  1002. @param {bname} Name for the new scratch buffer
  1003. @param {where} Where the new scratch buffer will be opened ('', or 'v')
  1004. @post The buffer has the following properties set:
  1005. 'bt'=nofile, 'bh'=wipe, 'nobl', 'noswf', 'ro'
  1006. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  1007. *lhvl-dialog* *lh#buffer#dialog#* {{{3
  1008. Functions for building interactive dialogs~
  1009. Unlike other |lh-vim-lib| functions which can be used independently from each
  1010. others, all the lh#buffer#dialog#*() functions constitute a coherent framework
  1011. to define interactive dialogs.
  1012. For the moment it only supports the selection of one or several items in a
  1013. list.
  1014. From a end-user point of view, a list of items is displayed in a (|scratch|)
  1015. buffer. If enabled, the user can select (/tag) one or several items, and then
  1016. validate its choice. He can always abort and quit the dialog. A few other
  1017. features are also supported: a help message can be shown, the list may be
  1018. colored, etc.
  1019. The items displayed can be of any kind (function signatures, email addresses,
  1020. suggested spellings, ...), as well as the validating action. The
  1021. help-header can be customized, as well as colours, other mappings, ...
  1022. However the list displaying + selection aspect is almost hardcoded.
  1023. How it works~
  1024. ------------
  1025. Scripts have to call the function *lh#buffer#dialog#new()*
  1026. lh#buffer#dialog#new(bname, title, where, support-tagging, action, choices)~
  1027. with:
  1028. - {bname} being the name the |scratch| buffer will receive.
  1029. - {title} the title that appears at the first line of the scratch buffer.
  1030. I usually use it to display the name of the "client" script, its version,
  1031. and its purpose/what to do.
  1032. - {where} are |:split| options (like "bot below") used to open the scratch
  1033. buffer.
  1034. - {support-tagging} is a boolean (0/1) option to enable the multi-selection.
  1035. - {action} is the name of the callback function (more
  1036. advanced calling mechanisms latter may be supported later with
  1037. |lhvl-functions|).
  1038. - {choices} is the |List| of exact strings to display.
  1039. The #new function builds and returns a |Dictionary|, it also opens and fills
  1040. the scratch buffer, and put us within its context -- i.e. any |:map-<buffer>|
  1041. or other buffer-related definitions will done in the new scratch buffer.
  1042. Thus, if we want to add other mappings, and set a syntax highlighting for the
  1043. new buffer, it is done at this point (see the *s:PostInit()* function in my
  1044. "client" scripts like |lh-tags|).
  1045. At this point, I also add all the high level information to the
  1046. dictionary (for instance, the list of function signatures is nice, but
  1047. it does not provides enough information (the corresponding file, the
  1048. command to jump to the definition/declaration, the scope, ...)
  1049. The dictionary returned is filled with the following information:
  1050. - buffer ids,
  1051. - where was the cursor at the time of the creation of the new scratch buffer,
  1052. - name of the callback function.
  1053. Regarding the callback function: *lhvl-dialog-select-callback*
  1054. - It ca not be a |script-local| function, only global and autoload functions
  1055. are supported.
  1056. - When called, we are still within the scratch buffer context.
  1057. - It must accept a |List| of numbers as its first parameter: the index (+1) of
  1058. the items selected.
  1059. - The number 0, when in the list, means "aborted". In that case, the
  1060. callback function is expected to call |lh#buffer#dialog#quit()| that will
  1061. terminate the scratch buffer (with |:quit|), and jump back to where we were
  1062. when #new was called, and display a little "Abort" message.
  1063. - We can terminate the dialog with just :quit if we don't need to jump
  1064. back anywhere. For instance, lh-tags callback function first
  1065. terminates the dialog, then jumps to the file where the selected tag
  1066. comes from.
  1067. - It's completely asynchronous: the callback function does not return anything
  1068. to anyone, but instead applies transformations in other places.
  1069. This aspect is very important. I don't see how this kind of feature can work
  1070. if not asynchronously in vim.
  1071. How to customize it:
  1072. - *lh#buffer#dialog#quit()* can be explicitly called, from a registered select
  1073. callback (|lhvl-dialog-select-callback|), in order to terminate the dialog.
  1074. - *lh#buffer#dialog#add_help()* can be used to complete the help/usage message
  1075. in both its short and long form.
  1076. - *lh#buffer#dialog#update()* can be called after the list of items has been
  1077. altered in order to refresh what is displayed. The rationale behind this
  1078. feature is to support sorting, filtering, items expansion, etc. See
  1079. |lh-tags| implementation for an example.
  1080. - *lh#buffer#dialog#select()* can be used in new mappings in order to handle
  1081. differently the selected items.
  1082. |lh-tags| uses this function to map 'o' to the split-opening of the selected
  1083. items.
  1084. NB: the way this feature is supported may change in future releases.
  1085. Limitations:
  1086. This script is a little bit experimental (even if it the result of almost 10
  1087. years of evolution), and it is a little bit cumbersome.
  1088. - it is defined to support only one callback -- see the hacks in |lh-tags| to
  1089. workaround this limitation.
  1090. - it is defined to display list of items, and to select one or several items
  1091. in the end.
  1092. - and of course, it requires many other functions from |lh-vim-lib|, but
  1093. nothing else.
  1094. ------------------------------------------------------------------------------
  1095. SYNTAX RELATED FUNCTIONS *lhvl#syntax* {{{2
  1096. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  1097. *lh#syntax#NameAt()* {{{3
  1098. lh#syntax#NameAt({lnum},{col}[,{trans}]) (*deprecated*)~
  1099. *lh#syntax#name_at()*
  1100. lh#syntax#name_at({lnum},{col}[,{trans}])~
  1101. @param {lnum} line of the character
  1102. @param {col} column of the character
  1103. @param {trans} see |synID()|, default=0
  1104. @return the syntax kind of the given character at {lnum}, {col}
  1105. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  1106. *lh#syntax#NameAtMark()* {{{3
  1107. lh#syntax#NameAtMark({mark}[,{trans}]) (*deprecated*)~
  1108. *lh#syntax#is_a_comment()* {{{3
  1109. lh#syntax#is_a_comment({mark})~
  1110. @param {mark} position of the character
  1111. @return whether the character is within a Comment syntax element.
  1112. *lh#syntax#name_at_mark()* {{{3
  1113. lh#syntax#name_at_mark({mark}[,{trans}])~
  1114. @param {mark} position of the character
  1115. @param {trans} see |synID()|, default=0
  1116. @return the syntax kind of the character at the given |mark|.
  1117. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  1118. *lh#syntax#Skip()* *lh#syntax#SkipAt()* *lh#syntax#SkipAtMark()* {{{3
  1119. lh#syntax#Skip() (*deprecated*)~
  1120. lh#syntax#SkipAt({lnum},{col}) (*deprecated*)~
  1121. lh#syntax#SkipAtMark({mark}) (*deprecated*)~
  1122. *lh#syntax#skip()* *lh#syntax#skip_at()* *lh#syntax#skip_at_mark()*
  1123. lh#syntax#skip()~
  1124. lh#syntax#skip_at({lnum},{col})~
  1125. lh#syntax#skip_at_mark({mark})~
  1126. Functions to be used with |searchpair()| functions in order to search for a
  1127. pair of elements, without taking comments, strings, characters and doxygen
  1128. (syntax) contexts into account while searching.
  1129. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  1130. *lh#syntax#list_raw()* {{{3
  1131. lh#syntax#list_raw({name})~
  1132. @param {group-name}
  1133. @return the result of "syn list {group-name}" as a string
  1134. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  1135. *lh#syntax#list()* {{{3
  1136. lh#syntax#list()~
  1137. @param {group-name}
  1138. @return the result of "syn list {group-name}" as a list.
  1139. This function tries to interpret the result of the raw list of syntax
  1140. elements.
  1141. ------------------------------------------------------------------------------
  1142. COMPLETION RELATED FUNCTIONS *lhvl#completion* {{{2
  1143. *lh#icomplete#run()* {{{3
  1144. lh#icomplete#run(startcol, matches, Hook)~
  1145. Runs |complete()| and registers the {Hook} to be executed when the user
  1146. selects one entry in the menu.
  1147. ------------------------------------------------------------------------------
  1148. }}}1
  1149. ==============================================================================
  1150. © Luc Hermitte, 2001-2012 <http://code.google.com/p/lh-vim/>, CC by SA 3.0 {{{1
  1151. $Id: lh-vim-lib.txt 558 2012-04-10 08:00:00Z luc.hermitte $
  1152. VIM: let b:VS_language = 'american'
  1153. vim:ts=8:sw=4:tw=80:fo=tcq2:ft=help:
  1154. vim600:fdm=marker: