ui: add ui.write() output labeling API

This adds output labeling support with the following methods:

- ui.write(..., label='topic.name topic2.name2 ...')
- ui.write_err(.., label=...)
- ui.popbuffer(labeled=False)
- ui.label(msg, label)

By adding an API to label output directly, the color extension can forgo
parsing command output and instead override the above methods to insert
ANSI color codes. GUI tools can also override the above methods and use
the labels to do GUI-specific styling.

popbuffer gains a labeled argument that, when set to True, returns its
buffered output with labels handled. In the case of the color extension,
this would return output with color codes embedded. For existing users
that use this method to capture and parse output, labels are discarded
and output returned as normal when labeled is False (the default).

Existing wrappers of ui.write() and ui.write_err() should make sure to
accept its new **opts argument.

hgext/progress.py

@@ -1,192 +1,192
 # progress.py show progress bars for some actions
 #
 # Copyright (C) 2010 Augie Fackler <[e-mail]>
 #
 # This program is free software; you can redistribute it and/or modify it
 # under the terms of the GNU General Public License as published by the
 # Free Software Foundation; either version 2 of the License, or (at your
 # option) any later version.
 #
 # This program is distributed in the hope that it will be useful, but
 # WITHOUT ANY WARRANTY; without even the implied warranty of
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
 # Public License for more details.
 #
 # You should have received a copy of the GNU General Public License along
 # with this program; if not, write to the Free Software Foundation, Inc.,
 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 
 """show progress bars for some actions
 
 This extension uses the progress information logged by hg commands
 to draw progress bars that are as informative as possible. Some progress
 bars only offer indeterminate information, while others have a definite
 end point.
 
 The following settings are available::
 
   [progress]
   delay = 3 # number of seconds (float) before showing the progress bar
   refresh = 0.1 # time in seconds between refreshes of the progress bar
   format = topic bar number # format of the progress bar
   width = <none> # if set, the maximum width of the progress information
                  # (that is, min(width, term width) will be used)
   clear-complete = True # clear the progress bar after it's done
   disable = False # if true, don't show a progress bar
   assume-tty = False # if true, ALWAYS show a progress bar, unless
                      # disable is given
 
 Valid entries for the format field are topic, bar, number, unit, and
 item. item defaults to the last 20 characters of the item, but this
 can be changed by adding either ``-<num>`` which would take the last
 num characters, or ``+<num>`` for the first num characters.
 """
 
 import sys
 import time
 
 from mercurial import extensions
 from mercurial import util
 
 def spacejoin(*args):
     return ' '.join(s for s in args if s)
 
 class progbar(object):
     def __init__(self, ui):
         self.ui = ui
         self.resetstate()
 
     def resetstate(self):
         self.topics = []
         self.printed = False
         self.lastprint = time.time() + float(self.ui.config(
             'progress', 'delay', default=3))
         self.indetcount = 0
         self.refresh = float(self.ui.config(
             'progress', 'refresh', default=0.1))
         self.order = self.ui.configlist(
             'progress', 'format',
             default=['topic', 'bar', 'number'])
 
     def show(self, topic, pos, item, unit, total):
         termwidth = self.width()
         self.printed = True
         head = ''
         needprogress = False
         tail = ''
         for indicator in self.order:
             add = ''
             if indicator == 'topic':
                 add = topic
             elif indicator == 'number':
                 if total:
                     add = ('% ' + str(len(str(total))) +
                            's/%s') % (pos, total)
                 else:
                     add = str(pos)
             elif indicator.startswith('item') and item:
                 slice = 'end'
                 if '-' in indicator:
                     wid = int(indicator.split('-')[1])
                 elif '+' in indicator:
                     slice = 'beginning'
                     wid = int(indicator.split('+')[1])
                 else:
                     wid = 20
                 if slice == 'end':
                     add = item[-wid:]
                 else:
                     add = item[:wid]
                 add += (wid - len(add)) * ' '
             elif indicator == 'bar':
                 add = ''
                 needprogress = True
             elif indicator == 'unit' and unit:
                 add = unit
             if not needprogress:
                 head = spacejoin(head, add)
             else:
                 tail = spacejoin(add, tail)
         if needprogress:
             used = 0
             if head:
                 used += len(head) + 1
             if tail:
                 used += len(tail) + 1
             progwidth = termwidth - used - 3
             if total:
                 amt = pos * progwidth // total
                 bar = '=' * (amt - 1)
                 if amt > 0:
                     bar += '>'
                 bar += ' ' * (progwidth - amt)
             else:
                 progwidth -= 3
                 self.indetcount += 1
                 # mod the count by twice the width so we can make the
                 # cursor bounce between the right and left sides
                 amt = self.indetcount % (2 * progwidth)
                 amt -= progwidth
                 bar = (' ' * int(progwidth - abs(amt)) + '<=>' +
                        ' ' * int(abs(amt)))
             prog = ''.join(('[', bar , ']'))
             out = spacejoin(head, prog, tail)
         else:
             out = spacejoin(head, tail)
         sys.stderr.write('\r' + out[:termwidth])
         sys.stderr.flush()
 
     def clear(self):
         sys.stderr.write('\r%s\r' % (' ' * self.width()))
 
     def complete(self):
         if self.ui.configbool('progress', 'clear-complete', default=True):
             self.clear()
         else:
             sys.stderr.write('\n')
         sys.stderr.flush()
 
     def width(self):
         tw = util.termwidth()
         return min(int(self.ui.config('progress', 'width', default=tw)), tw)
 
     def progress(self, orig, topic, pos, item='', unit='', total=None):
         if pos is None:
             if self.topics and self.topics[-1] == topic and self.printed:
                 self.complete()
                 self.resetstate()
         else:
             if topic not in self.topics:
                 self.topics.append(topic)
             now = time.time()
             if (now - self.lastprint >= self.refresh
                 and topic == self.topics[-1]):
                 self.lastprint = now
                 self.show(topic, pos, item, unit, total)
         return orig(topic, pos, item=item, unit=unit, total=total)
 
