documentation: Add documentation for autoload/msgpack.vim

1 files changed, 139 insertions, 0 deletions

diff --git a/runtime/doc/pi_msgpack.txt b/runtime/doc/pi_msgpack.txt
new file mode 100644
index 0000000000..95d6ff7467
--- /dev/null
+++ b/runtime/doc/pi_msgpack.txt
@@ -0,0 +1,139 @@
+*pi_msgpack.txt*	For NeoVim version 0.1.
+
+Author:  Nikolay Pavlov <kp-pav@yandex.ru>
+Copyright: (c) 2015 by Nikolay Pavlov
+
+The Apache license applies to the files in this package, including 
+runtime/autoload/msgpack.vim, runtime/doc/pi_msgpack.txt and 
+test/functional/plugin/msgpack_spec.lua.  Like anything else that's free, 
+msgpack.vim and its associated files are provided *as is* and comes with no 
+warranty of any kind, either expressed or implied.  No guarantees of 
+merchantability.  No guarantees of suitability for any purpose.  By using this 
+plugin, you agree that in no event will the copyright holder be liable for any 
+damages resulting from the use of this software. Use at your own risk!
+
+==============================================================================
+1. Contents				*msgpack.vim-contents*
+
+	1. Contents..............................: |msgpack.vim-contents|
+	2. Msgpack.vim introduction..............: |msgpack.vim-intro|
+	3. Msgpack.vim manual....................: |msgpack.vim-manual|
+	   Function arguments....................: |msgpack.vim-arguments|
+	   msgpack#is_int function...............: |msgpack#is_int()|
+	   msgpack#is_uint function..............: |msgpack#is_uint()|
+	   msgpack#strftime function.............: |msgpack#strftime()|
+	   msgpack#strptime function.............: |msgpack#strptime()|
+	   msgpack#int_dict_to_str function......: |msgpack#int_dict_to_str()|
+	   msgpack#special_type function.........: |msgpack#special_type()|
+	   msgpack#type function.................: |msgpack#type()|
+	   msgpack#deepcopy function.............: |msgpack#deepcopy()|
+	   msgpack#string function...............: |msgpack#string()|
+	   msgpack#eval function.................: |msgpack#eval()|
+	   msgpack#equal function................: |msgpack#equal()|
+
+
+==============================================================================
+2. Msgpack.vim introduction			*msgpack.vim-intro*
+
+This plugin contains utility functions to be used in conjunction with 
+|msgpackdump()| and |msgpackparse()| functions.
+
+==============================================================================
+3. Msgpack.vim manual				*msgpack.vim-manual*
+
+FUNCTION ARGUMENTS				*msgpack.vim-arguments*
+
+Disambiguation of arguments described below.  Note: if e.g. function is listed 
+as accepting |{msgpack-integer}| (or anything else) it means that function 
+does not check whether argument matches its description.
+
+*{msgpack-value}*	Either |msgpack-special-dict| or a regular value, but 
+			not function reference.
+*{msgpack-integer}*	Any value for which |msgpack#type| will return 
+			"integer".
+*{msgpack-special-int}*	|msgpack-special-dict| representing integer.
+
+msgpack#is_int({msgpack-value})				*msgpack#is_int()*
+	Returns 1 if given {msgpack-value} is integer value, 0 otherwise.
+
+msgpack#is_uint({msgpack-value})			*msgpack#is_uint()*
+	Returns 1 if given {msgpack-value} is integer value greater or equal 
+	to zero, 0 otherwise.
+
+							*msgpack#strftime*
+msgpack#strftime({format}, {msgpack-integer})		*msgpack#strftime()*
+	Same as |strftime()|, but second argument may be 
+	|msgpack-special-dict|.  Requires |+python| or |+python3| to really 
+	work with |msgpack-special-dict|s.
+
+							*msgpack#strptime*
+msgpack#strptime({format}, {time})			*msgpack#strptime()*
+	Reverse of |msgpack#strptime()|: for any time and format 
+	|msgpack#equal|( |msgpack#strptime|(format, |msgpack#strftime|(format, 
+	time)), time) be true.  Requires |+python| or |+python3|, without it 
+	only supports non-|msgpack-special-dict| nonnegative times and format 
+	equal to `%Y-%m-%dT%H:%M:%S`.
+
+msgpack#int_dict_to_str({msgpack-special-int})	*msgpack#int_dict_to_str()*
+	Function which converts |msgpack-special-dict| integer value to 
+	a hexadecimal value like 0x1234567890ABCDEF (always returns exactly 16 
+	hexadecimal digits).
+
+msgpack#special_type({msgpack-value})		*msgpack#special_type()*
+	Returns zero if {msgpack-value} is not |msgpack-special-dict|.  If it 
+	is it returns name of the key in |v:msgpack_types| which represents 
+	{msgpack-value} type.
+
+msgpack#type({msgpack-value})				*msgpack#type()*
+	Returns name of the key in |v:msgpack_types| that represents 
+	{msgpack-value} type.  Never returns zero: this function returns 
+	msgpack type which will be dumped by |msgpackdump()| should it receive 
+	a list with singe {msgpack-value} as input.
+
+msgpack#deepcopy({msgpack-value})			*msgpack#deepcopy()*
+	Like |deepcopy()|, but works correctly with |msgpack-special-dict| 
+	values.  Plain |deepcopy()| will destroy all types in 
+	|msgpack-special-dict| values because it will copy _TYPE key values, 
+	while they should be preserved.
+
+msgpack#string({msgpack-value})				*msgpack#string()*
+	Like |string()|, but saves information about msgpack types.  Values 
+	dumped by msgpack#string may be read back by |msgpack#eval()|.  
+	Returns is the following:
+
+	- Dictionaries are dumped as "{key1: value1, key2: value2}". Note: 
+	  msgpack allows any values in keys, so with some 
+	  |msgpack-special-dict| values |msgpack#string()| may produce even 
+	  "{{1: 2}: 3, [4]: 5}".
+	- Lists are dumped as "[value1, value2]".
+	- Strings are dumped as
+	  1. `"abc"`: binary string.
+	  2. `="abc"`: string.
+	  3. `+(10)"ext"`: extension strings (10 may be replaced with any 
+	     8-bit signed integer).
+	  Inside strings the following escape sequences may be present: "\0" 
+	  (represents NUL byte), "\n" (represents line feed) and "\"" 
+	  (represents double quote).
+	- Floating-point and integer values are dumped using |string()| or 
+	  |msgpack#int_dict_to_str()|.
+	- Booleans are dumped as "TRUE" or "FALSE".
+	- Nil values are dumped as "NIL".
+
+msgpack#eval({string}, {dict})				*msgpack#eval()*
+	Transforms string created by |msgpack#string()| into a value suitable 
+	for |msgpackdump()|.  Second argument allows adding special values 
+	that start with head characters (|/\h|) and contain only word 
+	characters (|/\w|).  Built-in special values are "TRUE", "FALSE", 
+	"NIL", "nan" and "inf" and they cannot be overridden.  Map values are 
+	always evaluated to |msgpack-special-dict| values, as well as 
+	hexadecimal digits.  When evaluating maps order of keys is preserved.
+
+							*msgpack#equal*
+msgpack#equal({msgpack-value}, {msgpack-value})		*msgpack#equal()*
+	Returns 1 if given values are equal, 0 otherwise.  When comparing 
+	msgpack map values order of keys is ignored.  Comparing 
+	|msgpack-special-dict| with equivalent non-special-dict value 
+	evaluates to 1.
+
+==============================================================================
+vim:tw=78:ts=8:ft=help:fdm=marker