preliminary rubycomplete documentation for review

classic Classic list List threaded Threaded
17 messages Options
Reply | Threaded
Open this post in threaded view
|

preliminary rubycomplete documentation for review

Mark Guzman
Everyone,
  Please take a moment and look over ft-ruby-omni in the attached file.
  --mark

--
sic transit gloria et adulescentia
blog | http://blog.hasno.info/blog
wiki | http://wiki.hasno.info


*insert.txt*    For Vim version 7.0e.  Last change: 2006 Apr 14


                  VIM REFERENCE MANUAL    by Bram Moolenaar


                                                *Insert* *Insert-mode*
Inserting and replacing text *mode-ins-repl*

Most of this file is about Insert and Replace mode.  At the end are a few
commands for inserting text in other ways.

An overview of the most often used commands can be found in chapter 24 of the
user manual |usr_24.txt|.

1. Special keys |ins-special-keys|
2. Special special keys |ins-special-special|
3. 'textwidth' and 'wrapmargin' options |ins-textwidth|
4. 'expandtab', 'smarttab' and 'softtabstop'  options |ins-expandtab|
5. Replace mode |Replace-mode|
6. Virtual Replace mode |Virtual-Replace-mode|
7. Insert mode completion |ins-completion|
8. Insert mode commands |inserting|
9. Ex insert commands |inserting-ex|
10. Inserting a file |inserting-file|

Also see 'virtualedit', for moving the cursor to positions where there is no
character.  Useful for editing a table.

==============================================================================
1. Special keys *ins-special-keys*

In Insert and Replace mode, the following characters have a special meaning;
other characters are inserted directly.  To insert one of these special
characters into the buffer, precede it with CTRL-V.  To insert a <Nul>
character use "CTRL-V CTRL-@" or "CTRL-V 000".  On some systems, you have to
use "CTRL-V 003" to insert a CTRL-C.  Note: When CTRL-V is mapped you can
often use CTRL-Q instead |i_CTRL-Q|.

If you are working in a special language mode when inserting text, see the
'langmap' option, |'langmap'|, on how to avoid switching this mode on and off
all the time.

If you have 'insertmode' set, <Esc> and a few other keys get another meaning.
See |'insertmode'|.

