fancyopts: prevent mutation of the default value in customopts

Differential Revision: https://phab.mercurial-scm.org/D2937

mercurial/fancyopts.py

@@ -1,368 +1,378
 # fancyopts.py - better command line parsing
 #
 #  Copyright 2005-2009 Matt Mackall <[e-mail]> and others
 #
 # This software may be used and distributed according to the terms of the
 # GNU General Public License version 2 or any later version.
 
 from __future__ import absolute_import
 
 import abc
 import functools
 
 from .i18n import _
 from . import (
     error,
     pycompat,
 )
 
 # Set of flags to not apply boolean negation logic on
 nevernegate = {
     # avoid --no-noninteractive
     'noninteractive',
     # These two flags are special because they cause hg to do one
     # thing and then exit, and so aren't suitable for use in things
     # like aliases anyway.
     'help',
     'version',
 }
 
 def _earlyoptarg(arg, shortlist, namelist):
     """Check if the given arg is a valid unabbreviated option
 
     Returns (flag_str, has_embedded_value?, embedded_value, takes_value?)
 
     >>> def opt(arg):
     ...     return _earlyoptarg(arg, b'R:q', [b'cwd=', b'debugger'])
 
     long form:
 
     >>> opt(b'--cwd')
     ('--cwd', False, '', True)
     >>> opt(b'--cwd=')
     ('--cwd', True, '', True)
     >>> opt(b'--cwd=foo')
     ('--cwd', True, 'foo', True)
     >>> opt(b'--debugger')
     ('--debugger', False, '', False)
     >>> opt(b'--debugger=')  # invalid but parsable
     ('--debugger', True, '', False)
 
     short form:
 
     >>> opt(b'-R')
     ('-R', False, '', True)
     >>> opt(b'-Rfoo')
     ('-R', True, 'foo', True)
     >>> opt(b'-q')
     ('-q', False, '', False)
     >>> opt(b'-qfoo')  # invalid but parsable
     ('-q', True, 'foo', False)
 
     unknown or invalid:
 
     >>> opt(b'--unknown')
     ('', False, '', False)
     >>> opt(b'-u')
     ('', False, '', False)
     >>> opt(b'-ufoo')
     ('', False, '', False)
     >>> opt(b'--')
     ('', False, '', False)
     >>> opt(b'-')
     ('', False, '', False)
     >>> opt(b'-:')
     ('', False, '', False)
     >>> opt(b'-:foo')
     ('', False, '', False)
     """
     if arg.startswith('--'):
         flag, eq, val = arg.partition('=')
         if flag[2:] in namelist:
             return flag, bool(eq), val, False
         if flag[2:] + '=' in namelist:
             return flag, bool(eq), val, True
     elif arg.startswith('-') and arg != '-' and not arg.startswith('-:'):
         flag, val = arg[:2], arg[2:]
         i = shortlist.find(flag[1:])
         if i >= 0:
             return flag, bool(val), val, shortlist.startswith(':', i + 1)
     return '', False, '', False
 
 def earlygetopt(args, shortlist, namelist, gnu=False, keepsep=False):
     """Parse options like getopt, but ignores unknown options and abbreviated
     forms
 
     If gnu=False, this stops processing options as soon as a non/unknown-option
     argument is encountered. Otherwise, option and non-option arguments may be
     intermixed, and unknown-option arguments are taken as non-option.
 
     If keepsep=True, '--' won't be removed from the list of arguments left.
     This is useful for stripping early options from a full command arguments.
 
     >>> def get(args, gnu=False, keepsep=False):
     ...     return earlygetopt(args, b'R:q', [b'cwd=', b'debugger'],
     ...                        gnu=gnu, keepsep=keepsep)
 
     default parsing rules for early options:
 
     >>> get([b'x', b'--cwd', b'foo', b'-Rbar', b'-q', b'y'], gnu=True)
     ([('--cwd', 'foo'), ('-R', 'bar'), ('-q', '')], ['x', 'y'])
     >>> get([b'x', b'--cwd=foo', b'y', b'-R', b'bar', b'--debugger'], gnu=True)
     ([('--cwd', 'foo'), ('-R', 'bar'), ('--debugger', '')], ['x', 'y'])
     >>> get([b'--unknown', b'--cwd=foo', b'--', '--debugger'], gnu=True)
     ([('--cwd', 'foo')], ['--unknown', '--debugger'])
 
     restricted parsing rules (early options must come first):
 
     >>> get([b'--cwd', b'foo', b'-Rbar', b'x', b'-q', b'y'], gnu=False)
     ([('--cwd', 'foo'), ('-R', 'bar')], ['x', '-q', 'y'])
     >>> get([b'--cwd=foo', b'x', b'y', b'-R', b'bar', b'--debugger'], gnu=False)
     ([('--cwd', 'foo')], ['x', 'y', '-R', 'bar', '--debugger'])
     >>> get([b'--unknown', b'--cwd=foo', b'--', '--debugger'], gnu=False)
     ([], ['--unknown', '--cwd=foo', '--', '--debugger'])
 
     stripping early options (without loosing '--'):
 
     >>> get([b'x', b'-Rbar', b'--', '--debugger'], gnu=True, keepsep=True)[1]
     ['x', '--', '--debugger']
 
     last argument:
 
     >>> get([b'--cwd'])
     ([], ['--cwd'])
     >>> get([b'--cwd=foo'])
     ([('--cwd', 'foo')], [])
     >>> get([b'-R'])
     ([], ['-R'])
     >>> get([b'-Rbar'])
     ([('-R', 'bar')], [])
     >>> get([b'-q'])
     ([('-q', '')], [])
     >>> get([b'-q', b'--'])
     ([('-q', '')], [])
 
     '--' may be a value:
 
     >>> get([b'-R', b'--', b'x'])
     ([('-R', '--')], ['x'])
     >>> get([b'--cwd', b'--', b'x'])
     ([('--cwd', '--')], ['x'])
 
     value passed to bool options:
 
     >>> get([b'--debugger=foo', b'x'])
     ([], ['--debugger=foo', 'x'])
     >>> get([b'-qfoo', b'x'])
     ([], ['-qfoo', 'x'])
 
     short option isn't separated with '=':
 
     >>> get([b'-R=bar'])
     ([('-R', '=bar')], [])
 
     ':' may be in shortlist, but shouldn't be taken as an option letter:
 
     >>> get([b'-:', b'y'])
     ([], ['-:', 'y'])
 
     '-' is a valid non-option argument:
 
     >>> get([b'-', b'y'])
     ([], ['-', 'y'])
     """
     parsedopts = []
     parsedargs = []
     pos = 0
     while pos < len(args):
         arg = args[pos]
         if arg == '--':
             pos += not keepsep
             break
         flag, hasval, val, takeval = _earlyoptarg(arg, shortlist, namelist)
         if not hasval and takeval and pos + 1 >= len(args):
             # missing last argument
             break
         if not flag or hasval and not takeval:
             # non-option argument or -b/--bool=INVALID_VALUE
             if gnu:
                 parsedargs.append(arg)
                 pos += 1
             else:
                 break
         elif hasval == takeval:
             # -b/--bool or -s/--str=VALUE
             parsedopts.append((flag, val))
             pos += 1
         else:
             # -s/--str VALUE
             parsedopts.append((flag, args[pos + 1]))
             pos += 2
 
     parsedargs.extend(args[pos:])
     return parsedopts, parsedargs
 
 class customopt(object):
     """Manage defaults and mutations for any type of opt."""
 
     __metaclass__ = abc.ABCMeta
 
     def __init__(self, defaultvalue):
