# help.py - help data for mercurial

#

# Copyright 2006 Matt Mackall <mpm@selenic.com>

#

# 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 re

import textwrap

from .i18n import (

    _,

    gettext,

)

from . import (

    cmdutil,

    encoding,

    error,

    extensions,

    fancyopts,

    filemerge,

    fileset,

    minirst,

    pycompat,

    registrar,

    revset,

    templatefilters,

    templatefuncs,

    templatekw,

    ui as uimod,

    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)"),

}

# The order in which command categories will be displayed.

# Extensions with custom categories should insert them into this list

# after/before the appropriate item, rather than replacing the list or

# assuming absolute positions.

CATEGORY_ORDER = [

    registrar.command.CATEGORY_REPO_CREATION,

    registrar.command.CATEGORY_REMOTE_REPO_MANAGEMENT,

    registrar.command.CATEGORY_COMMITTING,

    registrar.command.CATEGORY_CHANGE_MANAGEMENT,

    registrar.command.CATEGORY_CHANGE_ORGANIZATION,

    registrar.command.CATEGORY_FILE_CONTENTS,

    registrar.command.CATEGORY_CHANGE_NAVIGATION ,

    registrar.command.CATEGORY_WORKING_DIRECTORY,

    registrar.command.CATEGORY_IMPORT_EXPORT,

    registrar.command.CATEGORY_MAINTENANCE,

    registrar.command.CATEGORY_HELP,

    registrar.command.CATEGORY_MISC,

    registrar.command.CATEGORY_NONE,

]

# Human-readable category names. These are translated.

# Extensions with custom categories should add their names here.

CATEGORY_NAMES = {

    registrar.command.CATEGORY_REPO_CREATION: 'Repository creation',

    registrar.command.CATEGORY_REMOTE_REPO_MANAGEMENT:

        'Remote repository management',

    registrar.command.CATEGORY_COMMITTING: 'Change creation',

    registrar.command.CATEGORY_CHANGE_NAVIGATION: 'Change navigation',

    registrar.command.CATEGORY_CHANGE_MANAGEMENT: 'Change manipulation',

    registrar.command.CATEGORY_CHANGE_ORGANIZATION: 'Change organization',

    registrar.command.CATEGORY_WORKING_DIRECTORY:

        'Working directory management',

    registrar.command.CATEGORY_FILE_CONTENTS: 'File content management',

    registrar.command.CATEGORY_IMPORT_EXPORT: 'Change import/export',

    registrar.command.CATEGORY_MAINTENANCE: 'Repository maintenance',

    registrar.command.CATEGORY_HELP: 'Help',

    registrar.command.CATEGORY_MISC: 'Miscellaneous commands',

    registrar.command.CATEGORY_NONE: 'Uncategorized commands',

}

# Topic categories.

TOPIC_CATEGORY_IDS = 'ids'

TOPIC_CATEGORY_OUTPUT = 'output'

TOPIC_CATEGORY_CONFIG = 'config'

TOPIC_CATEGORY_CONCEPTS = 'concepts'

TOPIC_CATEGORY_MISC = 'misc'

TOPIC_CATEGORY_NONE = 'none'

# The order in which topic categories will be displayed.

# Extensions with custom categories should insert them into this list

# after/before the appropriate item, rather than replacing the list or

# assuming absolute positions.

TOPIC_CATEGORY_ORDER = [

    TOPIC_CATEGORY_IDS,

    TOPIC_CATEGORY_OUTPUT,

    TOPIC_CATEGORY_CONFIG,

    TOPIC_CATEGORY_CONCEPTS,

    TOPIC_CATEGORY_MISC,

    TOPIC_CATEGORY_NONE,

]

# Human-readable topic category names. These are translated.