char action ~
-----------------------------------------------------------------------
                                                *i_CTRL-[* *i_<Esc>*
<Esc> or CTRL-[ End insert or Replace mode, go back to Normal mode.  Finish
                abbreviation.
                Note: If your <Esc> key is hard to hit on your keyboard, train
                yourself to use CTRL-[.
                                                *i_CTRL-C*
CTRL-C Quit insert mode, go back to Normal mode.  Do not check for
                abbreviations.  Does not trigger the |InsertLeave| autocommand
                event.

                                                *i_CTRL-@*
CTRL-@ Insert previously inserted text and stop insert.  {Vi: only
                when typed as first char, only up to 128 chars}
                                                *i_CTRL-A*
CTRL-A Insert previously inserted text.  {not in Vi}

                                                *i_CTRL-H* *i_<BS>* *i_BS*
<BS> or CTRL-H Delete the character before the cursor (see |i_backspacing|
                about joining lines).
                See |:fixdel| if your <BS> key does not do what you want.
                {Vi: does not delete autoindents}
                                                *i_<Del>* *i_DEL*
<Del> Delete the character under the cursor.  If the cursor is at
                the end of the line, and the 'backspace' option includes
                "eol", delete the <EOL>; the next line is appended after the
                current one.
                See |:fixdel| if your <Del> key does not do what you want.
                {not in Vi}
                                                *i_CTRL-W*
CTRL-W Delete the word before the cursor (see |i_backspacing| about
                joining lines).  See the section "word motions",
                |word-motions|, for the definition of a word.
                                                *i_CTRL-U*
CTRL-U Delete all entered characters in the current line (see
                |i_backspacing| about joining lines).

                                                *i_CTRL-I* *i_<Tab>* *i_Tab*
<Tab> or CTRL-I Insert a tab.  If the 'expandtab' option is on, the
                equivalent number of spaces is inserted (use CTRL-V <Tab> to
                avoid the expansion; use CTRL-Q <Tab> if CTRL-V is mapped
                |i_CTRL-Q|).  See also the 'smarttab' option and
                |ins-expandtab|.
                                                *i_CTRL-J* *i_<NL>*
<NL> or CTRL-J Begin new line.
                                                *i_CTRL-M* *i_<CR>*
<CR> or CTRL-M Begin new line.
                                                *i_CTRL-K*
CTRL-K {char1} [char2]
                Enter digraph (see |digraphs|).  When {char1} is a special
                key, the code for that key is inserted in <> form.  For
                example, the string "<S-Space>" can be entered by typing
                <C-K><S-Space> (two keys).  Neither char is considered for
                mapping.  {not in Vi}

CTRL-N Find next keyword (see |i_CTRL-N|).  {not in Vi}
CTRL-P Find previous keyword (see |i_CTRL-P|).  {not in Vi}

CTRL-R {0-9a-z"%#*+:.-=} *i_CTRL-R*
                Insert the contents of a register.  Between typing CTRL-R and
                the second character, '"' will be displayed to indicate that
                you are expected to enter the name of a register.
                The text is inserted as if you typed it, but mappings and
                abbreviations are not used.  If you have options like
                'textwidth', 'formatoptions', or 'autoindent' set, this will
                influence what will be inserted.  This is different from what
                happens with the "p" command and pasting with the mouse.
                Special registers:
                        '"' the unnamed register, containing the text of
                                the last delete or yank
                        '%' the current file name
                        '#' the alternate file name
                        '*' the clipboard contents (X11: primary selection)
                        '+' the clipboard contents
                        '/' the last search pattern
                        ':' the last command-line
                        '.' the last inserted text
                        '-' the last small (less than a line) delete
                        '=' the expression register: you are prompted to
                                enter an expression (see |expression|)
                                Note that 0x80 (128 decimal) is used for
                                special keys.  E.g., you can use this to move
                                the cursor up:
                                        CTRL-R ="\<Up>"
                                Use CTRL-R CTRL-R to insert text literally.
                                When the result is a |List| the items are used
                                as lines.  They can have line breaks inside
                                too.
                See |registers| about registers.  {not in Vi}

CTRL-R CTRL-R {0-9a-z"%#*+/:.-=} *i_CTRL-R_CTRL-R*
                Insert the contents of a register.  Works like using a single
                CTRL-R, but the text is inserted literally, not as if typed.
                This differs when the register contains characters like <BS>.
                Example, where register a contains "ab^Hc": >
        CTRL-R a results in "ac".
        CTRL-R CTRL-R a results in "ab^Hc".
< Options 'textwidth', 'formatoptions', etc. still apply.  If
                you also want to avoid these, use "<C-R><C-O>r", see below.
                The '.' register (last inserted text) is still inserted as
                typed.  {not in Vi}

CTRL-R CTRL-O {0-9a-z"%#*+/:.-=} *i_CTRL-R_CTRL-O*
                Insert the contents of a register literally and don't
                auto-indent.  Does the same as pasting with the mouse
                |<MiddleMouse>|.
                Does not replace characters!
                The '.' register (last inserted text) is still inserted as
                typed.  {not in Vi}

CTRL-R CTRL-P {0-9a-z"%#*+/:.-=} *i_CTRL-R_CTRL-P*
                Insert the contents of a register literally and fix the
                indent, like |[<MiddleMouse>|.
                Does not replace characters!
                The '.' register (last inserted text) is still inserted as
                typed.  {not in Vi}

                                                *i_CTRL-T*
CTRL-T Insert one shiftwidth of indent at the start of the current
                line.  The indent is always rounded to a 'shiftwidth' (this is
                vi compatible).  {Vi: only when in indent}
                                                *i_CTRL-D*
CTRL-D Delete one shiftwidth of indent at the start of the current
                line.  The indent is always rounded to a 'shiftwidth' (this is
                vi compatible).  {Vi: CTRL-D works only when used after
                autoindent}
                                                *i_0_CTRL-D*
0 CTRL-D Delete all indent in the current line.  {Vi: CTRL-D works
                only when used after autoindent}
                                                *i_^_CTRL-D*
^ CTRL-D Delete all indent in the current line.  The indent is
                restored in the next line.  This is useful when inserting a
                label.  {Vi: CTRL-D works only when used after autoindent}

                                                *i_CTRL-V*
CTRL-V Insert next non-digit literally.  For special keys, the
                terminal code is inserted.  It's also possible to enter the
                decimal, octal or hexadecimal value of a character
                |i_CTRL-V_digit|.
                The characters typed right after CTRL-V are not considered for
                mapping.  {Vi: no decimal byte entry}
                Note: When CTRL-V is mapped (e.g., to paste text) you can
                often use CTRL-Q instead |i_CTRL-Q|.

                                                *i_CTRL-Q*
CTRL-Q Same as CTRL-V.
                Note: Some terminal connections may eat CTRL-Q, it doesn't
                work then.  It does work in the GUI.

CTRL-X Enter CTRL-X mode.  This is a sub-mode where commands can
                be given to complete words or scroll the window.  See
                |i_CTRL-X| and |ins-completion|. {not in Vi}

                                                *i_CTRL-E*
CTRL-E Insert the character which is below the cursor.  {not in Vi}
                                                *i_CTRL-Y*
CTRL-Y Insert the character which is above the cursor.  {not in Vi}
                Note that for CTRL-E and CTRL-Y 'textwidth' is not used, to be
                able to copy characters from a long line.

                                                *i_CTRL-_*
CTRL-_ Switch between languages, as follows:
                -  When in a rightleft window, revins and nohkmap are toggled,
                   since English will likely be inserted in this case.
                -  When in a norightleft window, revins and hkmap are toggled,
                   since Hebrew will likely be inserted in this case.

                CTRL-_ moves the cursor to the end of the typed text.

                This command is only available when the 'allowrevins' option
                is set.
                Please refer to |rileft.txt| for more information about
                right-to-left mode.
                {not in Vi}
                Only if compiled with the |+rightleft| feature (which is not
                the default).
                                                *i_CTRL-^*
CTRL-^ Toggle the use of typing language characters.
                When language |:lmap| mappings are defined:
                - If 'iminsert' is 1 (langmap mappings used) it becomes 0 (no
                  langmap mappings used).
                - If 'iminsert' has another value it becomes 1, thus langmap
                  mappings are enabled.
                When no language mappings are defined:
                - If 'iminsert' is 2 (Input Method used) it becomes 0 (no
                  Input Method used).
                - If 'iminsert' has another value it becomes 2, thus the Input
                  Method is enabled.
                When set to 1, the value of the "b:keymap_name" variable, the
                'keymap' option or "<lang>" appears in the status line.
                The language mappings are normally used to type characters
                that are different from what the keyboard produces.  The
                'keymap' option can be used to install a whole number of them.
                {not in Vi}

                                                *i_CTRL-]*
CTRL-] Trigger abbreviation, without inserting a character.  {not in
                Vi}

                                                *i_<Insert>*
<Insert> Toggle between Insert and Replace mode.  {not in Vi}
-----------------------------------------------------------------------

                                                *i_backspacing*
The effect of the <BS>, CTRL-W, and CTRL-U depend on the 'backspace' option
(unless 'revins' is set).  This is a comma separated list of items:

item    action ~
indent    allow backspacing over autoindent
eol    allow backspacing over end-of-line (join lines)
start    allow backspacing over the start position of insert; CTRL-W and
            CTRL-U stop once at the start position

When 'backspace' is empty, Vi compatible backspacing is used.  You cannot
backspace over autoindent, before column 1 or before where insert started.

For backwards compatibility the values "0", "1" and "2" are also allowed, see
|'backspace'|.

If the 'backspace' option does contain "eol" and the cursor is in column 1
when one of the three keys is used, the current line is joined with the
previous line.  This effectively deletes the <EOL> in front of the cursor.
{Vi: does not cross lines, does not delete past start position of insert}

                                                *i_CTRL-V_digit*
With CTRL-V the decimal, octal or hexadecimal value of a character can be
entered directly.  This way you can enter any character, except a line break
(<NL>, value 10).  There are five ways to enter the character value:

first char mode     max nr of chars   max value ~
(none) decimal   3 255
o or O octal   3 377 (255)
x or X hexadecimal   2 ff (255)
u hexadecimal   4 ffff (65535)
U hexadecimal   8 7fffffff (2147483647)

Normally you would type the maximum number of characters.  Thus to enter a
space (value 32) you would type <C-V>032.  You can omit the leading zero, in
which case the character typed after the number must be a non-digit.  This
happens for the other modes as well: As soon as you type a character that is
invalid for the mode, the value before it will be used and the "invalid"
character is dealt with in the normal way.

If you enter a value of 10, it will end up in the file as a 0.  The 10 is a
<NL>, which is used internally to represent the <Nul> character.  When writing
the buffer to a file, the <NL> character is translated into <Nul>.  The <NL>
character is written at the end of each line.  Thus if you want to insert a
<NL> character in a file you will have to make a line break.

                                                *i_CTRL-X* *insert_expand*
CTRL-X enters a sub-mode where several commands can be used.  Most of these
commands do keyword completion; see |ins-completion|.  These are not available
when Vim was compiled without the |+insert_expand| feature.

Two commands can be used to scroll the window up or down, without exiting
insert mode:

                                                *i_CTRL-X_CTRL-E*
CTRL-X CTRL-E scroll window one line up.
                        When doing completion look here: |complete_CTRL-E|

                                                *i_CTRL-X_CTRL-Y*
CTRL-X CTRL-Y scroll window one line down.
                        When doing completion look here: |complete_CTRL-Y|

After CTRL-X is pressed, each CTRL-E (CTRL-Y) scrolls the window up (down) by
one line unless that would cause the cursor to move from its current position
in the file.  As soon as another key is pressed, CTRL-X mode is exited and
that key is interpreted as in Insert mode.


==============================================================================
2. Special special keys *ins-special-special*

The following keys are special.  They stop the current insert, do something,
and then restart insertion.  This means you can do something without getting
out of Insert mode.  This is very handy if you prefer to use the Insert mode
all the time, just like editors that don't have a separate Normal mode.  You
may also want to set the 'backspace' option to "indent,eol,start" and set the
'insertmode' option.  You can use CTRL-O if you want to map a function key to
a command.

The changes (inserted or deleted characters) before and after these keys can
be undone separately.  Only the last change can be redone and always behaves
like an "i" command.

char action ~
-----------------------------------------------------------------------
<Up> cursor one line up     *i_<Up>*
<Down> cursor one line down     *i_<Down>*
CTRL-G <Up> cursor one line up, insert start column     *i_CTRL-G_<Up>*
CTRL-G k cursor one line up, insert start column     *i_CTRL-G_k*
CTRL-G CTRL-K cursor one line up, insert start column     *i_CTRL-G_CTRL-K*
CTRL-G <Down> cursor one line down, insert start column    *i_CTRL-G_<Down>*
CTRL-G j cursor one line down, insert start column    *i_CTRL-G_j*
CTRL-G CTRL-J cursor one line down, insert start column    *i_CTRL-G_CTRL-J*
<Left> cursor one character left     *i_<Left>*
<Right> cursor one character right     *i_<Right>*
<S-Left> cursor one word back (like "b" command)     *i_<S-Left>*
<C-Left> cursor one word back (like "b" command)     *i_<C-Left>*
<S-Right> cursor one word forward (like "w" command)   *i_<S-Right>*
<C-Right> cursor one word forward (like "w" command)   *i_<C-Right>*
<Home> cursor to first char in the line     *i_<Home>*
<End> cursor to after last char in the line     *i_<End>*
<C-Home> cursor to first char in the file     *i_<C-Home>*
<C-End> cursor to after last char in the file     *i_<C-End>*
<LeftMouse> cursor to position of mouse click     *i_<LeftMouse>*
<S-Up> move window one page up     *i_<S-Up>*
<PageUp> move window one page up     *i_<PageUp>*
<S-Down> move window one page down     *i_<S-Down>*
<PageDown> move window one page down     *i_<PageDown>*
<MouseDown> scroll three lines down     *i_<MouseDown>*
<S-MouseDown> scroll a full page down     *i_<S-MouseDown>*
<MouseUp> scroll three lines up     *i_<MouseUp>*
<S-MouseUp> scroll a full page up     *i_<S-MouseUp>*
CTRL-O execute one command, return to Insert mode   *i_CTRL-O*
CTRL-\ CTRL-O like CTRL-O but don't move the cursor     *i_CTRL-\_CTRL-O*
CTRL-L when 'insertmode' is set: go to Normal mode  *i_CTRL-L*
CTRL-G u break undo sequence, start new change     *i_CTRL-G_u*
-----------------------------------------------------------------------

Note: If the cursor keys take you out of Insert mode, check the 'noesckeys'
option.

The CTRL-O command sometimes has a side effect: If the cursor was beyond the
end of the line, it will be put on the last character in the line.  In
mappings it's often better to use <Esc> (first put an "x" in the text, <Esc>
will then always put the cursor on it).  Or use CTRL-\ CTRL-O, but then
beware of the cursor possibly being beyond the end of the line.

The shifted cursor keys are not available on all terminals.

Another side effect is that a count specified before the "i" or "a" command is
ignored.  That is because repeating the effect of the command after CTRL-O is
too complicated.

An example for using CTRL-G u: >

        :inoremap <C-H> <C-G>u<C-H>

This redefines the backspace key to start a new undo sequence.  You can now
undo the effect of the backspace key, without changing what you typed before
that, with CTRL-O u.

Using CTRL-O splits undo: the text typed before and after it is undone
separately.  If you want to avoid this (e.g., in a mapping) you might be able
to use CTRL-R = |i_CTRL-R|.  E.g., to call a function: >
        :imap <F2> <C-R>=MyFunc()<CR>

When the 'whichwrap' option is set appropriately, the <Left> and <Right>
keys on the first/last character in the line make the cursor wrap to the
previous/next line.

The CTRL-G j and CTRL-G k commands can be used to insert text in front of a
column.  Example: >
   int i;
   int j;
Position the cursor on the first "int", type "istatic <C-G>j       ".  The
result is: >
   static int i;
          int j;
When inserting the same text in front of the column in every line, use the
Visual blockwise command "I" |v_b_I|.

==============================================================================
3. 'textwidth' and 'wrapmargin' options *ins-textwidth*

The 'textwidth' option can be used to automatically break a line before it
gets too long.  Set the 'textwidth' option to the desired maximum line
length.  If you then type more characters (not spaces or tabs), the
last word will be put on a new line (unless it is the only word on the
line).  If you set 'textwidth' to 0, this feature is disabled.

The 'wrapmargin' option does almost the same.  The difference is that
'textwidth' has a fixed width while 'wrapmargin' depends on the width of the
screen.  When using 'wrapmargin' this is equal to using 'textwidth' with a
value equal to (columns - 'wrapmargin'), where columns is the width of the
screen.

When 'textwidth' and 'wrapmargin' are both set, 'textwidth' is used.

If you don't really want to break the line, but view the line wrapped at a
convenient place, see the 'linebreak' option.

The line is only broken automatically when using Insert mode, or when
appending to a line.  When in replace mode and the line length is not
changed, the line will not be broken.

Long lines are broken if you enter a non-white character after the margin.
The situations where a line will be broken can be restricted by adding
characters to the 'formatoptions' option:
"l"  Only break a line if it was not longer than 'textwidth' when the insert
     started.
"v"  Only break at a white character that has been entered during the
     current insert command.  This is mostly Vi-compatible.
"lv" Only break if the line was not longer than 'textwidth' when the insert
     started and only at a white character that has been entered during the
     current insert command.  Only differs from "l" when entering non-white
     characters while crossing the 'textwidth' boundary.

Normally an internal function will be used to decide where to break the line.
If you want to do it in a different way set the 'formatexpr' option to an
expression that will take care of the line break.

If you want to format a block of text, you can use the "gq" operator.  Type
"gq" and a movement command to move the cursor to the end of the block.  In
many cases, the command "gq}" will do what you want (format until the end of
paragraph).  Alternatively, you can use "gqap", which will format the whole
paragraph, no matter where the cursor currently is.  Or you can use Visual
mode: hit "v", move to the end of the block, and type "gq".  See also |gq|.

==============================================================================
4. 'expandtab', 'smarttab' and 'softtabstop' options *ins-expandtab*

If the 'expandtab' option is on, spaces will be used to fill the amount of
whitespace of the tab.  If you want to enter a real <Tab>, type CTRL-V first
(use CTRL-Q when CTRL-V is mapped |i_CTRL-Q|).
The 'expandtab' option is off by default.  Note that in Replace mode, a single
character is replaced with several spaces.  The result of this is that the
number of characters in the line increases.  Backspacing will delete one
space at a time.  The original character will be put back for only one space
that you backspace over (the last one).  {Vi does not have the 'expandtab'
option}

                                                        *ins-smarttab*
When the 'smarttab' option is on, a <Tab> inserts 'shiftwidth' positions at
the beginning of a line and 'tabstop' positions in other places.  This means
that often spaces instead of a <Tab> character are inserted.  When 'smarttab
is off, a <Tab> always inserts 'tabstop' positions, and 'shiftwidth' is only
used for ">>" and the like.  {not in Vi}

                                                        *ins-softtabstop*
When the 'softtabstop' option is non-zero, a <Tab> inserts 'softtabstop'
positions, and a <BS> used to delete white space, will delete 'softtabstop'
positions.  This feels like 'tabstop' was set to 'softtabstop', but a real
<Tab> character still takes 'tabstop' positions, so your file will still look
correct when used by other applications.

If 'softtabstop' is non-zero, a <BS> will try to delete as much white space to
move to the previous 'softtabstop' position, except when the previously
inserted character is a space, then it will only delete the character before
the cursor.  Otherwise you cannot always delete a single character before the
cursor.  You will have to delete 'softtabstop' characters first, and then type
extra spaces to get where you want to be.

==============================================================================
5. Replace mode *Replace* *Replace-mode* *mode-replace*

Enter Replace mode with the "R" command in normal mode.

In Replace mode, one character in the line is deleted for every character you
type.  If there is no character to delete (at the end of the line), the
typed character is appended (as in Insert mode).  Thus the number of
characters in a line stays the same until you get to the end of the line.
If a <NL> is typed, a line break is inserted and no character is deleted.

Be careful with <Tab> characters.  If you type a normal printing character in
its place, the number of characters is still the same, but the number of
columns will become smaller.

If you delete characters in Replace mode (with <BS>, CTRL-W, or CTRL-U), what
happens is that you delete the changes.  The characters that were replaced
are restored.  If you had typed past the existing text, the characters you
added are deleted.  This is effectively a character-at-a-time undo.

If the 'expandtab' option is on, a <Tab> will replace one character with
several spaces.  The result of this is that the number of characters in the
line increases.  Backspacing will delete one space at a time.  The original
character will be put back for only one space that you backspace over (the
last one).  {Vi does not have the 'expandtab' option}

==============================================================================
6. Virtual Replace mode *vreplace-mode* *Virtual-Replace-mode*

Enter Virtual Replace mode with the "gR" command in normal mode.
{not available when compiled without the +vreplace feature}
{Vi does not have Virtual Replace mode}

Virtual Replace mode is similar to Replace mode, but instead of replacing
actual characters in the file, you are replacing screen real estate, so that
characters further on in the file never appear to move.

So if you type a <Tab> it may replace several normal characters, and if you
type a letter on top of a <Tab> it may not replace anything at all, since the
<Tab> will still line up to the same place as before.

Typing a <NL> still doesn't cause characters later in the file to appear to
move.  The rest of the current line will be replaced by the <NL> (that is,
they are deleted), and replacing continues on the next line.  A new line is
NOT inserted unless you go past the end of the file.

Interesting effects are seen when using CTRL-T and CTRL-D.  The characters
before the cursor are shifted sideways as normal, but characters later in the
line still remain still.  CTRL-T will hide some of the old line under the
shifted characters, but CTRL-D will reveal them again.

As with Replace mode, using <BS> etc will bring back the characters that were
replaced.  This still works in conjunction with 'smartindent', CTRL-T and
CTRL-D, 'expandtab', 'smarttab', 'softtabstop', etc.

In 'list' mode, Virtual Replace mode acts as if it was not in 'list' mode,
unless "L" is in 'cpoptions'.

Note that the only times characters beyond the cursor should appear to move
are in 'list' mode, and occasionally when 'wrap' is set (and the line changes
length to become shorter or wider than the width of the screen), or
momentarily when typing over a CTRL character.  A CTRL character takes up two
screen spaces.  When replacing it with two normal characters, the first will
be inserted and the second will replace the CTRL character.

This mode is very useful for editing <Tab> separated columns in tables, for
entering new data while keeping all the columns aligned.

==============================================================================
7. Insert mode completion *ins-completion*

In Insert and Replace mode, there are several commands to complete part of a
keyword or line that has been typed.  This is useful if you are using
complicated keywords (e.g., function names with capitals and underscores).

These commands are not available when the |+insert_expand| feature was
disabled at compile time.

Completion can be done for:

1. Whole lines |i_CTRL-X_CTRL-L|
2. keywords in the current file |i_CTRL-X_CTRL-N|
3. keywords in 'dictionary' |i_CTRL-X_CTRL-K|
4. keywords in 'thesaurus', thesaurus-style |i_CTRL-X_CTRL-T|
5. keywords in the current and included files |i_CTRL-X_CTRL-I|
6. tags |i_CTRL-X_CTRL-]|
7. file names |i_CTRL-X_CTRL-F|
8. definitions or macros |i_CTRL-X_CTRL-D|
9. Vim command-line |i_CTRL-X_CTRL-V|
10. User defined completion |i_CTRL-X_CTRL-U|
11. omni completion |i_CTRL-X_CTRL-O|
12. Spelling suggestions |i_CTRL-X_s|
13. keywords in 'complete' |i_CTRL-N|

All these (except 2) are done in CTRL-X mode.  This is a sub-mode of Insert
and Replace modes.  You enter CTRL-X mode by typing CTRL-X and one of the
CTRL-X commands.  You exit CTRL-X mode by typing a key that is not a valid
CTRL-X mode command.  Valid keys are the CTRL-X command itself, CTRL-N (next),
and CTRL-P (previous).

Also see the 'infercase' option if you want to adjust the case of the match.

                                                        *complete_CTRL-E*
When completion is active you can use CTRL-E to stop it and go back to the
orignally typed text.  The CTRL-E will not be inserted.

                                                        *complete_CTRL-Y*
When the popup menu is displayed you can use CTRL-Y to stop completion and
accept the currently selected entry.  The CTRL-Y is not inserted.  Typing a
space, Enter, or some other unprintable character will leave completion mode
and insert that typed character.

When the popup menu is displayed there are a few more special keys, see
|popupmenu-keys|.

Note: The keys that are valid in CTRL-X mode are not mapped.  This allows for
":map ^F ^X^F" to work (where ^F is CTRL-F and ^X is CTRL-X).  The key that
ends CTRL-X mode (any key that is not a valid CTRL-X mode command) is mapped.
Also, when doing completion with 'complete' mappings apply as usual.

The following mappings are suggested to make typing the completion commands
a bit easier (although they will hide other commands): >
    :inoremap ^] ^X^]
    :inoremap ^F ^X^F
    :inoremap ^D ^X^D
    :inoremap ^L ^X^L

As a special case, typing CTRL-R to perform register insertion (see
|i_CTRL-R|) will not exit CTRL-X mode.  This is primarily to allow the use of
the '=' register to call some function to determine the next operation.  If
the contents of the register (or result of the '=' register evaluation) are
not valid CTRL-X mode keys, then CTRL-X mode will be exited as if those keys
had been typed.

For example, the following will map <Tab> to either actually insert a <Tab> if
the current line is currently only whitespace, or start/continue a CTRL-N
completion operation: >

        function! CleverTab()
           if strpart( getline('.'), 0, col('.')-1 ) =~ '^\s*$'
              return "\<Tab>"
           else
              return "\<C-N>"
        endfunction
        inoremap <Tab> <C-R>=CleverTab()<CR>



Completing whole lines *compl-whole-line*

                                                        *i_CTRL-X_CTRL-L*
CTRL-X CTRL-L Search backwards for a line that starts with the
                        same characters as those in the current line before
                        the cursor.  Indent is ignored.  The matching line is
                        inserted in front of the cursor.
                        The 'complete' option is used to decide which buffers
                        are searched for a match.  Both loaded and unloaded
                        buffers are used.
        CTRL-L or
        CTRL-P Search backwards for next matching line.  This line
                        replaces the previous matching line.

        CTRL-N Search forward for next matching line.  This line
                        replaces the previous matching line.

        CTRL-X CTRL-L After expanding a line you can additionally get the
                        line next to it by typing CTRL-X CTRL-L again, unless
                        a double CTRL-X is used.

Completing keywords in current file *compl-current*

                                                        *i_CTRL-X_CTRL-P*
                                                        *i_CTRL-X_CTRL-N*
CTRL-X CTRL-N Search forwards for words that start with the keyword
                        in front of the cursor.  The found keyword is inserted
                        in front of the cursor.

CTRL-X CTRL-P Search backwards for words that start with the keyword
                        in front of the cursor.  The found keyword is inserted
                        in front of the cursor.

        CTRL-N Search forward for next matching keyword.  This
                        keyword replaces the previous matching keyword.

        CTRL-P Search backwards for next matching keyword.  This
                        keyword replaces the previous matching keyword.

        CTRL-X CTRL-N or
        CTRL-X CTRL-P Further use of CTRL-X CTRL-N or CTRL-X CTRL-P will
                        copy the words following the previous expansion in
                        other contexts unless a double CTRL-X is used.

If there is a keyword in front of the cursor (a name made out of alphabetic
characters and characters in 'iskeyword'), it is used as the search pattern,
with "\<" prepended (meaning: start of a word).  Otherwise "\<\k\k" is used
as search pattern (start of any keyword of at least two characters).

In Replace mode, the number of characters that are replaced depends on the
length of the matched string.  This works like typing the characters of the
matched string in Replace mode.

If there is not a valid keyword character before the cursor, any keyword of
at least two characters is matched.
        e.g., to get:
            printf("(%g, %g, %g)", vector[0], vector[1], vector[2]);
        just type:
            printf("(%g, %g, %g)", vector[0], ^P[1], ^P[2]);

The search wraps around the end of the file, the value of 'wrapscan' is not
used here.

Multiple repeats of the same completion are skipped; thus a different match
will be inserted at each CTRL-N and CTRL-P (unless there is only one
matching keyword).

Single character matches are never included, as they usually just get in
the way of what you were really after.
        e.g., to get:
                printf("name = %s\n", name);
        just type:
                printf("name = %s\n", n^P);
        or even:
                printf("name = %s\n", ^P);
The 'n' in '\n' is skipped.

After expanding a word, you can use CTRL-X CTRL-P or CTRL-X CTRL-N to get the
word following the expansion in other contexts.  These sequences search for
the text just expanded and further expand by getting an extra word.  This is
useful if you need to repeat a sequence of complicated words.  Although CTRL-P
and CTRL-N look just for strings of at least two characters, CTRL-X CTRL-P and
CTRL-X CTRL-N can be used to expand words of just one character.
        e.g., to get:
                M&eacute;xico
        you can type:
                M^N^P^X^P^X^P
CTRL-N starts the expansion and then CTRL-P takes back the single character
"M", the next two CTRL-X CTRL-P's get the words "&eacute" and ";xico".

If the previous expansion was split, because it got longer than 'textwidth',
then just the text in the current line will be used.

If the match found is at the end of a line, then the first word in the next
line will be inserted and the message "word from next line" displayed, if
this word is accepted the next CTRL-X CTRL-P or CTRL-X CTRL-N will search
for those lines starting with this word.


Completing keywords in 'dictionary' *compl-dictionary*

                                                        *i_CTRL-X_CTRL-K*
CTRL-X CTRL-K Search the files given with the 'dictionary' option
                        for words that start with the keyword in front of the
                        cursor.  This is like CTRL-N, but only the dictionary
                        files are searched, not the current file.  The found
                        keyword is inserted in front of the cursor.  This
                        could potentially be pretty slow, since all matches
                        are found before the first match is used.  By default,
                        the 'dictionary' option is empty.
                        For suggestions where to find a list of words, see the
                        'dictionary' option.

        CTRL-K or
        CTRL-N Search forward for next matching keyword.  This
                        keyword replaces the previous matching keyword.

        CTRL-P Search backwards for next matching keyword.  This
                        keyword replaces the previous matching keyword.

                                                        *i_CTRL-X_CTRL-T*
CTRL-X CTRL-T Works as CTRL-X CTRL-K, but in a special way.  It uses
                        the 'thesaurus' option instead of 'dictionary'.  If a
                        match is found in the thesaurus file, all the
                        remaining words on the same line are included as
                        matches, even though they don't complete the word.
                        Thus a word can be completely replaced.

                        For an example, imagine the 'thesaurus' file has a
                        line like this: >
                                angry furious mad enraged
< Placing the cursor after the letters "ang" and typing
                        CTRL-X CTRL-T would complete the word "angry";
                        subsequent presses would change the word to "furious",
                        "mad" etc.
                        Other uses include translation between two languages,
                        or grouping API functions by keyword.

        CTRL-T or
        CTRL-N Search forward for next matching keyword.  This
                        keyword replaces the previous matching keyword.

        CTRL-P Search backwards for next matching keyword.  This
                        keyword replaces the previous matching keyword.


Completing keywords in the current and included files *compl-keyword*

The 'include' option is used to specify a line that contains an include file
name.  The 'path' option is used to search for include files.

                                                        *i_CTRL-X_CTRL-I*
CTRL-X CTRL-I Search for the first keyword in the current and
                        included files that starts with the same characters
                        as those before the cursor.  The matched keyword is
                        inserted in front of the cursor.

        CTRL-N Search forwards for next matching keyword.  This
                        keyword replaces the previous matching keyword.
                        Note: CTRL-I is the same as <Tab>, which is likely to
                        be typed after a successful completion, therefore
                        CTRL-I is not used for searching for the next match.

        CTRL-P Search backward for previous matching keyword.  This
                        keyword replaces the previous matching keyword.

        CTRL-X CTRL-I Further use of CTRL-X CTRL-I will copy the words
                        following the previous expansion in other contexts
                        unless a double CTRL-X is used.

Completing tags *compl-tag*
                                                        *i_CTRL-X_CTRL-]*
CTRL-X CTRL-] Search for the first tag that starts with the same
                        characters as before the cursor.  The matching tag is
                        inserted in front of the cursor.  Alphabetic
                        characters and characters in 'iskeyword' are used
                        to decide which characters are included in the tag
                        name (same as for a keyword).  See also |CTRL-]|.
                        The 'showfulltag' option can be used to add context
                        from around the tag definition.
        CTRL-] or
        CTRL-N Search forwards for next matching tag.  This tag
                        replaces the previous matching tag.

        CTRL-P Search backward for previous matching tag.  This tag
                        replaces the previous matching tag.


