# 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 .pycompat import getattr

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 = {

    b"(ADVANCED)",

    b"(DEPRECATED)",

    b"(EXPERIMENTAL)",

    # i18n: "(ADVANCED)" is a keyword, must be translated consistently

    _(b"(ADVANCED)"),

    # i18n: "(DEPRECATED)" is a keyword, must be translated consistently

    _(b"(DEPRECATED)"),

    # i18n: "(EXPERIMENTAL)" is a keyword, must be translated consistently

    _(b"(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: b'Repository creation',

    registrar.command.CATEGORY_REMOTE_REPO_MANAGEMENT: b'Remote repository management',

    registrar.command.CATEGORY_COMMITTING: b'Change creation',

    registrar.command.CATEGORY_CHANGE_NAVIGATION: b'Change navigation',

    registrar.command.CATEGORY_CHANGE_MANAGEMENT: b'Change manipulation',

    registrar.command.CATEGORY_CHANGE_ORGANIZATION: b'Change organization',

    registrar.command.CATEGORY_WORKING_DIRECTORY: b'Working directory management',

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

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

    registrar.command.CATEGORY_MAINTENANCE: b'Repository maintenance',

    registrar.command.CATEGORY_HELP: b'Help',

    registrar.command.CATEGORY_MISC: b'Miscellaneous commands',

    registrar.command.CATEGORY_NONE: b'Uncategorized commands',

}

# Topic categories.

TOPIC_CATEGORY_IDS = b'ids'

TOPIC_CATEGORY_OUTPUT = b'output'

TOPIC_CATEGORY_CONFIG = b'config'

TOPIC_CATEGORY_CONCEPTS = b'concepts'

TOPIC_CATEGORY_MISC = b'misc'

TOPIC_CATEGORY_NONE = b'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: b'Mercurial identifiers',

    TOPIC_CATEGORY_OUTPUT: b'Mercurial output',

    TOPIC_CATEGORY_CONFIG: b'Mercurial configuration',

    TOPIC_CATEGORY_CONCEPTS: b'Concepts',

    TOPIC_CATEGORY_MISC: b'Miscellaneous',

    TOPIC_CATEGORY_NONE: b'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(pycompat.iteritems(exts)):

            if not showdeprecated and any(w in desc for w in _exclkeywords):

                continue

            rst.append(b'%s:%s: %s\n' % (b' ' * indent, name, desc))

    if rst:

        rst.insert(0, b'\n%s\n\n' % header)

    return rst

def extshelp(ui):

    rst = loaddoc(b'extensions')(ui).splitlines(True)

    rst.extend(

        listexts(

            _(b'enabled extensions:'), extensions.enabled(), showdeprecated=True

        )

    )

    rst.extend(

        listexts(

            _(b'disabled extensions:'),

            extensions.disabled(),

            showdeprecated=ui.verbose,

        )

    )

    doc = b''.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 = _(b"VALUE")  # default label

        if not verbose and any(w in desc for w in _exclkeywords):

            continue

        so = b''

        if shortopt:

            so = b'-' + shortopt

        lo = b'--' + longopt

        if default is True:

            lo = b'--[no-]' + longopt

        if isinstance(default, fancyopts.customopt):

            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.

            defaultstr = pycompat.bytestr(default)

            if default is True:

                defaultstr = _(b"on")

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

        if isinstance(default, list):

            lo += b" %s [+]" % optlabel

            multioccur = True

        elif (default is not None) and not isinstance(default, bool):

            lo += b" %s" % optlabel

        data.append((so, lo, desc))

    if multioccur:

        header += _(b" ([+] can be repeated)")

    rst = [b'\n%s:\n\n' % header]

    rst.extend(minirst.maketable(data, 1))

    return b''.join(rst)

def indicateomitted(rst, omitted, notomitted=None):

    rst.append(b'\n\n.. container:: omitted\n\n    %s\n\n' % omitted)

    if notomitted:

        rst.append(b'\n\n.. container:: notomitted\n\n    %s\n\n' % notomitted)

def filtercmd(ui, cmd, func, kw, doc):

    if not ui.debugflag and cmd.startswith(b"debug") and kw != b"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 == b"shortlist" and not getattr(func, 'helpbasic', False):

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

        return True

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

        # Configuration explicitly hides the command.

        return True

    return False

def filtertopic(ui, topic):

    return ui.configbool(b'help', b'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 = {

        b'topics': [],

        b'commands': [],

        b'extensions': [],

        b'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[b'topics'].append((names[0], header))

    for cmd, entry in pycompat.iteritems(commands.table):

        if len(entry) == 3:

            summary = entry[2]

        else:

            summary = b''

        # translate docs *before* searching there

        func = entry[0]

        docs = _(pycompat.getdoc(func)) or b''

        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[b'commands'].append((cmdname, summary))

    for name, docs in itertools.chain(

        pycompat.iteritems(extensions.enabled(False)),

        pycompat.iteritems(extensions.disabled()),

    ):

        if not docs:

            continue

        name = name.rpartition(b'.')[-1]

        if lowercontains(name) or lowercontains(docs):

            # extension docs are already translated

            results[b'extensions'].append((name, docs.splitlines()[0]))

        try:

            mod = extensions.load(ui, name, b'')

        except ImportError:

            # debug message would be printed in extensions.load()

            continue

        for cmd, entry in pycompat.iteritems(getattr(mod, 'cmdtable', {})):

            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 = _(b'(no help text available)')

                if filtercmd(ui, cmdname, func, kw, cmddoc):

                    continue

                results[b'extensioncommands'].append((cmdname, cmddoc))

    return results

def loaddoc(topic, subdir=None):

    """Return a delayed loader for help/topic.txt."""

    def loader(ui):

        if subdir:

            docdir = os.path.join(docdir, subdir)

        path = os.path.join(docdir, topic + b".txt")

        doc = gettext(util.readfile(path))

        for rewriter in helphooks.get(topic, []):

            doc = rewriter(ui, topic, doc)

        return doc

    return loader

internalstable = sorted(

    [

        ([b'bundle2'], _(b'Bundle2'), loaddoc(b'bundle2', subdir=b'internals')),

        ([b'bundles'], _(b'Bundles'), loaddoc(b'bundles', subdir=b'internals')),

        ([b'cbor'], _(b'CBOR'), loaddoc(b'cbor', subdir=b'internals')),

        ([b'censor'], _(b'Censor'), loaddoc(b'censor', subdir=b'internals')),

        (

            [b'changegroups'],

            _(b'Changegroups'),

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

        ),

        (

            [b'config'],

            _(b'Config Registrar'),

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

        ),

        (

            [b'extensions', b'extension'],

            _(b'Extension API'),

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

        ),

        (

            [b'mergestate'],

            _(b'Mergestate'),

            loaddoc(b'mergestate', subdir=b'internals'),

        ),

        (

            [b'requirements'],

            _(b'Repository Requirements'),

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

        ),

        (

            [b'revlogs'],

            _(b'Revision Logs'),

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

        ),

        (

            [b'wireprotocol'],

            _(b'Wire Protocol'),

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

        ),

        (

            [b'wireprotocolrpc'],