# keyword.py - $Keyword$ expansion for Mercurial

#

# Copyright 2007 Christian Ebert <blacktrash@gmx.net>

#

# This software may be used and distributed according to the terms

# of the GNU General Public License, incorporated herein by reference.

#

# $Id$

#

# Keyword expansion hack against the grain of a DSCM

#

# There are many good reasons why this is not needed in a distributed

# SCM, still it may be useful in very small projects based on single

# files (like LaTeX packages), that are mostly addressed to an audience

# not running a version control system.

#

# For in-depth discussion refer to

# <http://www.selenic.com/mercurial/wiki/index.cgi/KeywordPlan>.

#

# Keyword expansion is based on Mercurial's changeset template mappings.

#

# Binary files are not touched.

#

# Setup in hgrc:

#

#   [extensions]

#   # enable extension

#   keyword = /full/path/to/hgkw/keyword.py

#   # or, if script in canonical hgext folder:

#   # hgext.keyword =

#

# Files to act upon/ignore are specified in the [keyword] section.

# Customized keyword template mappings in the [keywordmaps] section.

#

# Run "hg help keyword" and "hg kwdemo" to get info on configuration.

'''keyword expansion in local repositories

This extension expands RCS/CVS-like or self-customized $Keywords$

in tracked text files selected by your configuration.

Keywords are only expanded in local repositories and not stored in

the change history. The mechanism can be regarded as a convenience

for the current user or for archive distribution.

Configuration is done in the [keyword] and [keywordmaps] sections

of hgrc files.

Example:

    [keyword]

    # expand keywords in every python file except those matching "x*"

    **.py =

    x*    = ignore

Note: the more specific you are in your filename patterns

      the less you lose speed in huge repos.

For [keywordmaps] template mapping and expansion demonstration and

control run "hg kwdemo".

An additional date template filter {date|utcdate} is provided.

The default template mappings (view with "hg kwdemo -d") can be replaced

with customized keywords and templates.

Again, run "hg kwdemo" to control the results of your config changes.

Before changing/disabling active keywords, run "hg kwshrink" to avoid

the risk of inadvertedly storing expanded keywords in the change history.

To force expansion after enabling it, or a configuration change, run

"hg kwexpand".

Expansions spanning more than one line and incremental expansions,

like CVS' $Log$, are not supported. A keyword template map

"Log = {desc}" expands to the first line of the changeset description.

Caveat: "hg import" fails if the patch context contains an active

        keyword. In that case run "hg kwshrink", and then reimport.

        Or, better, use bundle/unbundle to share changes.

'''

from mercurial import commands, cmdutil, context, fancyopts

from mercurial import filelog, localrepo, revlog, templater, util

from mercurial.i18n import gettext as _

import getopt, re, shutil, sys, tempfile, time

# backwards compatibility hacks

try:

    # cmdutil.parse moves to dispatch._parse in 18a9fbb5cd78

    from mercurial import dispatch

    _parse = dispatch._parse

except ImportError:

    try:

        # commands.parse moves to cmdutil.parse in 0c61124ad877

        _parse = cmdutil.parse

    except AttributeError:

        _parse = commands.parse

try:

    # bail_if_changed moves from commands to cmdutil in 0c61124ad877

    bail_if_changed = cmdutil.bail_if_changed

except AttributeError:

    bail_if_changed = commands.bail_if_changed

# commands.parse/cmdutil.parse returned nothing for

# "hg diff --rev" before 88803a69b24a due to bug in fancyopts

def _fancyopts(args, options, state):

    '''Fixed fancyopts from 88803a69b24a.'''

    long = []

    short = ''

    map = {}

    dt = {}

    for s, l, d, c in options:

        pl = l.replace('-', '_')

        map['-'+s] = map['--'+l] = pl

        if isinstance(d, list):

            state[pl] = d[:]

        else:

            state[pl] = d

        dt[pl] = type(d)

        if (d is not None and d is not True and d is not False and

            not callable(d)):

            if s: s += ':'

            if l: l += '='

        if s: short = short + s

        if l: long.append(l)

    opts, args = getopt.getopt(args, short, long)

    for opt, arg in opts:

        if dt[map[opt]] is type(fancyopts): state[map[opt]](state, map[opt], arg)

        elif dt[map[opt]] is type(1): state[map[opt]] = int(arg)

        elif dt[map[opt]] is type(''): state[map[opt]] = arg

        elif dt[map[opt]] is type([]): state[map[opt]].append(arg)

        elif dt[map[opt]] is type(None): state[map[opt]] = True

        elif dt[map[opt]] is type(False): state[map[opt]] = True

    return args

