hop.txt

*hop.txt*    For Neovim version 0.9                  Last change: 2023 Sep 11

                                 __
                                / /_  ____  ____
                               / __ \/ __ \/ __ \
                              / / / / /_/ / /_/ /
                             /_/ /_/\____/ .___/
                                        /_/
                         · Neovim motions on speed! ·
                                     v2.3.0

==============================================================================
CONTENTS                                                          *hop-contents*

  Introduction ·············································· |hop-introduction|
  Requirements ·············································· |hop-requirements|
  Usage ···························································· |hop-usage|
    Commands ···················································· |hop-commands|
    Lua API ······················································ |hop-lua-api|
    Jump target API ······································ |hop-jump-target-api|
  Configuration ··················································· |hop-config|
  Extension ···················································· |hop-extension|
  Highlights ·················································· |hop-highlights|
  License ························································ |hop-license|

==============================================================================
INTRODUCTION                                              *hop* *hop-introduction*

Hop is an “EasyMotion” like plugin allowing you to jump anywhere in a document
with as few keystrokes as possible. It does so by annotating text in your
buffer with |hints|, short string sequences for which each character represents
a key to type to jump to the annotated text. Most of the time, those
sequences’ lengths will be between 1 to 3 characters, making every jump target
in your document reachable in a few keystrokes.

Hop is a complete from-scratch rewrite of EasyMotion, a famous plugin to
enhance the native motions of Vim. Even though EasyMotion is usable in
Neovim, it suffers from a few drawbacks making it not comfortable to use with
Neovim version >0.5 – at least at the time of writing these lines:

- EasyMotion uses an old trick to annotate jump targets by saving the
  contents of the buffer, replacing it with the highlighted annotations and
  then restoring the initial buffer after jump. This trick is dangerous as it
  will change the contents of your buffer. A UI plugin should never do anything
  to existing buffers’ contents.
- Because the contents of buffers will temporarily change, other parts of the
  editor and/or plugins relying on buffer change events will react and will go
  mad. An example is the internal LSP client implementation of Neovim >0.5 or
  its treesitter native implementation. For LSP, it means that the connected
  LSP server will receive a buffer with the jump target annotations… not
  ideal.

==============================================================================
REQUIREMENTS                                                  *hop-requirements*

Hop works only with Neovim and was written with Neovim-0.9.

Especially, hop uses |api-extended-marks|, which are not available before
Neovim-0.5.

==============================================================================
USAGE                                                                *hop-usage*

Before doing anything else, you have to setup the plugin. If you are not using
a package manager or environment doing that automatically for you, you need to
call the |hop.setup| function to correctly initialize the plugin.

For a minimal setup:

    For people using init.lua~
        In your `init.lua`, add:
>
            require'hop'.setup()
<
    For people using init.vim~
        In your `init.vim`, add:
>
            lua << EOF
            require'hop'.setup()
            EOF
<
You can pass an optional argument to `setup(opts)` in order to pass {opts}.
Have a look at |hop.setup| for further details.

                                                                    *hop-health*
Healthcheck~

Hop has support for |:checkhealth|. If you find yourself in a situation where
something looks odd or incorrect, do not forget to run this command before
opening an issue.

                                                                  *hop-commands*
Commands~

You can try those commands by typing them in your command line. By default,
they will use the default options for the configuration of Hop. If you want to
customize how those commands work, have a look at |hop.setup|. Also, something
pretty important to know is that those are Vim commands. Hop tries to expose
as many features as possible via the Vim commands but ultimately, you will
have access to more features by using the Lua API directly. Have a look at
|hop-lua-api| for more documentation.

Some of the commands have a suffix, such as `BC`, `AC` and `MW`. Those are
variations of the commands without the suffix, applying to the visible part of
the buffer before and after the cursor, and multiple windows, respectively.
Another kind of suffix (that can be mixed with `BC` and `AC`) is `CurrentLine`. This
creates a variant of the command that will only run for the current line.

`:HopWord`                                                              *:HopWord*
`:HopWordBC`                                                          *:HopWordBC*
`:HopWordAC`                                                          *:HopWordAC*
`:HopWordCurrentLine`                                        *:HopWordCurrentLine*
`:HopWordCurrentLineBC`                                    *:HopWordCurrentLineBC*
`:HopWordCurrentLineAC`                                    *:HopWordCurrentLineAC*
`:HopWordMW`                                                          *:HopWordMW*
    Hint all |word|s with key sequences. Typing a first key will visually
    filter the sequences and reduce them. Continue typing key sequences until
    you reduce a sequence completely, which will bring your cursor at that
    position.

    This is akin to calling the |hop.hint_words| Lua function.

`:HopPattern`                                                        *:HopPattern*
`:HopPatternBC`                                                    *:HopPatternBC*
`:HopPatternAC`                                                    *:HopPatternAC*
`:HopPatternCurrentLine`                                  *:HopPatternCurrentLine*
`:HopPatternCurrentLineBC`                              *:HopPatternCurrentLineBC*
`:HopPatternCurrentLineAC`                              *:HopPatternCurrentLineAC*
`:HopPatternMW`                                                    *:HopPatternMW*
    Ask the user for a pattern and hint the document with it.

    This is akin to calling the |hop.hint_patterns| Lua function
    with no explicit pattern.

`:HopChar1`                                                            *:HopChar1*
`:HopChar1BC`                                                        *:HopChar1BC*
`:HopChar1AC`                                                        *:HopChar1AC*
`:HopChar1CurrentLine`                                      *:HopChar1CurrentLine*
`:HopChar1CurrentLineBC`                                  *:HopChar1CurrentLineBC*
`:HopChar1CurrentLineAC`                                  *:HopChar1CurrentLineAC*
`:HopChar1MW`                                                        *:HopChar1MW*
    Type a key and immediately hint the document for this key.

    This is akin to calling the |hop.hint_char1| Lua Function

`:HopChar2`                                                            *:HopChar2*
`:HopChar2BC`                                                        *:HopChar2BC*
`:HopChar2AC`                                                        *:HopChar2AC*
`:HopChar2CurrentLine`                                      *:HopChar2CurrentLine*
`:HopChar2CurrentLineBC`                                  *:HopChar2CurrentLineBC*
`:HopChar2CurrentLineAC`                                  *:HopChar2CurrentLineAC*
`:HopChar2MW`                                                        *:HopChar2MW*
    Type two keys and immediately hint the document for this bigram.

    This is akin to calling the |hop.hint_char2| Lua Function

`:HopLine`                                                              *:HopLine*
`:HopLineBC`                                                          *:HopLineBC*
`:HopLineAC`                                                          *:HopLineAC*
`:HopLineCurrentLine`                                        *:HopLineCurrentLine*
`:HopLineCurrentLineBC`                                    *:HopLineCurrentLineBC*
`:HopLineCurrentLineAC`                                    *:HopLineCurrentLineAC*
`:HopLineMW`                                                          *:HopLineMW*
    Jump to the beginning of the line of your choice inside your buffer.

    This is akin to calling the |hop.hint_lines| Lua function.

`:HopLineStart`                                                    *:HopLineStart*
`:HopLineStartBC`                                                *:HopLineStartBC*
`:HopLineStartAC`                                                *:HopLineStartAC*
`:HopLineStartCurrentLine`                              *:HopLineStartCurrentLine*
`:HopLineStartCurrentLineBC`                          *:HopLineStartCurrentLineBC*
`:HopLineStartCurrentLineAC`                          *:HopLineStartCurrentLineAC*
`:HopLineStartMW`                                                *:HopLineStartMW*
    Like `HopLine` but skips leading whitespace on every line. Blank lines are
    skipped over.

    This is akin to calling the |hop.hint_lines_skip_whitespace| Lua function.

`:HopVertical`                                                      *:HopVertical*
`:HopVerticalBC`                                                  *:HopVerticalBC*
`:HopVerticalAC`                                                  *:HopVerticalAC*
`:HopVerticalMW`                                                  *:HopVerticalMW*
    Like `HopLine` but keeps the column position of the cursor.

    This is akin to calling the |hop.hint_vertical| Lua function.

`:HopAnywhere`                                                      *:HopAnywhere*
`:HopAnywhereBC`                                                  *:HopAnywhereBC*
`:HopAnywhereAC`                                                  *:HopAnywhereAC*
`:HopAnywhereCurrentLine`                                *:HopAnywhereCurrentLine*
`:HopAnywhereCurrentLineBC`                            *:HopAnywhereCurrentLineBC*
`:HopAnywhereCurrentLineAC`                            *:HopAnywhereCurrentLineAC*
`:HopAnywhereMW`                                                  *:HopAnywhereMW*
    Hint anywhere with key sequences.

    This is akin to calling the |hop.hint_anywhere| Lua function.

