doc/vital/OptionParser.txt

*vital/OptionParser.txt*	Option parser library for Vim.

Maintainer: rhysd <lin90162@yahoo.co.jp>

==============================================================================
CONTENTS				*Vital.OptionParser-contents*

INTRODUCTION			|Vital.OptionParser-introduction|
USAGE				|Vital.OptionParser-usage|
INTERFACE			|Vital.OptionParser-interface|
  FUNCTIONS			|Vital.OptionParser-functions|
OBJECTS				|Vital.OptionParser-objects|
  PARSER OBJECT			|Vital.OptionParser-Parser|
SPECIAL OPTIONS			|Vital.OptionParser-special-options|
BUILT-IN COMPLETERS		|Vital.OptionParser-built-in-completer|
REAL WORLD EXAMPLES		|Vital.OptionParser-real-world-examples|


==============================================================================
INTRODUCTION				*Vital.OptionParser-introduction*

*Vital.OptionParser* is an option parser library for Vim script.
It can parse key-value style options (like --foo=bar) in Vim commands and
|:command| attributes like <count>, <bang>, <range> and so on.
A great advantage of key-value type options is that you need not take care of
the order of options.  And it provides completion for option names and you can
add your own completion for the option values.


==============================================================================
USAGE					*Vital.OptionParser-usage*

At first, make a new instance of a parser with |Vital.OptionParser.new()|, then
define options you want to parse with |Vital.OptionParser-Parser.on()|.  At last,
define a command with |Vital.OptionParser-Parser.parse()|.
This library's interface is inspired by OptionParser in Ruby.
>
  " make option parser instance
  let s:V = vital#{plugin-name}#new()
  let s:O = s:V.import('OptionParser')
  let s:parser = s:O.new()

  " user-defined option completion (see :help :command-completion-customlist)
  "   Note: optlead is NOT arglead (when '--baz=h', 'h' is optlead.)
  function! CompleteBazOption(optlead, cmdline, cursorpos)
    return filter(['sushi', 'yakiniku', 'yakitori'],
            \ 'a:optlead == "" ? 1 : (v:val =~# a:optlead)')
  endfunction

  " define options
  call s:parser.on('--hoge=VALUE', 'description of hoge, must have value')
  call s:parser.on('--foo', 'description of foo')
  " Note: definitions can chain
  call s:parser.on('--[no-]bar', 'description of bar, deniable', {'completion' : 'file'})
              \.on('--baz', 'description of baz, has short option',
                      \ {'short' : '-b', 'completion' : function('CompleteBazOption')})
              \.on('--qux', 'description of qux, defaults to "aaa"', {'default' : 'aaa'})

  " set complete function for unknown options
  let s:parser.unknown_options_completion = 'file'

  " prepare for a completion function
  function! CompleteHoge(arglead, cmdline, cursorpos)
    return s:parser.complete(a:arglead, a:cmdline, a:cursorpos)
  endfunction

  " define command with the parser
  command! -nargs=* -count -bang -complete=customlist,CompleteHoge
                  \ Hoge echo s:parser.parse(<q-args>, <count>, <q-bang>)

  " execute!
  Hoge! --hoge=huga --no-bar poyo -b
  " => {
  "      '__count__' : 0,
  "      '__bang__' : '!',
  "      'hoge' : 'huga',
  "      'bar' : 0,
  "      'baz' : 1,
  "      'qux' : 'aaa',
  "      '__unknown_args__' : ['poyo'],
  "    }

  " show help
  Hoge --help
  " echo following message
  "   Options:
  "     --hoge=VALUE : description of hoge, must have value
  "     --foo        : description of foo
  "     --[no-]bar   : description of bar, deniable
  "     --baz, -b    : description of baz, has short option
  "     --qux        : description of qux, defaults to "aaa" (DEFAULT: 'aaa')
  "
  " => {
  "      '__count__' : 0,
  "      'help' : 1,
  "    }
<


==============================================================================
INTERFACE				*Vital.OptionParser-interface*

------------------------------------------------------------------------------
FUNCTIONS				*Vital.OptionParser-functions*

new()					*Vital.OptionParser.new()*

	Make an option parser instance.  It returns |Dictionary| which is like
	an object in OOP.  You can define options in this instance and parse
	arguments with this instance.


==============================================================================
OBJECTS					*Vital.OptionParser-objects*

------------------------------------------------------------------------------
PARSER OBJECT				*Vital.OptionParser-Parser*

					*Vital.OptionParser-Parser.on()*
