driver: Rename highlighter entry points

This updates the docs and the driver, in a manner backwards compatible with
existing highlighters.  (None of the highlighters are touched by this change,
yet tests continue to pass.)

Part of issue #329.

docs/highlighters.md

@@ -54,16 +54,16 @@ To create your own `acme` highlighter:
 * Create your script at
     `highlighters/acme/acme-highlighter.zsh`.
 
-* Implement the `_zsh_highlight_acme_highlighter_predicate` function.
+* Implement the `_zsh_highlight_highlighter_acme_predicate` function.
   This function must return 0 when the highlighter needs to be called and
   non-zero otherwise, for example:
 
-        _zsh_highlight_acme_highlighter_predicate() {
+        _zsh_highlight_highlighter_acme_predicate() {
           # Call this highlighter in SVN working copies
           [[ -d .svn ]]
         }
 
-* Implement the `_zsh_highlight_acme_highlighter` function.
+* Implement the `_zsh_highlight_highlighter_acme_paint` function.
   This function does the actual syntax highlighting, by calling
   `_zsh_highlight_add_highlight` with the start and end of the region to
   be highlighted and the `ZSH_HIGHLIGHT_STYLES` key to use. Define the default
@@ -73,13 +73,23 @@ To create your own `acme` highlighter:
 
         : ${ZSH_HIGHLIGHT_STYLES[acme:aurora]:=fg=green}
 
-        _zsh_highlight_acme_highlighter() {
+        _zsh_highlight_highlighter_acme_paint() {
           # Colorize the whole buffer with the 'aurora' style
           _zsh_highlight_add_highlight 0 $#BUFFER acme:aurora
         }
 
 * Name your own functions and global variables `_zsh_highlight_acme_*`.
 
+    - In zsh-syntax-highlighting 0.4.0 and earlier, the entrypoints 
+        `_zsh_highlight_highlighter_acme_predicate` and
+        `_zsh_highlight_highlighter_acme_paint`
+        were named
+        `_zsh_highlight_acme_highlighter_predicate` and
+        `_zsh_highlight_highlighter_acme_paint` respectively.
+
+        These names are still supported for backwards compatibility;
+        however, support for them will be removed in a a future major or minor release (v0.x.0 or v1.0.0).
+
 * Activate your highlighter in `~/.zshrc`:
 
         ZSH_HIGHLIGHT_HIGHLIGHTERS+=(acme)

zsh-syntax-highlighting.zsh

@@ -85,7 +85,7 @@ _zsh_highlight()
       typeset -ga ${cache_place}
 
       # If highlighter needs to be invoked
-      if "_zsh_highlight_${highlighter}_highlighter_predicate"; then
+      if "_zsh_highlight_highlighter_${highlighter}_predicate"; then
 
         # save a copy, and cleanup region_highlight
         region_highlight_copy=("${region_highlight[@]}")
@@ -93,7 +93,7 @@ _zsh_highlight()
 
         # Execute highlighter and save result
         {
-          "_zsh_highlight_${highlighter}_highlighter"
+          "_zsh_highlight_highlighter_${highlighter}_paint"
         } always {
           eval "${cache_place}=(\"\${region_highlight[@]}\")"
         }
@@ -301,13 +301,26 @@ _zsh_highlight_load_highlighters()
   local highlighter highlighter_dir
   for highlighter_dir ($1/*/); do
     highlighter="${highlighter_dir:t}"
-    [[ -f "$highlighter_dir/${highlighter}-highlighter.zsh" ]] && {
+    [[ -f "$highlighter_dir/${highlighter}-highlighter.zsh" ]] &&
       . "$highlighter_dir/${highlighter}-highlighter.zsh"
-      type "_zsh_highlight_${highlighter}_highlighter" &> /dev/null &&
+    if type "_zsh_highlight_highlighter_${highlighter}_paint" &> /dev/null &&
-      type "_zsh_highlight_${highlighter}_highlighter_predicate" &> /dev/null || {
+       type "_zsh_highlight_highlighter_${highlighter}_predicate" &> /dev/null;
-        print -r -- >&2 "zsh-syntax-highlighting: '${highlighter}' highlighter should define both required functions '_zsh_highlight_${highlighter}_highlighter' and '_zsh_highlight_${highlighter}_highlighter_predicate' in '${highlighter_dir}/${highlighter}-highlighter.zsh'."
+    then
-      }
+        # New (0.5.0) function names
-    }
+    elif type "_zsh_highlight_${highlighter}_highlighter" &> /dev/null &&
+         type "_zsh_highlight_${highlighter}_highlighter_predicate" &> /dev/null;
+    then
+        # Old (0.4.x) function names
+        if false; then
+            # TODO: only show this warning for plugin authors/maintainers, not for end users
+            print -r -- >&2 "zsh-syntax-highlighting: warning: ${(qq)highlighter} highlighter uses deprecated entry point names; please ask its maintainer to update it: https://github.com/zsh-users/zsh-syntax-highlighting/issues/329"
+        fi
+        # Make it work.
+        eval "_zsh_highlight_highlighter_${(q)highlighter}_paint() { _zsh_highlight_${(q)highlighter}_highlighter \"\$@\" }"
+        eval "_zsh_highlight_highlighter_${(q)highlighter}_predicate() { _zsh_highlight_${(q)highlighter}_highlighter_predicate \"\$@\" }"
+    else
+        print -r -- >&2 "zsh-syntax-highlighting: '${highlighter}' highlighter should define both required functions '_zsh_highlight_highlighter_${highlighter}_paint' and '_zsh_highlight_highlighter_${highlighter}_predicate' in '${highlighter_dir}/${highlighter}-highlighter.zsh'."
+    fi
   done
 }