`:HopPasteChar1`                                                  *:HopPasteChar1*
`:HopPasteChar1BC`                                              *:HopPasteChar1BC*
`:HopPasteChar1AC`                                              *:HopPasteChar1AC*
`:HopPasteChar1CurrentLine`                            *:HopPasteChar1CurrentLine*
`:HopPasteChar1CurrentLineBC`                        *:HopPasteChar1CurrentLineBC*
`:HopPasteChar1CurrentLineAC`                        *:HopPasteChar1CurrentLineAC*

    Pastes the `defaults.yank_register` register contents by hinting the document
    like `hop.hop_char1` without jumping to the target.

    You can configure the position of the paste relative to the jump target by
    using the `hint_offset` option.

    This is akin to calling the |hop.paste_char1| Lua Function
`:HopYankChar1`                                                     *:HopYankChar1*
`:HopYankChar1BC`                                                 *:HopYankChar1BC*
`:HopYankChar1AC`                                                 *:HopYankChar1AC*
`:HopYankChar1CurrentLine`                               *:HopYankChar1CurrentLine*
`:HopYankChar1CurrentLineBC`                           *:HopYankChar1CurrentLineBC*
`:HopYankChar1CurrentLineAC`                           *:HopYankChar1CurrentLineAC*

    Yanks a range to `defaults.yank_register` register by hinting document like
    `hop.hop_char1` without jumping to bounds.
    range is (inclusive,inclusive).

    This is akin to calling the |hop.yank_char1| Lua Function

`:HopNodes`                                                             *:HopNodes*

    Hint all Treesitter nodes surranding the node on the cursor position.
    
    This is akin to calling the |hop.hint_nodes| Lua Function
                                                                   *hop-lua-api*
Lua API~

The Lua API comprises several modules. Even though those modules might have
more public functions than described here, you are only supposed to use the
functions in this help page. Using one that is not listed here is considered
unstable.

`hop`             Entry point and main interface. If you just want to use
                Hop from within Lua via keybindings, you shouldn’t need to
                read any other modules.
`hop.defaults`    Default options.
`hop.hint`        Various functions to create, update and reduce hints.
`hop.highlight`   Highlight functions (creation / autocommands / etc.).
`hop.jump_target` Core module used to create jump targets.
`hop.perm`        Permutation functions. Permutations are used as labels for
                the hints.
`hop.yank`        Yank and paste functions
`hop.treesitter`  Parse buffer language tree

Main API~

Most of the functions and values you need to know about are in `hop`.

`hop.setup(`{opts}`)`                                                    *hop.setup*
    Setup the library with options.

    This function will setup the Lua API and commands in a way that respects
    the options you pass. It is mandatory to call that function at some time
    if you want to be able to use Hop.

    Note:
	Some plugins will automatically call the `setup` public function of a
	plugin if declared, which is the case with Hop. With such plugins, you
	shouldn’t have to care too much about `setup` but focus more on the
	{opts} you can pass it.

    Arguments:~
        {opts}  List of options. See the |hop-config| section.

`hop.hint_with(`{jump_target_gtr}`,` {opts}`)`                         *hop.hint_with*
    Main entry-point of Hop, this function expects a jump target generator and
    will call it with {opts} to get a list of jump targets. This function will
    take care of reducing the hints for you automatically and will perform the
    actual jumps.

    If you would like to use a more general version to implement different
    kind of actions instead of jumping, have a look at
    |hop.hint_with_callback|.

    Arguments:~
        {jump_target_gtr} Jump target generator. See |hop-jump-target-api| for
                          further information.
        {opts}            User options.

`hop.hint_with_callback(`                                 *hop.hint_with_callback*
  {jump_target_gtr}`,`
  {opts}`,`
  {callback}
`)`
    Main entry-point of Hop, this function expects a jump target generator and
    will call it with {opts} to get a list of jump targets. This function will
    take care of reducing the hints for you automatically. Once a jump target
    is reduced completely, this function will call the {callback} with the
    selected jump target.

    Arguments:~
        {jump_target_gtr} Jump target generator. See |hop-jump-target-api| for
                          further information.
        {opts}            User options.