Completing file names *compl-filename*
                                                        *i_CTRL-X_CTRL-F*
CTRL-X CTRL-F Search for the first file name that starts with the
                        same characters as before the cursor.  The matching
                        file name is inserted in front of the cursor.
                        Alphabetic characters and characters in 'isfname'
                        are used to decide which characters are included in
                        the file name.  Note: the 'path' option is not used
                        here (yet).
        CTRL-F or
        CTRL-N Search forwards for next matching file name.  This
                        file name replaces the previous matching file name.

        CTRL-P Search backward for previous matching file name.
                        This file name replaces the previous matching file
                        name.


Completing definitions or macros *compl-define*

The 'define' option is used to specify a line that contains a definition.
The 'include' option is used to specify a line that contains an include file
name.  The 'path' option is used to search for include files.

                                                        *i_CTRL-X_CTRL-D*
CTRL-X CTRL-D Search in the current and included files for the
                        first definition (or macro) name that starts with
                        the same characters as before the cursor.  The found
                        definition name is inserted in front of the cursor.
        CTRL-D or
        CTRL-N Search forwards for next matching macro name.  This
                        macro name replaces the previous matching macro
                        name.

        CTRL-P Search backward for previous matching macro name.
                        This macro name replaces the previous matching macro
                        name.

        CTRL-X CTRL-D Further use of CTRL-X CTRL-D will copy the words
                        following the previous expansion in other contexts
                        unless a double CTRL-X is used.


Completing Vim commands *compl-vim*

Completion is context-sensitive.  It works like on the Command-line.  It
completes an Ex command as well as its arguments.  This is useful when writing
a Vim script.

                                                        *i_CTRL-X_CTRL-V*
CTRL-X CTRL-V Guess what kind of item is in front of the cursor and
                        find the first match for it.
                        Note: When CTRL-V is mapped you can often use CTRL-Q
                        instead |i_CTRL-Q|.
        CTRL-V or
        CTRL-N Search forwards for next match.  This match replaces
                        the previous one.

        CTRL-P Search backward for previous match.  This match
                        replaces the previous one.

        CTRL-X CTRL-V Further use of CTRL-X CTRL-V will do the same as
                        CTRL-V.  This allows mapping a key to do Vim command
                        completion, for example: >
                                :imap <Tab> <C-X><C-V>

User defined completion *compl-function*

Completion is done by a function that can be defined by the user with the
'completefunc' option.  See below for how the function is called and an
example |complete-functions|.

                                                        *i_CTRL-X_CTRL-U*
CTRL-X CTRL-U Guess what kind of item is in front of the cursor and
                        find the first match for it.
        CTRL-U or
        CTRL-N Use the next match.  This match replaces the previous
                        one.

        CTRL-P Use the previous match.  This match replaces the
                        previous one.