fancyopts.fancyopts = _fancyopts

commands.optionalrepo += ' kwdemo'

def utcdate(date):

    '''Returns hgdate in cvs-like UTC format.'''

    return time.strftime('%Y/%m/%d %H:%M:%S', time.gmtime(date[0]))

class kwtemplater(object):

    '''

    Sets up keyword templates, corresponding keyword regex, and

    provides keyword substitution functions.

    '''

    templates = {

        'Revision': '{node|short}',

        'Author': '{author|user}',

        'Date': '{date|utcdate}',

        'RCSFile': '{file|basename},v',

        'Source': '{root}/{file},v',

        'Id': '{file|basename},v {node|short} {date|utcdate} {author|user}',

        'Header': '{root}/{file},v {node|short} {date|utcdate} {author|user}',

    }

    def __init__(self, ui, repo, expand, path='', node=None):

        self.ui = ui

        self.repo = repo

        self.t = expand or None

        self.path = path

        self.node = node

        self.debug = self.ui.debugflag

        kwmaps = self.ui.configitems('keywordmaps')

        if kwmaps: # override default templates

            kwmaps = [(k, templater.parsestring(v, quoted=False))

                      for (k, v) in kwmaps]

            self.templates = dict(kwmaps)

        escaped = map(re.escape, self.templates.keys())

        kwpat = r'\$(%s)(: [^$\n\r]*? )??\$' % '|'.join(escaped)

        self.re_kw = re.compile(kwpat)

        if self.t:

            templater.common_filters['utcdate'] = utcdate

            self.t = self._changeset_templater()

    def _changeset_templater(self):

        '''Backwards compatible cmdutil.changeset_templater.'''

        # before 1e0b94cfba0e there was an extra "brinfo" argument

        try:

            return cmdutil.changeset_templater(self.ui, self.repo,

                                               False, '', False)

        except TypeError:

            return cmdutil.changeset_templater(self.ui, self.repo,

                                               False, None, '', False)

    def _wwrite(self, f, data, man):

        '''Makes repo.wwrite backwards compatible.'''

        # 656e06eebda7 removed file descriptor argument

        # 67982d3ee76c added flags argument

        try:

            self.repo.wwrite(f, data, man.flags(f))

        except (AttributeError, TypeError):

            self.repo.wwrite(f, data)

    def _normal(self, files):

        '''Backwards compatible repo.dirstate.normal/update.'''

        # 6fd953d5faea introduced dirstate.normal()

        try:

            for f in files:

                self.repo.dirstate.normal(f)

        except AttributeError:

            self.repo.dirstate.update(files, 'n')

    def _kwsub(self, mobj):

        '''Substitutes keyword using corresponding template.'''

        kw = mobj.group(1)

        self.t.use_template(self.templates[kw])

        self.ui.pushbuffer()

        self.t.show(changenode=self.node, root=self.repo.root, file=self.path)

        keywordsub = templater.firstline(self.ui.popbuffer())

        return '$%s: %s $' % (kw, keywordsub)

    def _substitute(self, node, data, subfunc):

        '''Obtains node if missing.

        Ensures consistent templates regardless of ui.debugflag.

        Calls given substitution function.'''

        if not self.node:

            c = context.filectx(self.repo, self.path, fileid=node)

            self.node = c.node()

        self.ui.debugflag = False

        result = subfunc(self._kwsub, data)

        self.ui.debugflag = self.debug

        return result

    def expand(self, node, data):

        '''Returns data with keywords expanded.'''

        if util.binary(data):

            return data

        return self._substitute(node, data, self.re_kw.sub)

    def process(self, node, data):

        '''Returns a tuple: data, count.

        Count is number of keywords/keyword substitutions.

        Keywords in data are expanded, if templater was initialized.'''

        if util.binary(data):

            return data, None

        if self.t:

            return self._substitute(node, data, self.re_kw.subn)

        return data, self.re_kw.search(data)

    def shrink(self, text):

        '''Returns text with all keyword substitutions removed.'''

        if util.binary(text):

            return text

        return self.re_kw.sub(r'$\1$', text)

    def overwrite(self, candidates, man, commit):

        '''Overwrites files in working directory if keywords are detected.

        Keywords are expanded if keyword templater is initialized,

        otherwise their substitution is removed.'''

        expand = self.t is not None

        action = ('shrinking', 'expanding')[expand]

        notify = (self.ui.note, self.ui.debug)[commit]

        overwritten = []

        for f in candidates:

            fp = self.repo.file(f, kwexp=expand, kwcnt=True, kwmatch=True)

            data, kwfound = fp.read(man[f])

            if kwfound:

                notify(_('overwriting %s %s keywords\n') % (f, action))

                self._wwrite(f, data, man)

                overwritten.append(f)

        self._normal(overwritten)