`hop.hint_words(`{opts}`)`                                          *hop.hint_words*
    Annotate all words in the current window with key sequences. Typing a
    first key will visually filter the sequences and reduce them. Continue
    typing key sequences until you reduce a sequence completely, which will
    bring your cursor at that position. See |hop-config| for a complete list
    of the options you can pass as arguments.

    Arguments:~
        {opts}  Hop options.

`hop.hint_patterns(`{opts}`,` {pattern}`)`                         *hop.hint_patterns*
    Annotate all matched patterns in the current window with key sequences.

    Arguments:~
        {opts}     Hop options.
        {pattern}  (optional) The pattern to search for.
                   If not set, the user is prompted for the pattern to search.

`hop.hint_char1(`{opts}`)`                                          *hop.hint_char1*
    Let the user type a key and immediately hint all of its occurrences.

    Arguments:~
        {opts}  Hop options.

`hop.hint_char2(`{opts}`)`                                          *hop.hint_char2*
    Let the user type a bigram (two concatenated keys) and immediately hint
    all of its occurrences.

    This function can behave like |hop.hint_char1| in some cases. See
    |hop-config-char2_fallback_key|.

    Arguments:~
        {opts}  Hop options.

`hop.hint_lines(`{opts}`)`                                          *hop.hint_lines*
    Hint the beginning of each lines currently visible in the buffer view and
    allow to jump to them.

    This works with empty lines as well.

    Arguments:~
        {opts}  Hop options.

`hop.hint_lines_skip_whitespace(`{opts}`)`          *hop.hint_lines_skip_whitespace*
    Hint the first non-whitespace character of each lines currently visible in
    the buffer view and allow to jump to them.

    This works with empty lines as well.

    Arguments:~
        {opts}  Hop options.

`hop.hint_vertical(`{opts}`)`                                    *hop.hint_vertical*
    Hint the cursor position of each lines currently visible in the buffer
    view and allow to jump to them. If the line is shorter than the current
    cursor column position, it will default to the end of the line.

    This works with empty lines as well.

    Arguments:~
        {opts}  Hop options.

`hop.hint_anywhere(`{opts}`)`                                   *hop.hint_anywhere*
    Annotate anywhere in the current window with key sequences.

    Arguments:~
        {opts}  Hop options.

`hop.hint_nodes(`{opts}`)`                                         *hop.hint_nodes*
    Hint all Treesitter nodes surranding the node on the cursor position.

    Arguments:~
        {opts}  Hop options.

Hint API~

The hint API provide the `HintDirection` and `HintPosition`

`hop.hint.HintDirection`                                  *hop.hint.HintDirection*
    Enumeration for hinting direction.

    Use this table as a value for |hop-config-direction|. Setting it to {nil}
    makes the command / function act on the whole visible part of the buffer.

    Enumeration variants:~
        {BEFORE_CURSOR} Create and apply hints before the cursor.
        {AFTER_CURSOR}  Create and apply hints after the cursor.

`hop.hint.HintPosition`                                    *hop.hint.HintPosition*
    Enumeration for hinting position in match.

    Use this table as a value for |hop-config-hint_posititon|.

    Enumeration variants:~
        {BEGIN}  Create and apply hints at the beginning of the match.
        {MIDDLE} Create and apply hints at the middle of the match.
        {END}    Create and apply hints at the end of the match.

                                                           *hop-jump-target-api*
Jump target API~

The jump target API is probably the most core API of all. It provides some
helper functions to help you extend Hop by providing your own jump targets.
Most importantly, you will want to read this documentation section to know
exactly which kind of format Hop expects for the jump targets when
implementing your own.

Jump targets are locations in buffers where users might jump to. They are
wrapped in a table and provide the required information so that Hop can
associate labels and display the hints. Such a table must have the following
form:
>
    {
      jump_targets = {},
      indirect_jump_targets = {},
    }
>
The `jump_targets` field is a list-table of jump targets. A single jump target
is simply a location in a given window. Actually, the location will be set on
the buffer that is being displayed by that window. So you can picture a jump
target as a triple (line, column, window).
>
    {
      line = 0,
      column = 0,
      window = 0,
    }
<
`indirect_jump_targets` is an optional yet highly recommended table. They
provide an indirect access to `jump_targets` to re-order them. They are for
instance used to be able to distribute hints according to their distance to
the current location of the cursor. Not providing that table (`nil`) will
result in the jump targets being considered fully ordered and will be assigned
sequences based on their index in `jump_targets`.

Indirect jump targets are encoded as a flat list-table of pairs
(index, score). This table allows to quickly score and sort jump targets.
>
    {
      index = 0,
      score = 0,
    }
