johnzeng / vim-codequery

Search + Browse + Understand your code more efficiently.

> Choose what you want to know! 😼

" query directly
:CodeQuery Definition get_user_id

vim-codequery

This Vim plugin is built on top of the great tool CodeQuery created by ruben2020, and aims at providing three primary functions to help you to:

1. Search source code gracefully within Vim.
   • You can find: definition, call, caller, callee, symbol, class, parent, child and more for a string.
   • Convenient menus are created for you.
   • Well-formated results are shown in a custom Quickfix window with usable key bindings.
   • Support asynchronous search (Vim version >= 8.0)
2. Manage your database easily.
   • Load, make and move your database file by custom Vim commands.
   • Support asynchronous build (Vim version >= 8.0 or by Dispatch plugin)
   • Note: CodeQuery's SQLite database is built on top of ctags and cscope.
3. Know your code more instantly.
   • (TBD)

Supported languages

• Python 😎
• Javascript
• Ruby
• Go
• Java
• C, C++

Demo

Choose a query from menu ➙ Get results

... ➙ Switch to different query ➙ Get results ... ➙ Filter them ➙ Get Results ➙ Undo ➙ Redo

more demo and screenshots

These videos are quite old.   
Now vim-codequery works better than what you see by using Vim8's async feature.

Schedule

This project is released.

Main TODO:

• Use Vim8's new features to enhance usability.
• Do lazy-loading.
• Enhance usability.
• Test it.
• Add explain command in v1.0.0
• Doc it.

Current Version: v0.9.1

Welcome to try it! 👌

Installation

1. Make sure these commands are in your system

/bin/sh echo mkdir mv cut find awk stat git(optional)

2. Install CodeQuery

• Linux => Install binaries or build it.
• Mac => brew install codequery 🍺 (make sure codequery version >= v0.17.0)

3. Install additional ctags/cscope tools for your languages

Language	Tools	How to install
Python	PyCscope	sudo pip install pycscope
Javascript	Starscope	sudo gem install starscope
Ruby	Starscope	sudo gem install starscope
Go	Starscope	sudo gem install starscope

Java, C and C++ users do not need to install additional ctags/cscope tools.
Starscope has been packaged for Arch Linux

4. Install Vim plugins

• Use your favorite plugins manager: pathogen, Vundle, Plug, NeoBundle, Dein, ...
• Take Plug as an example:

" Required
Plug 'Shougo/unite.vim'
Plug 'devjoe/vim-codequery'
  
" Optional
" if your vim version < 8.0
Plug 'tpope/vim-dispatch'
" if you don't have an :Ack (or :Ag) liked command
Plug 'mileszs/ack.vim'

• In case you prefer to use Vim8's native package manager to manage plugins manually. Here comes an installation guide for that:
  1. Go to ~/.vim
  2. Run mkdir -p pack/vim-codequery/start/ and then go to start directory
  3. Run git clone https://github.com/devjoe/vim-codequery to get latest vim-codequery code
  4. It's done. 😎 Now vim-codequery will be loaded when your Vim starts. You can install unite in the same way
  5. Learn more about Vim8's package system by typing :help package | only
      

Usage

1. Setup

• Go to the (git) root directory of your project. Open vim and type:

" Index Python files
:CodeQueryMakeDB python
  
" Or index Python + Javascript files
:CodeQueryMakeDB python javascript 

• That's all. python.db, javascript.db ... will be created in the root directory.
• It's recommended that you should use :CodeQueryMoveDBToGitDir python to hide the DB file to .git/codequery/ directory. If you do so, next time you can call :CodeQueryMakeDB directly in any opened Python buffer to rebuild the DB file.

2. Search

• Find symbol under your cursor

:CodeQuery

• Find word (by subcommands) under your cursor

:CodeQuery [SubCommand]  
  
" Supported SubCommands are: `Symbol, Text, Call, Caller, Callee, Class, Parent, Child, Member, FunctionList, FileImporter`.  

• Find arbitrary word

:CodeQuery [SubCommand] [word]  

• Find again with the same word

:CodeQueryAgain [SubCommand]  

• Use fuzzy Option

:CodeQuery [SubCommand] [word] -f  
  
" [word] can be: get_* or *user_info or find_*_by_id

