Skip to content

configuration

Jump to bottom
chimay edited this page Oct 4, 2023 · 80 revisions

Vim options

To facilitate the navigation between buffers, the following vim options can be useful :

set hidden
set bufhidden=hide

If you don't want to activate these options, remember to write your files before using a wheel navigation tool.

To enable nice completion in prompting wheel functions :

set wildchar=<TAB>
set wildmode=longest,full

See vim help on 'wildmode' to adapt it to your taste.

Dictionary

Customization is done using the g:wheel_config dictionary. You must first initialize it :

let g:wheel_config                 = {}
let g:wheel_config.project         = {}
let g:wheel_config.storage         = {}
let g:wheel_config.storage.wheel   = {}
let g:wheel_config.storage.session = {}
let g:wheel_config.maxim           = {}
let g:wheel_config.completion      = {}
let g:wheel_config.frecency        = {}
let g:wheel_config.display         = {}
let g:wheel_config.display.sign    = {}

Mappings

Determine how many default mappings are available :

let g:wheel_config.mappings = 10

See the mapping levels for more information.

Default : 0

Prefix

Prefix for mappings of level 0, 1, 2 :

let g:wheel_config.prefix = '<my-wonderful-prefix>'

See the mapping prefix for more information.

Default : <M-w>

Locate database

If you want to use a custom database when using locate :

let g:wheel_config.locate_db = '~/my_locate.db'

Default : empty

Grep ex command

Whether to use internal :vimgrep or external :grep to grep files :

let g:wheel_config.grep = 'vimgrep'
" or
let g:wheel_config.grep = 'grep'

Default : internal vimgrep, in case external grep is not available.

Project markers

File(s) or directories(s) marking a project root. Can take a string or list value. :

    let g:wheel_config.project.markers = '.git'
    let g:wheel_config.project.markers = ['.git', '.my-project-root']

If a list is given, the project directory is found as soon as one marker of the list is found in it

Default : '.git'

Auto chdir project

Try to change directory to project root if > 0 :

    let g:wheel_config.project.auto_chdir = 1

To find the right folder, the plugin looks at files or dirs listed in g:wheel_config.project_markers.

Default : 0

Wheel folder

The plugin can save your wheel catégories & groups in wheel files.

You can have as many wheel files as you want, they will be stored in a wheel folder.

Folder where your wheels will be saved :

    let g:wheel_config.storage.wheel.folder = '~/.local/share/wheel'

It is highly recommended to define this folder and regularly save the wheel, either manually or automatically, using the autowrite config.

Default

  • vim : ~/.vim/wheel
  • nvim : ~/.local/share/nvim/wheel

Wheel name

Name for the default wheel file :

  let g:wheel_config.storage.wheel.name = 'wheel.vim'

This file will be located in g:wheel_config.storage.wheel.folder

Default : wheel.vim

Autoread wheel

Auto read wheel file on startup if non null :

let g:wheel_config.storage.wheel.autoread = 1

To enable it, you need to add an autocommand on vim enter :

autocmd VimEnter * call wheel#void#init()

Default : 0

Autowrite wheel

Auto write wheel file on exit if non null :

let g:wheel_config.storage.wheel.autowrite = 1

To enable it, you need to add an autocommand on vim leave :

autocmd VimLeave * call wheel#void#exit()

Default : 0

Session folder

Wheel can save your tabs & windows layout in session files.

You can have as many session files as you want, they will be stored in a session folder.

Folder where your sessions will be saved :

    let g:wheel_config.storage.session.folder = '~/.local/share/wheel/session'

Default

  • vim : ~/.vim/wheel/session
  • nvim : ~/.local/share/nvim/wheel/session

Session name

Name for the default session file :

let g:wheel_config.storage.session.name = 'session.vim'

This file will be located in g:wheel_config.storage.session.folder

Default : 'session.vim'

Autoread session

Auto read current or default session file on startup if non null :

let g:wheel_config.storage.session.autoread = 1