<
The `index` field gives the index in the `jump_targets` list. The `score` is any
number. The rule is that the lower the score is, the less prioritized the
jump target will be.

So for instance, for two jump targets, a jump target generator must return
such a table:
>
    {
      jump_targets = {
        { line = 1, column = 14, window = 0 },
        { line = 2, column = 1, window = 0 },
      },

      indirect_jump_targets = {
        { index = 0, score = 14 },
        { index = 1, score = 7 },
      },
    }
<

If you don’t need to change the score, or if the scores are always ascending
with the indices ascending, you can completely omit the
`indirect_jump_targets` table:
>
    {
      jump_targets = {
        { line = 1, column = 14, window = 0 },
        { line = 2, column = 1, window = 0 },
      },
    }
<
This module provides several functions, named `jump_targets_*`, which are
called jump target generators. Such functions are to be passed to
|hop.hint_with| or |hop.hint_with_callback|. Most of the Vim commands are already
doing that for you.

`hop.jump_target.jump_targets_by_scanning_line(` *hop.jump_target.jump_targets_by_scanning_line*
  {regex}
`)`
    Jump target generator that scans lines of the currently visible buffer and
    create the jump targets by using the input {regex}.

    Arguments:~
        {regex} Regex-like table to apply to each line. See the various
                `hop.jump_target.regex*` functions below for a list of available
                options.

                If you want to create your own regex-like table, you need to
                provide a table with two fields: `oneshot`, a boolean value,
                that is to be set to `true` if the regex should be applied
                only once to each line, and `match`, which is the actual
                matcher that returns the beginning / end
                (inclusive / exclusive) byte indices of the match. You are
                advised to use |vim.regex|.

`hop.jump_target.jump_targets_for_current_line(` *hop.jump_target.jump_targets_for_current_line*
  {regex}
`)`
    Jump target generator that applies {regex} only to the current line of the
    currently active window.

    Arguments:~
        {regex} Regex-like table to apply to each line. See the various
                `hop.jump_target.regex*` functions below for a list of available
                options.

                If you want to create your own regex-like table, you need to
                provide a table with two fields: `oneshot`, a boolean value,
                that is to be set to `true` if the regex should be applied to
                each line only once, and `match`, which is the actual matcher
                that returns the beginning / end (inclusive / exclusive) byte
                indices of the match. You are advised to use |vim.regex|.


`hop.jump_target.sort_indirect_jump_targets(` *hop.jump_target.sort_indirect_jump_targets*
  {indirect_jump_targets}`,`
  {opts}
`)`
    Sort {indirect_jump_targets} according to their scores.

    Arguments:~
        {indirect_jump_targets} Indirect jump targets to sort.
        {opts}                  User options.

`hop.jump_target.regex_by_searching(`         *hop.jump_target.regex_by_searching*
  {pat}`,`
  {plain_search}
`)`
    Buffer-line based |pattern| hint mode. This mode will highlight the
    beginnings of a pattern you will be prompted for in the document and
    will make the cursor jump to the one fully reduced.

    Arguments:~
        {pat}          Pattern to search.
        {plain_search} Should the pattern by plain-text.

`hop.jump_target.regex_by_case_searching(` *hop.jump_target.regex_by_case_searching*
  {pat}`,`
  {plain_search}`,`
  {opts}
`)`
    Similar to |hop.jump_target.regex_by_searching|, but respects the user case
    sensitivity set by 'smartcase' and |hop-config-case_insensitive|.

    Arguments:~
        {pat}          Pattern to search.
        {plain_search} Should the pattern by plain-text.
        {opts}         User options.

`hop.jump_target.regex_by_word_start()`      *hop.jump_target.regex_by_word_start*
    Buffer-line based |word| hint mode. This mode will highlight the beginnings
    of all the words in the window and will make the cursor jump to the one
    fully reduced.

`hop.jump_target.by_line_start()`                  *hop.jump_target.by_line_start*
    Highlight the beginning of each line in the current window.

`hop.jump_target.regex_by_line_start_skip_whitespace()` *hop.jump_target.regex_by_line_start_skip_whitespace*
    Highlight the non-whitespace character of each line in the current window.

`hop.jump_target.regex_by_anywhere()`          *hop.jump_target.regex_by_anywhere*
    Highlight the anywhere in the current window.