-        self.defaultvalue = defaultvalue
+        self._defaultvalue = defaultvalue
 
     def _isboolopt(self):
         return False
 
+    def getdefaultvalue(self):
+        """Returns the default value for this opt.
+
+        Subclasses should override this to return a new value if the value type
+        is mutable."""
+        return self._defaultvalue
+
     @abc.abstractmethod
     def newstate(self, oldstate, newparam, abort):
         """Adds newparam to oldstate and returns the new state.
 
         On failure, abort can be called with a string error message."""
 
 class _simpleopt(customopt):
     def _isboolopt(self):
-        return isinstance(self.defaultvalue, (bool, type(None)))
+        return isinstance(self._defaultvalue, (bool, type(None)))
 
     def newstate(self, oldstate, newparam, abort):
         return newparam
 
 class _callableopt(customopt):
     def __init__(self, callablefn):
         self.callablefn = callablefn
         super(_callableopt, self).__init__(None)
 
     def newstate(self, oldstate, newparam, abort):
         return self.callablefn(newparam)
 
 class _listopt(customopt):
+    def getdefaultvalue(self):
+        return self._defaultvalue[:]
+
     def newstate(self, oldstate, newparam, abort):
         oldstate.append(newparam)
         return oldstate
 
 class _intopt(customopt):
     def newstate(self, oldstate, newparam, abort):
         try:
             return int(newparam)
         except ValueError:
             abort(_('expected int'))
 
 def _defaultopt(default):
     """Returns a default opt implementation, given a default value."""
 
     if isinstance(default, customopt):
         return default
     elif callable(default):
         return _callableopt(default)
     elif isinstance(default, list):
         return _listopt(default[:])
     elif type(default) is type(1):
         return _intopt(default)
     else:
         return _simpleopt(default)
 
 def fancyopts(args, options, state, gnu=False, early=False, optaliases=None):
     """
     read args, parse options, and store options in state
 
     each option is a tuple of:
 
       short option or ''
       long option
       default value
       description
       option value label(optional)
 
     option types include:
 
       boolean or none - option sets variable in state to true
       string - parameter string is stored in state
       list - parameter string is added to a list
       integer - parameter strings is stored as int
       function - call function with parameter
       customopt - subclass of 'customopt'
 
     optaliases is a mapping from a canonical option name to a list of
     additional long options. This exists for preserving backward compatibility
     of early options. If we want to use it extensively, please consider moving
     the functionality to the options table (e.g separate long options by '|'.)
 
     non-option args are returned
     """
     if optaliases is None:
         optaliases = {}
     namelist = []
     shortlist = ''
     argmap = {}
     defmap = {}
     negations = {}
     alllong = set(o[1] for o in options)
 
     for option in options:
         if len(option) == 5:
             short, name, default, comment, dummy = option
         else:
             short, name, default, comment = option
         # convert opts to getopt format
         onames = [name]
         onames.extend(optaliases.get(name, []))
         name = name.replace('-', '_')
 
         argmap['-' + short] = name
         for n in onames:
             argmap['--' + n] = name
         defmap[name] = _defaultopt(default)
 
         # copy defaults to state
-        state[name] = defmap[name].defaultvalue
+        state[name] = defmap[name].getdefaultvalue()
 
         # does it take a parameter?
         if not defmap[name]._isboolopt():
             if short:
                 short += ':'
             onames = [n + '=' for n in onames]
         elif name not in nevernegate:
             for n in onames:
                 if n.startswith('no-'):
                     insert = n[3:]
                 else:
                     insert = 'no-' + n
                 # backout (as a practical example) has both --commit and
                 # --no-commit options, so we don't want to allow the
                 # negations of those flags.
                 if insert not in alllong:
                     assert ('--' + n) not in negations
                     negations['--' + insert] = '--' + n
                     namelist.append(insert)
         if short:
             shortlist += short
         if name:
             namelist.extend(onames)
 
     # parse arguments
     if early:
         parse = functools.partial(earlygetopt, gnu=gnu)
     elif gnu:
         parse = pycompat.gnugetoptb
     else:
         parse = pycompat.getoptb
     opts, args = parse(args, shortlist, namelist)
 
     # transfer result to state
     for opt, val in opts:
         boolval = True
         negation = negations.get(opt, False)
         if negation:
             opt = negation
             boolval = False
         name = argmap[opt]
         obj = defmap[name]
         if obj._isboolopt():
             state[name] = boolval
         else:
             def abort(s):
                 raise error.Abort(
                     _('invalid value %r for option %s, %s') % (val, opt, s))
             state[name] = defmap[name].newstate(state[name], val, abort)
 
     # return unparsed args
     return args

mercurial/help.py

@@ -1,689 +1,689
 # help.py - help data for mercurial
 #
 # Copyright 2006 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 __future__ import absolute_import
 
 import itertools
 import os
 import textwrap
 
 from .i18n import (
     _,
     gettext,
 )
 from . import (
     cmdutil,
     encoding,
     error,
     extensions,
     fancyopts,
     filemerge,
     fileset,
     minirst,
     pycompat,
     revset,
     templatefilters,
     templatefuncs,
     templatekw,
     util,
 )
 from .hgweb import (
     webcommands,
 )
 
 _exclkeywords = {
     "(ADVANCED)",
     "(DEPRECATED)",
     "(EXPERIMENTAL)",
     # i18n: "(ADVANCED)" is a keyword, must be translated consistently
     _("(ADVANCED)"),
     # i18n: "(DEPRECATED)" is a keyword, must be translated consistently
     _("(DEPRECATED)"),
     # i18n: "(EXPERIMENTAL)" is a keyword, must be translated consistently
     _("(EXPERIMENTAL)"),
 }
 
 def listexts(header, exts, indent=1, showdeprecated=False):
     '''return a text listing of the given extensions'''
     rst = []
     if exts:
         for name, desc in sorted(exts.iteritems()):
             if not showdeprecated and any(w in desc for w in _exclkeywords):
                 continue
             rst.append('%s:%s: %s\n' % (' ' * indent, name, desc))
     if rst:
         rst.insert(0, '\n%s\n\n' % header)
     return rst
 
 def extshelp(ui):
     rst = loaddoc('extensions')(ui).splitlines(True)
     rst.extend(listexts(
         _('enabled extensions:'), extensions.enabled(), showdeprecated=True))
     rst.extend(listexts(_('disabled extensions:'), extensions.disabled(),
                         showdeprecated=ui.verbose))
     doc = ''.join(rst)
     return doc
 
 def optrst(header, options, verbose):
     data = []
     multioccur = False
     for option in options:
         if len(option) == 5:
             shortopt, longopt, default, desc, optlabel = option
         else:
             shortopt, longopt, default, desc = option
             optlabel = _("VALUE") # default label
 
         if not verbose and any(w in desc for w in _exclkeywords):
             continue
 
         so = ''
         if shortopt:
             so = '-' + shortopt
         lo = '--' + longopt
 
         if isinstance(default, fancyopts.customopt):