• Use append Option (results will be added to the current Quickfix)

:CodeQuery [SubCommand] [word] -a  

• Filter Search Results

:CodeQueryFilter [string]  
  
" [string] can be a regex

3. Use Quickfix

• Move your cursor inside Quickfix window to use these key bindings

Key	Action	Note
s	:CodeQueryAgain Symbol
x	:CodeQueryAgain Text	use :Ack! by default. #1
c	:CodeQueryAgain Call
r	:CodeQueryAgain Caller
e	:CodeQueryAgain Callee
d	:CodeQueryAgain Definition
C	:CodeQueryAgain Class
M	:CodeQueryAgain Member
P	:CodeQueryAgain Parent
D	:CodeQueryAgain Child
q	:cclose
\	:CodeQueryFilter
p	<CR><C-W>p	Preview
u	:colder | CodeQueryShowQF	Older Quickfix Result
<C-R>	:cnewer | CodeQueryShowQF	Newer Quickfix Result

#1 You can override g:codequery_find_text_cmd to change it.

• Show Quickfix with above key bindings

:CodeQueryShowQF  
  
" This command can also be used to **patch** standard Quickfix.

Tips

Query

nnoremap <space><CR> :CodeQuery Symbol<CR>
  
" Chain commands to find possible tests (for python)
nnoremap <space>t :CodeQuery Caller<CR>:CodeQueryFilter test_<CR>

Filter

" Filter reversely by adding '!'
:CodeQueryFilter ! [word]

Build

" Trigger db building (in current filetype) when your query fails
let g:codequery_trigger_build_db_when_db_not_found = 1

Find Text

" Custom your `CodeQuery Text` commands
let g:codequery_find_text_cmd = 'Ack!'
  
let g:codequery_find_text_from_current_file_dir = 0
" 0 => search from project dir (git root directory -> then the directory containing xxx.db file)
" 1 => search from the directory containing current file
  
" If you use ':CodeQuery Symbol' in a txt file, of course, it will fail due to wrong filetype.
" With the following option set to 1, ':CodeQuery Text' will be automatically sent when your query fails.
let g:codequery_auto_switch_to_find_text_for_wrong_filetype = 0

Load Ctags File

" Set tags option
set tags=./javascript_tags;/
set tags+=./python_tags;/
set tags+=./ruby_tags;/
set tags+=./go_tags;/
set tags+=./java_tags;/
set tags+=./c_tags;/

Clean Ctags, Cscope ... Files by Languages

let g:codequery_enable_auto_clean_languages = ['python']
  
" It accpepts a list of your languages written in lowercase

Custom Database Building

" Make sure to generate a python.db or xxxx.db file as a result
let g:codequery_build_python_db_cmd = '...'
let g:codequery_build_javascript_db_cmd = '...'
let g:codequery_build_ruby_db_cmd = '...'
let g:codequery_build_go_db_cmd = '...'  
let g:codequery_build_java_db_cmd = '...'  
let g:codequery_build_c_db_cmd = '...'  

Others

" You can disable key binding within quickfix
let g:codequery_disable_qf_key_bindings = 1
  
" if your function usually begins with a capital letter ..., you can change your magic menu to a not-so-magic one
let g:codequery_enable_not_so_magic_menu = 1

FAQ

Why writing this plugin?

Because I need it.

I already shared the story of making this plugin in local Python user groups Taipei.py and Tainan.py.
Slides are available here: Taipei.py / Tainan.py (Language: Traditional Chinese)

Why not using Ctags or Cscope directly?

Read what @ruben2020 the author of CodeQuery said: Link

In addittion, vim-codequery provides:

1. Good interface.
2. Separated Database Management Mechanism.
   (You can open as many projects as you wish in a single Vim session without worrying about messing up Ctags or Cscope files or getting wrong result!)

for Vim users.

More Questions

Ask here or create an issue.

How to Contribute

Use It

And give me feedback or bug report.

Fork It

And give me PR. It would be better if you open an issue and discuss with me before sending PR.

Star It

If you like it. 👍

Credits

Thank all for working on these great projects!

• CodeQuery
• Starscope
• PyCscope
• dispatch.vim
• ack.vim
• vim-addon-qf-layout