From 5a7135fa1c31290711b194c33e86e538ce8e131c Mon Sep 17 00:00:00 2001 From: ZyX Date: Sun, 12 Jul 2015 17:31:55 +0300 Subject: eval: Add msgpackparse and msgpackdump functions --- runtime/doc/eval.txt | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) (limited to 'runtime') diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index e80ab2c714..f465cafb8e 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -1904,6 +1904,8 @@ min( {list}) Number minimum value of items in {list} mkdir( {name} [, {path} [, {prot}]]) Number create directory {name} mode( [expr]) String current editing mode +msgpackdump( {list}) List dump a list of objects to msgpack +msgpackparse( {list}) List parse msgpack to a list of objects nextnonblank( {lnum}) Number line nr of non-blank line >= {lnum} nr2char( {expr}[, {utf8}]) String single char with ASCII/UTF8 value {expr} or( {expr}, {expr}) Number bitwise OR @@ -4613,6 +4615,40 @@ mode([expr]) Return a string that indicates the current mode. "c" or "n". Also see |visualmode()|. +msgpackdump({list}) *msgpackdump()* + Convert a list of VimL objects to msgpack. Returned value is + |readfile()|-style list. Example: > + call writefile(msgpackdump([{}]), 'fname.mpack', 'b') +< This will write the single 0x80 byte to `fname.mpack` file + (dictionary with zero items is represented by 0x80 byte in + messagepack). + + Limitations: + 1. |Funcref|s cannot be dumped as funcrefs, they are dumped as + NIL objects instead. + 2. NIL and BOOL objects are never dumped, as well as objects + from EXT family. + 3. Strings are always dumped as BIN strings. + +msgpackparse({list}) *msgpackparse()* + Convert a |readfile()|-style list to a list of VimL objects. + Example: > + let fname = expand('~/.nvim/shada/main.shada') + let mpack = readfile(fname, 'b') + let shada_objects = msgpackparse(mpack) +< This will read |shada-file| to `shada_objects` list. + + Limitations: + 1. Strings that contain one of EXT format family objects + cannot be parsed by msgpackparse(). + 2. It may appear that parsed integers do not fit in |Number| + range. Even if your NeoVim installation uses 64-bit + Numbers, it may appear that string contain 64-bit unsigned + number above INT64_MAX. + 3. NIL objects are parsed as zeroes. BOOL objects are parsed + as either 1 (true) or 0 (false). + 4. BIN and STR strings cannot be distinguished after parsing. + nextnonblank({lnum}) *nextnonblank()* Return the line number of the first line at or below {lnum} that is not blank. Example: > -- cgit From 7fbefd585e6bcee6d99baabd077666fc35785d88 Mon Sep 17 00:00:00 2001 From: ZyX Date: Fri, 17 Jul 2015 00:42:53 +0300 Subject: eval: Remove most of msgpack* functions limitations --- runtime/doc/eval.txt | 85 +++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 71 insertions(+), 14 deletions(-) (limited to 'runtime') diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index f465cafb8e..aee3676e12 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -1517,6 +1517,12 @@ v:mouse_col Column number for a mouse click obtained with |getchar()|. This is the screen column number, like with |virtcol()|. The value is zero when there was no mouse button click. + *v:msgpack_types* *msgpack_types-variable* +v:msgpack_types Dictionary containing msgpack types used by |msgpackparse()| + and |msgpackdump()|. All types inside dictionary are fixed + (not editable) empty lists. To check whether some list is one + of msgpack types, use |is| operator. + *v:oldfiles* *oldfiles-variable* v:oldfiles List of file names that is loaded from the |viminfo| file on startup. These are the files that Vim remembers marks for. @@ -4624,11 +4630,11 @@ msgpackdump({list}) *msgpackdump()* messagepack). Limitations: - 1. |Funcref|s cannot be dumped as funcrefs, they are dumped as - NIL objects instead. - 2. NIL and BOOL objects are never dumped, as well as objects - from EXT family. - 3. Strings are always dumped as BIN strings. + 1. |Funcref|s cannot be dumped. + 2. Containers that reference themselves cannot be dumped. + 3. Dictionary keys are always dumped as STR strings. + 4. Other strings are always dumped as BIN strings. + 5. Points 3. and 4. do not apply to |msgpack-special-dict|s. msgpackparse({list}) *msgpackparse()* Convert a |readfile()|-style list to a list of VimL objects. @@ -4639,15 +4645,66 @@ msgpackparse({list}) *msgpackparse()* < This will read |shada-file| to `shada_objects` list. Limitations: - 1. Strings that contain one of EXT format family objects - cannot be parsed by msgpackparse(). - 2. It may appear that parsed integers do not fit in |Number| - range. Even if your NeoVim installation uses 64-bit - Numbers, it may appear that string contain 64-bit unsigned - number above INT64_MAX. - 3. NIL objects are parsed as zeroes. BOOL objects are parsed - as either 1 (true) or 0 (false). - 4. BIN and STR strings cannot be distinguished after parsing. + 1. Mapping ordering is not preserved unless messagepack + mapping is dumped using generic mapping + (|msgpack-special-map|). + 2. Since the parser aims to preserve all data untouched + (except for 1.) some strings are parsed to + |msgpack-special-dict| format which is not convenient to + use. + *msgpack-special-dict* + Some messagepack strings may be parsed to special + dictionaries. Special dictionaries are dictionaries which + + 1. Contain exactly two keys: `_TYPE` and `_VALUE`. + 2. `_TYPE` key is one of the types found in |v:msgpack_types| + variable. + 3. Value for `_VALUE` has the following format (Key column + contains name of the key from |v:msgpack_types|): + + Key Value ~ + nil Zero, ignored when dumping. + boolean One or zero. When dumping it is only checked that + value is a |Number|. + integer |List| with four numbers: sign (-1 or 1), highest two + bits, number with bits from 62nd to 31st, lowest 31 + bits. I.e. to get actual number one will need to use + code like > + _VALUE[0] * ((_VALUE[1] << 62) + & (_VALUE[2] << 31) + & _VALUE[3]) +< Special dictionary with this type will appear in + |msgpackparse()| output under one of the following + circumstances: + 1. |Number| is 32-bit and value is either above + INT32_MAX or below INT32_MIN. + 2. |Number| is 64-bit and value is above INT64_MAX. It + cannot possibly be below INT64_MIN because msgpack + C parser does not support such values. + float |Float|. This value cannot possibly appear in + |msgpackparse()| output. + string |readfile()|-style list of strings. This value will + appear in |msgpackparse()| output if string contains + zero byte or if string is a mapping key and mapping is + being represented as special dictionary for other + reasons. + binary |readfile()|-style list of strings. This value will + appear in |msgpackparse()| output if binary string + contains zero byte. + array |List|. This value cannot appear in |msgpackparse()| + output. + *msgpack-special-map* + map |List| of |List|s with two items (key and value) each. + This value will appear in |msgpackparse()| output if + parsed mapping contains one of the following keys: + 1. Any key that is not a string (including keys which + are binary strings). + 2. String with NUL byte inside. + 3. Duplicate key. + 4. Empty key. + ext |List| with two values: first is a signed integer + representing extension type. Second is + |readfile()|-style list of strings. nextnonblank({lnum}) *nextnonblank()* Return the line number of the first line at or below {lnum} -- cgit From 69a42f2d1d0892cfb926314cb990dfa89c75821a Mon Sep 17 00:00:00 2001 From: ZyX Date: Sun, 2 Aug 2015 19:34:32 +0300 Subject: documentation: Add {Nvim} tag to new functions --- runtime/doc/eval.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'runtime') diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index aee3676e12..ba8948197e 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -4621,7 +4621,7 @@ mode([expr]) Return a string that indicates the current mode. "c" or "n". Also see |visualmode()|. -msgpackdump({list}) *msgpackdump()* +msgpackdump({list}) {Nvim} *msgpackdump()* Convert a list of VimL objects to msgpack. Returned value is |readfile()|-style list. Example: > call writefile(msgpackdump([{}]), 'fname.mpack', 'b') @@ -4636,7 +4636,7 @@ msgpackdump({list}) *msgpackdump()* 4. Other strings are always dumped as BIN strings. 5. Points 3. and 4. do not apply to |msgpack-special-dict|s. -msgpackparse({list}) *msgpackparse()* +msgpackparse({list}) {Nvim} *msgpackparse()* Convert a |readfile()|-style list to a list of VimL objects. Example: > let fname = expand('~/.nvim/shada/main.shada') -- cgit