To enable it, you need to add an autocommand on vim enter :

autocmd VimEnter * call wheel#void#init()

Default : 0

Autowrite session

Auto write current or default session file on exit if non null :

let g:wheel_config.storage.session.autowrite = 1

To enable it, you need to add an autocommand on vim leave :

    autocmd VimLeave * call wheel#void#exit()

Default : 0

Backups

Number of backups for wheel & session files :

let g:wheel_config.storage.backups = 3

Assuming your wheel file is wheel.vim, the backups will be named wheel.vim.1, wheel.vim.2, wheel.vim.3, and so on.

It is recommended to use backups, in case things get messed up accidentally.

Default : 3

Max number of elements in history

Maximum number of elements in the wheel history :

let g:wheel_config.maxim.history = 400

Default : 500

Max number of elements in input history

Maximum number of elements in the input history :

let g:wheel_config.maxim.input = 200

Default : 500

Max number of elements in mru

Maximum number of elements in mru :

let g:wheel_config.maxim.mru = 300

Default : 500

Max number of elements in yank ring

Maximum number of elements in the yank ring :

Default : 500

Maximum number of elements in the yank ring for unnamed register :

let g:wheel_config.maxim.unnamed_yanks = 700

Default : 500

Maximum number of elements in the yank ring for other registers :

let g:wheel_config.maxim.other_yanks = 100

Default : 50

Maximum number of lines of a yank

Maximum number of lines of a yank added in the yank ring :

let g:wheel_config.maxim.yank_lines = 50

Default : 30

Maximum size of a yank

Maximum size of a yank added in the yank ring, in bytes :

let g:wheel_config.maxim.yank_size = 3000

Default : 3000

Max layers in dedicated buffers

Maximum size of layer ring in dedicated buffers :

let g:wheel_config.maxim.layers = 5

Default : 5

Max number of tabs

Maximum number of tabs in tab layouts :

let g:wheel_config.maxim.tabs = 12

Default : 15

Max number or horizontal splits

Maximum number of horizontal splits in layouts :

let g:wheel_config.maxim.horizontal = 3

Default : 3

Max number or vertical splits

Maximum number of vertical splits in layouts :

let g:wheel_config.maxim.vertical = 4

Default : 4

Completion

To enable a kind of fuzzy-vowels completion :

let g:wheel_config.completion.vocalize = 1

Default : 0

To enable a kind of fuzzy-word completion :

 let g:wheel_config.completion.wordize = 1

Overrrides g:wheel_config.completion.vocalize.

Default : 0

To enable full fuzzy completion :

 let g:wheel_config.completion.fuzzy = 1

Overrrides vocalize and wordize settings.

Default : 0

Frecency

The frecency (frequent & recent) algorithm is very simple :

  • when you jump to a location, its score is increased by a reward
  • the scores of all the other locations of the frecency list are decreased by a penalty
  • when a score dives below 0, the location is removed from the list

You can customize the reward :

let g:wheel_config.frecency.reward = 150

and the penalty :

let g:wheel_config.frecency.penalty = 1

The higher the reward/penaly ratio, the bigger your frecency list will be.

Default

  • reward : 50
  • penalty : 1

Statusline in dedicated buffers

By default, dedicated buffers status is displayed in the statusline. If you'd rather have it printed in the echo area, just set the option to zero :

let g:wheel_config.display.statusline = 0

Default : 1

The highlight group is WheelStatusLine. You can customize it :

highlight WheelStatusLine guifg=#5b3c11 guibg=#0 gui=bold,reverse

Messages

You can ask wheel to print one-line messages when possible :

let g:wheel_config.display.dedibuf_msg = 'one-line'

or to accept multi-line messages :

let g:wheel_config.display.dedibuf_msg = 'multi-line'

Default : one-line

if you set this option to multi-line, I recommend you set 'cmdheight' option to a minimum of 3 :

    set cmdheight=3

Filter prompt in dedicated buffers

You can customize the filter prompt in dedicated buffers :