Omni completion *compl-omni*

Completion is done by a function that can be defined by the user with the
'omnifunc' option.  This is to be used for filetype-specific completion.

See below for how the function is called and an example |complete-functions|.
For remarks about specific filetypes see |compl-omni-filetypes|.

                                                        *i_CTRL-X_CTRL-O*
CTRL-X CTRL-O Guess what kind of item is in front of the cursor and
                        find the first match for it.
        CTRL-O or
        CTRL-N Use the next match.  This match replaces the previous
                        one.

        CTRL-P Use the previous match.  This match replaces the
                        previous one.


Spelling suggestions *compl-spelling*

A word before or at the cursor is located and correctly spelled words are
suggested to replace it.  If there is a badly spelled word in the line, before
or under the cursor, the cursor is moved to after it.  Otherwise the word just
before the cursor is used for suggestions, even though it isn't badly spelled.

NOTE: CTRL-S suspends display in many Unix terminals.  Use 's' instead.  Type
CTRL-Q to resume displaying.

                                                *i_CTRL-X_CTRL-S* *i_CTRL-X_s*
CTRL-X CTRL-S   or
CTRL-X s Locate the word in front of the cursor and find the
                        first spell suggestion for it.
        CTRL-S or
        CTRL-N Use the next suggestion.  This replaces the previous
                        one.  Note that you can't use 's' here.

        CTRL-P Use the previous suggestion.  This replaces the
                        previous one.


Completing keywords from different sources *compl-generic*

                                                        *i_CTRL-N*
CTRL-N Find next match for words that start with the
                        keyword in front of the cursor, looking in places
                        specified with the 'complete' option.  The found
                        keyword is inserted in front of the cursor.

                                                        *i_CTRL-P*
CTRL-P Find previous match for words that start with the
                        keyword in front of the cursor, looking in places
                        specified with the 'complete' option.  The found
                        keyword is inserted in front of the cursor.

        CTRL-N Search forward for next matching keyword.  This
                        keyword replaces the previous matching keyword.

        CTRL-P Search backwards for next matching keyword.  This
                        keyword replaces the previous matching keyword.

        CTRL-X CTRL-N or
        CTRL-X CTRL-P Further use of CTRL-X CTRL-N or CTRL-X CTRL-P will
                        copy the words following the previous expansion in
                        other contexts unless a double CTRL-X is used.


FUNCTIONS FOR FINDING COMPLETIONS *complete-functions*

This applies to 'completefunc' and 'omnifunc'.

The function is called in two different ways:
- First the function is called to find the start of the text to be completed.
- Later the function is called to actually find the matches.

On the first invocation the arguments are:
   a:findstart  1
   a:base empty