`hop.jump_target.manh_dist(`                           *hop.jump_target.manh_dist*
  {a}`,`
  {b}`,`
  {x_bias}
`)`
    Manhattan distance between two buffer positions. Both {a} and {b} must be
    tables containing two values: the first one for the line and the second one
    for the column.

    {x_bias} is to be used to skew the Manhattan distance in terms of lines.

    Arguments:~
        {a}      First position.
        {b}      Second position.
        {x_bias} Optional bias applied to the line distance. Defaults to 10.

Highlight API~

The highlight API gives two functions to manipulate the highlights Hop uses:

`hop.highlight.insert_highlights()`              *hop.highlight.insert_highlights*
    Manually insert the highlights by calling the `highlight default` command.
    See |hop-highlights| for further details about the list of highlights
    currently available.

`hop.highlight.create_autocmd`                      *hop.highlight.create_autocmd*
    Register autocommands for the `ColorScheme` event, calling
    |hop.highlight.insert_highlights|. This is called when you require Hop and
    you shouldn’t need to call this function by yourself.

Permutation API~

The permutation API is the core part of the algorithm used in Hop.
Permutations in Hop are made out of a source sequence of characters, called
a key set and represented with {keys}. A good choice of key set is important
to yield short and concise permutations, allowing to jump to targets with
fewer keystrokes.

`hop.perm.permutations(`{keys}`,` {n}`,` {opts}`)`               *hop.perm.permutations*
    Get the first {n} permutations out of {keys}.

    Arguments:~
        {keys}  Input key set to use to create permutations.
        {n}     Number of permutations to generate.
        {opts}  Hop options.

    Return:~
        The {n} first permutations for the given {keys} and
        |hop-config-perm_method| set in {opts}.

==============================================================================
CONFIGURATION                                                       *hop-config*

The configuration can be provided in two different ways:

- Either by explicitly passing an {opts} table to the various Lua
  functions.
- Or by passing an {opts} table to the Lua |hop.setup| function.

Not providing any of the two above will use the default values, as described
below.

`keys`                                                           *hop-config-keys*
    A string representing all the keys that can be part of a permutation.
    Every character (key) used in the string will be used as part of a
    permutation. The shortest permutation is a permutation of a single
    character, and, depending on the content of your buffer, you might end up
    with 3-character (or more) permutations in worst situations.

    However, it is important to notice that if you decide to provide `keys`,
    you have to ensure to use enough characters in the string, otherwise you
    might get very long sequences and a not so pleasant experience.

    Defaults:~
        `keys = 'asdghklqwertyuiopzxcvbnmfj'`

`quit_key`                                                   *hop-config-quit_key*
    A string representing a key that will quit Hop mode without also feeding
    that key into Neovim to be treated as a normal key press.

    It is possible to quit hopping by pressing any key that is not present in
    |hop-config-keys|; however, when you do this, the key normal function is
    also performed. For example if, hopping in |visual-mode|, pressing <Esc>
    will quit hopping and also exit |visual-mode|.

    If the user presses `quit_key`, Hop will be quit without the key normal
    function being performed. For example if hopping in |visual-mode| with
    `quit_key` set to '<Esc>', pressing <Esc> will quit hopping without
    quitting |visual-mode|.

    If you don't want to use a `quit_key`, set `quit_key` to an empty string.

    Note:~
        `quit_key` should only contain a single key or be an empty string.

    Note:~
        `quit_key` should not contain a key that is also present in
        |hop-config-keys|.

    Defaults:~
        `quit_key = '<Esc>'`

`perm_method`                                             *hop-config-perm_method*
    Permutation method to use.

    Permutation methods allow to change the way permutations (i.e. hints
    sequence labels) are generated internally. There is currently only
    one possible option:

        `TrieBacktrackFilling`
            Permutation algorithm based on tries and backtrack filling.

            This algorithm uses the full potential of |hop-config-keys| by
            using them all to saturate a trie, representing all the
            permutations. Once a layer is saturated, this algorithm will
            backtrack (from the end of the trie, deepest first) and create a
            new layer in the trie, ensuring that the first permutations will
            be shorter than the last ones.

            Because of the last, deepest trie insertion mechanism and trie
            saturation, this algorithm yields a much better distribution
            accross your buffer, and you should get 1-sequences and
            2-sequences most of the time. Each dimension grows
            exponentially, so you get `keys_length²` 2-sequence keys,
            `keys_length³` 3-sequence keys, etc in the worst cases.

    Default value~
        `perm_method = require'hop.perm'.TrieBacktrackFilling`