-            default = default.defaultvalue
+            default = default.getdefaultvalue()
         if default and not callable(default):
             # default is of unknown type, and in Python 2 we abused
             # the %s-shows-repr property to handle integers etc. To
             # match that behavior on Python 3, we do str(default) and
             # then convert it to bytes.
             desc += _(" (default: %s)") % pycompat.bytestr(default)
 
         if isinstance(default, list):
             lo += " %s [+]" % optlabel
             multioccur = True
         elif (default is not None) and not isinstance(default, bool):
             lo += " %s" % optlabel
 
         data.append((so, lo, desc))
 
     if multioccur:
         header += (_(" ([+] can be repeated)"))
 
     rst = ['\n%s:\n\n' % header]
     rst.extend(minirst.maketable(data, 1))
 
     return ''.join(rst)
 
 def indicateomitted(rst, omitted, notomitted=None):
     rst.append('\n\n.. container:: omitted\n\n    %s\n\n' % omitted)
     if notomitted:
         rst.append('\n\n.. container:: notomitted\n\n    %s\n\n' % notomitted)
 
 def filtercmd(ui, cmd, kw, doc):
     if not ui.debugflag and cmd.startswith("debug") and kw != "debug":
         return True
     if not ui.verbose and doc and any(w in doc for w in _exclkeywords):
         return True
     return False
 
 def topicmatch(ui, commands, kw):
     """Return help topics matching kw.
 
     Returns {'section': [(name, summary), ...], ...} where section is
     one of topics, commands, extensions, or extensioncommands.
     """
     kw = encoding.lower(kw)
     def lowercontains(container):
         return kw in encoding.lower(container)  # translated in helptable
     results = {'topics': [],
                'commands': [],
                'extensions': [],
                'extensioncommands': [],
                }
     for names, header, doc in helptable:
         # Old extensions may use a str as doc.
         if (sum(map(lowercontains, names))
             or lowercontains(header)
             or (callable(doc) and lowercontains(doc(ui)))):
             results['topics'].append((names[0], header))
     for cmd, entry in commands.table.iteritems():
         if len(entry) == 3:
             summary = entry[2]
         else:
             summary = ''
         # translate docs *before* searching there
         docs = _(pycompat.getdoc(entry[0])) or ''
         if kw in cmd or lowercontains(summary) or lowercontains(docs):
             doclines = docs.splitlines()
             if doclines:
                 summary = doclines[0]
             cmdname = cmdutil.parsealiases(cmd)[0]
             if filtercmd(ui, cmdname, kw, docs):
                 continue
             results['commands'].append((cmdname, summary))
     for name, docs in itertools.chain(
         extensions.enabled(False).iteritems(),
         extensions.disabled().iteritems()):
         if not docs:
             continue
         name = name.rpartition('.')[-1]
         if lowercontains(name) or lowercontains(docs):
             # extension docs are already translated
             results['extensions'].append((name, docs.splitlines()[0]))
         try:
             mod = extensions.load(ui, name, '')
         except ImportError:
             # debug message would be printed in extensions.load()
             continue
         for cmd, entry in getattr(mod, 'cmdtable', {}).iteritems():
             if kw in cmd or (len(entry) > 2 and lowercontains(entry[2])):
                 cmdname = cmdutil.parsealiases(cmd)[0]
                 cmddoc = pycompat.getdoc(entry[0])
                 if cmddoc:
                     cmddoc = gettext(cmddoc).splitlines()[0]
                 else:
                     cmddoc = _('(no help text available)')
                 if filtercmd(ui, cmdname, kw, cmddoc):
                     continue
                 results['extensioncommands'].append((cmdname, cmddoc))
     return results
 
 def loaddoc(topic, subdir=None):
     """Return a delayed loader for help/topic.txt."""
 
     def loader(ui):
         docdir = os.path.join(util.datapath, 'help')
         if subdir:
             docdir = os.path.join(docdir, subdir)
         path = os.path.join(docdir, topic + ".txt")
         doc = gettext(util.readfile(path))
         for rewriter in helphooks.get(topic, []):
             doc = rewriter(ui, topic, doc)
         return doc
 
     return loader
 
 internalstable = sorted([
     (['bundle2'], _('Bundle2'),
      loaddoc('bundle2', subdir='internals')),
     (['bundles'], _('Bundles'),
      loaddoc('bundles', subdir='internals')),
     (['censor'], _('Censor'),
      loaddoc('censor', subdir='internals')),
     (['changegroups'], _('Changegroups'),
      loaddoc('changegroups', subdir='internals')),
     (['config'], _('Config Registrar'),
      loaddoc('config', subdir='internals')),
     (['requirements'], _('Repository Requirements'),
      loaddoc('requirements', subdir='internals')),
     (['revlogs'], _('Revision Logs'),
      loaddoc('revlogs', subdir='internals')),
     (['wireprotocol'], _('Wire Protocol'),
      loaddoc('wireprotocol', subdir='internals')),
 ])
 
 def internalshelp(ui):
     """Generate the index for the "internals" topic."""
     lines = ['To access a subtopic, use "hg help internals.{subtopic-name}"\n',
              '\n']
     for names, header, doc in internalstable:
         lines.append(' :%s: %s\n' % (names[0], header))
 
     return ''.join(lines)
 
 helptable = sorted([
     (['bundlespec'], _("Bundle File Formats"), loaddoc('bundlespec')),
     (['color'], _("Colorizing Outputs"), loaddoc('color')),
     (["config", "hgrc"], _("Configuration Files"), loaddoc('config')),
     (["dates"], _("Date Formats"), loaddoc('dates')),
     (["flags"], _("Command-line flags"), loaddoc('flags')),
     (["patterns"], _("File Name Patterns"), loaddoc('patterns')),
     (['environment', 'env'], _('Environment Variables'),
      loaddoc('environment')),
     (['revisions', 'revs', 'revsets', 'revset', 'multirevs', 'mrevs'],
       _('Specifying Revisions'), loaddoc('revisions')),
     (['filesets', 'fileset'], _("Specifying File Sets"), loaddoc('filesets')),
     (['diffs'], _('Diff Formats'), loaddoc('diffs')),
     (['merge-tools', 'mergetools', 'mergetool'], _('Merge Tools'),
      loaddoc('merge-tools')),
     (['templating', 'templates', 'template', 'style'], _('Template Usage'),
      loaddoc('templates')),
     (['urls'], _('URL Paths'), loaddoc('urls')),
     (["extensions"], _("Using Additional Features"), extshelp),
     (["subrepos", "subrepo"], _("Subrepositories"), loaddoc('subrepos')),
     (["hgweb"], _("Configuring hgweb"), loaddoc('hgweb')),
     (["glossary"], _("Glossary"), loaddoc('glossary')),
     (["hgignore", "ignore"], _("Syntax for Mercurial Ignore Files"),
      loaddoc('hgignore')),
     (["phases"], _("Working with Phases"), loaddoc('phases')),
     (['scripting'], _('Using Mercurial from scripts and automation'),
      loaddoc('scripting')),
     (['internals'], _("Technical implementation topics"),
      internalshelp),
     (['pager'], _("Pager Support"), loaddoc('pager')),
 ])
 
 # Maps topics with sub-topics to a list of their sub-topics.
 subtopics = {
     'internals': internalstable,
 }
 
 # Map topics to lists of callable taking the current topic help and
 # returning the updated version
 helphooks = {}
 
 def addtopichook(topic, rewriter):
     helphooks.setdefault(topic, []).append(rewriter)
 
 def makeitemsdoc(ui, topic, doc, marker, items, dedent=False):
     """Extract docstring from the items key to function mapping, build a
     single documentation block and use it to overwrite the marker in doc.
     """
     entries = []
     for name in sorted(items):
         text = (pycompat.getdoc(items[name]) or '').rstrip()
         if (not text
             or not ui.verbose and any(w in text for w in _exclkeywords)):
             continue
         text = gettext(text)
         if dedent:
             # Abuse latin1 to use textwrap.dedent() on bytes.
             text = textwrap.dedent(text.decode('latin1')).encode('latin1')
         lines = text.splitlines()
         doclines = [(lines[0])]
         for l in lines[1:]:
             # Stop once we find some Python doctest
             if l.strip().startswith('>>>'):
                 break
             if dedent:
                 doclines.append(l.rstrip())
             else:
                 doclines.append('  ' + l.strip())
         entries.append('\n'.join(doclines))
     entries = '\n\n'.join(entries)
     return doc.replace(marker, entries)
 
 def addtopicsymbols(topic, marker, symbols, dedent=False):
     def add(ui, topic, doc):
         return makeitemsdoc(ui, topic, doc, marker, symbols, dedent=dedent)
     addtopichook(topic, add)
 
 addtopicsymbols('bundlespec', '.. bundlecompressionmarker',
                 util.bundlecompressiontopics())
 addtopicsymbols('filesets', '.. predicatesmarker', fileset.symbols)
 addtopicsymbols('merge-tools', '.. internaltoolsmarker',
                 filemerge.internalsdoc)
 addtopicsymbols('revisions', '.. predicatesmarker', revset.symbols)
 addtopicsymbols('templates', '.. keywordsmarker', templatekw.keywords)
 addtopicsymbols('templates', '.. filtersmarker', templatefilters.filters)
 addtopicsymbols('templates', '.. functionsmarker', templatefuncs.funcs)
 addtopicsymbols('hgweb', '.. webcommandsmarker', webcommands.commands,
                 dedent=True)
 
 def help_(ui, commands, name, unknowncmd=False, full=True, subtopic=None,
           **opts):
     '''
     Generate the help for 'name' as unformatted restructured text. If
     'name' is None, describe the commands available.
     '''
 
     opts = pycompat.byteskwargs(opts)
 
     def helpcmd(name, subtopic=None):
         try:
             aliases, entry = cmdutil.findcmd(name, commands.table,
                                              strict=unknowncmd)
         except error.AmbiguousCommand as inst:
             # py3k fix: except vars can't be used outside the scope of the
             # except block, nor can be used inside a lambda. python issue4617
             prefix = inst.args[0]
             select = lambda c: cmdutil.parsealiases(c)[0].startswith(prefix)
             rst = helplist(select)
             return rst
 
         rst = []
 
         # check if it's an invalid alias and display its error if it is
         if getattr(entry[0], 'badalias', None):
             rst.append(entry[0].badalias + '\n')
             if entry[0].unknowncmd:
                 try:
                     rst.extend(helpextcmd(entry[0].cmdname))
                 except error.UnknownCommand:
                     pass
             return rst
 
         # synopsis
         if len(entry) > 2:
             if entry[2].startswith('hg'):
                 rst.append("%s\n" % entry[2])
             else:
                 rst.append('hg %s %s\n' % (aliases[0], entry[2]))
         else:
             rst.append('hg %s\n' % aliases[0])
         # aliases
         if full and not ui.quiet and len(aliases) > 1:
             rst.append(_("\naliases: %s\n") % ', '.join(aliases[1:]))
         rst.append('\n')
 
         # description
         doc = gettext(pycompat.getdoc(entry[0]))
         if not doc:
             doc = _("(no help text available)")
         if util.safehasattr(entry[0], 'definition'):  # aliased command
             source = entry[0].source
             if entry[0].definition.startswith('!'):  # shell alias
                 doc = (_('shell alias for::\n\n    %s\n\ndefined by: %s\n') %
                        (entry[0].definition[1:], source))
             else:
                 doc = (_('alias for: hg %s\n\n%s\n\ndefined by: %s\n') %
                        (entry[0].definition, doc, source))
         doc = doc.splitlines(True)
         if ui.quiet or not full:
             rst.append(doc[0])
         else:
             rst.extend(doc)
         rst.append('\n')
 
         # check if this command shadows a non-trivial (multi-line)
         # extension help text
         try:
             mod = extensions.find(name)
             doc = gettext(pycompat.getdoc(mod)) or ''
             if '\n' in doc.strip():
                 msg = _("(use 'hg help -e %s' to show help for "
                         "the %s extension)") % (name, name)
                 rst.append('\n%s\n' % msg)
         except KeyError:
             pass
 
         # options
         if not ui.quiet and entry[1]:
             rst.append(optrst(_("options"), entry[1], ui.verbose))
 
         if ui.verbose:
             rst.append(optrst(_("global options"),
                               commands.globalopts, ui.verbose))
 
         if not ui.verbose:
             if not full:
                 rst.append(_("\n(use 'hg %s -h' to show more help)\n")
                            % name)
             elif not ui.quiet:
                 rst.append(_('\n(some details hidden, use --verbose '
                                'to show complete help)'))
 
         return rst
 
 
     def helplist(select=None, **opts):
         # list of commands
         if name == "shortlist":
             header = _('basic commands:\n\n')
         elif name == "debug":
             header = _('debug commands (internal and unsupported):\n\n')
         else:
             header = _('list of commands:\n\n')
 
         h = {}
         cmds = {}
         for c, e in commands.table.iteritems():
             fs = cmdutil.parsealiases(c)
             f = fs[0]
             p = ''
             if c.startswith("^"):
                 p = '^'
             if select and not select(p + f):
                 continue
             if (not select and name != 'shortlist' and
                 e[0].__module__ != commands.__name__):
                 continue
             if name == "shortlist" and not p:
                 continue
             doc = pycompat.getdoc(e[0])
             if filtercmd(ui, f, name, doc):
                 continue
             doc = gettext(doc)
             if not doc:
                 doc = _("(no help text available)")
             h[f] = doc.splitlines()[0].rstrip()
             cmds[f] = '|'.join(fs)
 
         rst = []
         if not h:
             if not ui.quiet:
                 rst.append(_('no commands defined\n'))
             return rst
 
         if not ui.quiet:
             rst.append(header)
         fns = sorted(h)
         for f in fns:
             if ui.verbose:
                 commacmds = cmds[f].replace("|",", ")
                 rst.append(" :%s: %s\n" % (commacmds, h[f]))
             else:
                 rst.append(' :%s: %s\n' % (f, h[f]))
 
         ex = opts.get
         anyopts = (ex(r'keyword') or not (ex(r'command') or ex(r'extension')))
         if not name and anyopts:
             exts = listexts(_('enabled extensions:'), extensions.enabled())
             if exts:
                 rst.append('\n')
                 rst.extend(exts)
 
             rst.append(_("\nadditional help topics:\n\n"))
             topics = []
             for names, header, doc in helptable:
                 topics.append((names[0], header))
             for t, desc in topics:
                 rst.append(" :%s: %s\n" % (t, desc))
 
         if ui.quiet:
             pass
         elif ui.verbose:
             rst.append('\n%s\n' % optrst(_("global options"),
                                          commands.globalopts, ui.verbose))
             if name == 'shortlist':
                 rst.append(_("\n(use 'hg help' for the full list "
                              "of commands)\n"))
         else:
             if name == 'shortlist':
                 rst.append(_("\n(use 'hg help' for the full list of commands "
                              "or 'hg -v' for details)\n"))
             elif name and not full:
                 rst.append(_("\n(use 'hg help %s' to show the full help "
                              "text)\n") % name)
             elif name and cmds and name in cmds.keys():
                 rst.append(_("\n(use 'hg help -v -e %s' to show built-in "
                              "aliases and global options)\n") % name)
             else:
                 rst.append(_("\n(use 'hg help -v%s' to show built-in aliases "
                              "and global options)\n")
                            % (name and " " + name or ""))
         return rst
 
     def helptopic(name, subtopic=None):
         # Look for sub-topic entry first.
         header, doc = None, None
         if subtopic and name in subtopics:
             for names, header, doc in subtopics[name]:
                 if subtopic in names:
                     break
 
         if not header:
             for names, header, doc in helptable:
                 if name in names:
                     break
             else:
                 raise error.UnknownCommand(name)
 
         rst = [minirst.section(header)]
 
         # description
         if not doc:
             rst.append("    %s\n" % _("(no help text available)"))
         if callable(doc):
             rst += ["    %s\n" % l for l in doc(ui).splitlines()]
 
         if not ui.verbose:
             omitted = _('(some details hidden, use --verbose'
                          ' to show complete help)')
             indicateomitted(rst, omitted)
 
         try:
             cmdutil.findcmd(name, commands.table)
             rst.append(_("\nuse 'hg help -c %s' to see help for "
                        "the %s command\n") % (name, name))
         except error.UnknownCommand:
             pass
         return rst
 
     def helpext(name, subtopic=None):
         try:
             mod = extensions.find(name)
             doc = gettext(pycompat.getdoc(mod)) or _('no help text available')
         except KeyError:
             mod = None
             doc = extensions.disabledext(name)
             if not doc:
                 raise error.UnknownCommand(name)
 
         if '\n' not in doc:
             head, tail = doc, ""
         else:
             head, tail = doc.split('\n', 1)
         rst = [_('%s extension - %s\n\n') % (name.rpartition('.')[-1], head)]
         if tail:
             rst.extend(tail.splitlines(True))
             rst.append('\n')
 
         if not ui.verbose:
             omitted = _('(some details hidden, use --verbose'
                          ' to show complete help)')
             indicateomitted(rst, omitted)
 
         if mod:
             try:
                 ct = mod.cmdtable
             except AttributeError:
                 ct = {}
             modcmds = set([c.partition('|')[0] for c in ct])
             rst.extend(helplist(modcmds.__contains__))
         else:
             rst.append(_("(use 'hg help extensions' for information on enabling"
                        " extensions)\n"))
         return rst
 
     def helpextcmd(name, subtopic=None):
         cmd, ext, mod = extensions.disabledcmd(ui, name,
                                                ui.configbool('ui', 'strict'))
         doc = gettext(pycompat.getdoc(mod)).splitlines()[0]
 
         rst = listexts(_("'%s' is provided by the following "
                               "extension:") % cmd, {ext: doc}, indent=4,
                        showdeprecated=True)
         rst.append('\n')
         rst.append(_("(use 'hg help extensions' for information on enabling "
                    "extensions)\n"))
         return rst
 
 
     rst = []
     kw = opts.get('keyword')
     if kw or name is None and any(opts[o] for o in opts):
         matches = topicmatch(ui, commands, name or '')
         helpareas = []
         if opts.get('extension'):
             helpareas += [('extensions', _('Extensions'))]
         if opts.get('command'):
             helpareas += [('commands', _('Commands'))]
         if not helpareas:
             helpareas = [('topics', _('Topics')),
                          ('commands', _('Commands')),
                          ('extensions', _('Extensions')),
                          ('extensioncommands', _('Extension Commands'))]
         for t, title in helpareas:
             if matches[t]:
                 rst.append('%s:\n\n' % title)
                 rst.extend(minirst.maketable(sorted(matches[t]), 1))
                 rst.append('\n')
         if not rst:
             msg = _('no matches')
             hint = _("try 'hg help' for a list of topics")
             raise error.Abort(msg, hint=hint)
     elif name and name != 'shortlist':
         queries = []
         if unknowncmd:
             queries += [helpextcmd]
         if opts.get('extension'):
             queries += [helpext]
         if opts.get('command'):
             queries += [helpcmd]
         if not queries:
             queries = (helptopic, helpcmd, helpext, helpextcmd)
         for f in queries:
             try:
                 rst = f(name, subtopic)
                 break
             except error.UnknownCommand:
                 pass
         else:
             if unknowncmd:
                 raise error.UnknownCommand(name)
             else:
                 msg = _('no such help topic: %s') % name
                 hint = _("try 'hg help --keyword %s'") % name
                 raise error.Abort(msg, hint=hint)
     else:
         # program name
         if not ui.quiet:
             rst = [_("Mercurial Distributed SCM\n"), '\n']
         rst.extend(helplist(None, **pycompat.strkwargs(opts)))
 
     return ''.join(rst)
 
 def formattedhelp(ui, commands, name, keep=None, unknowncmd=False, full=True,
                   **opts):
     """get help for a given topic (as a dotted name) as rendered rst
 
     Either returns the rendered help text or raises an exception.
     """
     if keep is None:
         keep = []
     else:
         keep = list(keep) # make a copy so we can mutate this later
     fullname = name
     section = None
     subtopic = None
     if name and '.' in name:
         name, remaining = name.split('.', 1)
         remaining = encoding.lower(remaining)
         if '.' in remaining:
             subtopic, section = remaining.split('.', 1)
         else:
             if name in subtopics:
                 subtopic = remaining
             else:
                 section = remaining
     textwidth = ui.configint('ui', 'textwidth')
     termwidth = ui.termwidth() - 2
     if textwidth <= 0 or termwidth < textwidth:
         textwidth = termwidth
     text = help_(ui, commands, name,
                  subtopic=subtopic, unknowncmd=unknowncmd, full=full, **opts)
 
     formatted, pruned = minirst.format(text, textwidth, keep=keep,
                                        section=section)
 
     # We could have been given a weird ".foo" section without a name
     # to look for, or we could have simply failed to found "foo.bar"
     # because bar isn't a section of foo
     if section and not (formatted and name):
         raise error.Abort(_("help section not found: %s") % fullname)
 
     if 'verbose' in pruned:
         keep.append('omitted')
     else:
         keep.append('notomitted')
     formatted, pruned = minirst.format(text, textwidth, keep=keep,
                                        section=section)
     return formatted