The function must return the column where the completion starts.  It must be a
number between zero and the cursor column "col('.')".  This involves looking
at the characters just before the cursor and including those characters that
could be part of the completed item.  The text between this column and the
cursor column will be replaced with the matches.  Return -1 if no completion
can be done.

On the second invocation the arguments are:
   a:findstart  0
   a:base the text with which matches should match; the text that was
                located in the first call (can be empty)

The function must return a List with the matching words.  These matches
usually include the "a:base" text.  When there are no matches return an empty
List.
                                                *complete-items*
Each list item can either be a string or a Dictionary.  When it is a string it
is used as the completion.  When it is a Dictionary it can contain these
items:
        word the text that will be inserted, mandatory
        abbr abbreviation of "word"; when not empty it is used in
                        the menu instead of "word"
        menu extra text for the popup menu, displayed after "word"
                        or "abbr"
        info more information about the item, can be displayed in a
                        preview window
        kind single letter indicating the type of completion
        icase when non-zero case is to be ignored; when omitted
                        the 'ignorecase' option is used

All of these except 'icase' must be a string.  If an item does not meet these
requirements then an error message is given and further items in the list are
not used.  You can mix string and Dictionary items in the returned list.

The "menu" item is used in the popup menu and may be truncated, thus it should
be relatively short.  The "info" item can be longer, it will  be displayed in
the preview window when "preview" appears in 'completeopt'.  The "info" item
will also remain displayed after the popup menu has been removed.  This is
useful for function arguments.

The "kind" item uses a single letter to indicate the kind of completion.  This
may be used to show the completion differently (different color or icon).
Currently these types can be used:
        v variable
        f function or method
        m member of a struct or class
        t typedef
        d #define or macro

When searching for matches takes some time call |complete_add()| to add each
match to the total list.  These matches should then not appear in the returned
list!  Call |complete_check()| now and then to allow the user to press a key
while still searching for matches.  Stop searching when it returns non-zero.

The function is allowed to move the cursor, it is restored afterwards.  This
option cannot be set from a |modeline| or in the |sandbox|, for security
reasons.

An example that completes the names of the months: >
        fun! CompleteMonths(findstart, base)
          if a:findstart
            " locate the start of the word
            let line = getline('.')
            let start = col('.') - 1
            while start > 0 && line[start - 1] =~ '\a'
              let start -= 1
            endwhile
            return start
          else
            " find months matching with "a:base"
            let res = []
            for m in split("Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec")
              if m =~ '^' . a:base
                call add(res, m)
              endif
            endfor
            return res
          endif
        endfun
        set completefunc=CompleteMonths
<
The same, but now pretending searching for matches is slow: >
        fun! CompleteMonths(findstart, base)
          if a:findstart
            " locate the start of the word
            let line = getline('.')
            let start = col('.') - 1
            while start > 0 && line[start - 1
Reply | Threaded
Open this post in threaded view
|

Re: preliminary rubycomplete documentation for review

Gavin Sinclair
On 4/20/06, Mark Guzman <[hidden email]> wrote:
> Everyone,
>   Please take a moment and look over ft-ruby-omni in the attached file.
>   --mark


My suggested replacement for the relevant section is below.  I aimed
for a style that's consistent with the rest of the Vim online help.

It should be viewed in Vim with ':set filetype=help' to see the highlighting.

BTW Mark, your prelim documentation mentioned that object specific
completion would be done after any of {. : ::}.  What is ":" supposed
to do?

Cheers,
Gavin

P.S. Please only send the relevant text in future.  The attachment
before was so large that Mailman asked me to approve it before it
could be posted to the list!


== begin

RUBY                                                    *ft-ruby-omni*

Completion of Ruby code requires that vim be built with |+ruby|.

Ruby completion will parse your buffer on demand in order to provide a list of
completions.  These completions will be drawn from modules loaded by 'require'
and modules defined in the current buffer.

The completions provided by CTRL-X CTRL-O are sensitive to the context:

          CONTEXT                          COMPLETIONS PROVIDED ~

 1. Not inside a class definition    Classes, constants and globals

 2. Inside a class definition        Methods or constants defined in the class

 3. After '.' or '::'                Methods applicable to the object being
                                       dereferenced

Notes:
 - Vim will load/evaluate code in order to provide completions.  This may
   cause some code execution, which may be a concern.
 - In context 2 above, anonymous classes are not supported.
 - In context 3 above, Vim will attempt to determine the methods supported by
   the object.

== end

_______________________________________________
vim-ruby-devel mailing list
[hidden email]
http://rubyforge.org/mailman/listinfo/vim-ruby-devel
Reply | Threaded
Open this post in threaded view
|

Re: preliminary rubycomplete documentation for review

Mark Guzman
Gavin Sinclair wrote:

>
>
> My suggested replacement for the relevant section is below.  I aimed
> for a style that's consistent with the rest of the Vim online help.
>
> It should be viewed in Vim with ':set filetype=help' to see the highlighting.
>
> BTW Mark, your prelim documentation mentioned that object specific
> completion would be done after any of {. : ::}.  What is ":" supposed
> to do?
>
> Cheers,
> Gavin
>
> P.S. Please only send the relevant text in future.  The attachment
> before was so large that Mailman asked me to approve it before it
> could be posted to the list!
>  
Gavin,
: will complete symbols. If done with no preceding text it will provide
a list of global symbols.
Sorry about the file-size, I'll snip the segment next time.

Here's a slightly updated version of the doc:

== begin

RUBY                                                    *ft-ruby-omni*

Completion of Ruby code requires that vim be built with |+ruby|.

Ruby completion will parse your buffer on demand in order to provide a list of
completions.  These completions will be drawn from modules loaded by 'require'
and modules defined in the current buffer.

The completions provided by CTRL-X CTRL-O are sensitive to the context:

          CONTEXT                          COMPLETIONS PROVIDED ~

 1. Not inside a class definition    Classes, constants and globals

 2. Inside a class definition        Methods or constants defined in the class

 3. After '.', '::' or ':'           Methods applicable to the object being
                                       dereferenced, Symbols in the case of ':'

Notes:
 - Vim will load/evaluate code in order to provide completions.  This may
   cause some code execution, which may be a concern.
 - In context 2 above, anonymous classes are not supported.
 - In context 3 above, Vim will attempt to determine the methods supported by
   the object.
 - Vim can detect and load the Rails environment for files within a rails
   project. The feature is disabled by default, to enable it add
   let g:rubycomplete_rails = 1
   to your vimrc

== end


--
sic transit gloria et adulescentia
blog | http://blog.hasno.info/blog
wiki | http://wiki.hasno.info

_______________________________________________
vim-ruby-devel mailing list
[hidden email]
http://rubyforge.org/mailman/listinfo/vim-ruby-devel
Reply | Threaded
Open this post in threaded view
|

Re: preliminary rubycomplete documentation for review

Gavin Sinclair
On 4/20/06, Mark Guzman <[hidden email]> wrote:

> Gavin,
> : will complete symbols. If done with no preceding text it will provide
> a list of global symbols.

[...]

>
>  3. After '.' or '::'                 Methods applicable to the object being
>                                        dereferenced

 4. After ':' or ':foo'                    Symbol name (beginning with 'foo')

How does that sound?  Completing symbols is completely different to
completing methods, so it's confusing to read them lumped together.

Completing symbols seems like a pointless feature.  When I want to
complete a symbol, Vim's normal text completion (CTRL-P in insert
mode) does the job just fine.  I hate to think of the processing
involved in getting all the symbol names and narrowing it :)  Not that
I've tried it, though.

Gavin

_______________________________________________
vim-ruby-devel mailing list
[hidden email]
http://rubyforge.org/mailman/listinfo/vim-ruby-devel
Reply | Threaded
Open this post in threaded view
|

Re: preliminary rubycomplete documentation for review

Doug Kearns
On Thu, Apr 20, 2006 at 06:44:25PM +1000, Gavin Sinclair wrote:

> On 4/20/06, Mark Guzman <[hidden email]> wrote:
>
> > Gavin,
> > : will complete symbols. If done with no preceding text it will provide
> > a list of global symbols.
>
> [...]
>
> >
> >  3. After '.' or '::'                 Methods applicable to the object being
> >                                        dereferenced
>
>  4. After ':' or ':foo'                    Symbol name (beginning with 'foo')
>
> How does that sound?  Completing symbols is completely different to
> completing methods, so it's confusing to read them lumped together.