`reverse_distribution`                           *hop-config-reverse_distribution*
    The default behavior for key sequence distribution in your buffer is to
    concentrate shorter sequences near the cursor, grouping 1-character
    sequences around. As hints get further from the cursor, the dimension of
    the sequences will grow, making the furthest sequences the longest ones
    to type.

    Set this option to `true` to reverse the density and concentrate the
    shortest sequences (1-character) around the furthest words and the longest
    sequences around the cursor.

    Defaults:~
        `reverse_distribution = false`

`x_bias`                                                     *hop-config-x_bias*
    This Determines which hints get shorter key sequences. The default value
    has a more balanced distribution around the cursor but increasing it
    means that hints which are closer vertically will have a shorter key
    sequences.
    For instance, when `x_bias` is set to 100, hints located at the end of the
    line will have shorter key sequence compared to hints in the lines above
    or below.
    
    Defaults:~
        `x_bias = 10`

`teasing`                                                     *hop-config-teasing*
    Boolean value stating whether Hop should tease you when you do something
    you are not supposed to.

    If you find this setting annoying, feel free to turn it to `false`.

    Defaults:~
        `teasing = true`

`jump_on_sole_occurrence`                     *hop-config-jump_on_sole_occurrence*
    Immediately jump without displaying hints if only one occurrence exists.

    Defaults:~
        `jump_on_sole_occurrence = true`

`ignore_injections`                            *hop-config-ignore_injections*
   Ignore injected languages when jumping to treesitter node.

    Defaults:~
        `ignore_injections = false`

`case_insensitive`                                   *hop-config-case_insensitive*
    Use case-insensitive matching by default for commands requiring user
    input.

    Defaults:~
        `case_insensitive = true`

`create_hl_autocmd`                                 *hop-config-create_hl_autocmd*
    Create and set highlight autocommands to automatically apply highlights.
    You will want this if you use a theme that clears all highlights before
    applying its colorscheme.

    Defaults:~
        `create_hl_autocmd = true`

`dim_unmatched`                                       *hop-config-dim_unmatched*
    Whether or not dim the unmatched text to emphasize the hint chars.

    Defaults:~
        `dim_unmatched = true`

`direction`                                                 *hop-config-direction*
    Direction in which to hint. See |hop.hint.HintDirection| for further
    details.

    Setting this in the user configuration will make all commands default to
    that direction, unless overriden.

    Defaults:~
        `direction = nil`

`hint_position`                                         *hop-config-hint_position*
    Position of hint in match. See |hop.hint.HintPosition| for further
    details.

    Defaults:~
        `hint_position = require'hop.hint'.HintPosition.BEGIN`

`hint_type`                                         *hop-config-hint_type*
    How to show the hint char.
    Possible values:
         "overlay": display over the specified column, without
                      shifting the underlying text.
         "inline": display at the specified column, and shift the
                      buffer text to the right as needed.

    Defaults:~
        `hint_type = require'hop.hint'.HintType.OVERLAY`

`hint_offset`                                             *hop-config-hint_offset*
    Offset to apply to a jump location.

    If it is non-zero, the jump target will be offset horizontally from the
    selected jump position by `hint_offset` character(s).

    This option can be used for emulating the motion commands |t| and |T| where
    the cursor is positioned on/before the target position.

    Defaults:~
        `hint_offset = 0`

`current_line_only`                                 *hop-config-current_line_only*
    Apply Hop commands only to the current line.

    Note:
        Trying to use this option along with |hop-config-multi_windows| is
        unsound.

    Defaults:~
        `current_line_only = false`

`uppercase_labels`                                   *hop-config-uppercase_labels*
    Display labels as uppercase. This option only affects the displayed
    labels; you still select them by typing the keys on your keyboard.

    Defaults:~
        `uppercase_labels = false`

`yank_register`                                   *hop-config-yank_register*
    Determines which one of the `registers` stores the yanked text.
    Defaults:~
        `yank_register = ''`

`extensions`                                               *hop-config-extensions*
    List-table of extensions to enable (names). As described in |hop-extension|,
    extensions for which the name in that list must have a `register(opts)`
    function in their public API for Hop to correctly initialized them.

    Defaults:~
        `extensions = nil`

