*vimple.txt*	Programmatic access to Vim's read-only command output.


			VIM REFERENCE MANUAL	by Barry Arthur


Help on using vimple                                                 *vimple*

1.  Introduction			|vimple-intro|
2.  View         			|vimple-view-command|
3.  Collect				|vimple-collect-command|
4.  GCollect				|vimple-gcollect-function|
5.  GCCollect				|vimple-gccollect-function|
6.  MyMaps         			|vimple-mymaps-command|
7.  ReadIntoBuffer			|vimple-readintobuffer-command|
8.  Filter				|vimple-filter-command|
9.  QFdo				|vimple-quickfix-commands|
10. BufDo				|vimple-bufdo-commands|
11. Overlay Tools			|vimple-overlay-tools|
12. Scope				|vimple-scope|
13. Custom Insert-mode Completers	|vimple-completers|


==============================================================================
 1. INTRODUCTION                                               *vimple-intro*

Vimple provides VimLOO (Object-oriented VimL) objects for several
built-in commands, such as:

* ls / buffers -> vimple#bl
* scriptnames  -> vimple#sn
* highlight    -> vimple#hl
* version      -> vimple#vn
* marks        -> vimple#ma
* maps         -> vimple#mp
* undolist     -> vimple#ul

These objects all support at least the following three methods:

* update() -> refresh the object's data
* to_s()   -> return a string representation fit for :echo
* to_l()   -> return a list representation

Vimple also provides the following two utility commands to make it
easier to work with Vim's command output:

==============================================================================
 2. VIEW                                     *:View* *vimple-view-command*
>
    :View <command>
<
View will show the output of the given command in a split window.
Having the output in a buffer makes it easily searchable and
modifiable. This command is great if all you want to do is quickly
check for the existance of somthing within the messy formatted output
of a command, or if you need to elaborately massage the output for
some reason. Being in a Vim buffer, you have all of Vim's editing
tools at your disposal.

By default, :View will prompt you for a pattern to filter the results by. If
you want to disable this default behaviour, add a line like this to your
|$MYVIMRC|:
>
  let vimple_auto_filter = []
< or >
  let vimple_auto_filter = ['vfm']
< (if you want auto-filter in VFM but not :View)

==============================================================================
 3. COLLECT                            *:Collect* *vimple-collect-command*
>
    :Collect <register-or-variable> <command>
<
Collect is useful for grabbing the command's output into a named
register or variable. This is useful for doing further programmatic
manipulations on the data. If the first argument is a single letter
[a-z] then it is treated as the corresponding register to save the
command output into. If you want to save the command output into a
variable, use a fully scoped variable, like:
>
    :Collect g:regs registers
<
==============================================================================
 4. GCollect()                    *GCollect()*  *vimple-gcollect-function*
>
    GCollect( pattern )
<
Uses "pattern" in a   :global /pattern/   command and returns the results as a
list of lines.
>
    :echo GCollect('^\s*===\s*')
<
==============================================================================
 5. GCCollect()                  *CGCollect()* *vimple-gccollect-function*
>
    GCCollect( pattern )
<
Uses "pattern" in a   :global /pattern/   command and returns the results as a
list of lines with the "pattern" stripped.
>
    :echo GCCollect('^\s*===\s*')

==============================================================================
 6. MYMAPS                               *:MyMaps* *vimple-mymaps-command*
>
  :MyMaps
<
Will show in a new buffer your curently active maps (:map and :map!). The maps
are displayed slightly differently to the builtin commands in that the map
special indicators (*, & and @) are shown immediately after the mode indicator
at the start of the map. <Plug> maps (where <plug> appears in the
lefthand-side) are removed for clarity, and the maps are sorted in an attempt
to group related maps together.

==============================================================================
 7. READINTOBUFFER       *:ReadIntoBuffer* *vimple-readintobuffer-command*
>
  :ReadIntoBuffer
<
For those times when you'd like to read in a subset of lines from a file.
>
  :ReadIntoBuffer foo 5 10
<
Will grab six lines (5 through 10, both inclusive) from file 'foo' into the
current file beneath the current line (as |:read| does).


It defaults to the current line, but you can specify another:
>
  :7 ReadIntoBuffer foo 5 10
<
Will grab six lines (5 through 10, both inclusive) from file 'foo' into the
current file beneath line seven (which means it starts on line 8 - the start
range in this command is exclusive; the end range (shown next) is inclusive.)


And you can limit the insertion range too:
>
  :7,9 ReadIntoBuffer foo 5 10
<
Will grab two lines (5 and 6) from file 'foo' into the current file beneath
line seven (therefore occupying lines 8 and 9 in the current buffer).

The usefulness of being able to limit the range at both ends is debatable, but
if I didn't I'd get requests to do so, surely.

==============================================================================
 8. FILTER                               *:Filter* *vimple-filter-command*
>
  :Filter
<
The :Filter command behaves like an interactive :g/re/p on the current buffer.
Only matching lines are shown, with non-matching ones being filtered out.

WARNING: This command alters your buffer contents. Using it from within a
         buffer you don't intend to filter is ill advised.


