diff options
| -rw-r--r-- | runtime/doc/filetype.txt | 143 |
1 files changed, 143 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 |