`multi_windows`                                         *hop-config-multi_windows*
    Enable cross-windows support and hint all the currently visible windows.
    This behavior allows you to jump around any position in any buffer
    currently visible in a window. Although a powerful a feature, remember
    that enabling this will also generate many more sequence combinations, so
    you could get deeper sequences to type (most of the time it should be good
    if you have enough keys in |hop-config-keys|).

    Defaults:~
        `multi_windows = false`

`excluded_filetypes`
    Skip hinting windows with the excluded filetypes. Those windows to check
    filetypes are collected only when you enable `multi_windows` or execute
    `MW`-commands. This option is useful to skip the windows which are only
    for displaying something but not for editing.

    Defaults:~
        `excluded_filetypes = { }`

`match_mappings`
    This option allows you to specify the match mappings to use when applying
    the hint. If you set a non-empty `match_mappings`, the hint will be used as
    a key to look up the pattern to search for.

    Currently supported mappings:~
        'fa' : farsi characters
        'zh' : Basic characters for Chinese
        'zh_sc' : Simplified Chinese
        'zh_tc' : Traditional Chinese

    For example, if `match_mappings` is set to `{'zh', 'zh_sc'}`, the characters
    in 'zh' and 'zh_sc' can be mixed to match together.

    Defaults:~
        `match_mappings = { }`

==============================================================================
EXTENSION                                                        *hop-extension*

Hop supports extensions, that can provide ad hoc jump targets that are not
part of the core of Hop. If you want to write a Hop extension, this section
should provide all the required informations.

The first important part is to know how to generate jump targets. You will
then first want to read the |hop-jump-target-api|, that describes this process
in terms of Lua protocol.

The second part is that because you will depend on the Hop API, you need to be
sure that Hop is completely setup before initiating your Hop extension plugin.
In order to do so, your users will have to read the user guide of the package
manager they are using to mark Hop as a dependency of your plugin when
installing. You should ensure such instructions are easily accessible to them,
for instance in your help pages and README.

Finally, Hop extension plugins do not get initialized via the regular `setup`
function — well, it’s up to you to still provide that function, but keep in
mind that Hop should not be assumed ready if you do so, so really keep setting
up things unrelated to Hop in your `setup` function. In order to setup a Hop
extension plugin, your plugin must provide the `register(opts)` function, that
takes the same {opts} arguments as `setup(opts)`. This function will be called
by Hop automatically.

Once a user has installed both Hop and the extension plugin, they can simply
modify the configuration of Hop and pass the name of your plugin in the
`extensions` user configuration. See |hop-config-extensions| for further
details about that.

==============================================================================
HIGHLIGHTS                                                      *hop-highlights*

Anywhere in the hint buffer that doesn’t contain a hint, the |hl-EndOfBuffer|
highlight is used. For the rest:

`HopNextKey`                                                   *hop-hl-HopNextkey*
    Highlight used for the mono-sequence keys (i.e. sequence of 1).

`HopNextKey1`                                                 *hop-hl-HopNextKey1*
    Highlight used for the first key in a sequence.

`HopNextKey2`                                                 *hop-hl-HopNextKey2*
    Highlight used for the second and remaining keys in a sequence.

`HopUnmatched`                                               *hop-hl-HopUnmatched*
    Highlight used for unmatched part of the buffer when running a Hop command
    / Lua functions.

`HopCursor`                                                     *hop-hl-HopCursor*
    Highlight used for the fake cursor visible when running a Hop command /
    Lua functions.

`HopPreview`                                                   *hop-hl-HopPreview*
    Highlight used for to preview the hint for HopPattern.

Highlights are inserted in an augroup, `HopInitHighlight`, and an autocommand
is automatically set when initializing the plugin, unless you set
|hop-config-create_hl_autocmd| to `false`.

==============================================================================
LICENSE                                                            *hop-license*

Copyright (c) 2021-2022, Dimitri Sabadie <dimitri.sabadie@gmail.com>

All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

    * Redistributions of source code must retain the above copyright
      notice, this list of conditions and the following disclaimer.

    * Redistributions in binary form must reproduce the above
      copyright notice, this list of conditions and the following
      disclaimer in the documentation and/or other materials provided
      with the distribution.

    * Neither the name of Dimitri Sabadie <dimitri.sabadie@gmail.com> nor the
      names of other contributors may be used to endorse or promote products
      derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

==============================================================================
vim:tw=78:sw=4:ts=8:ft=help:norl: