PATCH: (0/3) vcs_info: hg fixes, enhancements and hooks for vcs_info

[Frank Terbeck <ft@bewatermyfriend.org>]

This is a series of three patches (two by Seth House, one by myself),
which fixes bugs in the `hg' backend, adds a new feature to it and adds
the concept of `hooks' to vcs_info.

Seth is the author of all the purely mercurial (hg) related changes.
Including a bug fix: if you're on a mercurial branch, but check out an
older commit, the hash returned by the `get-revision' style if still
the one of the branch's top commit.

The other change Seth made, is support for mercurial's "bookmarks",
which - according to Seth - are mercurial's way of cheap branches. They
are similar to a tag, but they move along as commits are made.

The changes I made, introduce "hooks" into vcs_info. I did that, because
Seth told me, that at the same time more than one bookmark could be
active. So, when you're on a commit that has 123 bookmarks on it, you're
getting an awfully long string in return.

Vcs_info's formats could only strim entries to a certain size. E.g.: if
you'd want the %m item to be eight characters wide, you'd use "%8.8m".
With that bookmarks business, I didn't feel that was quite enough.

Also up to now, a backend could only hand over *one* "misc" parameter to
VCS_INFO_formats(). And with the support for bookmarks, the hg backend
needed more, because the misc parameter is already in use by the
mq-top-patch support. Now, every backend may hand over one or more
misc parameters to VCS_INFO_formats(). The default is, to insert a
comma separated list of all misc parameters as the `%m' item. (Fine-
grained access to what is really inserted is possible through the
`set-message' hook.)

A short example of a hook to control how the hg-bookmarks string is
generated could look like this (included in the documentation too):

Register a function:

% zstyle ':vcs_info:hg+gen-hg-bookmark-string:*' hooks hgbookmarks

Define the function (the `+vi-' prefix is to avoid namespace issues,
the manual describes this, too):

function +vi-hgbookmarks() {
    # The default is to connect all bookmark names by semicolons. This
    # mixes things up a little.
    # Imagine, there's one type of bookmarks that is special to you.
    # Say, because it's *your* work. Those bookmarks look always like
    # this: "sh/*". And you only want to see those.
    local s i

    # The bookmarks returned by `hg' are available in the functions
    # positional parameters.
    (( $# == 0 )) && return 0
    for i in "$@"; do
        if [[ $i == sh/* ]]; then
            [[ -n $s ]] && s=$s,
            s=${s}$i
        fi
    done

    # Now, the communication with the code that calls the hook functions
    # is done via the hook_com[] hash. The key, at which the
    # `gen-hg-bookmark-string' hook looks at is `hg-bookmark-string'.
    # So:
    hook_com[hg-bookmark-string]=$s

    # And to signal, that we want to use the sting we just generated,
    # set the special variable `ret' to something other than the default
    # zero:
    ret=1
    return 0
}

There are currently five hooks available:
    set-message
    set-branch-format
    set-hgrev-format
    gen-hg-bookmark-string
    gen-mq-patch-string
    gen-stgit-patch-string
    gen-stgit-unapplied-string
    set-stgit-format

Those give the user full control over what is being output. Adding hooks
is trivial, but I didn't come up with useful cases yet. :)

Regards, Frank

Frank Terbeck (1):
  vcs_info: Introduce the concept of hooks

Seth House (2):
  vcs_info: hg fixes and enhancements
  vcs_info: hg bookmarks support

 Doc/Zsh/contrib.yo                                |  290 ++++++++++++++++++++-
 Functions/VCS_Info/Backends/VCS_INFO_get_data_bzr |    9 +-
 Functions/VCS_Info/Backends/VCS_INFO_get_data_git |   65 +++---
 Functions/VCS_Info/Backends/VCS_INFO_get_data_hg  |  117 ++++++---
 Functions/VCS_Info/Backends/VCS_INFO_get_data_p4  |   15 +-
 Functions/VCS_Info/Backends/VCS_INFO_get_data_svk |    9 +-
 Functions/VCS_Info/Backends/VCS_INFO_get_data_svn |    9 +-
 Functions/VCS_Info/VCS_INFO_formats               |   83 ++++--
 Functions/VCS_Info/VCS_INFO_hook                  |   42 +++
 Functions/VCS_Info/vcs_info                       |    1 +
 10 files changed, 530 insertions(+), 110 deletions(-)