NEW!: :Filter is now even fuzzier! That's right! Put _down_ your hair-drier,
      because :Filter now automatically inserts `.*` whenever you press <space>!
      Awesomes, right? Searching for /some/long/path/to/file.boring?!
      Make it fun with   s l p t f      \o/

The :Filter command is heavily used by the |VimFindsMe| plugin from within its
browse window.

==============================================================================
 9. QUICKFIX COMMANDS                           *vimple-quickfix-commands*
                                                                    *QFdo*
NOTE: The location-list analogue for the QuickFix  commands start with LL

>
  :QFdo
  :LLdo
<
The :QFdo command performs the series of bar-separated ex-commands over the
buffers in the QuickFix list.

Example:
>
  :vimgrep /prince/j **/*.txt
  :QFdo %s/Vim/frog/g
<
Will change all princes into frogs recursively throughout your txt files.

NOTE: If you have the (https://github.com/dahu/grope) Grope plugin (which uses
      the |location-list|, this is even easier:
>
  :Grope /prince/ @@txt
  :LLdo %s/Vim/frog/g
<

>
  :QFbufs
  :LLbufs
<
Returns the unique list of buffer names within the QuickFix / Location list.

>
  :QFargs
  :QFargslocal
  :LLargs
  :LLargslocal
<
Sets the |:args| or |:arglocal| from the relevant list.

Example:
>
  :vimgrep /prince/j **/*.txt
  :tabnew | QFargslocal
<
Will open a new tab-page and set the local argument list to the unique set of
buffers contained within the QuickFix list.


==============================================================================
 10. BUFDO COMMANDS                                *vimple-bufdo-commands*
                                          *BufDo* *BufTypeDo* *BufMatchDo*

Example:
>
  :BufTypeDo vim %s/func\\>\\ze/&tion/e
<

Will replace 'func' with 'function' in all VIM files.

Note the use of the 'e' |s_flags| to ignore errors where the search term
doesn't exist in a file.

Example:
>
  :Nexus 1 1
  :BufMatchDo test g/Test/s/\\d\\+/\\=Nexus()
<

Will re-number the test cases in all files containing 'test' in their filename.

NOTE: This example depends on https://github.com/dahu/Nexus


==============================================================================
 11. OVERLAY TOOLS                                  *vimple-overlay-tools*
                                       *vimple-z=* *vimple-[I* *vimple-g]*

|z=|

Shows |spell| suggestions in an overlay window. Pressing `<enter>`
will replace the word under the cursor in the original window with the
current word under the cursor in the overlay.

Use `<plug>vimple_spell_suggest` if you want to map this behaviour
to a differnt key.

|[I|

Shows |ident-search| results in an overlay window. Pressing `<enter>`
will jump to the associated line of the identifier under the cursor.

Use `<plug>vimple_ident_search` if you want to map this behaviour
to a differnt key.

|g]|

Shows |tag| search results in an overlay window. Pressing `<enter>`
will jump to the associated line of the tag under the cursor.

Use `<plug>vimple_tag_search` if you want to map this behaviour
to a differnt key.



==============================================================================
 12. SCOPE                                                  *vimple-scope*

The Scope() function attempts to show the current function or class/method
scope. Some people like to display this information in their `statusline`,
like:
>
  set statusline=%f%m%r%h%w\ [%n:%{&ff}/%Y]\%{Scope()}%=[0x\%04.4B][%03v][%p%%\ line\ %l\ of\ %L]
<

Currently only Vim & Python (and Python only for testing purposes, created by
a NON Pythonista -- patches welcome) have been implemented, but it is very
easy for you to write scope functions for your own filetypes. Take Ruby for
example: Create `~/.vim/ftplugin/ruby_scope.vim` like this:

----
function! Scope_ruby()
  let class_scope  = scope#inspect('^\s*class\s\+\([a-zA-Z0-9_.]\+\)', '^\s*end')
  let method_scope = scope#inspect('^\s*def\s\+\([a-zA-Z0-9_.]\+\)', '^\s*end')
  return ' ' . join(map(class_scope.stack, 'v:val.head_line_number . "," . v:val.tail_line_number . " " . v:val.head_string'), ' :: ')
        \. ' >> ' . join(map(method_scope.stack, 'v:val.head_line_number . "," . v:val.tail_line_number . " " . v:val.head_string'), ' > ')
endfunction
----

NOTE: The above example for Ruby is woefully inadequate. A better effect might
be achievable with more context in the regex patterns. The patterns in
`syntax/ruby.vim` might be useful. Parsing with regex is futile.


==============================================================================
 13. COMPOSABLE COMPLETIONS                            *vimple-completers*
                                                               *vimple-jj*


By default, `jj` in insert mode activates a user-extendible meta-completion
list. The default list includes abbreviations (if you have
https://github.com/dahu/Aboriginal), some date-time patterns and the built-in
dictionary completion (`<c-x><c-k>`).

The default `jj` can be overridden like this:
>
  imap <c-x><c-c> <plug>vimple_completers_trigger
<

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