*ku.txt* An interface for anything
Version 0.2.4.1
Script ID: 2337
Copyright (C) 2008-2009 kana <http://whileimautomaton.net/>
License: MIT license {{{
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
}}}
CONTENTS *ku-contents*
Introduction |ku-introduction|
Interface |ku-interface|
Commands |ku-commands|
Functions |ku-functions|
Key Mapings |ku-key-mappings|
Pattern |ku-pattern|
Input History |ku-input-history|
Default Action Table |ku-default-action-table|
Default Key Table |ku-default-key-table|
Default Sources |ku-default-sources|
Sources |ku-sources|
Customizing |ku-customizing|
Terms |ku-terms|
Bugs |ku-bugs|
Changelog |ku-changelog|
==============================================================================
INTRODUCTION *ku-introduction*
*ku* is a Vim plugin to provide new interface for Vim. With ku,
- You can choose many items from various sources such as buffers, files and
others. This selection is very efficient, because ku supports it by
automatic and elegant completion, so that you don't have to type much.
- Then you can take an action on the selected item. Various actions are
available for each kind of items.
To start a selection, execute |:Ku| or |ku#start()|. |the-ku-window| will be
opened at the top of the current tabpage. The window is to select items and
to do an action on a selected item. In the window,
- |ins-completion-menu| is automatically appeared to show available items.
As you input a character, the menu is updated to show more proper items for
the given input.
If you want to know how ku interpret what you input,
see |ku-pattern|, |ku-auto-component-completion| and |ku-prefix-expansion|.
- If you find what you want in the menu, select it with <C-n> or <C-p>. If
the first item in the menu is what you want, you don't have to select it.
- Then you can take an action on the selected item with <Enter> or <Tab>.
- With <Enter>, ku executes the default action for the item.
- With <Tab>, ku shows a list of available actions for the item. Each
action is labeled with a key to execute it. If you type one of the keys,
the corresponding action will be executed.
<Enter> and <Tab> are just the default key bindings. You can customize
them, of course. See |ku-key-mappings| and |ku#default_key_mappings()|.
If you want to customize key bindings in a list of actions by <Tab>, see
|ku#custom_key()|, |ku-default-key-table| and |ku-key-table|.
- If you don't want to take any action and stop to select, type <C-c> in any
mode. The window is closed and the current tabpage is restored to the
previous state.
In ku, a kind of items is called "source". Some sources are available by
default. See |ku-default-sources| for the details. You can write your own
sources if you want to select and to take action on something which is not
provided by the default sources. To add sources, put the corresponding
scripts into "autoload/ku/" directories in 'runtimepath'. As scripts are put,
ku recognizes them automatically, so that you don't have to reboot Vim. See
alsso |ku-sources| for the details.
Screenshots:
http://www.flickr.com/photos/whileimautomaton/tags/vim-ku/
Demonstration movie:
http://www.screencast.com/t/P6nJkJ0DE
Requirements:
- Vim 7.1.299 or later
Sources and related scripts:
http://www.vim.org/scripts/script_search_results.php?keywords=ku
Latest version:
http://github.com/kana/config/commits/vim-ku
Document in HTML format:
http://kana.github.com/config/vim/ku.html
==============================================================================
INTERFACE *ku-interface*
------------------------------------------------------------------------------
COMMANDS *ku-commands*
:Ku {source} *:Ku*
Start a selection from the specified {source}.
It is an error to use this command while ku is active.
See also |ku#start()|.
For example: Define several key mappings to start
a selection from various sources.
>
<
:KuDoAction {action} *:KuDoAction*
Do the {action} for the current item.
This function does work only while ku is active.
See also |ku#do_action()|.
The main purpose of this command is to define a key
mapping to execute a specified action without
choosing, like |<Plug>(ku-do-the-default-action)|.
See |filetype-ku| for an example of usage.
:KuReload *:KuReload*
Reload the whole system of ku. This is useful to
reflect the changes made to any scripts after ku is
loaded.
------------------------------------------------------------------------------
FUNCTIONS *ku-functions*
ku#available_source_p({source}) *ku#available_source_p()*
Return true if {source} is a valid one.
Otherwise, return false.
ku#available_sources() *ku#available_sources()*
Return a list of strings. This list represents the
names of available sources.
ku#custom_action({source}, {action}, {function}) *ku#custom_action()*
ku#custom_action({source}, {action}, {source2}, {action2})
Define a new {action} for items from {source}.
In the former case, {function} is the name of
a function which will be called whenever {action} is
executed.
*ku-disable-action*
{function} can be "nop", if so, the corresponding
action will be disabled.
In the latter case, the function corresponding to the
{action2} for items from {source2} will be called as
{action}. {action2} will be searched from the default
action table for {source2} or the default action table
for all sources if {source2} is "common".
{source} is the name of a source or "common". In the
former case, the given {action} is only available for
the given {source}. In the latter case, the given
{action} is available for all sources.
See also |ku-action-table| and
|ku-default-action-table|.
ku#custom_key({source}, {key}, {action}) *ku#custom_key()*
Define a {key} to do the {action} for items from
{source}. This definition is used by
|<Plug>(ku-choose-action)|.
{source} is the name of a source or "common". In the
former case, the given {key} is available for the
given {source}. In the latter case, the given {key}
is available for all sources.
See also |ku-key-table| and |ku-default-key-table|.
ku#custom_prefix({source}, {prefix}, {text}) *ku#custom_prefix()*
Define a {prefix} to be expanded to {text} for
{source}. If {text} is empty string, delete
a {prefix} from the prefix table for {source}.
{source} is the name of a source or "common". In the
former case, the given {prefix} is available for the
given {source}. In the latter case, the given
{prefix} is available for all sources.
See also |ku-prefix-table| and |ku-prefix-expansion|.
ku#custom_priority({source}, {priority}) *ku#custom_priority()*
Set the priority of {source} to {priority}.
{priority} is an integer and it must be in the range
[100, 999], i.e, 100 <= {priority} and {priority} <=
999. The default priority of each source is 500.
See also |ku-sources-list|.
ku#default_key_mappings({override-p}) *ku#default_key_mappings()*
Define the following key mappings which are local to
the current buffer in Normal mode and Insert mode.
Existent key mappings will be override if {override-p}
is true.
{lhs} {rhs} ~
------------------------------------------------~
<C-c> <Plug>(ku-cancel)
<Return> <Plug>(ku-do-the-default-action)
<S-Return> <Plug>(ku-do-the-default-action)
<C-Return> <Plug>(ku-do-the-default-action)
<C-m> <Plug>(ku-do-the-default-action)
<Tab> <Plug>(ku-choose-an-action)
<C-i> <Plug>(ku-choose-an-action)
<Esc>i <Plug>(ku-do-persistent-action)
<C-j> <Plug>(ku-next-source)
<C-k> <Plug>(ku-previous-source)
<C-l> <Plug>(ku-choose-source)
<Esc>l <Plug>(ku-history-source)
<Esc>j <Plug>(ku-newer-history)
<Esc>k <Plug>(ku-older-history)
<Esc>J <Plug>(ku-newer-history-and-source)
<Esc>K <Plug>(ku-older-history-and-source)
ku#do_action({name}) *ku#do_action()*
Function version of |:KuDoAction|.
ku#get_the_current_input_pattern() *ku#get_the_current_input_pattern()*
Return the current input pattern in |the-ku-buffer|.
Returned value doesn't contain a prompt leading the
pattern.
If ku is not active, return 0.
ku#input_history() *ku#input_history()*
Return a list of input patterns which you inputted.
Returned value must not be modified. The first item
is corresponding to the newest input pattern. Each
item is a dictionary which content is as follows:
"pattern" String
What user inputed before.
"time" Number
The time when user inputted the pattern.
See |localtime()| for the detail of value.
"source" String
The name of the source for which the pattern
was inputted.
ku#make_path({component}, ...) *ku#make_path()*
ku#make_path([{component}, ...])
Return a path which consists of given {component}s.
For example:
>
<
ku#path_separator() *ku#path_separator()*
Return the path separator for the current environment.
It returns "/" for most environments such as *nix or
"\" for some environments such as Microsoft Windows.
ku#reload() *ku#reload()*
Function version of |:KuReload|.
ku#restart() *ku#restart()*
Call |ku#start()| with the last inputted pattern and
the last active source.
This is useful if you cancel a selection once,
but you want to continue the selection later.
ku#set_the_current_input_pattern({s}) *ku#set_the_current_input_pattern()*
Set the current input pattern in |the-ku-buffer| to
{s}, then return the old one.
If ku is not active, just return 0.
ku#start({source}, [{initial-pattern}]) *ku#start()*
Function version of |:Ku|.
If {initial-pattern} is given, it will be inserted
before your input.
ku#switch_source({source}) *ku#switch_source()*
Change the current source to {source}. This function
works only while ku is active. Otherwise, do nothing.
------------------------------------------------------------------------------
KEY MAPPINGS *ku-key-mappings*
In |the-ku-buffer|, the following key mappings are defined.
See also |ku#default_key_mappings()| for the default key mappings for them.
<Plug>(ku-cancel) *<Plug>(ku-cancel)*
Cancel the current selection,
then close |the-ku-window|.
<Plug>(ku-choose-an-action) *<Plug>(ku-choose-an-action)*
Like |<Plug>(ku-do-the-default-action)|, but you can
choose an action from all available actions for the
currently selected item.
What this function does is as follows:
(1) show a message about what actions are available,
(2) take an input of a single key stroke,
(3) then do the action corresponding to the key.
See also:
- |g:ku_choosing_actions_sorting_style|
- |ku-default-key-table|
- |ku-default-key-table|
<Plug>(ku-do-persistent-action) *<Plug>(ku-do-persistent-action)*
Like |<Plug>(ku-choose-an-action)|,
but execute an action without quitting ku.
<Plug>(ku-do-the-default-action) *<Plug>(ku-do-the-default-action)*
Do the default action on the currently selected item,
then close |the-ku-window|.
<Plug>(ku-history-source) *<Plug>(ku-history-source)*
If you recall a pattern from |ku-input-history|,
change the current source to the one for which the
currently recalled pattern was inputted. Otherwise,
nothing will happen.
For example, if:
- you use |<Plug>(ku-older-history)| several times,
- the source for the recalled pattern is "file",
- and the current source is "buffer",
then the current source will be changed to "file".
<Plug>(ku-next-source) *<Plug>(ku-next-source)*
<Plug>(ku-previous-source) *<Plug>(ku-previous-source)*
Change the current source to the next one or the
previous one in |ku-sources-list|.
*ku-sources-list*
Ku has a list of available sources. The list is
sorted by their priorities, then sorted by their
names. Priorities can be configured by
|ku#custom_priority()|.
For example, if
- the list == ["buffer", "file", "metarw-git"], and
- the current source is "buffer",
the next one is "file" and
the previous one is "metarw-git".
<Plug>(ku-older-history) *<Plug>(ku-older-history)*
<Plug>(ku-newer-history) *<Plug>(ku-newer-history)*
Replace the current input pattern with older/newer
one in |ku-input-history|.
<Plug>(ku-older-history-and-source) *<Plug>(ku-older-history-and-source)*
<Plug>(ku-newer-history-and-source) *<Plug>(ku-newer-history-and-source)*
Like |<Plug>(ku-older-history)| or
|<Plug>(ku-newer-history)|, but change the current
source as same as the one for which the pattern was
inputted.
If the new source is not currently available, the
current source will not be changed.
------------------------------------------------------------------------------
PATTERN *ku-pattern*
Inserted characters in |the-ku-buffer| are treated as 3 "patterns".
- The 1st one is "asis" pattern. Ku tries to literally match user input to
each item.
- The 2nd one is "word" pattern. User input is split by spaces,
and each space is treated as a wild card, so it is matched to any
0 or more characters. Ku tries to match this pattern for each item.
- The last one is "skip" pattern. Ku treats user input have a wild card
between each character and another character. Ku tries to match this
pattern for each item.
Ku uses the matched positions of the above patterns for each item. In the
completion list, items are sorted by matched positions. Matched position of
"asis" pattern have higher priority than "word" pattern, and "word" pattern
have higher priority than "skip" pattern.
Ku also tries to match in case-sensitive way and case-insensitive way. The
matched positions of case-sensitive way have higher priority than the ones of
case-insensitive way.
See also |g:ku_common_junk_pattern|.
*ku-pattern-prefix-assumption*
Ku assumes that the "prefix" of a pattern is always matched to the head of
each item, so that skips the "prefix" for pattern matching described in the
above.
Here the "prefix" of a pattern is defined as follows:
1. Split the pattern with any character in |g:ku_component_separators|.
2. Exclude the tail one from the pattern. This is the "prefix".
For example, the "prefix" of a pattern "/foo/bar/baz" is "/foo/bar/"
(if g:ku_component_separators contains "/").
AUTO COMPONENT COMPLETION *ku-auto-component-completion*
*ku-auto-directory-completion*
Whenever a special character (*1) is typed,
the names of appropriate components (*2) will be automatically inserted.
For example, if the 1st item in the completion menu is 'usr/share/man/man1',
the current input pattern will be replaced (i.e., completed) as follows:
User Input Replacement ~
------------- --------------
u/ usr/
usr// usr/share/
usr/share// usr/share/man/
sh/ usr/share/ (*3)
m/ usr/share/man/ (*3)
This feature is derived from bluewind, command-based application launcher for
Microsoft Windows <http://cspace.s2.xrea.com/software/bluewind/>.
See also:
- |g:ku_acc_style|
- |g:ku_component_separators|
(*1) In the above example, '/' is a special character to activate this
completion. This character is configurable with |g:ku_component_separators|.
(*2) In the above example, components are directories. More precisely,
components are just strings separated by a special character. So in the above
example, components are directory-like stuffs and they may not be directories.
(*3) In these cases, ku completes more than 1 directories. Because user seems
to want to complete several directories rather than just 1 directory. This
behavior is not in bluewind, but it's useful.
PREFIX EXPANSION *ku-prefix-expansion*
If the head of an input pattern is matched to one of the prefixes in
|ku-prefix-table|, the matched part will be expanded. For example, if you
configure ku with the following setting:
>
<
Input pattern will be treated as follows
(in the following examples, $HOME == '/home/kana'):
Input pattern Treated as ~
------------- ----------
~ /home/kana
~/working/meta /home/kana/working/meta
.vim/autoload/ku.vim /home/kana/.vim/autoload/ku.vim
junk-file~ junk-file~ (not expanded, because "~" is not
appeared at the head of user input)
This expansion is not recursive.
See also |ku-prefix-table| and |ku#custom_prefix()|.
------------------------------------------------------------------------------
INPUT HISTORY *ku-input-history*
Input patterns are automatically saved and they will be automatically loaded
the next Vim session. You can recall an old input pattern in the ku window.
- Input history is saved as "info/ku/history" under the directory which is
specified by |g:ku_personal_runtime|. For example, the default path to the
file is "$HOME/.vim/info/ku/history" on *nix environments.
- Maximum size of input history is configured by |g:ku_history_size|.
Whenever the number of inputted patterns exceeds the limit, the oldest
patterns will be removed.
- In the ku window, |<Plug>(ku-older-history)| and |<Plug>(ku-newer-history)|
can be used to recall an old input pattern.
- Input pattern will be added to the input history
if some action is executed on it.
------------------------------------------------------------------------------
DEFAULT ACTION TABLE *ku-default-action-table*
The following actions are available as the default ones:
cancel *ku-action-cancel*
Cancel to take an action.
This is a pseudo action - it cannot be overridden.
cd *ku-action-cd*
|:cd| to the selected item. If the item is the name
of a directory, change to that one. If the item is
the name of a file, change to the directory which
contains the file.
default *ku-action-default*
Do the default action for the selected item. This
action is just a placeholder and it is overridden by
each source. So what this action does is varied for
each source. See the document of each source for the
details of its "default" action.
ex *ku-action-ex*
Shift to Command-line mode, insert the selected item
as a file or a directory, then move the cursor to the
beginning of the command-line. This action is useful
to execute an Ex command on the selected item.
lcd *ku-action-lcd*
Like "cd", but do |:lcd| on the selected item.
nop *ku-action-nop*
Do nothing. Only the name of this action matters.
This is a pseudo action - it cannot be overridden.
Use this action to remove an entry from a key table.
selection *ku-action-selection*
Return to the previous selection.
This action does nothing on the selected item.
This is a pseudo action - it cannot be overridden.
Bottom *ku-action-Bottom*
Left *ku-action-Left*
Right *ku-action-Right*
Top *ku-action-Top*
above *ku-action-above*
below *ku-action-below*
left *ku-action-left*
right *ku-action-right*
Open a new window in the direction specified by the
name of each action, then do |ku-action-default|.
NB: "default" action will be searched from the default
action table of the current source.
For example, "left" opens a window at the left side of
the current window, then do |ku-action-default| in the
new window.
Actions of which names start with upper case are
similar to the ones of which names start with lower
case. But they open a window at the most outside of
Vim screen. See also |:topleft|.
tab-left *ku-action-tab-left*
tab-right *ku-action-tab-right*
tab-Left *ku-action-tab-Left*
tab-Right *ku-action-tab-Right*
Like "left", "right", "Left" or "Right",
but open a new tab page instead of a window,
then do |ku-action-default|.
------------------------------------------------------------------------------
DEFAULT KEY TABLE *ku-default-key-table*
The following keys are used by |<Plug>(ku-choose-an-action)|.
Key Action ~
-------- --------
/ cd |ku-action-cd|
: ex |ku-action-ex|
; ex |ku-action-ex|
<C-c> cancel |ku-action-cancel|
<C-h> left |ku-action-left|
<C-j> below |ku-action-below|
<C-k> above |ku-action-above|
<C-l> right |ku-action-right|
<C-r> selection |ku-action-selection|
<C-t> tab-Right |ku-action-tab-Right|
<Esc> cancel |ku-action-cancel|
<Return> default |ku-action-default|
? lcd |ku-action-lcd|
H Left |ku-action-Left|
J Bottom |ku-action-Bottom|
K Top |ku-action-Top|
L Right |ku-action-Right|
h left |ku-action-left|
j below |ku-action-below|
k above |ku-action-above|
l right |ku-action-right|
t tab-Right |ku-action-tab-Right|
------------------------------------------------------------------------------
DEFAULT SOURCES *ku-default-sources*
The following sources are included with packages of ku:
- buffer (|ku-buffer.txt|)
- file (|ku-file.txt|)
- history (|ku-history.txt|)
- source (|ku-source.txt|)
==============================================================================
SOURCES *ku-sources*
Sources are like kinds of items. For example, "buffer" source gathers all
buffers as items to be completed. You can choose and take an action on
a buffer with this source. The same can be said for other sources.
*ku-source-action-tables*
Sources have their own action table. These action tables have higher priority
than common action tables, but these have lower priority than custom action
table for each source. See also |ku-action-table|.
*ku-source-key-tables*
Sources have their own key table. These key tables have higher priority than
common key tables, but these have lower priority than custom key table for
each source. See also |ku-key-table|.
*ku-source-name*
Sources must be named as one of the following formats:
- {source}
- {source}/{ext}
Where {source} and {ext} should consist of lower cases only.
For example:
- "buffer", "history" and "metarw/git" are valid.
- "BadOne", "hy-phen" and "too/o/many" are not valid.
*ku-source-scripts*
Sources are written as autoload scripts called as "source scripts" which are
placed in "autoload/ku/" directory in 'runtimepath'. Source scripts must be
named as "{source}.vim", where {source} is the name of a source. For sources
named as "{source}/{ext}", corresponding source scripts are named as
"{source}.vim", not "{source}/{ext}.vim".
*ku-source-api*
Sources must provide the following functions. In the following descriptions,
{source}
means the name of a source. For sources named as
"{source}/{ext}", "/{ext}" is not included.
{ext}
means the tail of the name of a source namaed as
"{source}/{ext}". For sources without {ext} in their names,
{ext} is an empty string.
ku#{source}#acc_valid_p({ext}, {item}, {sep}) *ku#{source}#acc_valid_p()*
Return true if {item} can be used for ACC,
|ku-auto-component-completion|, or return false
otherwise.
{sep} is the separator inputted by user.
This function is optional; if it is not defined,
all {item}s can not be used for ACC.
ku#{source}#action_table({ext}) *ku#{source}#action_table()*
Return the default action table for {souce}.
See also |ku-action-table|.
This function is requried.
ku#{source}#available_sources() *ku#{source}#available_sources()*
Return a list of strings. Each string represents the
name of a source which this source script provides.
Normally, a source script provides just one source, so
that all you have to do is to define one like the
following:
>
<
This function is requried.
ku#{source}#gather_items({ext}, {pattern}) *ku#{source}#gather_items()*
Return a list of items which are matched to the given
{pattern}. Each item is a dictionary.
See |complete-items| for the details.
Sources may add additional entries for each item.
Keys of such entries must be prefixed with
"ku_{source}_", where {source} is the name of
a source. Also sources may add the following items:
*ku__sort_priority*
ku__sort_priority (integer)
This value is used to sort items,
and it is prior to user input.
The default value is 0
if this item is omitted.
Also, ku adds additional entries for each item.
Keys of such entries are prefixed with "ku__".
The following keys are officially provided:
*ku__completed_p*
ku__completed_p (boolean)
Normally true.
If the item is not completed one,
it is set to false.
*ku__source*
ku__source (string)
The name of the source
to which an item belongs.
There are the following rules on return values:
- During a |ku-session|, ku assumes that
a return value is determined only by {pattern}.
This means: >
< - During a ku session, return values are cached by ku,
so that sources don't have to do caching unless they
want to do caching over ku sessions.
- ku may modify any item in return lists. If so,
ku adds/modifies entries named "ku__..." in items.
But ku doesn't modify return lists themselves.
- See also |ku#{source}#special_char_p()|.
This function is requried.
ku#{source}#key_table({ext}) *ku#{source}#key_table()*
Return the default key table for {souce}.
See also |ku-key-table|.
This function is requried.
*ku#{source}#on_before_action()*
ku#{source}#on_before_action({ext}, {item})
Event handler - this function is called:
- Before executing an action.
{item} is a dictionary which represents the item to be
primarily passed to the action.
Return value is dictionary which represents an item.
This item will be passed to the action instead of the
item given to the event handler. Note that if you
want to pass a modified item based on the given item,
you must not modify the given item in-place. Because
items may be cached by {source}.
This function is optional; if this function is not
defined, nothing will happen for the above event.
*ku#{source}#on_source_enter()*
ku#{source}#on_source_enter({ext})
Event handler - this function is called:
- Before switching the current source from another
source to {source}.
- After opening |the-ku-window|, and the current
source is {source}.
Return value is ignored.
This function is optional; if this function is not
defined, nothing will happen for the above events.
*ku#{source}#on_source_leave()*
ku#{source}#on_source_leave({ext})
Event handler - this function is called:
- Before switching the current source from {source} to
another source.
- Before closing |the-ku-window| and the current
source is {source}.
Return value is ignored.
This function is optional; if this function is not
defined, nothing will happen for the above events.
ku#{source}#special_char_p({ext}, {character}) *ku#{source}#special_char_p()*
Return true if a given {character} is a special one,
otherwise return false.
Here "a special character" is defined as follows:
|ku#{source}#gather_items()| returns a different list
before whenever user types that character.
For example, return lists from |ku-file| are different
whenever user types "/" or "\".
So that ku#file#special_char_p() returns true for '/'
and '\', while returns false for other values.
This function is optional; if it is not defined,
it returns true if {character} is in
|g:ku_component_separators|
or it returns false otherwise.
==============================================================================
CUSTOMIZING *ku-customizing*
FileType ku *filetype-ku*
This event is published whenever the ku buffer is created then being
initialized. Use this event to do your initialization, for example,
customize key mappings for the ku buffer.
Note that if there is no |:autocmd| nor filetype plugin for this
event, ku will call ku#default_key_mappings(!0) to define the default
key mappings. Otherwise, this initialization will not be done. See
|ku#default_key_mappings()| for the details of key mappings.
Example: Define a key mapping to execute "left" action with a single
key stroke.
>
<
g:ku_acc_style *g:ku_acc_style*
A string which specifies the behavior
about |ku-auto-component-completion| (ACC).
This value is a comma-separated list of words. The valid words and
their meanings are as follows:
rejection
Whenever ACC is failed,
the last inserted component separator is deleted.
The default value is "".
g:ku_buffer_name *g:ku_buffer_name*
A string which represents the name of the ku buffer. This value
should be unique one which cannot be a name of a usual file to avoid
unexpected behavior.
Default value is '*ku*' or '[ku]'. The latter is used for Microsoft
Windows. Because '*' cannot be used for buffer name on Microsoft
Windows.
g:ku_choosing_actions_sorting_style *g:ku_choosing_actions_sorting_style*
A string which specifies how to sort actions
when |<Plug>(ku-choose-an-action)| shows available actions.
This variable can be one of the following values:
'by-action'
Sort by the name of each action.
'by-key'
Sort by the name of each key to choose an action.
Default value is 'by-action'.
g:ku_common_junk_pattern *g:ku_common_junk_pattern*
g:ku_{source}_junk_pattern *g:ku_{source}_junk_pattern*
Variables to hold regular expressions to determine "junk" items. Junk
items are listed at the bottom of the completion menu.
g:ku_common_junk_pattern is used for items from any sources, while
g:ku_{source}_junk_pattern is used for items from a specific {source}.
g:ku_component_separators *g:ku_component_separators*
A string which represents special characters to activate
|ku-auto-component-completion|.
The default value is '/\:', so if you type '/', '\' or ':',
|ku-auto-component-completion| will be activated.
g:ku_history_added_p *g:ku_history_added_p*
A string which represents the name of a function. This function is
used to determine whether an input pattern can be added to
|ku-input-history| or not.
This function must take 2 arguments: the 1st argument is an input
pattern, and the 2nd argument is the source for which the input
pattern was inputted. If it returns true, the input pattern will be
added to the input history. Otherwise, the input pattern will not be
added.
The default value will not add the following patterns:
- Any patterns which were inputted for source |ku-history|, or
- Any patterns which were inputted for source |ku-source|, or
- Empty patterns.
g:ku_history_reloading_style *g:ku_history_reloading_style*
A string which specifies timings to reload and to save
|ku-input-history|. This variable can be one of the following values:
"each"
- Whenever input history is required.
- The same timings as "once" and "idle".
"idle"
- Whenever Vim becomes idle or ku is activated after idle.
See also |CursorHold|.
- The same timings as "once".
"once"
- Loading: After first activating ku for each Vim process.
- Saving: Before exiting Vim.
Default value is "idle".
g:ku_history_size *g:ku_history_size*
A number which is the maximum size of input history.
Default value is 1000.
g:ku_personal_runtime *g:ku_personal_runtime*
A string which is the path to the directory to store personal settings
and information. Whenever ku saves information such as
|ku-input-history|, this directory is used.
Default value is the same as the first directory in the default value
of 'runtimepath'. For example:
- "$HOME/.vim/info/ku/history" on *nix environments,
- "$HOME/vimfiles/info/ku/history" on Microsoft Windows,
- etc.
See 'runtimepath' for the details of which directory is used.
==============================================================================
TERMS *ku-terms*
action *ku-action*
An action is a function which is called by
|<Plug>(ku-do-the-default-action)|,
|<Plug>(ku-choose-an-action)|,
|:KuDoAction| and other commands.
Every action is registered in |ku-action-table| by
|ku#custom_action()|. The above commands look into
the tables for available actions.
An action consists of the following elements:
- The "name" of the action.
It should consist of only alphabets and hyphens.
- The name of the "function"
which is called whenever the action is executed.
- This function must take 1 argument which is
a dictionary as an item.
- This function must return 0 if it succeeds, or
a string which represents an error message if it
fails.
- The list of the names of "sources"
to which the action can be applied.
action table *ku-action-table*
Action table is a dictionary, where each key is the
name of an action, and each value is the name of
a function that implements the action.
There are 4 action tables for each source:
(1) custom action table for a source
(2) default action table for a source
(3) custom action table for all sources
(4) default action table for all sources
If there is the same name action in two or more
tables, the one in the most above table is used.
For example, if action "default" is found in (2) and
(4), the one in (2) is used.
Custom action tables ((1) and (3)) can be configured
with |ku#custom_action()|.
See also |ku-default-action-table| for (4),
and |ku-buffer-action-table| for an example of (2).
key table *ku-key-table*
Key table is a dictionary, where each key is a string
that represents a single key stroke to choose an
action by |<Plug>(ku-choose-an-action)|, and each
value is the name of an action to be executed by the
key.
There are 4 key tables for each source:
(1) custom key table for a source
(2) default key table for a source
(3) custom key table for all sources
(4) default key table for all sources
If there is the same key in two or more table,
the entry in the most above table is used.
For example, if key "K" is found in (2) and (4),
the entry in (2) is used.
Custom key tables ((1) and (3)) can be configured with
|ku#custom_key()|.
See also |ku-default-key-table| for (4),
and |ku-buffer-key-table| for an example of (2).
ku session *ku-session*
Ku session is a period of time while |the-ku-window|
is opened and it is visible.
ku window *the-ku-window* *the-ku-buffer*
The window which is opened by |:Ku| or |ku#start()|.
This window will be automatically closed when:
- An action is taken for an item.
- Selection is canceled.
- Another window or another tab page becomes active.
prefix table *ku-prefix-table*
Prefix table is a dictionary, where each key is
a string that represents a prefix, and each value is
a string that represents the expanded text for the
corresponding prefix.
There are 2 prefix tables for each source:
(1) custom prefix table for a source
(2) custom prefix table for all sources
If there is the same prefix in the both tables,
the prefix in (1) is used.
Custom prefix tables can be configured with
|ku#custom_prefix()|.
There is no default entry in any prefix tables.
See also |ku-prefix-expansion|.
==============================================================================
BUGS *ku-bugs*
*ku-assumptions*
- Ku assumes that any configuration is not changed during a |ku-session|. For
example, |ku#custom_action()| or other customization must not be done during
a ku session. If you do, ku will not properly work.
- Ku assumes that available sources are not changed during a |ku-session|.
- Ku assumes interactive use,
so that it may not work with |recording| and/or |key-mapping|.
- Ku assumes that 'shellslash' is never changed after any script of ku is
loaded.
- Many bugs must be around the world.
*ku-planned-features*
- Inline completion in a buffer other than the ku buffer.
- Pluggable architecture to sort items.
- Pluggable architecture to filter items.
- A key mapping to delete a component in the ku buffer.
- Mark multiple items then take an action on the marked items.
- Source "all" to gather items for all sources. No need to choose a source.
- More sources: "tag", "mark", "action", etc.
- More actions.
==============================================================================
CHANGELOG *ku-changelog*
0.2.5 2009-09-01T19:40:18+09:00 *ku-changelog-0.2.5*
Bugfixes:
- |ku#default_key_mappings()|: Define <S-Return> and <C-Return> to
execute |<Plug>(ku-do-the-default-action)|.
0.2.4.1 2009-05-29T09:23:03+09:00 *ku-changelog-0.2.4.1*
Bug fixes:
- |ku-file|: Fix a serious bug which was mixed in ku source file
version 0.1.3. See |ku-file-changelog-0.1.4| for the details.
0.2.4 2009-05-25T00:53:07+09:00 *ku-changelog-0.2.4*
Feature enhancements:
- |ku-file|: Support to deal with files in archives. See also
|ku-file-changelog-0.1.3| for the details.
Misc. improvements:
- |filetype-ku|: Modify the default initialization on |the-ku-buffer|.
Old versions don't override existing key mappings.
New versions now override existing key mappings.
It is convenient for starters to use ku without any configuration.
For example, many people customize <Tab> to complete something in
Insert mode. In such cases, old versions don't override <Tab> to
|<Plug>(ku-choose-an-action)|, but it's very inconvenient to use ku.
All key mappings defined by |ku#default_key_mappings()| are local to
a buffer, so that it's not necessary to avoid overriding.
Thanks to rphillips and other persons for reporting this problem.
Bug fixes:
- |ku#restart()|: Fix a bug that is caused by a change in the previous
version. As ku#restart() is called, the prompt character will be
inserted many times.
0.2.3 2009-05-16T03:05:10+09:00 *ku-changelog-0.2.3*
Feature enhancements:
- Add |g:ku_personal_runtime| to customize where information such as
|ku-input-history| to be saved.
- Add |:KuReload| and |ku#reload()| to reload the whole system of ku.
Misc. improvements:
- Improve an error message.
- Add tests, not perfect yet.
- |ku-input-history|: Change the directory to save input history. Use
the first directory in the default value of 'runtimepath', instead
of the current value of 'runtimepath'. Because some users customize
'runtimepath', and the first directory in such values may not refer
a directory for personal settings.
Bug fixes:
- Fix a bug that ku list the same sources many times if there are 2 or
more source scripts which filenames are the same in 'runtimepath'.
- Fix bugs that ku may be confuse if typeahead buffer is not empty at
the beginning of a |ku-session|.
- |ku#set_the_current_input_pattern()|:
- Fix a wrong description in the document.
- Fix a bug on the treatment of a given string. If a given string
starts with the same character as the prompt, that character is
treated as the prompt and not a part of the given string, so it's
not easy to set such strings.
- Fix a bug on the automatic completion. The cursor position may be
altered in several cases.
See also:
- |ku-source-changelog-0.1.2|
0.2.2 2009-05-13T21:40:20+09:00 *ku-changelog-0.2.2*
Bug fixes:
- Fix an assumption that the separator for pathes is "/". This
assumption causes unexpected behavior on some environments such as
Microsoft Windows.
- Fix a wrong condition to use 'shellslash'.
Feature enhancements:
- Add API functions to deal with pathes. See also:
- |ku#make_path()|
- |ku#path_separator()|
See also:
- |ku-file-changelog-0.1.2|
0.2.1 2009-05-01T01:40:08+09:00 *ku-changelog-0.2.1*
Bug fixes:
- |<Plug>(ku-choose-action)|: Fix a bug that an error message is
displayed unexpectedly, whenever a key which is not associated with
any action is pressed.
- Fix a bug that the current source name in |the-ku-buffer| is not
highlighted correctly in some cases.
- Document: Fix a wrong description on the default value of
|g:ku_history_reloading_style|. It is "idle", not "once".
- |ku__source|: Fix a bug that it doesn't exist for items which are
not completed by ku.
- |ku-action-left| and other actions: Fix a bug that they don't close
a window or a tab page created by them even if |ku-action-default|
is failed.
Incompatible changes:
- Change the behavior not to take any action if an input pattern is
empty and there is no item, because there is nothing to do in such
case.
- Change the specification on |ku-action|. Now the function
corresponding to an action must return 0 if it succeeds, or a string
which represents an error message if it fails. Old versions don't
touch on return values.
Misc.:
- Refactor the core.
0.2.0 2009-04-28T01:45:50+09:00 *ku-changelog-0.2.0*
- Add |ku__source|.
- Fix a few assumptions on path separator.
- Improve the performance to complete items.
Now it is 10 times faster than old versions.
- Modify the sorting order of items.
If an item contains any character of |g:ku_component_separators|,
it is prior to other items which don't contain that characters.
For example, if there are two items "foo/bar" and "foo-bar",
new versions put "foo/bar" before "foo-bar",
while old versions put "foo-bar" before "foo/bar".
This change is to avoid selecting unexpected item with
|ku-auto-component-completion|.
- |ku-auto-component-completion|:
- Improve the conditions to activate.
Now it is not unexpectedly activated for some cases.
- Improve how many components to be completed.
- |g:ku_acc_style|: New.
Incompatible changes:
- Change many points about |ku-sources| and |ku-action|.
- Sources for 0.1.x are not compatible with 0.2.x.
- |ku#{source}#gather_items()|:
- Change the naming rules about additional entries for each item:
Old versions use "_{source}_..." and "_ku_...".
New versions use "ku_{source}_..." and "ku__..." instead.
- Add several rules on return values.
- |ku#{source}#gather_items()|: New API to implement.
- |ku#{source}#acc_valid_p()|:
Change the default value if it is not defined.
Old versions always return true.
New versions always return false.
- |ku-special-sources|: Delete this concept. Now all source scripts
may provide more than one sources.
- |ku#{source}#available_sources()|: New function to implement.
- |ku-source-api|: Most of functions must take an additional
argument about source name.
- |ku#{source}#event_handler()|: Delete. This function is now split
into the following functions:
- |ku#{source}#on_before_action()|
- |ku#{source}#on_source_enter()|
- |ku#{source}#on_source_leave()|
- |ku-pattern|:
- Change the definition of "word" pattern.
Old versions use spaces and slashes as wildcards.
New versions use only spaces as wildcards.
- Add an assumption - see |ku-pattern-prefix-assumption|.
0.1.9 2008-12-31T06:52:02+09:00 *ku-changelog-0.1.9*
- Add |g:ku_history_reloading_style|.
- Change the default timings to reload and to save |ku-input-history|.
See also "idle" on |g:ku_history_reloading_style|.
Old versions use "each", but "idle" is used instead from now on.
0.1.8 2008-12-24T17:33:31+09:00 *ku-changelog-0.1.8*
- Add |g:ku_choosing_actions_sorting_style|.
- Change the sorting style of |<Plug>(ku-choose-an-action)|.
See also |g:ku_choosing_actions_sorting_style|.
- Fix some bugs - see |ku-buffer-changelog| and |ku-file-changelog|.
0.1.7 2008-12-11T17:08:52+09:00 *ku-changelog-0.1.7*
- Include new source |ku-source|.
- Change the default value of |g:ku_history_added_p|.
Now it also omits patterns for source |ku-source|.
- Add |<Plug>(ku-choose-source)| and the default key mapping for it
(see |ku#default_key_mappings()|).
- Add |ku#get_the_current_input_pattern()|.
- Add |ku#set_the_current_input_pattern()|.
- Fix typos in this document.
- Revise the internal stuffs.
- Change |ku#restart()| to use the last inputted pattern and the last
active source. Old versions don't use ones if a selection is
canceled by |<Plug>(ku-cancel)|.
- Add |ku-action-selection|
and the entry for it in |ku-default-key-table|.
- Show an additional message while choosing an action for
|<Plug>(ku-do-persistent-action)|. In older versions, it cannot be
distinct from a message either |<Plug>(ku-do-persistent-action)| or
|<Plug>(choose-an-action)| is used.
Incompatible changes:
- Remove |ku-action-persistent|;
use |<Plug>(ku-do-persistent-action)| instead.
- Change |ku-action-cancel| - now it cannot be overridden,
though it should not be overridden from the beginning.
- Don't add the current input pattern into |ku-input-history|
if the action to be taken is |ku-action-cancel|.
Old versions do add, but it seems to be unexpected behabior.
0.1.6 2008-12-08T16:41:47+09:00 *ku-changelog-0.1.6*
- Add |ku#switch_source()|.
- Add |ku-action-persistent|, |<Plug>(ku-do-persistent-action)| and
the default key mapping for it (see |ku#default_key_mappings()|).
- Include new source |ku-history|.
- Add |ku#available_source_p()|.
- Change the default value of |g:ku_history_added_p|. Now it also
omits patterns for source |ku-history|.
Incompatible changes:
- Change the behavior of |:Ku| and |ku#start()| if ku is already
active. Old ones change the current source to the specified source.
New ones don't nothing. Use |ku#switch_source()| to change the
current source.
- Change the specification of |g:ku_history_added_p|. It took
a single argument, but now, it takes 2 arguments.
0.1.5 2008-12-08T01:31:24+09:00 *ku-changelog-0.1.5*
- Show the information about |ku-input-history| in |the-ku-buffer|.
- |ku#custom_action()|: Accept "common" for {source2} to specify an
action from the default action table for all sources. For example:
>
<
- Modify |ku-action-right| and other actions to refer "default" action
from the default action table of the current source. Because they
may fall into infinite loop if user-defined "default" action refers
"default" action.
- Add |g:ku_history_size|.
- Add |<Plug>(ku-older-history-and-source)| and
|<Plug>(ku-newer-history-and-source)|.
- Add |<Plug>(ku-history-source)|.
Incompatible changes:
- Change the format of value returned by |ku#input_history()|.
Now it is a list of dictionaries, not a list of strings.
0.1.4 2008-09-29T02:31:12+09:00 *ku-changelog-0.1.4*
- Add |ku#{source}#acc_valid_p()| to filter items for
|ku-auto-component-completion|.
- Add |g:ku_history_added_p|.
- Fix an error when input history becomes larger than its maximum
size.
- Add a way to disable a specific action. See |ku-disable-action|.
- Set 'filetype' of |the-ku-buffer| to "ku".
- Add syntax highlighting for |the-ku-buffer| and messages by
|<Plug>(ku-choose-an-action)|.
- Refactor on minor stuffs.
Incompatible changes:
- Don't publish "User plugin-ku-buffer-initialized".
Use "FileType ku" and/or filetype plugin instead.
0.1.3 2008-09-28T03:30:42+09:00 *ku-changelog-0.1.3*
- Incompatible change:
- For |ku-special-sources|, |ku-source-api| takes the name of the
current source as the 1st argument.
- |ku-SourceEnter| and |ku-SourceLeave| don't take extra argument.
- |ku#custom_action()|: Add new way to specify {function}.
- |ku#start()|: Add {initial-pattern}.
- Show some information on the selected item while choosing action.
- Add |ku-input-history|.
- Add |ku#restart()|.
- Add source-specific priority on sorting items. See
|_ku_sort_priority| for the detail.
0.1.2 2008-08-11T01:56:15+09:00 *ku-changelog-0.1.2*
- Fix a bug in |ku-prefix-expansion| - it didn't expand proper prefix
if there are 2 or more prefixes which have the same head part. For
example, if there are prefixes "ab", "abc", "abcd" and so forth, it
is not possible to predict which prefix will be expanded for user
input "abcd/efgh". It should expand "abcd", but it may use "abc" or
"ab" instead.
- Add |ku-assumptions|.
- Change the name of the ku buffer for Microsoft Windows to avoid
unexpected behavior (see |g:ku_buffer_name| for the detail).
- Add |g:ku_buffer_name|.
- Improve |ku-auto-directory-completion|. Now the feature is called
as |ku-auto-component-completion|.
- Fix a bug in |ku-auto-directory-completion|. It may raise an error
if user input contains a special character.
- Add |ku-prefix-expansion|.
- Fix |:KuDoAction| to check whether ku is active or not.
- Improve the performance of |ku#available_sources()|.
- Add priorities for |ku-sources-list|.
0.1.1 2008-08-10T12:17:09+09:00 *ku-changelog-0.1.1*
- Add |ku-special-sources|.
- Remove the feature to provide |metarw-schemes| as |ku-sources|.
This feature is implemented as a special source and it is included
in |metarw| 0.0.1 or later.
- Fix requirements - ku uses |fnameescape()| which is added since Vim
7.1.299. (thanks to id:thinca)
0.1.0 2008-07-18T15:23:02+09:00 *ku-changelog-0.1.0*
- Redesign.
0.0.0 2008-01-25T19:34:13+09:00 *ku-changelog-0.0.0*
- Derived from buffuzzy and zapit.
- Still under development.
==============================================================================
vim:tw=78:ts=8:ft=help:norl:fen:fdl=0:fdm=marker: