patch 8.1.0579: cannot attach properties to text
Problem: Cannot attach properties to text.
Solution: First part of adding text properties.
diff --git a/runtime/doc/Makefile b/runtime/doc/Makefile
index e4b2b5b..7dbb2ba 100644
--- a/runtime/doc/Makefile
+++ b/runtime/doc/Makefile
@@ -102,6 +102,7 @@
tagsrch.txt \
term.txt \
terminal.txt \
+ textprop.txt \
tips.txt \
todo.txt \
uganda.txt \
@@ -238,6 +239,7 @@
tagsrch.html \
term.html \
terminal.html \
+ textprop.html \
tips.html \
todo.html \
uganda.html \
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index 21fc43a..4e80f4a 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -1,4 +1,4 @@
-*eval.txt* For Vim version 8.1. Last change: 2018 Dec 09
+*eval.txt* For Vim version 8.1. Last change: 2018 Dec 13
VIM REFERENCE MANUAL by Bram Moolenaar
@@ -1104,7 +1104,7 @@
also use functions, like the following: >
:let pi = acos(-1.0)
:let e = exp(1.0)
-
+<
*floating-point-precision*
The precision and range of floating points numbers depends on what "double"
means in the library Vim was compiled with. There is no way to change this at
@@ -2317,6 +2317,22 @@
prompt_setcallback({buf}, {expr}) none set prompt callback function
prompt_setinterrupt({buf}, {text}) none set prompt interrupt function
prompt_setprompt({buf}, {text}) none set prompt text
+prop_add({lnum}, {col}, {props}) none add a text property
+prop_clear({lnum} [, {lnum_end} [, {bufnr}]])
+ none remove all text properties
+prop_find({props} [, {direction}])
+ Dict search for a text property
+prop_list({lnum} [, {props}) List text properties in {lnum}
+prop_remove({props} [, {lnum} [, {lnum_end}]])
+ Number remove a text property
+prop_type_add({name}, {props}) none define a new property type
+prop_type_change({name}, {props})
+ none change an existing property type
+prop_type_delete({name} [, {props}])
+ none delete a property type
+prop_type_get([{name} [, {props}])
+ Dict get property type values
+prop_type_list([{props}]) List get list of property types
pumvisible() Number whether popup menu is visible
pyeval({expr}) any evaluate |Python| expression
py3eval({expr}) any evaluate |python3| expression
@@ -3142,8 +3158,9 @@
When {mode} is omitted or "a" append to the file.
When {mode} is "w" start with an empty file.
- The file is flushed after every message, on Unix you can use
- "tail -f" to see what is going on in real time.
+ Use |ch_log()| to write log messages. The file is flushed
+ after every message, on Unix you can use "tail -f" to see what
+ is going on in real time.
This function is not available in the |sandbox|.
NOTE: the channel communication is stored in the file, be
@@ -6656,6 +6673,191 @@
The result is only visible if {buf} has 'buftype' set to
"prompt". Example: >
call prompt_setprompt(bufnr(''), 'command: ')
+<
+ *prop_add()* *E965*
+prop_add({lnum}, {col}, {props})
+ Attach a text property at position {lnum}, {col}. Use one for
+ the first column.
+ If {lnum} is invalid an error is given. *E966*
+ If {col} is invalid an error is given. *E964*
+
+ {props} is a dictionary with these fields:
+ "length" - length of text in characters, can only be
+ used for a property that does not
+ continue in another line
+ "end_lnum" - line number for end of text
+ "end_col" - column for end of text; not used when
+ "length" is present
+ "bufnr - buffer to add the property to; when
+ omitted the current buffer is used
+ "id" - user defined ID for the property; when
+ omitted zero is used
+ "type" - name of the text property type
+ All fields except "type" are optional.
+
+ It is an error when both "length" and "end_lnum" or "end_col"
+ are passed. Either use "length" or "end_col" for a property
+ within one line, or use "end_lnum" and "end_col" for a
+ property that spans more than one line.
+ When neither "length" or "end_col" are passed the property
+ will apply to one character.
+
+ "type" will first be looked up in the buffer the property is
+ added to. When not found, the global property types are used.
+ If not found an error is given.
+
+ See |text-properties| for information about text properties.
+
+
+prop_clear({lnum} [, {lnum_end} [, {props}]]) *prop_clear()*
+ Remove all text properties from line {lnum}.
+ When {lnum_end} is given, remove all text properties from line
+ {lnum} to {lnum_end} (inclusive).
+
+ When {props} contains a "bufnr" item use this buffer,
+ otherwise use the current buffer.
+
+ See |text-properties| for information about text properties.
+
+ *prop_find()*
+prop_find({props} [, {direction}])
+ NOT IMPLEMENTED YET
+ Search for a text property as specified with {props}:
+ "id" property with this ID
+ "type" property with this type name
+ "bufnr buffer to search in; when present a
+ start position with "lnum" and "col"
+ must be given; when omitted the
+ current buffer is used
+ "lnum" start in this line (when omitted start
+ at the cursor)
+ "col" start at this column (when omitted
+ and "lnum" is given: use column 1,
+ otherwise start at the cursor)
+ "skipstart" do not look for a match at the start
+ position
+
+ {direction} can be "f" for forward and "b" for backward. When
+ omitted forward search is performed.
+
+ If a match is found then a Dict is returned with the entries
+ as with prop_list(), and additionally an "lnum" entry.
+ If no match is found then an empty Dict is returned.
+
+ See |text-properties| for information about text properties.
+
+
+prop_list({lnum} [, {props}]) *prop_list()*
+ Return a List with all text properties in line {lnum}.
+
+ When {props} contains a "bufnr" item, use this buffer instead
+ of the current buffer.
+
+ The properties are ordered by starting column and priority.
+ Each property is a Dict with these entries:
+ "col" starting column
+ "length" length in bytes
+ "id" property ID
+ "type" name of the property type, omitted if
+ the type was deleted
+ "start" when TRUE property starts in this line
+ "end" when TRUE property ends in this line
+
+ When "start" is zero the property started in a previous line,
+ the current one is a continuation.
+ When "end" is zero the property continues in the next line.
+ The line break after this line is included.
+
+ See |text-properties| for information about text properties.
+
+
+ *prop_remove()* *E968*
+prop_remove({props} [, {lnum} [, {lnum_end}]])
+ Remove a matching text property from line {lnum}. When
+ {lnum_end} is given, remove matching text properties from line
+ {lnum} to {lnum_end} (inclusive).
+ When {lnum} is omitted remove matching text properties from
+ all lines.
+
+ {props} is a dictionary with these fields:
+ "id" - remove text properties with this ID
+ "type" - remove text properties with this type name
+ "bufnr" - use this buffer instead of the current one
+ "all" - when TRUE remove all matching text
+ properties, not just the first one
+ A property matches when either "id" or "type" matches.
+
+ Returns the number of properties that were removed.
+
+ See |text-properties| for information about text properties.
+
+
+prop_type_add({name}, {props}) *prop_type_add()* *E969* *E970*
+ Add a text property type {name}. If a property type with this
+ name already exists an error is given.
+ {props} is a dictionary with these optional fields:
+ "bufnr" - define the property only for this
+ buffer; this avoids name collisions and
+ automatically clears the property types
+ when the buffer is deleted.
+ "highlight" - name of highlight group to use
+ "priority" - when a character has multiple text
+ properties the one with the highest
+ priority will be used; negative values
+ can be used, the default priority is
+ zero
+ "start_incl" - when TRUE inserts at the start
+ position will be included in the text
+ property
+ "end_incl" - when TRUE inserts at the end
+ position will be included in the text
+ property
+
+ See |text-properties| for information about text properties.
+
+
+prop_type_change({name}, {props}) *prop_type_change()*
+ Change properties of an existing text property type. If a
+ property with this name does not exist an error is given.
+ The {props} argument is just like |prop_type_add()|.
+
+ See |text-properties| for information about text properties.
+
+
+prop_type_delete({name} [, {props}]) *prop_type_delete()*
+ Remove the text property type {name}. When text properties
+ using the type {name} are still in place, they will not have
+ an effect and can no longer be removed by name.
+
+ {props} can contain a "bufnr" item. When it is given, delete
+ a property type from this buffer instead of from the global
+ property types.
+
+ When text property type {name} is not found there is no error.
+
+ See |text-properties| for information about text properties.
+
+
+prop_type_get([{name} [, {props}]) *prop_type_get()*
+ Returns the properties of property type {name}. This is a
+ dictionary with the same fields as was given to
+ prop_type_add().
+ When the property type {name} does not exist, an empty
+ dictionary is returned.
+
+ {props} can contain a "bufnr" item. When it is given, use
+ this buffer instead of the global property types.
+
+ See |text-properties| for information about text properties.
+
+
+prop_type_list([{props}]) *prop_type_list()*
+ Returns a list with all property type names.
+
+ {props} can contain a "bufnr" item. When it is given, use
+ this buffer instead of the global property types.
+
+ See |text-properties| for information about text properties.
pumvisible() *pumvisible()*
@@ -9609,6 +9811,7 @@
terminfo Compiled with terminfo instead of termcap.
termresponse Compiled with support for |t_RV| and |v:termresponse|.
textobjects Compiled with support for |text-objects|.
+textprop Compiled with support for |text-properties|.
tgetent Compiled with tgetent support, able to use a termcap
or terminfo file.
timers Compiled with |timer_start()| support.
diff --git a/runtime/doc/textprop.txt b/runtime/doc/textprop.txt
new file mode 100644
index 0000000..c88ca37
--- /dev/null
+++ b/runtime/doc/textprop.txt
@@ -0,0 +1,114 @@
+*textprop.txt* For Vim version 8.1. Last change: 2018 Dec 13
+
+
+ VIM REFERENCE MANUAL by Bram Moolenaar
+
+
+Displaying text with properties attached. *text-properties*
+
+THIS IS UNDER DEVELOPMENT - ANYTHING MAY STILL CHANGE *E967*
+
+What is not working yet:
+- Adjusting column/length when inserting text
+- Text properties spanning more than one line
+- prop_find()
+- callbacks when text properties are outdated
+
+
+1. Introduction |text-prop-intro|
+2. Functions |text-prop-functions|
+
+
+{Vi does not have text properties}
+{not able to use text properties when the |+textprop| feature was
+disabled at compile time}
+
+==============================================================================
+1. Introduction *text-prop-intro*
+
+Text properties can be attached to text in a buffer. They will move with the
+text: If lines are deleted or inserted the properties move with the text they
+are attached to. Also when inserting/deleting text in the line before the
+text property. And when inserting/deleting text inside the text property, it
+will increase/decrease in size.
+
+The main use for text properties is to highlight text. This can be seen as a
+replacement for syntax highlighting. Instead of defining patterns to match
+the text, the highlighting is set by a script, possibly using the output of an
+external parser. This only needs to be done once, not every time when
+redrawing the screen, thus can be much faster, after the initial cost of
+attaching the text properties.
+
+Text properties can also be used for other purposes to identify text. For
+example, add a text property on a function name, so that a search can be
+defined to jump to the next/previous function.
+
+A text property is attached at a specific line and column, and has a specified
+length. The property can span multiple lines.
+
+A text property has these fields:
+ "id" a number to be used as desired
+ "type" the name of a property type
+
+
+Property Types ~
+ *E971*
+A text property normally has the name of a property type, which defines
+how to highlight the text. The property type can have these entries:
+ "highlight" name of the highlight group to use
+ "priority" when properties overlap, the one with the highest
+ priority will be used.
+ "start_incl" when TRUE inserts at the start position will be
+ included in the text property
+ "end_incl" when TRUE inserts at the end position will be
+ included in the text property
+
+
+Example ~
+
+Suppose line 11 in a buffer has this text (excluding the indent):
+
+ The number 123 is smaller than 4567.
+
+To highlight the numbers: >
+ call prop_type_add('number', {'highlight': 'Constant'})
+ call prop_add(11, 12, {'length': 3, 'type': 'number})
+ call prop_add(11, 32, {'length': 4, 'type': 'number})
+
+Setting "start_incl" and "end_incl" is useful when white space surrounds the
+text, e.g. for a function name. Using false is useful when the text starts
+and/or ends with a specific character, such as the quote surrounding a string.
+
+ func FuncName(arg) ~
+ ^^^^^^^^ property with start_incl and end_incl set
+
+ var = "text"; ~
+ ^^^^^^ property with start_incl and end_incl not set
+
+Nevertheless, when text is inserted or deleted the text may need to be parsed
+and the text properties updated. But this can be done asynchrnously.
+
+==============================================================================
+2. Functions *text-prop-functions*
+
+Manipulating text property types:
+
+prop_type_add({name}, {props}) define a new property type
+prop_type_change({name}, {props}) change an existing property type
+prop_type_delete({name} [, {props}]) delete a property type
+prop_type_get([{name} [, {props}]) get property type values
+prop_type_list([{props}]) get list of property types
+
+
+Manipulating text properties:
+
+prop_add({lnum}, {col}, {props}) add a text property
+prop_clear({lnum} [, {lnum_end} [, {bufnr}]])
+ remove all text properties
+prop_find({props} [, {direction}]) search for a text property
+prop_list({lnum} [, {props}) text properties in {lnum}
+prop_remove({props} [, {lnum} [, {lnum_end}]])
+ remove a text property
+
+
+ vim:tw=78:ts=8:noet:ft=help:norl: