Vim documentation: vital/Validator/Args
main help file
vital/Validator/Args.txt Arguments validation library
Maintainer: tyru <tyru.exe@gmail.com>
==============================================================================
CONTENTS Vital.Validator.Args-contents
INTRODUCTION Vital.Validator.Args-introduction
EXAMPLES Vital.Validator.Args-examples
INTERFACE Vital.Validator.Args-interface
FUNCTIONS Vital.Validator.Args-functions
VALIDATOR OBJECT Vital.Validator.Args-Validator-object
==============================================================================
INTRODUCTION Vital.Validator.Args-introduction
Vital.Validator.Args is a library to validate arity / types / contents of
function's arguments. This library separates concerns about invalid arity,
types, and values.
==============================================================================
EXAMPLES Vital.Validator.Args-examples
type() Vital.Validator.Args-example-type
------
let s:Validator = vital#{plugin-name}#import('Validator.Args')
let s:TYPE = s:Validator.TYPE
" s:func1() receives one number argument
let s:func1_args =
\ s:Validator.of('func1()')
\.type(v:t_number)
function! s:func1(...) abort
" validate() throws an exception when:
" * arity is not 1
" * if the first argument is not a number
let [n] = s:func1_args.validate(a:000)
echo 'n is a number: ' . n
endfunction
" s:func2() receives two number and string arguments
let s:func2_args =
\ s:Validator.of('func2()')
\.type(v:t_number, v:t_string)
type(): Union types Vital.Validator.Args-example-union-types
-------------------
" s:func3() receives one number or float argument
let s:func3_args =
\ s:Validator.of('func3()')
\.type([v:t_number, v:t_float])
Vital.Validator.Args-example-optional-arguments
type(): Optional arguments
--------------------------
" s:func4() receives one string argument and zero or more optional arguments
" (NOTE: if the last type is optional argument, skip the rest arguments validations)
let s:func4_args =
\ s:Validator.of('func4()')
\.type(v:t_string, 'option')
" if you want to check also the optional arguments, specify the types
" after optional argument (s:func5() receives exact 1-2 argument(s): Number [, Number])
let s:func5_args =
\ s:Validator.of('func5()')
\.type(v:t_number, 'option', v:t_number)
type(): Any type Vital.Validator.Args-example-any-type
----------------
" s:func6() receives one arbitrary type argument
let s:func6_args =
\ s:Validator.of('func6()')
\.type('any')
assert() Vital.Validator.Args-example-assert
--------
" s:func7() receives one positive number argument
" (type() validations were done before assert() validations
" regardless of invoked order)
let s:func7_args =
\ s:Validator.of('func7()')
\.type(v:t_number)
\.assert(1, 'v:val > 0',
\ 'the first argument should be a positive number')
function! s:func7(...) abort
" validate() throws an exception when:
" * arity is not 1
" * if the first argument is not a number
" * if the first argument is not a positive number
let [n] = s:func7_args.validate(a:000)
echo 'n is a positive number: ' . n
endfunction
" Here is an example of Vim script's built-in function range()
let s:range_args = validator.of('vital: Stream: range()')
\.type(v:t_number, 'option', v:t_number, v:t_number)
\.assert(3, 'v:val !=# 0', 'stride is zero')
==============================================================================
INTERFACE Vital.Validator.Args-interface
------------------------------------------------------------------------------
FUNCTIONS Vital.Validator.Args-functions
of({prefix} [, {enable}]) Vital.Validator.Args.of()
Creates validator of a function. {prefix} is a prefix of a thrown
exception message. see Vital.Validator.Args-exceptions for the
examples of thrown exception messages.
If {enable} was given and zero, this module does not perform any
validations. It is useful to switch in debug/production environment.
" Validates arguments if 'g:myplugin#enable_debug' is non-zero.
" Otherwise this does not validate arguments.
let func_args = s:Validator.of('func()', g:myplugin#enable_debug)
\.type(v:t_number)
function! s:func(...) abort
let [n] = s:func_args.validate(a:000)
" ...
endfunction
==============================================================================
VALIDATOR OBJECT Vital.Validator.Args-Validator-object
Validator.type([{type} ...]) Vital.Validator.Args-Validator.type()
Specify types of arguments.
{type} is Number (like , ) or
some special String values below.
"any"
An arbitrary type argument.
"option"
An optional argument (Vim script's "..." in :function arguments).
If the last type is optional argument, skip validation of rest arguments.
But if any type(s) were given after optional argument, check the type(s)
and arity.
See examples for Vital.Validator.Args-example-optional-arguments.
See Vital.Validator.Args-example-type for examples.
Vital.Validator.Args-Validator.assert()
Validator.assert({nth}, {assert} [, {msg}])
Specify assertions of arguments.
{nth} is 1-origin number which specifies the number of argument.
{assert} is a Funcref or String which is a function to receive a
value of each argument.
{msg} is an exception message.
Default value is:
See Vital.Validator.Args-example-assert for examples.
Validator.validate({args}) Vital.Validator.Args-Validator.validate()
Validates given arguments {args} and throw an exception if the given
arguments don't match with defined arguments. {args} is a List of
arguments. A thrown exception format is:
See Vital.Validator.Args-example-assert for examples.
Vital.Validator.Args-exceptions
This method throws an exception when:
* Arity is different with type()'s arguments:
or
* Any types of function arguments and type()'s arguments
are different:
* assert()'s {assert} argument doesn't match with the given argument:
or, assert()'s {msg} was given:
==============================================================================
vim:tw=78:fo=tcq2mM:ts=8:ft=help:norl
top - main help file - tag index