-    def write(self, orig, *args):
+    def write(self, orig, *args, **opts):
         if self.printed:
             self.clear()
-        return orig(*args)
+        return orig(*args, **opts)
 
 sharedprog = None
 
 def uisetup(ui):
     # Apps that derive a class from ui.ui() can use
     # setconfig('progress', 'disable', 'True') to disable this extension
     if ui.configbool('progress', 'disable'):
         return
     if ((sys.stderr.isatty() or ui.configbool('progress', 'assume-tty'))
         and not ui.debugflag and not ui.quiet):
         # we instantiate one globally shared progress bar to avoid
         # competing progress bars when multiple UI objects get created
         global sharedprog
         if not sharedprog:
             sharedprog = progbar(ui)
         extensions.wrapfunction(ui, 'progress', sharedprog.progress)
         extensions.wrapfunction(ui, 'write', sharedprog.write)
         extensions.wrapfunction(ui, 'write_err', sharedprog.write)
 
 def reposetup(ui, repo):
     uisetup(repo.ui)

mercurial/ui.py

@@ -1,419 +1,476
 # ui.py - user interface bits for mercurial
 #
 # Copyright 2005-2007 Matt Mackall <[e-mail]>
 #
 # This software may be used and distributed according to the terms of the
 # GNU General Public License version 2 or any later version.
 
 from i18n import _
 import errno, getpass, os, socket, sys, tempfile, traceback
 import config, util, error
 
 _booleans = {'1': True, 'yes': True, 'true': True, 'on': True,
              '0': False, 'no': False, 'false': False, 'off': False}
 
 class ui(object):
     def __init__(self, src=None):
         self._buffers = []
         self.quiet = self.verbose = self.debugflag = self.tracebackflag = False
         self._reportuntrusted = True
         self._ocfg = config.config() # overlay
         self._tcfg = config.config() # trusted
         self._ucfg = config.config() # untrusted
         self._trustusers = set()
         self._trustgroups = set()
 
         if src:
             self._tcfg = src._tcfg.copy()
             self._ucfg = src._ucfg.copy()
             self._ocfg = src._ocfg.copy()
             self._trustusers = src._trustusers.copy()
             self._trustgroups = src._trustgroups.copy()
             self.environ = src.environ
             self.fixconfig()
         else:
             # shared read-only environment
             self.environ = os.environ
             # we always trust global config files
             for f in util.rcpath():
                 self.readconfig(f, trust=True)
 
     def copy(self):
         return self.__class__(self)
 
     def _is_trusted(self, fp, f):
         st = util.fstat(fp)
         if util.isowner(st):
             return True
 
         tusers, tgroups = self._trustusers, self._trustgroups
         if '*' in tusers or '*' in tgroups:
             return True
 
         user = util.username(st.st_uid)
         group = util.groupname(st.st_gid)
         if user in tusers or group in tgroups or user == util.username():
             return True
 
         if self._reportuntrusted:
             self.warn(_('Not trusting file %s from untrusted '
                         'user %s, group %s\n') % (f, user, group))
         return False
 
     def readconfig(self, filename, root=None, trust=False,
                    sections=None, remap=None):
         try:
             fp = open(filename)
         except IOError:
             if not sections: # ignore unless we were looking for something
                 return
             raise
 
         cfg = config.config()
         trusted = sections or trust or self._is_trusted(fp, filename)
 
         try:
             cfg.read(filename, fp, sections=sections, remap=remap)
         except error.ConfigError, inst:
             if trusted:
                 raise
             self.warn(_("Ignored: %s\n") % str(inst))
 
         if self.plain():
             for k in ('debug', 'fallbackencoding', 'quiet', 'slash',
                       'logtemplate', 'style',
                       'traceback', 'verbose'):
                 if k in cfg['ui']:
                     del cfg['ui'][k]
             for k, v in cfg.items('alias'):
                 del cfg['alias'][k]
             for k, v in cfg.items('defaults'):
                 del cfg['defaults'][k]
 
         if trusted:
             self._tcfg.update(cfg)
             self._tcfg.update(self._ocfg)
         self._ucfg.update(cfg)
         self._ucfg.update(self._ocfg)
 
         if root is None:
             root = os.path.expanduser('~')
         self.fixconfig(root=root)
 
     def fixconfig(self, root=None):
         # translate paths relative to root (or home) into absolute paths
         root = root or os.getcwd()
         for c in self._tcfg, self._ucfg, self._ocfg:
             for n, p in c.items('paths'):
                 if p and "://" not in p and not os.path.isabs(p):
                     c.set("paths", n, os.path.normpath(os.path.join(root, p)))
 
         # update ui options
         self.debugflag = self.configbool('ui', 'debug')
         self.verbose = self.debugflag or self.configbool('ui', 'verbose')
         self.quiet = not self.debugflag and self.configbool('ui', 'quiet')
         if self.verbose and self.quiet:
             self.quiet = self.verbose = False
         self._reportuntrusted = self.configbool("ui", "report_untrusted", True)
         self.tracebackflag = self.configbool('ui', 'traceback', False)
 
         # update trust information
         self._trustusers.update(self.configlist('trusted', 'users'))
         self._trustgroups.update(self.configlist('trusted', 'groups'))
 
     def setconfig(self, section, name, value):
         for cfg in (self._ocfg, self._tcfg, self._ucfg):
             cfg.set(section, name, value)
         self.fixconfig()
 
     def _data(self, untrusted):
         return untrusted and self._ucfg or self._tcfg
 
     def configsource(self, section, name, untrusted=False):
         return self._data(untrusted).source(section, name) or 'none'
 
     def config(self, section, name, default=None, untrusted=False):
         value = self._data(untrusted).get(section, name, default)
         if self.debugflag and not untrusted and self._reportuntrusted:
             uvalue = self._ucfg.get(section, name)
             if uvalue is not None and uvalue != value:
                 self.debug(_("ignoring untrusted configuration option "
                              "%s.%s = %s\n") % (section, name, uvalue))
         return value
 
     def configbool(self, section, name, default=False, untrusted=False):
         v = self.config(section, name, None, untrusted)
         if v is None:
             return default
         if isinstance(v, bool):
             return v
         if v.lower() not in _booleans:
             raise error.ConfigError(_("%s.%s not a boolean ('%s')")
                                     % (section, name, v))
         return _booleans[v.lower()]
 
     def configlist(self, section, name, default=None, untrusted=False):
         """Return a list of comma/space separated strings"""
         result = self.config(section, name, untrusted=untrusted)
         if result is None:
             result = default or []
         if isinstance(result, basestring):
             result = result.replace(",", " ").split()
         return result
 
     def has_section(self, section, untrusted=False):
         '''tell whether section exists in config.'''
         return section in self._data(untrusted)
 
     def configitems(self, section, untrusted=False):
         items = self._data(untrusted).items(section)
         if self.debugflag and not untrusted and self._reportuntrusted:
             for k, v in self._ucfg.items(section):
                 if self._tcfg.get(section, k) != v:
                     self.debug(_("ignoring untrusted configuration option "
                                 "%s.%s = %s\n") % (section, k, v))
         return items
 
     def walkconfig(self, untrusted=False):
         cfg = self._data(untrusted)
         for section in cfg.sections():
             for name, value in self.configitems(section, untrusted):
                 yield section, name, str(value).replace('\n', '\\n')
 
     def plain(self):
         return 'HGPLAIN' in os.environ
 
     def username(self):
         """Return default username to be used in commits.
 
         Searched in this order: $HGUSER, [ui] section of hgrcs, $EMAIL
         and stop searching if one of these is set.
         If not found and ui.askusername is True, ask the user, else use
         ($LOGNAME or $USER or $LNAME or $USERNAME) + "@full.hostname".
         """
         user = os.environ.get("HGUSER")
         if user is None:
             user = self.config("ui", "username")
         if user is None:
             user = os.environ.get("EMAIL")
         if user is None and self.configbool("ui", "askusername"):
             user = self.prompt(_("enter a commit username:"), default=None)
         if user is None and not self.interactive():
             try:
                 user = '%s@%s' % (util.getuser(), socket.getfqdn())
                 self.warn(_("No username found, using '%s' instead\n") % user)
             except KeyError:
                 pass
         if not user:
             raise util.Abort(_('no username supplied (see "hg help config")'))
         if "\n" in user:
             raise util.Abort(_("username %s contains a newline\n") % repr(user))
         return user
 
     def shortuser(self, user):
         """Return a short representation of a user name or email address."""
         if not self.verbose:
             user = util.shortuser(user)
         return user
 
     def _path(self, loc):
         p = self.config('paths', loc)
         if p:
             if '%%' in p:
                 self.warn("(deprecated '%%' in path %s=%s from %s)\n" %
                           (loc, p, self.configsource('paths', loc)))
                 p = p.replace('%%', '%')
             p = util.expandpath(p)
         return p
 
     def expandpath(self, loc, default=None):
         """Return repository location relative to cwd or from [paths]"""
         if "://" in loc or os.path.isdir(os.path.join(loc, '.hg')):
             return loc
 
         path = self._path(loc)
         if not path and default is not None:
             path = self._path(default)
         return path or loc
 
     def pushbuffer(self):
         self._buffers.append([])
 