class kwfilelog(filelog.filelog):

    '''

    Subclass of filelog to hook into its read, add, cmp methods.

    Keywords are "stored" unexpanded, and processed on reading.

    '''

    def __init__(self, opener, path, kwtemplater, kwcnt):

        super(kwfilelog, self).__init__(opener, path)

        self.kwtemplater = kwtemplater

        self.kwcnt = kwcnt

    def read(self, node):

        '''Passes data through kwemplater methods for

        either unconditional keyword expansion

        or counting of keywords and substitution.'''

        data = super(kwfilelog, self).read(node)

        if not self.kwcnt:

            return self.kwtemplater.expand(node, data)

        return self.kwtemplater.process(node, data)

    def add(self, text, meta, tr, link, p1=None, p2=None):

        '''Removes keyword substitutions when adding to filelog.'''

        text = self.kwtemplater.shrink(text)

        return super(kwfilelog, self).add(text, meta, tr, link, p1=p1, p2=p2)

    def cmp(self, node, text):

        '''Removes keyword substitutions for comparison.'''

        text = self.kwtemplater.shrink(text)

        if self.renamed(node):

            t2 = super(kwfilelog, self).read(node)

            return t2 != text

        return revlog.revlog.cmp(self, node, text)

def _keywordmatcher(ui, repo):

    '''Collects include/exclude filename patterns for expansion

    candidates of current configuration. Returns filename matching

    function if include patterns exist, None otherwise.'''

    inc, exc = [], ['.hgtags']

    for pat, opt in ui.configitems('keyword'):

        if opt != 'ignore':

            inc.append(pat)

        else:

            exc.append(pat)

    if inc:

        return util.matcher(repo.root, inc=inc, exc=exc)[1]

    return None

def _weedcandidates(man, kwfmatcher, candidates):

    '''Weeds out files that do not match keyword file matcher,

    are not tracked, or are links.'''

    files = man.keys()

    if candidates:

        return [f for f in candidates if kwfmatcher(f)

                and f in files and not man.linkf(f)]

    return [f for f in files if kwfmatcher(f) and not man.linkf(f)]

def _overwrite(ui, repo, files, expand):

    '''Expands/shrinks keywords in working directory.'''

    wlock = lock = None

    try:

        wlock = repo.wlock()

        lock = repo.lock()

        bail_if_changed(repo)

        ctx = repo.changectx()

        kwfmatcher = _keywordmatcher(ui, repo)

        if kwfmatcher is None:

            ui.warn(_('no files configured for keyword expansion\n'))

            return

        man = ctx.manifest()

        if files:

            cwd = repo.getcwd()

            files = [util.canonpath(repo.root, cwd, f) for f in files]

        files = _weedcandidates(man, kwfmatcher, files)

        if files:

            kwt = kwtemplater(ui, repo, expand, node=ctx.node())

            # 3rd argument sets commit to False

            kwt.overwrite(files, man, False)

    finally:

        del wlock, lock

def shrink(ui, repo, *args):

    '''revert expanded keywords in working directory

    run before changing/disabling active keywords

    or if you experience problems with "hg import" or "hg merge"

    '''

    # 4th argument sets expansion to False

    _overwrite(ui, repo, args, False)

def expand(ui, repo, *args):

    '''expand keywords in working directory

    run after (re)enabling keyword expansion

    '''

    # 4th argument sets expansion to True

    _overwrite(ui, repo, args, True)

def files(ui, repo):

    '''print files currently configured for keyword expansion

    crosscheck which files are matched by [keyword] config patterns

    '''