Argonaut is a Vim plugin that gives Vim scripts and plugin developers a simple, yet powerful interface to create and parse custom command-line arguments for Vim commands. It provides:
- A clean interface for building and parsing custom command arguments.
- Support for in-line shell command execution, vim command execution, and environment variable retrieval.
- Rich tab-completion support that auto-completes your custom arguments, file paths, environment variable names, etc.
Want to supercharge your Vim commands? Check it:
Here is an example of Argonaut at work.
Install Argonaut with your preferred plugin manager:
" Vundle:
Plugin 'cwshugg/argonaut.vim'
" vim-plug
Plug 'cwshugg/argonaut.vim'
" minpac
call minpac#add('cwshugg/argonaut.vim')Or, clone it manually:
$ git clone https://github.com/cwshugg/argonaut.vim ~/.vim/bundle/argonaut.vimOnce you've installed Argonaut, you can open up the help page within Vim:
:h argonaut
:h argonaut-quickstartThis documents the entire function interface and the various objects that are provided and used by Argonaut.
Here's a quick look at how the plugin works. Start by setting up one or more argument objects:
" Help argument: to display the help menu
let s:arg_help = argonaut#arg#new()
call argonaut#arg#add_argid(s:arg_help, argonaut#argid#new('-', 'h'))
call argonaut#arg#add_argid(s:arg_help, argonaut#argid#new('--', 'help'))
" Username argument: for the user to input their username (required!)
let s:arg_username = argonaut#arg#new()
call argonaut#arg#add_argid(s:arg_username, argonaut#argid#new('-', 'u'))
call argonaut#arg#add_argid(s:arg_username, argonaut#argid#new('--', 'name'))
call argonaut#arg#add_argid(s:arg_username, argonaut#argid#new('--', 'username'))
call argonaut#arg#set_presence_count_min(s:arg_username, 1)
call argonaut#arg#set_value_required(s:arg_username, 1)
call argonaut#arg#set_value_hint(s:arg_username, 'USERNAME')
" Password argument: for the user to input their password (required!)
let s:arg_password = argonaut#arg#new()
call argonaut#arg#add_argid(s:arg_password, argonaut#argid#new('-', 'p'))
call argonaut#arg#add_argid(s:arg_password, argonaut#argid#new('--', 'password'))
call argonaut#arg#set_presence_count_min(s:arg_password, 1)
call argonaut#arg#set_value_required(s:arg_password, 1)
call argonaut#arg#set_value_hint(s:arg_password, 'USERNAME')
" Command argument: for the user to specify commands to run once authenticated.
" We'll configure this to allow the user to specify up to 10 commands.
let s:arg_command = argonaut#arg#new()
call argonaut#arg#add_argid(s:arg_command, argonaut#argid#new(' ', 'c'))
call argonaut#arg#add_argid(s:arg_command, argonaut#argid#new(' ', 'command'))
call argonaut#arg#set_presence_count_max(s:arg_command, 10)
call argonaut#arg#set_value_required(s:arg_command, 1)
call argonaut#arg#set_value_hint(s:arg_command, 'COMMAND_STRING')Next, set up an argument set to contain all of your arguments:
let s:argset = argonaut#argset#new()
call argonaut#argset#add_arg(s:argset, s:arg_help)
call argonaut#argset#add_arg(s:argset, s:arg_username)
call argonaut#argset#add_arg(s:argset, s:arg_password)
call argonaut#argset#add_arg(s:argset, s:arg_command)Set up your command to execute a function. Have that function create an
argparser object and execute it. Make sure to set up a completion function to
take advantage of Argonaut's command completion!
" Tab-completion function for `your_command`
function! your_command_completion(arg, line, pos) abort
return argonaut#completion#complete(a:arg, a:line, a:pos, s:argset)
endfunction
" Main command function for `your_command`
function! your_command(input) abort
let l:parser = argonaut#argparser#new(s:argset)
try
call argonaut#argparser#parse(l:parser, a:input)
" did the user specify your `--help` command? If so, we can show the
" help menu and return
if argonaut#argparser#has_arg(l:parser, '-h')
call argonaut#argparser#show_help(l:parser)
return
endif
" ... your command logic ...
catch
" ... your error handling logic ...
" (you may decide to check for your help argument here in the same way
" as above; depending on the parsing error that is encountered, the
" argparser may have been able to discover `-h`/`--help` before throwing
" the exception)
echo string(v:exception)
endtry
endfunction
" Command declaration for `your_command`. Make sure to use `<q-args>` so the
" Argonaut receives the command input as one concatenated string.
command!
\ -nargs=*
\ -complete=customlist,your_command_completion
\ YourCommand
\ call your_command(<q-args>)