-    def popbuffer(self):
+    def popbuffer(self, labeled=False):
+        '''pop the last buffer and return the buffered output
+
+        If labeled is True, any labels associated with buffered
+        output will be handled. By default, this has no effect
+        on the output returned, but extensions and GUI tools may
+        handle this argument and returned styled output. If output
+        is being buffered so it can be captured and parsed or
+        processed, labeled should not be set to True.
+        '''
         return "".join(self._buffers.pop())
 
-    def write(self, *args):
+    def write(self, *args, **opts):
+        '''write args to output
+
+        By default, this method simply writes to the buffer or stdout,
+        but extensions or GUI tools may override this method,
+        write_err(), popbuffer(), and label() to style output from
+        various parts of hg.
+
+        An optional keyword argument, "label", can be passed in.
+        This should be a string containing label names separated by
+        space. Label names take the form of "topic.type". For example,
+        ui.debug() issues a label of "ui.debug".
+
+        When labeling output for a specific command, a label of
+        "cmdname.type" is recommended. For example, status issues
+        a label of "status.modified" for modified files.
+        '''
         if self._buffers:
             self._buffers[-1].extend([str(a) for a in args])
         else:
             for a in args:
                 sys.stdout.write(str(a))
 
-    def write_err(self, *args):
+    def write_err(self, *args, **opts):
         try:
             if not getattr(sys.stdout, 'closed', False):
                 sys.stdout.flush()
             for a in args:
                 sys.stderr.write(str(a))
             # stderr may be buffered under win32 when redirected to files,
             # including stdout.
             if not getattr(sys.stderr, 'closed', False):
                 sys.stderr.flush()
         except IOError, inst:
             if inst.errno != errno.EPIPE:
                 raise
 
     def flush(self):
         try: sys.stdout.flush()
         except: pass
         try: sys.stderr.flush()
         except: pass
 
     def interactive(self):
         i = self.configbool("ui", "interactive", None)
         if i is None:
             try:
                 return sys.stdin.isatty()
             except AttributeError:
                 # some environments replace stdin without implementing isatty
                 # usually those are non-interactive
                 return False
 
         return i
 
     def _readline(self, prompt=''):
         if sys.stdin.isatty():
             try:
                 # magically add command line editing support, where
                 # available
                 import readline
                 # force demandimport to really load the module
                 readline.read_history_file
                 # windows sometimes raises something other than ImportError
             except Exception:
                 pass
         line = raw_input(prompt)
         # When stdin is in binary mode on Windows, it can cause
         # raw_input() to emit an extra trailing carriage return
         if os.linesep == '\r\n' and line and line[-1] == '\r':
             line = line[:-1]
         return line
 
     def prompt(self, msg, default="y"):
         """Prompt user with msg, read response.
         If ui is not interactive, the default is returned.
         """
         if not self.interactive():
             self.write(msg, ' ', default, "\n")
             return default
         try:
             r = self._readline(msg + ' ')
             if not r:
                 return default
             return r
         except EOFError:
             raise util.Abort(_('response expected'))
 
     def promptchoice(self, msg, choices, default=0):
         """Prompt user with msg, read response, and ensure it matches
         one of the provided choices. The index of the choice is returned.
         choices is a sequence of acceptable responses with the format:
         ('&None', 'E&xec', 'Sym&link') Responses are case insensitive.
         If ui is not interactive, the default is returned.
         """
         resps = [s[s.index('&')+1].lower() for s in choices]
         while True:
             r = self.prompt(msg, resps[default])
             if r.lower() in resps:
                 return resps.index(r.lower())
             self.write(_("unrecognized response\n"))
 
     def getpass(self, prompt=None, default=None):
         if not self.interactive():
             return default
         try:
             return getpass.getpass(prompt or _('password: '))
         except EOFError:
             raise util.Abort(_('response expected'))
-    def status(self, *msg):
+    def status(self, *msg, **opts):
+        '''write status message to output (if ui.quiet is False)
+
+        This adds an output label of "ui.status".
+        '''
         if not self.quiet:
-            self.write(*msg)
-    def warn(self, *msg):
-        self.write_err(*msg)
-    def note(self, *msg):
+            opts['label'] = opts.get('label', '') + ' ui.status'
+            self.write(*msg, **opts)
+    def warn(self, *msg, **opts):
+        '''write warning message to output (stderr)
+
+        This adds an output label of "ui.warning".
+        '''
+        opts['label'] = opts.get('label', '') + ' ui.warning'
+        self.write_err(*msg, **opts)
+    def note(self, *msg, **opts):
+        '''write note to output (if ui.verbose is True)
+
+        This adds an output label of "ui.note".
+        '''
         if self.verbose:
-            self.write(*msg)
-    def debug(self, *msg):
+            opts['label'] = opts.get('label', '') + ' ui.note'
+            self.write(*msg, **opts)
+    def debug(self, *msg, **opts):
+        '''write debug message to output (if ui.debugflag is True)
+
+        This adds an output label of "ui.debug".
+        '''
         if self.debugflag:
-            self.write(*msg)
+            opts['label'] = opts.get('label', '') + ' ui.debug'
+            self.write(*msg, **opts)
     def edit(self, text, user):
         (fd, name) = tempfile.mkstemp(prefix="hg-editor-", suffix=".txt",
                                       text=True)
         try:
             f = os.fdopen(fd, "w")
             f.write(text)
             f.close()
 
             editor = self.geteditor()
 
             util.system("%s \"%s\"" % (editor, name),
                         environ={'HGUSER': user},
                         onerr=util.Abort, errprefix=_("edit failed"))
 
             f = open(name)
             t = f.read()
             f.close()
         finally:
             os.unlink(name)
 
         return t
 
     def traceback(self, exc=None):
         '''print exception traceback if traceback printing enabled.
         only to call in exception handler. returns true if traceback
         printed.'''
         if self.tracebackflag:
             if exc:
                 traceback.print_exception(exc[0], exc[1], exc[2])
             else:
                 traceback.print_exc()
         return self.tracebackflag
 
     def geteditor(self):
         '''return editor to use'''
         return (os.environ.get("HGEDITOR") or
                 self.config("ui", "editor") or
                 os.environ.get("VISUAL") or
                 os.environ.get("EDITOR", "vi"))
 
     def progress(self, topic, pos, item="", unit="", total=None):
         '''show a progress message
 
         With stock hg, this is simply a debug message that is hidden
         by default, but with extensions or GUI tools it may be
         visible. 'topic' is the current operation, 'item' is a
         non-numeric marker of the current position (ie the currently
         in-process file), 'pos' is the current numeric position (ie
         revision, bytes, etc.), unit is a corresponding unit label,
         and total is the highest expected pos.
 
         Multiple nested topics may be active at a time.
 
         All topics should be marked closed by setting pos to None at
         termination.
         '''
 
         if pos == None or not self.debugflag:
             return
 
         if unit:
             unit = ' ' + unit
         if item:
             item = ' ' + item
 
         if total:
             pct = 100.0 * pos / total
             self.debug('%s:%s %s/%s%s (%4.2f%%)\n'
                      % (topic, item, pos, total, unit, pct))
         else:
             self.debug('%s:%s %s%s\n' % (topic, item, pos, unit))
+
+    def label(self, msg, label):
+        '''style msg based on supplied label
+
+        Like ui.write(), this just returns msg unchanged, but extensions
+        and GUI tools can override it to allow styling output without
+        writing it.
+
+        ui.write(s, 'label') is equivalent to
+        ui.write(ui.label(s, 'label')).
+        '''
+        return msg