Merge pull request #3270 from ZyX-I/shada-support

Add plugin for editing ShaDa files

2 files changed, 282 insertions, 0 deletions

diff --git a/runtime/doc/filetype.txt b/runtime/doc/filetype.txt
index d1f8b1de4c..baf7550948 100644
--- a/runtime/doc/filetype.txt
+++ b/runtime/doc/filetype.txt
@@ -557,6 +557,149 @@ Since the text for this plugin is rather long it has been put in a separate
 file: |pi_spec.txt|.
 
 
+SHADA							*ft-shada*
+
+Allows editing binary |shada-file|s in a nice way.  Opened binary files are 
+displayed in the following format: >
+
+    Type with timestamp YYYY-mm-ddTHH:MM:SS:
+      % Key__  Description___  Value
+      + fooba  foo bar baz fo  {msgpack-value}
+      + abcde  abc def ghi jk  {msgpack-value}
+    Other type with timestamp YYYY-mm-ddTHH:MM:SS:
+      @ Description__  Value
+      - foo bar baz t  {msgpack-value}
+      # Expected more elements in list
+    Some other type with timestamp YYYY-mm-ddTHH:MM:SS:
+      # Unexpected type: type instead of map
+      = {msgpack-value}
+
+Filetype plugin defines all |Cmd-event|s.  Defined |SourceCmd| event makes 
+"source file.shada" be equivalent to "|:rshada| file.shada".  |BufWriteCmd|, 
+|FileWriteCmd| and |FileAppendCmd| events are affected by the following 
+settings:
+
+*g:shada#keep_old_header*	Boolean, if set to false all header entries 
+				are ignored when writing.  Defaults to 1.
+*g:shada#add_own_header*	Boolean, if set to true first written entry 
+				will always be header entry with two values in 
+				a map with attached data: |v:version| attached 
+				to "version" key and "shada.vim" attached to 
+				"generator" key.  Defaults to 1.
+
+Format description:
+
+1. `#` starts a comment.  Lines starting with space characters and then `#` 
+   are ignored.  Plugin may only add comment lines to indicate some errors in 
+   ShaDa format.  Lines containing no non-whitespace characters are also 
+   ignored.
+2. Each entry starts with line that has format "{type} with timestamp 
+   {timestamp}:". {timestamp} is |strftime()|-formatted string representing 
+   actual UNIX timestamp value. First strftime() argument is equal to 
+   `%Y-%m-%dT%H:%M:%S`.  When writing this timestamp is parsed using 
+   |msgpack#strptime()|, with caching (it remembers which timestamp produced 
+   particular strftime() output and uses this value if you did not change 
+   timestamp). {type} is one of
+    1 - Header
+    2 - Search pattern
+    3 - Replacement string
+    4 - History entry
+    5 - Register
+    6 - Variable
+    7 - Global mark
+    8 - Jump
+    9 - Buffer list
+   10 - Local mark
+   11 - Change
+    * - Unknown (0x{type-hex})
+
+   Each type may be represented using Unknown entry: "Jump with timestamp ..." 
+   is the same as "Unknown (0x8) with timestamp ....".
+3. After header there is one of the following lines:
+   1. "  % Key__  Description__  Value": map header.  After mapping header 
+      follows a table which may contain comments and lines consisting of 
+      "  +", key, description and |{msgpack-value}|.  Key is separated by at 
+      least two spaces with description, description is separated by at least 
+      two spaces with the value.  Each key in the map must be at most as wide 
+      as "Key__" header: "Key" allows at most 3-byte keys, "Key__" allows at 
+      most 5-byte keys.  If keys actually occupy less bytes then the rest is 
+      filled with spaces.  Keys cannot be empty, end with spaces, contain two 
+      consequent spaces inside of them or contain multibyte characters (use 
+      "=" format if you need this).  Descriptions have the same restrictions 
+      on width and contents, except that empty descriptions are allowed.  
+      Description column may be omitted.
+
+      When writing description is ignored.  Keys with values |msgpack#equal| 
+      to default ones are ignored.  Order of keys is preserved.  All keys are 
+      treated as strings (not binary strings).
+
+      Note: specifically for buffer list entries it is allowed to have more 
+      then one map header.  Each map header starts a new map entry inside 
+      buffer list because ShaDa buffer list entry is an array of maps.  I.e. >
+
+        Buffer list with timestamp 1970-01-01T00:00:00:
+          % Key  Description  Value
+          + f    file name    "/foo"
+          + l    line number  1
+          + c    column       10
+<
+      is equivalent to >
+
+        Buffer list with timestamp 1970-01-01T00:00:00:
+          = [{="f": "/foo", ="c": 10}]
+<
+      and >
+
+        Buffer list with timestamp 1970-01-01T00:00:00:
+          % Key  Description  Value
+          + f    file name    "/foo"
+
+          % Key  Description  Value
+          + f    file name    "/bar"
+<
+      is equivalent to >
+
+        Buffer list with timestamp 1970-01-01T00:00:00:
+          = [{="f": "/foo"}, {="f": "/bar"}]
+<
+      Note 2: specifically for register entries special syntax for arrays was 
+      designed: >
+
+        Register with timestamp 1970-01-01T00:00:00:
+          % Key  Description  Value
+          + rc   contents     @
+          | - "line1"
+          | - "line2"
+<
+      This is equivalent to >
+
+        Register with timestamp 1970-01-01T00:00:00:
+          % Key  Description  Value
+          + rc   contents     ["line1", "line2"]
+<
+      Such syntax is automatically used if array representation appears to be 
+      too lengthy.
+   2. "  @  Description__  Value": array header.  Same as map, but key is 
+      omitted and description cannot be omitted.  Array entries start with 
+      "  -". Example: >
+
+        History entry with timestamp 1970-01-01T00:00:00:
+          @ Description_  Value
+          - history type  SEARCH
+          - contents      "foo"
+          - separator     '/'
+<
+      is equivalent to >
+
+        History entry with timestamp 1970-01-01T00:00:00:
+          = [SEARCH, "foo", '/']
+<
+      Note: special array syntax for register entries is not recognized here.
+   3. "  = {msgpack-value}": raw values.  |{msgpack-value}| in this case may 
+      have absolutely any type.  Special array syntax for register entries is 
+      not recognized here as well.
+
+
 SQL							*ft-sql*
 
 Since the text for this plugin is rather long it has been put in a separate
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