Parser.on({name}, {description} [, {extra}])

	Define an option to parse.  You should call this function every option.

	- {name} (required)
	  |String| value.  A name of option.
	  {name} can be one of the below patterns.  foo is an example of
	  option name.

		- "--foo"
		  Option whose name is "foo".  If it is used with value like
		  "--foo=bar", value of "foo" will be "bar".  If a value is
		  omitted,  value of "foo" will be 1.

		- "--foo=VALUE"
		  Option whose name is "foo" and it must have a value with
		  "--foo=bar" style.  In that case, Value of "foo" will be
		  "bar".  Name of value, VALUE is only an example of names.
		  It can be any names.  If a value is omitted, it occurs an
		  error.

		- "--[no-]foo"
		  Option whose name is "foo" and it is deniable with "no-"
		  prefix.  When it is used like "--no-foo", value of "foo"
		  will be 0.

	- {description} (required)
	  |String| value.  Description of option.  This is used for "--help"
	  argument.

	- {extra} (optional)
	  If {extra} is |Dictionary| value, it can contain below keys; "short",
	  "default", "completion", "required" or "pattern".
	  Otherwise, {extra} is dealt with a default value of the option.

	  - "short"
	    If {extra} has "short" key, its value should be |String| and means
	    an alias of {name}.  It must start with "-" and one alphabet must
	    follow it like "-f".

	  - "default"
	    If {extra} has "default" key, its value means a default value of the
	    option.  When the option is omitted, the default value would be
	    used.

	  - "completion"
	  Value of "completion" key must be |Funcref| or |String|.  If |String|, it
	  means a name of default completer.  See
	  |Vital.OptionParser-built-in-completer| to know default completers.  If
	  |Funcref|, it is called when the value of the option should be completed.
	  The |Funcref| should have 3 arguments, {optlead}, {cmdline}, {cursorpos}.
	  {optlead} is the lead portion of the VALUE of the option.  {cmdline}
	  is the |String| of command line.  {cursorpos} is the place of cursor.
	  For example, if you set |Funcref| for "--hoge=VALUE" option, it will be
	  called when a user inputs "--hoge=".  When the user inputs "--hoge=h",
	  "h" will be passed to {optlead}.  {optlead} is NOT ArgLead of
	  |:command-completion-custom|.

	  - "required"
	    Value of "required" key must be 1 or 0.
	    1 means this option must be specified. If not specified, Vital
	    throws an exception.
	    And 0 means this option is optional.
	    If "default" key is specified, "required" value is ignored.

	  - "pattern"
	    If {extra} has "pattern" key, its value must be |String| and means
	    this option must match the value.
	    If it doesn't match "pattern" value, Vital throws an exception.

					*Vital.OptionParser-Parser.parse()*
Parser.parse({q-args} [, {cmd-attributes}...])

	Parse command options.
	{q-args} is |String| value and you must pass <q-arg> to this argument.
	{cmd-attributes} are command attributes like <range>, <count>, <bang>
	and so on.  You need not take care of the order of attributes.
	Arguments not parsed result in "__unknown_args__" key's value as |List|
	of |String|.

	- {range}
	  You must use |List| of <line1> and <line2>.
	  "__range__" key's value is parsed result for {range}.

	- {count}
	  You must use <count>.
	  "__count__" key's value is parsed result for {count}.

	- {bang}
	  You must use <q-bang>.
	  "__bang__" key's value is parsed result for {bang}.

	- {reg}
	  You must use <reg> or <register>.
	  "__reg__" key's value is parsed result for {reg}.
>
  command! -range -bang -register Foo
      \ echo OptionParser.parse(<q-args>, [<line1>, <line2>], <q-bang>, <reg>)

Parser.help()				*Vital.OptionParser-Parser.help()*

	Make output for "--help" option and return it as |String|.

					*Vital.OptionParser-Parser.complete()*
Parser.complete({arglead}, {cmdline}, {cursorpos})

	It is |Funcref| to complete options in command line.  This function is
	assumed to pass to the function for customlist of command.  You must
	wrap it with a global or autoload function like below.
>
  function! CompleteFunctionForHoge(arglead, cmdline, cursorpos)
      return s:opt.complete(a:arglead, a:cmdline, a:cursorpos)
  endfunction
  command! -complete=customlist,CompleteFunctionForHoge Hoge ...
<
	This is because "customlist" cannot take |Funcref|.
	And this function return |List| of candidates.  You must use "customlist"
	and must not use "custom" in |:command|.

				*Vital.OptionParser-Parser.complete_greedily()*
Parser.complete_greedily({arglead}, {cmdline}, {cursorpos})

	It is |Funcref| to complete options in command line.  This |Funcref| is
	different from |Vital.OptionParser-Parser.complete()| in terms of
	candidates of the completion.  This |Funcref| shows all possible
	candidates greedily.

			*Vital.OptionParser-Parser.unknown_options_completion*
Parser.unknown_options_completion

	It is |String| or |Funcref| and used when options which OptionParser doesn't
	know should be completed.  If |String|, it means a name of default
	completer.  See |Vital.OptionParser-built-in-completer| to know default
	completers.  If |Funcref|, it is used directly when the value of the
	option should be completed.  The interface of the function is the same
	as "completion" of {extra}.  For example, when a user input
	":SomeCommand unknown", "unknown" will be passed to {optlead} of the
	complete function.


==============================================================================
SPECIAL OPTIONS				*Vital.OptionParser-special-options*

"--help" option is a special option which is available in all commands
parsed by |Vital.OptionParser|.  If "--help" echoes usage of the command.
Below is an output example.
>
  Options:
    --foo=VALUE : description of foo, must have value
    --foo       : description of foo
    --[no-]bar  : description of bar, deniable
    --baz, -b   : description of baz, has short option
    --qux       : description of qux, defaults to "aaa" (DEFAULT: 'aaa')
<
If you don't want to use "--help", set OptionParser.disable_auto_help to 1.
>
  let s:V = vital#{plugin-name}#new()
  let s:O = s:V.import('OptionParser')
  let s:parser = s:O.new()
  let s:parser.disable_auto_help = 1
<


==============================================================================
BUILT-IN COMPLETERS			*Vital.OptionParser-built-in-completer*

- 'file'
  It completes file or directory names.


==============================================================================
REAL WORLD EXAMPLES			*Vital.OptionParser-real-world-examples*

- wandbox-vim
https://github.com/rhysd/wandbox-vim

- vim-duzzle
https://github.com/deris/vim-duzzle

- translategoogle.vim
https://github.com/daisuzu/translategoogle.vim


==============================================================================
vim:tw=78:fo=tcq2mM:ts=8:ft=help:norl