# 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.
# The extension provides an additional UTC-date filter ({date|utcdate}).
#
# The user has the choice either to create his own keywords and their
# expansions or to use the CVS-like default ones.
#
# Default $keywords$ and their $keyword: substition $ are:
# Revision: changeset id
# Author: username
# Date: %Y/%m/%d %H:%M:%S [UTC]
# RCSFile: basename,v
# Source: /path/to/basename,v
# Id: basename,v csetid %Y/%m/%d %H:%M:%S username
# Header: /path/to/basename,v csetid %Y/%m/%d %H:%M:%S username
#
# Expansions spanning more than one line are truncated to their first line.
# Incremental expansion (like CVS' $Log$) is not supported.
#
# Simple setup in hgrc:
#
# # enable extension
# keyword = /full/path/to/keyword.py
# # or, if script in hgext folder:
# # hgext.keyword =
#
# # filename patterns for expansion are configured in this section
# # files matching patterns with value 'ignore' are ignored
# [keyword]
# **.py =
# x* = ignore
# ...
# # in case you prefer your own keyword maps over the cvs-like defaults:
# [keywordmaps]
# HGdate = {date|rfc822date}
# lastlog = {desc} ## same as {desc|firstline} in this context
# checked in by = {author}
# ...
'''keyword expansion in local repositories
This extension expands RCS/CVS-like or self-customized keywords in
the text files selected by your configuration.
Keywords are only expanded in local repositories and not logged by
Mercurial internally. The mechanism can be regarded as a convenience
for the current user and may be turned off anytime.
Substitution takes place on every commit and update of the working
repository.
Configuration is done in the [keyword] and [keywordmaps] sections of
hgrc files.
'''
try:
from mercurial.demandload import * # stable
from mercurial.i18n import gettext as _
demandload(globals(), 'mercurial:cmdutil,templater,util')
demandload(globals(), 'mercurial:context,filelog,revlog')
demandload(globals(), 're time')
except ImportError: # demandimport
from mercurial.i18n import _
from mercurial import cmdutil, templater, util
from mercurial import context, filelog, revlog
import re, time
deftemplates = {
'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 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.
'''
def __init__(self, ui, repo):
self.ui = ui
self.repo = repo
templates = dict(ui.configitems('keywordmaps'))
if templates:
# parse templates here for less overhead in kwsub matchfunc
for k in templates.keys():
templates[k] = templater.parsestring(templates[k],
quoted=False)
self.templates = templates or deftemplates
self.re_kw = re.compile(r'\$(%s)[^$]*?\$' %
'|'.join(re.escape(k) for k in self.templates.keys()))
templater.common_filters['utcdate'] = utcdate
try:
self.t = cmdutil.changeset_templater(ui, repo,
False, '', False)
except TypeError:
# depending on hg rev changeset_templater has extra "brinfo" arg
self.t = cmdutil.changeset_templater(ui, repo,
False, None, '', False)
def kwsub(self, mobj, path, node):
'''Substitutes keyword using corresponding template.'''
kw = mobj.group(1)
self.t.use_template(self.templates[kw])
self.ui.pushbuffer()
self.t.show(changenode=node, root=self.repo.root, file=path)
keywordsub = templater.firstline(self.ui.popbuffer())
return '$%s: %s $' % (kw, keywordsub)
def expand(self, path, node, filelog, data):
'''Returns data with expanded keywords.'''
if util.binary(data):
return data
c = context.filectx(self.repo, path, fileid=node, filelog=filelog)
cnode = c.node()
return self.re_kw.sub(lambda m: self.kwsub(m, path, cnode), 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, node):
'''Overwrites candidates in working dir expanding keywords.'''
files = []
for f in candidates:
data = self.repo.wfile(f).read()
if not util.binary(data):
data, kwct = self.re_kw.subn(lambda m:
self.kwsub(m, f, node), data)
if kwct:
self.ui.debug(_('overwriting %s expanding keywords\n') % f)
self.repo.wfile(f, 'w').write(data)
files.append(f)
if files:
self.repo.dirstate.update(files, 'n')
def reposetup(ui, repo):
'''Sets up repo, and filelog especially, as kwrepo and kwfilelog
for keyword substitution. This is done for local repos only.'''
if not repo.local():
return
inc, exc = [], ['.hg*']
for pat, opt in repo.ui.configitems('keyword'):
if opt != 'ignore':
inc.append(pat)
else:
exc.append(pat)
if not inc:
return
repo.kwfmatcher = util.matcher(repo.root, inc=inc, exc=exc)[1]
class kwrepo(repo.__class__):
def file(self, f):
if f[0] == '/':
f = f[1:]
return filelog.filelog(self.sopener, f, self, self.revlogversion)
def commit(self, files=None, text="", user=None, date=None,
match=util.always, force=False, lock=None, wlock=None,
force_editor=False, p1=None, p2=None, extra={}):
'''Wraps commit, expanding keywords of committed and
configured files in working directory.'''
removed = self.status()[2]
node = super(kwrepo, self).commit(files=files,
text=text, user=user, date=date,
match=match, force=force, lock=lock, wlock=wlock,
force_editor=force_editor, p1=p1, p2=p2, extra=extra)
if node is None:
return node
candidates = self.changelog.read(node)[3]
candidates = [f for f in candidates if f not in removed
and not self._link(f) and self.kwfmatcher(f)]
if not candidates:
return node
wrelease = False
if not wlock:
wlock = self.wlock()
wrelease = True
try:
kwt = kwtemplater(self.ui, self)
kwt.overwrite(candidates, node)
finally:
if wrelease:
wlock.release()
return node
class kwfilelog(filelog.filelog):
'''
Superclass over filelog to customize it's read, add, cmp methods.
Keywords are "stored" unexpanded, and expanded on reading.
'''
def __init__(self, opener, path, repo=None,
defversion=revlog.REVLOG_DEFAULT_VERSION):
super(kwfilelog, self).__init__(opener, path, defversion)
self._repo = repo
self._path = path
# only init kwtemplater if needed
if hasattr(repo, 'kwfmatcher') and repo.kwfmatcher(path):
self.kwt = kwtemplater(repo.ui, repo)
else:
self.kwt = None
def read(self, node):
'''Substitutes keywords when reading filelog.'''
data = super(kwfilelog, self).read(node)
if self.kwt:
data = self.kwt.expand(self._path, node, self, data)
return data
def add(self, text, meta, tr, link, p1=None, p2=None):
'''Removes keyword substitutions when adding to filelog.'''
if self.kwt:
text = self.kwt.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.'''
if self.kwt:
text = self.kwt.shrink(text)
return super(kwfilelog, self).cmp(node, text)
filelog.filelog = kwfilelog
repo.__class__ = kwrepo