# help.py - help data for mercurial

#

# Copyright 2006 Olivia Mackall <olivia@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 annotations

import itertools

import re

import textwrap

from typing import (

    Callable,

    Dict,

    Iterable,

    List,

    Optional,

    Set,

    Tuple,

    Union,

    cast,

)

from .i18n import (

    _,

    gettext,

)

from . import (

    cmdutil,

    encoding,

    error,

    extensions,

    fancyopts,

    filemerge,

    fileset,

    minirst,

    pycompat,

    registrar,

    revset,

    templatefilters,

    templatefuncs,

    templatekw,

    ui as uimod,

)

from .hgweb import webcommands

from .utils import (

    compression,

    resourceutil,

    stringutil,

)

_DocLoader = Callable[[uimod.ui], bytes]

# Old extensions may not register with a category

_HelpEntry = Union["_HelpEntryNoCategory", "_HelpEntryWithCategory"]

_HelpEntryNoCategory = Tuple[List[bytes], bytes, _DocLoader]

_HelpEntryWithCategory = Tuple[List[bytes], bytes, _DocLoader, bytes]

_SelectFn = Callable[[object], bool]

_SynonymTable = Dict[bytes, List[bytes]]

_TopicHook = Callable[[uimod.ui, bytes, bytes], bytes]

_exclkeywords: Set[bytes] = {

    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: List[bytes] = [

    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: Dict[bytes, bytes] = {

    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: List[bytes] = [

    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: Dict[bytes, bytes] = {

    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: bytes,

    exts: Dict[bytes, bytes],

    indent: int = 1,

    showdeprecated: bool = False,

) -> List[bytes]:

    '''return a text listing of the given extensions'''

    rst = []

    if exts:

        for name, desc in sorted(exts.items()):

            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 ext_help(ui: uimod.ui, ext) -> bytes:

    doc = pycompat.getdoc(ext)

    if doc is None:

        return b""

    assert doc is not None

    doc = gettext(doc)

    return sub_config_item_help(ui, doc)

def extshelp(ui: uimod.ui) -> bytes:

    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 parsedefaultmarker(text: bytes) -> Optional[Tuple[bytes, List[bytes]]]:

    """given a text 'abc (DEFAULT: def.ghi)',

    returns (b'abc', (b'def', b'ghi')). Otherwise return None"""

    if text[-1:] == b')':

        marker = b' (DEFAULT: '

        pos = text.find(marker)

        if pos >= 0:

            item = text[pos + len(marker) : -1]

            return text[:pos], item.split(b'.', 2)

def optrst(header: bytes, options, verbose: bool, ui: uimod.ui) -> bytes:

    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

        defaultstrsuffix = b''

        if default is None:

            parseresult = parsedefaultmarker(desc)

            if parseresult is not None:

                (desc, (section, name)) = parseresult

                if ui.configbool(section, name):

                    default = True

                    defaultstrsuffix = _(b' from config')

        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 + defaultstrsuffix)

        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: List[bytes], omitted: bytes, notomitted: Optional[bytes] = None

) -> 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: uimod.ui, cmd: bytes, func, kw: bytes, doc: bytes) -> bool:

    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: uimod.ui, topic: bytes) -> bool:

    return ui.configbool(b'help', b'hidden-topic.%s' % topic, False)

def topicmatch(

    ui: uimod.ui, commands, kw: bytes

) -> Dict[bytes, List[Tuple[bytes, bytes]]]:

    """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 commands.table.items():

        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):

            if docs:

                summary = stringutil.firstline(docs)

            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(

        extensions.enabled(False).items(),

        extensions.disabled().items(),

    ):

        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, stringutil.firstline(docs)))

        try:

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

        except ImportError:

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

            continue

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

            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 = stringutil.firstline(gettext(cmddoc))

                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: bytes, subdir: Optional[bytes] = None) -> _DocLoader:

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

    def loader(ui: uimod.ui) -> bytes:

        package = b'mercurial.helptext'

        if subdir:

            package += b'.' + subdir

        with resourceutil.open_resource(package, topic + b'.txt') as fp:

            doc = gettext(fp.read())

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

            doc = rewriter(ui, topic, doc)

        doc = sub_config_item_help(ui, doc)

        return doc

    return loader

internalstable: List[_HelpEntryNoCategory] = sorted(

    [

        (

            [b'bid-merge'],

            _(b'Bid Merge Algorithm'),

            loaddoc(b'bid-merge', subdir=b'internals'),

        ),

        ([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'dirstate-v2'],

            _(b'dirstate-v2 file format'),

            loaddoc(b'dirstate-v2', 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'],

            _(b'Wire Protocol RPC'),

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

        ),

        (

            [b'wireprotocolv2'],

            _(b'Wire Protocol Version 2'),

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

        ),

    ]

)

def internalshelp(ui: uimod.ui) -> bytes:

    """Generate the index for the "internals" topic."""

    lines = [

        b'To access a subtopic, use "hg help internals.{subtopic-name}"\n',

        b'\n',

    ]

    for names, header, doc in internalstable:

        lines.append(b' :%s: %s\n' % (names[0], header))

    return b''.join(lines)

helptable: List[_HelpEntryWithCategory] = sorted(

    [

        (

            [b'bundlespec'],

            _(b"Bundle File Formats"),

            loaddoc(b'bundlespec'),

            TOPIC_CATEGORY_CONCEPTS,

        ),

        (

            [b'color'],

            _(b"Colorizing Outputs"),

            loaddoc(b'color'),

            TOPIC_CATEGORY_OUTPUT,

        ),

        (

            [b"config", b"hgrc"],

            _(b"Configuration Files"),

            loaddoc(b'config'),

            TOPIC_CATEGORY_CONFIG,

        ),