For regular dedicated buffer, without BufWriteCmd autocommand :

let g:wheel_config.display.prompt = 'wheel $ '

Default : '☯ '

For writable dedicated buffer, with BufWriteCmd autocommand :

let g:wheel_config.display.prompt_writable = 'wheel # '

Default : '☈ '

Selection marker

You can customize the selection marker in dedicated buffers :

let g:wheel_config.display.selection = '-> '

Default : '☰ '

Signs

By default, signs are displayed at :

  • wheel locations
  • cursor line after a native jump

You can disable it if you want :

let g:wheel_config.display.sign.switch = 0

The sign settings for wheel location can be modified :

let g:wheel_config.display.sign.settings = { 'text' : '@' }

Default : { 'text' : '☯' }

Sign settings for native navigation :

let g:wheel_config.display.sign.native_settings = { 'text' : '*' }

Default : { 'text' : '✻' }

See also sign.txt and :sign in vim help.

Tabline

Text

If you want wheel to manage your tabline, use this function :

set tabline=%!wheel#status#tabline()

The format is :

  • tabnumber:filename
  • tabnumber:filename[+] if at least a file is modified
  • tabnumber:filename(win_num) if there is more than one window

Gui tabs of gvim

If you are using gui tabs in gvim, you can ask wheel to manage the labels :

set guitablabel=%{wheel#status#guitablabel()}

Gui tabs of nvim-qt

If you find a way to customize gui tabs labels for nvim-qt, feel free to describe it in a github issue.

If you prefer using text tabs even in nvim-qt, simply put :

GuiTabline 0

in your ginit.vim.

Example

Here is an example of a complete configuration :

if ! exists("g:wheel_loaded")
  " ---- DONT FORGET TO INITIALIZE DICTS BEFORE USING THEM
  let g:wheel_config                 = {}
  let g:wheel_config.project         = {}
  let g:wheel_config.storage         = {}
  let g:wheel_config.storage.wheel   = {}
  let g:wheel_config.storage.session = {}
  let g:wheel_config.maxim           = {}
  let g:wheel_config.completion      = {}
  let g:wheel_config.frecency        = {}
  let g:wheel_config.display         = {}
  let g:wheel_config.display.sign    = {}

  " ---- The bigger it is, the more mappings available
  let g:wheel_config.mappings = 10
  " ---- Prefix for mappings
  let g:wheel_config.prefix = '<M-w>'
  " ---- Locate database ; default one if left empty
  let g:wheel_config.locate_db = '~/index/locate/home.db'
  " ---- Grep command : :grep or :vimpgrep
  let g:wheel_config.grep = 'grep'

  " Marker of project root
  "let g:wheel_config.project.markers = '.git'
  "let g:wheel_config.project.markers = '.project-root'
  " List of markers
  " The project dir is found as soon as one marker is found in it
  let g:wheel_config.project.markers = ['.hg' , '.git', '.project-root']
  " Auto cd to project root if > 0
  let g:wheel_config.project.auto_chdir = 1

  " The folder where toruses and circles will be stored and read
  let g:wheel_config.storage.wheel.folder = '~/.local/share/wheel'
  " Name of the default wheel file
  let g:wheel_config.storage.wheel.name = 'wheel.vim'
  " Auto read wheel file on startup if > 0
  let g:wheel_config.storage.wheel.autoread = 1
  " Auto write wheel file on exit if > 0
  let g:wheel_config.storage.wheel.autowrite = 1
  " The folder where sessions will be stored and read
  let g:wheel_config.storage.session.folder = '~/.local/share/wheel/session'
  " Name of the default session file
  let g:wheel_config.storage.session.name = 'session.vim'
  " Auto read default session file on startup if > 0
  let g:wheel_config.storage.session.autoread = 1
  " Auto write default session file on exit if > 0
  let g:wheel_config.storage.session.autowrite = 1
  " Number of backups for wheel & session files
  let g:wheel_config.storage.backups = 5

  " ---- Maximum number of elements in history
  let g:wheel_config.maxim.history = 400
  " ---- Maximum number of elements in input history
  let g:wheel_config.maxim.input = 200

  " ---- Maximum number of elements in mru
  let g:wheel_config.maxim.mru = 300

  " ---- Maximum number of elements in yank ring
  let g:wheel_config.maxim.default_yanks = 700
  let g:wheel_config.maxim.other_yanks = 100
  " ---- Maximum lines of yank to add in yank ring
  let g:wheel_config.maxim.yank_lines = 30
  " ---- Maximum size of yank to add in yank ring
  let g:wheel_config.maxim.yank_size = 3000

  " ---- Maximum size of layer ring
  let g:wheel_config.maxim.layers = 10

  " ---- Maximum number of tabs in layouts
  let g:wheel_config.maxim.tabs = 12
  " ---- Maximum number of horizontal splits
  let g:wheel_config.maxim.horizontal = 3
  " ---- Maximum number of vertical splits
  let g:wheel_config.maxim.vertical = 4

  " ---- Completion
  let g:wheel_config.completion.vocalize = 1
  let g:wheel_config.completion.wordize = 1
  let g:wheel_config.completion.fuzzy = 0
  let g:wheel_config.completion.scores = 1

  " ---- Frecency
  let g:wheel_config.frecency.reward = 120
  let g:wheel_config.frecency.penalty = 1

  " ---- Mandala & leaf status in statusline ?
  let g:wheel_config.display.statusline = 1
  " ---- Wheel dedibuf message : one-line or multi-line
  let g:wheel_config.display.dedibuf_msg = 'one-line'
  " ---- Filter prompt in dedicated buffers
  "let g:wheel_config.display.prompt = 'wheel $ '
  "let g:wheel_config.display.prompt_writable = 'wheel # '
  " ---- Selection marker in dedicated buffers
  "let g:wheel_config.display.selection = '-> '
  " ---- Signs
  let g:wheel_config.display.sign.switch = 1
  " ---- Signs at wheel locations
  "let g:wheel_config.display.sign.settings = { 'text' : '@' }
  " ---- Signs after using Wheel interface to native navigation (buffer, marker, jump, change, tag, ...)
  "let g:wheel_config.display.sign.native_settings = { 'text' : '*' }

  let g:wheel_config.debug = 0
endif

augroup wheel
	" Clear the group
	autocmd!
	" On vim enter, for autoreading
	autocmd VimEnter * call wheel#void#init()
	" On vim leave, for autowriting
	autocmd VimLeave * call wheel#void#exit()
	" Update location line & col before leaving a window
	autocmd BufLeave * call wheel#vortex#update()
	" Executed before jumping to a location
	autocmd User WheelBeforeJump call wheel#vortex#update()
	" Executed before organizing the wheel
	autocmd User WheelBeforeOrganize call wheel#vortex#update()
	" Executed before writing the wheel
	autocmd User WheelBeforeWrite call wheel#vortex#update()
	" Executed after jumping to a location
	"autocmd User WheelAfterJump norm zMzx
	" For current wheel location to auto follow window changes
	autocmd WinEnter * call wheel#projection#follow()
	" For current wheel location to follow on editing, buffer loading
	"autocmd BufRead * call wheel#projection#follow()
	" For current wheel location to follow on entering buffer
	"autocmd BufEnter * call wheel#projection#follow()
	" Executed after using Wheel interface to a native jump (buffer, marker, jump, change, tag, ...)
	"autocmd User WheelAfterNative call wheel#projection#follow()
	" Add current non-wheel file to MRU files
	autocmd BufRead * call wheel#attic#record()
	" To record your yanks in the yank ring
	autocmd TextYankPost * call wheel#codex#add()
augroup END

Home

step-by-step

workflow

straightforward

completion

prompting-functions

dedicated-buffers

dedicated-buffers-applications

command

configuration

autocommands

bindings

examples

files

vim-script

release-notes

Clone this wiki locally