Sounds good to me. I've added it to doc/ft-ruby-omni.txt
 
> Completing symbols seems like a pointless feature.  When I want to
> complete a symbol, Vim's normal text completion (CTRL-P in insert
> mode) does the job just fine.  I hate to think of the processing
> involved in getting all the symbol names and narrowing it :)  Not that
> I've tried it, though.

Am I right in assuming this will be useful for rails users, in
particular?

Regards,
Doug
_______________________________________________
vim-ruby-devel mailing list
[hidden email]
http://rubyforge.org/mailman/listinfo/vim-ruby-devel
Reply | Threaded
Open this post in threaded view
|

Re: preliminary rubycomplete documentation for review

Gavin Sinclair
On 4/20/06, Doug Kearns <[hidden email]> wrote:
> >  4. After ':' or ':foo'                    Symbol name (beginning with 'foo')
> >
> > How does that sound?  Completing symbols is completely different to
> > completing methods, so it's confusing to read them lumped together.
>
> Sounds good to me. I've added it to doc/ft-ruby-omni.txt

So this is user documentation, not to be inserted into insert.txt like
Mark distributed to us?  It's the user's responsibility to generate it
after installation?

> > Completing symbols seems like a pointless feature.  When I want to
> > complete a symbol, Vim's normal text completion (CTRL-P in insert
> > mode) does the job just fine.  I hate to think of the processing
> > involved in getting all the symbol names and narrowing it :)  Not that
> > I've tried it, though.
>
> Am I right in assuming this will be useful for rails users, in
> particular?

Rails uses a lot of symbols, to be sure, but once you've typed it once
anywhere in any buffer, symbol completion is only a CTRL-P away :)

Gavin

_______________________________________________
vim-ruby-devel mailing list
[hidden email]
http://rubyforge.org/mailman/listinfo/vim-ruby-devel
Reply | Threaded
Open this post in threaded view
|

Re: preliminary rubycomplete documentation for review

Mark Guzman
Gavin Sinclair wrote:

> On 4/20/06, Doug Kearns <[hidden email]> wrote:
>  
>>>  4. After ':' or ':foo'                    Symbol name (beginning with 'foo')
>>>
>>> How does that sound?  Completing symbols is completely different to
>>> completing methods, so it's confusing to read them lumped together.
>>>      
>> Sounds good to me. I've added it to doc/ft-ruby-omni.txt
>>    
>
> So this is user documentation, not to be inserted into insert.txt like
> Mark distributed to us?  It's the user's responsibility to generate it
> after installation?
>
>  
No clue on my part, I assumed it should follow suite with ft-c-omni et. al.
<snip>

>
> Rails uses a lot of symbols, to be sure, but once you've typed it once
> anywhere in any buffer, symbol completion is only a CTRL-P away :)
>
>  
Irb/complete provided the symbol list, we can always pull it out. Though
it is nice to have some of the rails symbols handy.
 --mark

--
sic transit gloria et adulescentia
blog | http://blog.hasno.info/blog
wiki | http://wiki.hasno.info

_______________________________________________
vim-ruby-devel mailing list
[hidden email]
http://rubyforge.org/mailman/listinfo/vim-ruby-devel
Reply | Threaded
Open this post in threaded view
|

Re: preliminary rubycomplete documentation for review

Doug Kearns
In reply to this post by Gavin Sinclair
On Thu, Apr 20, 2006 at 11:19:25PM +1000, Gavin Sinclair wrote:

> On 4/20/06, Doug Kearns <[hidden email]> wrote:
> > >  4. After ':' or ':foo'                    Symbol name (beginning with 'foo')
> > >
> > > How does that sound?  Completing symbols is completely different to
> > > completing methods, so it's confusing to read them lumped together.
> >
> > Sounds good to me. I've added it to doc/ft-ruby-omni.txt
>
> So this is user documentation, not to be inserted into insert.txt like
> Mark distributed to us?  It's the user's responsibility to generate it
> after installation?

Well it's possibly both now. I used to have the syntax documentation in
syntax/doc/ruby.txt but since we're also adding some for omni completion
I thought it might be a good idea to make them more obviously accessible
to the user. I've sent the contents of ft-ruby-omni.txt to Bram and he's
already added it to insert.txt.

If you think it's confusing there's no need to package up the doc
directory for release. It just seems like a good idea to have it in the
repository too - for when we're all long gone...bus or no bus. ;-)
 

> > > Completing symbols seems like a pointless feature.  When I want to
> > > complete a symbol, Vim's normal text completion (CTRL-P in insert
> > > mode) does the job just fine.  I hate to think of the processing
> > > involved in getting all the symbol names and narrowing it :)  Not that
> > > I've tried it, though.
> >
> > Am I right in assuming this will be useful for rails users, in
> > particular?
>
> Rails uses a lot of symbols, to be sure, but once you've typed it once
> anywhere in any buffer, symbol completion is only a CTRL-P away :)

Sure but how many times are you going to call something like url_for in
a simple controller and with the same 'options'? I assume, from what
Mark was saying, he has some way to provide the appropriate symbols.
 
Note: I've only ever looked at Rails once and this was the first method
I could find in my old rails 'sandbox'. ;-)

Regards,
Doug
_______________________________________________
vim-ruby-devel mailing list
[hidden email]
http://rubyforge.org/mailman/listinfo/vim-ruby-devel
Reply | Threaded
Open this post in threaded view
|

Re: preliminary rubycomplete documentation for review

Doug Kearns
On Fri, Apr 21, 2006 at 12:42:26AM +1000, Doug Kearns wrote:

> On Thu, Apr 20, 2006 at 11:19:25PM +1000, Gavin Sinclair wrote:
> > On 4/20/06, Doug Kearns <[hidden email]> wrote:
> > > >  4. After ':' or ':foo'                    Symbol name (beginning with 'foo')
> > > >
> > > > How does that sound?  Completing symbols is completely different to
> > > > completing methods, so it's confusing to read them lumped together.
> > >
> > > Sounds good to me. I've added it to doc/ft-ruby-omni.txt
> >
> > So this is user documentation, not to be inserted into insert.txt like
> > Mark distributed to us?  It's the user's responsibility to generate it
> > after installation?
>
> Well it's possibly both now. I used to have the syntax documentation in
> syntax/doc/ruby.txt but since we're also adding some for omni completion
> I thought it might be a good idea to make them more obviously accessible
> to the user. I've sent the contents of ft-ruby-omni.txt to Bram and he's
> already added it to insert.txt.

If it was distributed I hadn't actually considered _installing_ it
locally. I doubt it'd change enough to make that worthwhile although
Mark seems to have some plans for the omni completion so maybe it would
be?
 
<snip>

Regards,
Doug
_______________________________________________
vim-ruby-devel mailing list
[hidden email]
http://rubyforge.org/mailman/listinfo/vim-ruby-devel
Reply | Threaded
Open this post in threaded view
|

Re: preliminary rubycomplete documentation for review

Gavin Sinclair
On 4/21/06, Doug Kearns <[hidden email]> wrote:

> > >
> > > So this is user documentation, not to be inserted into insert.txt like
> > > Mark distributed to us?  It's the user's responsibility to generate it
> > > after installation?
> >
> > Well it's possibly both now. I used to have the syntax documentation in
> > syntax/doc/ruby.txt but since we're also adding some for omni completion
> > I thought it might be a good idea to make them more obviously accessible
> > to the user. I've sent the contents of ft-ruby-omni.txt to Bram and he's
> > already added it to insert.txt.
>
> If it was distributed I hadn't actually considered _installing_ it
> locally. I doubt it'd change enough to make that worthwhile although
> Mark seems to have some plans for the omni completion so maybe it would
> be?

'Fraid I don't have a quick or a good answer to that one.  There are
obvious advantages in having the docs embedded in Vim's docs.

Perhaps if the ft-ruby-omni docs included a link to the website people
would know where to look for updates and updated information.

Also, if it's embedded, people should know that compiling with +ruby
is a necessary but not sufficient condition for omni completion: it
must be enabled in the .vimrc or (better) an ftplugin file.  Another
reason to link to vim-ruby.rubyforge.org.

I must confess I hadn't realised that the Ruby *syntax* docs were
embedded.  Since they are, let's ensure the omni ones are too.

And what about a website link in the syntax docs, Doug?

Cheers,
Gavin

_______________________________________________
vim-ruby-devel mailing list
[hidden email]
http://rubyforge.org/mailman/listinfo/vim-ruby-devel
Reply | Threaded
Open this post in threaded view
|

Re: preliminary rubycomplete documentation for review

Gavin Sinclair
In reply to this post by Doug Kearns
On 4/21/06, Doug Kearns <[hidden email]> wrote:

> >
> > So this is user documentation, not to be inserted into insert.txt like
> > Mark distributed to us?  It's the user's responsibility to generate it
> > after installation?
>
> Well it's possibly both now. I used to have the syntax documentation in
> syntax/doc/ruby.txt but since we're also adding some for omni completion
> I thought it might be a good idea to make them more obviously accessible
> to the user. I've sent the contents of ft-ruby-omni.txt to Bram and he's
> already added it to insert.txt.

As per my ranting in the other email: I agree, the accessability is a
good thing, outweighing other concerns.

Is it too late to get a website link in there?

> If you think it's confusing there's no need to package up the doc
> directory for release. It just seems like a good idea to have it in the
> repository too - for when we're all long gone...bus or no bus. ;-)

Agree to that too.  The FAQ or something should explain the situation.

> > Rails uses a lot of symbols, to be sure, but once you've typed it once
> > anywhere in any buffer, symbol completion is only a CTRL-P away :)
>
> Sure but how many times are you going to call something like url_for in
> a simple controller and with the same 'options'?

Lots of times :)

Gavin

_______________________________________________
vim-ruby-devel mailing list
[hidden email]
http://rubyforge.org/mailman/listinfo/vim-ruby-devel
Reply | Threaded
Open this post in threaded view
|

Re: preliminary rubycomplete documentation for review

Gavin Sinclair
In reply to this post by Mark Guzman
On 4/20/06, Mark Guzman <[hidden email]> wrote:
> >
> > Rails uses a lot of symbols, to be sure, but once you've typed it once
> > anywhere in any buffer, symbol completion is only a CTRL-P away :)
>
> Irb/complete provided the symbol list, we can always pull it out. Though
> it is nice to have some of the rails symbols handy.

Unlike on other subjects, Mark, my rantings on this subject are not to
be taken seriously :)  No need to pull it out.

Cheers,
Gavin

_______________________________________________
vim-ruby-devel mailing list
[hidden email]
http://rubyforge.org/mailman/listinfo/vim-ruby-devel
Reply | Threaded
Open this post in threaded view
|

Re: preliminary rubycomplete documentation for review

Mark Guzman
Gavin Sinclair wrote:

> On 4/20/06, Mark Guzman <[hidden email]> wrote:
>  
>>> Rails uses a lot of symbols, to be sure, but once you've typed it once
>>> anywhere in any buffer, symbol completion is only a CTRL-P away :)
>>>      
>> Irb/complete provided the symbol list, we can always pull it out. Though
>> it is nice to have some of the rails symbols handy.
>>    
>
> Unlike on other subjects, Mark, my rantings on this subject are not to
> be taken seriously :)  No need to pull it out.
>
> Cheers,
> Gavin
>
>  
No worries man, its all good.
  --mark

--
sic transit gloria et adulescentia
blog | http://blog.hasno.info/blog
wiki | http://wiki.hasno.info

_______________________________________________
vim-ruby-devel mailing list
[hidden email]
http://rubyforge.org/mailman/listinfo/vim-ruby-devel
Reply | Threaded
Open this post in threaded view
|

Re: preliminary rubycomplete documentation for review

Doug Kearns
In reply to this post by Gavin Sinclair
On Fri, Apr 21, 2006 at 08:35:34AM +1000, Gavin Sinclair wrote:

<snip>
 
> Perhaps if the ft-ruby-omni docs included a link to the website people
> would know where to look for updates and updated information.

Well they should know to look in the runtime file header. That's why
it's there - same as any other runtime file.
 
> Also, if it's embedded, people should know that compiling with +ruby
> is a necessary but not sufficient condition for omni completion: it
> must be enabled in the .vimrc or (better) an ftplugin file.  Another
> reason to link to vim-ruby.rubyforge.org.

This is no different from all the other omni scripts - they all have the
same requirements which are documented in the Vim help.
 
> I must confess I hadn't realised that the Ruby *syntax* docs were
> embedded.  Since they are, let's ensure the omni ones are too.

Hmmm, must be because the defaults are so spectacularly good.
 
> And what about a website link in the syntax docs, Doug?

Well if we're going to go down this path perhaps we could also consider
creating a file like:

:help sql.txt
 
Regards,
Doug
_______________________________________________
vim-ruby-devel mailing list
[hidden email]
http://rubyforge.org/mailman/listinfo/vim-ruby-devel
Reply | Threaded
Open this post in threaded view
|

Re: preliminary rubycomplete documentation for review

Gavin Sinclair
On 4/21/06, Doug Kearns <[hidden email]> wrote:
> On Fri, Apr 21, 2006 at 08:35:34AM +1000, Gavin Sinclair wrote:
>
> > Perhaps if the ft-ruby-omni docs included a link to the website people
> > would know where to look for updates and updated information.
>
> Well they should know to look in the runtime file header. That's why
> it's there - same as any other runtime file.

Oh yeah...

Except some people might not know that there *is* a runtime file
header, especially as they're reading docs that just came with Vim.

> > Also, if it's embedded, people should know that compiling with +ruby
> > is a necessary but not sufficient condition for omni completion: it
> > must be enabled in the .vimrc or (better) an ftplugin file.  Another
> > reason to link to vim-ruby.rubyforge.org.
>
> This is no different from all the other omni scripts - they all have the
> same requirements which are documented in the Vim help.

True.

> > I must confess I hadn't realised that the Ruby *syntax* docs were
> > embedded.  Since they are, let's ensure the omni ones are too.
>
> Hmmm, must be because the defaults are so spectacularly good.

I've never considered looking into my options :)

> > And what about a website link in the syntax docs, Doug?
>
> Well if we're going to go down this path perhaps we could also consider
> creating a file like:
>
> :help sql.txt

Huh??

Gavin

_______________________________________________
vim-ruby-devel mailing list
[hidden email]
http://rubyforge.org/mailman/listinfo/vim-ruby-devel
Reply | Threaded
Open this post in threaded view
|

Re: preliminary rubycomplete documentation for review

Doug Kearns
On Fri, Apr 21, 2006 at 05:51:28PM +1000, Gavin Sinclair wrote:
> On 4/21/06, Doug Kearns <[hidden email]> wrote:

<snip>

> > Well they should know to look in the runtime file header. That's why
> > it's there - same as any other runtime file.
>
> Oh yeah...
>
> Except some people might not know that there *is* a runtime file
> header, especially as they're reading docs that just came with Vim.

I thought the Vim docs mentioned that you should always check the
header?
 
<snip>

> > > And what about a website link in the syntax docs, Doug?
> >
> > Well if we're going to go down this path perhaps we could also consider
> > creating a file like:
> >
> > :help sql.txt
>
> Huh??

Type it in Vim 7. ;-)

Regards,
Doug
_______________________________________________
vim-ruby-devel mailing list
[hidden email]
http://rubyforge.org/mailman/listinfo/vim-ruby-devel
Reply | Threaded
Open this post in threaded view
|

Re: preliminary rubycomplete documentation for review

Gavin Sinclair
On 4/21/06, Doug Kearns <[hidden email]> wrote:
> >
> > Except some people might not know that there *is* a runtime file
> > header, especially as they're reading docs that just came with Vim.
>
> I thought the Vim docs mentioned that you should always check the
> header?

News to me... I'm such an old-timer now I don't know what the correct
assumptions are :)


> > > Well if we're going to go down this path perhaps we could also consider
> > > creating a file like:
> > >
> > > :help sql.txt
> >
> > Huh??
>
> Type it in Vim 7. ;-)

<whinge>Oh, but I don't <em>have</em> Vim 7!...</whinge>

Gavin

_______________________________________________
vim-ruby-devel mailing list
[hidden email]
http://rubyforge.org/mailman/listinfo/vim-ruby-devel