TOPIC_CATEGORY_NAMES = {

    TOPIC_CATEGORY_IDS: 'Mercurial identifiers',

    TOPIC_CATEGORY_OUTPUT: 'Mercurial output',

    TOPIC_CATEGORY_CONFIG: 'Mercurial configuration',

    TOPIC_CATEGORY_CONCEPTS: 'Concepts',

    TOPIC_CATEGORY_MISC: 'Miscellaneous',

    TOPIC_CATEGORY_NONE: 'Uncategorized topics',

    TOPIC_CATEGORY_NONE: 'Uncategorized topics',

}

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.getdefaultvalue()

        if (default and not callable(default)) or default is False:

            # 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.

            defaultstr = pycompat.bytestr(default)

            if isinstance(default, bool):

                defaultstr = _("on") if default else _("off")

            desc += _(" (default: %s)") % defaultstr

        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, func, kw, doc):

    if not ui.debugflag and cmd.startswith("debug") and kw != "debug":

        # Debug command, and user is not looking for those.

        return True

    if not ui.verbose:

        if not kw and not doc:

            # Command had no documentation, no point in showing it by default.

            return True

        if getattr(func, 'alias', False) and not getattr(func, 'owndoc', False):

            # Alias didn't have its own documentation.

            return True

        if doc and any(w in doc for w in _exclkeywords):

            # Documentation has excluded keywords.

            return True

    if kw == "shortlist" and not getattr(func, 'helpbasic', False):

        # We're presenting the short list but the command is not basic.

        return True

    if ui.configbool('help', 'hidden-command.%s' % cmd):

        # Configuration explicitly hides the command.

        return True

    return False

def filtertopic(ui, topic):

    return ui.configbool('help', 'hidden-topic.%s' % topic, 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 topic in helptable:

        names, header, doc = topic[0:3]

        # Old extensions may use a str as doc.

        if (sum(map(lowercontains, names))

            or lowercontains(header)

            or (callable(doc) and lowercontains(doc(ui)))):

            name = names[0]

            if not filtertopic(ui, name):

                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

        func = entry[0]

        docs = _(pycompat.getdoc(func)) 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, func, 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]

                func = entry[0]

                cmddoc = pycompat.getdoc(func)

                if cmddoc:

                    cmddoc = gettext(cmddoc).splitlines()[0]

                else:

                    cmddoc = _('(no help text available)')

                if filtercmd(ui, cmdname, func, 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')),

    (['cbor'], _('CBOR'),

     loaddoc('cbor', subdir='internals')),

    (['censor'], _('Censor'),

     loaddoc('censor', subdir='internals')),

    (['changegroups'], _('Changegroups'),

     loaddoc('changegroups', subdir='internals')),

    (['config'], _('Config Registrar'),

     loaddoc('config', subdir='internals')),

    (['extensions', 'extension'], _('Extension API'),

     loaddoc('extensions', subdir='internals')),

    (['requirements'], _('Repository Requirements'),

     loaddoc('requirements', subdir='internals')),

    (['revlogs'], _('Revision Logs'),

     loaddoc('revlogs', subdir='internals')),

    (['wireprotocol'], _('Wire Protocol'),

     loaddoc('wireprotocol', subdir='internals')),

    (['wireprotocolrpc'], _('Wire Protocol RPC'),

     loaddoc('wireprotocolrpc', subdir='internals')),

    (['wireprotocolv2'], _('Wire Protocol Version 2'),

     loaddoc('wireprotocolv2', 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'),

     TOPIC_CATEGORY_CONCEPTS),

    (['color'], _("Colorizing Outputs"), loaddoc('color'),

     TOPIC_CATEGORY_OUTPUT),

    (["config", "hgrc"], _("Configuration Files"), loaddoc('config'),

     TOPIC_CATEGORY_CONFIG),

    (['deprecated'], _("Deprecated Features"), loaddoc('deprecated'),

     TOPIC_CATEGORY_MISC),

    (["dates"], _("Date Formats"), loaddoc('dates'), TOPIC_CATEGORY_OUTPUT),

    (["flags"], _("Command-line flags"), loaddoc('flags'),

     TOPIC_CATEGORY_CONFIG),

    (["patterns"], _("File Name Patterns"), loaddoc('patterns'),

     TOPIC_CATEGORY_IDS),

    (['environment', 'env'], _('Environment Variables'),

     loaddoc('environment'), TOPIC_CATEGORY_CONFIG),

    (['revisions', 'revs', 'revsets', 'revset', 'multirevs', 'mrevs'],

      _('Specifying Revisions'), loaddoc('revisions'), TOPIC_CATEGORY_IDS),

    (['filesets', 'fileset'], _("Specifying File Sets"), loaddoc('filesets'),

     TOPIC_CATEGORY_IDS),

    (['diffs'], _('Diff Formats'), loaddoc('diffs'), TOPIC_CATEGORY_OUTPUT),

    (['merge-tools', 'mergetools', 'mergetool'], _('Merge Tools'),

     loaddoc('merge-tools'), TOPIC_CATEGORY_CONFIG),

    (['templating', 'templates', 'template', 'style'], _('Template Usage'),