================================================================================
                                                                *telescope.nvim*

Telescope.nvim is a plugin for fuzzy finding and neovim. It helps you search,
filter, find and pick things in Lua.

To find out more:
https://github.com/nvim-telescope/telescope.nvim

  :h telescope.setup
  :h telescope.builtin
  :h telescope.layout
  :h telescope.actions

telescope.setup({opts})                                    *telescope.setup()*
    Setup function to be run by user. Configures the defaults, extensions and
    other aspects of telescope.


    Valid keys for {opts.defaults}

                                          *telescope.defaults.entry_prefix*
    entry_prefix: ~
        Prefix in front of each result entry. Current selection not included.

        Default: '  '

                                         *telescope.defaults.prompt_prefix*
    prompt_prefix: ~
        Will be shown in front of the prompt.

        Default: '> '

                                       *telescope.defaults.scroll_strategy*
    scroll_strategy: ~
        Determines what happens you try to scroll past view of the picker.

        Available options are:
        - "cycle" (default)
        - "limit"

                                       *telescope.defaults.selection_caret*
    selection_caret: ~
        Will be shown in front of the selection.

        Default: '> '

                                    *telescope.defaults.selection_strategy*
    selection_strategy: ~
        Determines how the cursor acts after each sort iteration.

        Available options are:
        - "reset" (default)
        - "follow"
        - "row"

                                      *telescope.defaults.sorting_strategy*
    sorting_strategy: ~
        Determines the direction "better" results are sorted towards.

        Available options are:
        - "descending" (default)
        - "ascending"

    Parameters: ~
        {opts} (table)  Configuration opts. Keys: defaults, extensions


telescope.register_extension({mod})           *telescope.register_extension()*
    Register an extension. To be used by plugin authors.


    Parameters: ~
        {mod} (table)  Module


telescope.load_extension({name})                  *telescope.load_extension()*
    Load an extension.


    Parameters: ~
        {name} (string)  Name of the extension


telescope.extensions()                                *telescope.extensions()*
    Use telescope.extensions to reference any extensions within your
    configuration.
    While the docs currently generate this as a function, it's actually a
    table. Sorry.




================================================================================
                                                         *telescope.actions.set*

Telescope action sets are used to provide an interface for managing actions
that all primarily do the same thing, but with slight tweaks.

For example, when editing files you may want it in the current split, a
vertical split, etc. Instead of making users have to overwrite EACH of those
every time they want to change this behavior, they can instead replace the
`set` itself and then it will work great and they're done.

The first two arguments of all action sets are: function(prompt_bufnr, context,
...)


action_set.shift_selection({prompt_bufnr}, {change})*action_set.shift_selection()*
    Move the current selection of a picker {change} rows. Handles not
    overflowing / underflowing the list.


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr
        {change}       (number)  The amount to shift the selection by


action_set.select({prompt_bufnr}, {type})                *action_set.select()*
    Select the current entry. This is the action set to overwrite common
    actions by the user.

    By default maps to editing a file.


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr
        {type}         (string)  The type of selection to make


action_set.edit({prompt_bufnr}, {command})                 *action_set.edit()*
    Edit a file based on the current selection.


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr
        {command}      (string)  The command to use to open the file.


action_set.scroll_previewer({prompt_bufnr}, {direction})*action_set.scroll_previewer()*
    Scrolls the previewer up or down


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr
        {direction}    (number)  The direction of the scrolling



================================================================================
                                                             *telescope.actions*

Actions functions that are useful for people creating their own mappings.

All actions follow the same signature: function(prompt_bufnr, context)

prompt_bufnr: The bufnr for the prompt context: Table, Valid keys: index: The
multi-selection index, if applicable entry: The entry to perform the action on.


actions.move_selection_previous({prompt_bufnr})*actions.move_selection_previous()*
    Move the selection to the previous entry


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr


actions.move_selection_worse({prompt_bufnr})  *actions.move_selection_worse()*
    Move the selection to the entry that has a worse score


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr


actions.move_selection_better({prompt_bufnr})*actions.move_selection_better()*
    Move the selection to the entry that has a better score


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr


actions.move_to_top({prompt_bufnr})                    *actions.move_to_top()*
    Move to the top of the picker


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr


actions.move_to_middle({prompt_bufnr})              *actions.move_to_middle()*
    Move to the middle of the picker


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr


actions.move_to_bottom({prompt_bufnr})              *actions.move_to_bottom()*
    Move to the bottom of the picker


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr


actions.add_selection({prompt_bufnr})                *actions.add_selection()*
    Add current entry to multi select


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr


actions.remove_selection({prompt_bufnr})          *actions.remove_selection()*
    Remove current entry from multi select


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr


actions.toggle_selection({prompt_bufnr})          *actions.toggle_selection()*
    Toggle current entry status for multi select


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr


actions.select_default()                            *actions.select_default()*
    THIS DOESNT ACTUALLY EXIST YET



actions.git_create_branch({prompt_bufnr})        *actions.git_create_branch()*
    Create and checkout a new git branch if it doesn't already exist


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr


actions.git_checkout({prompt_bufnr})                  *actions.git_checkout()*
    Checkout an existing git branch


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr


actions.git_track_branch({prompt_bufnr})          *actions.git_track_branch()*
    Tell git to track the currently selected remote branch in Telescope


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr


actions.send_selected_to_qflist()          *actions.send_selected_to_qflist()*
    TODO: These would be good candidates for thinking about how to add them one
    at a time OR with the list of items.

    Very cool



actions.open_qflist()                                  *actions.open_qflist()*
    Open the quickfix list




================================================================================
                                                             *telescope.builtin*

A collection of builtin pickers for telescope.

Meant for both example and for easy startup.

Any of these functions can just be called directly by doing:

:lua require('telescope.builtin').$NAME()

This will use the default configuration options. Other configuration options
are still in flux at the moment

builtin.live_grep()                                      *builtin.live_grep()*
    Live grep means grep as you type.




================================================================================
                                                       *telescope.actions.state*

Functions to be used to determine the current state of telescope.

Generally used from within other |telescope.actions|

action_state.get_selected_entry()          *action_state.get_selected_entry()*
    Get the current entry



action_state.get_current_line()              *action_state.get_current_line()*
    Gets the current line



action_state.get_current_picker()          *action_state.get_current_picker()*
    Gets the current picker




================================================================================
                                                          *telescope.previewers*

Provides a Previewer table that has to be implemented by each previewer. To
achieve this, this module also provides two wrappers that abstract most of the
work and make it really easy create new previewers.
  - `previewers.new_termopen_previewer`
  - `previewers.new_buffer_previewer`

Furthermore, there are a collection of previewers already defined which can be
used for every picker, as long as the entries of the picker provide the
necessary fields. The more important once are
  - `previewers.cat`
  - `previewers.vimgrep`
  - `previewers.qflist`
  - `previewers.vim_buffer_cat`
  - `previewers.vim_buffer_vimgrep`
  - `previewers.vim_buffer_qflist`

Previewers can be disabled for any builtin or custom picker by doing :Telescope
find_files previewer=false

previewers.Previewer()                                *previewers.Previewer()*
    This is the base table all previewers have to implement. It's possible to
    write a wrapper for this because most previewers need to have the same keys
    set. Examples of wrappers are:
      - `new_buffer_previewer`
      - `new_termopen_previewer`

    To create a new table do following:
      - `local new_previewer = Previewer:new(opts)`

    What `:new` expects is listed below

    The interface provides following set of functions. All of them, besides
    `new`, will be handled by telescope pickers.
    - `:new(opts)`
    - `:preview(entry, status)`
    - `:teardown()`
    - `:send_input(input)`
    - `:scroll_fn(direction)`

    `Previewer:new()` expects a table as input with following keys:
      - `setup` function(self): Will be called the first time preview will be 
        called.
      - `teardown` function(self): Will be called on cleanup.
      - `preview_fn` function(self, entry, status): Will be called each time a
        new entry was selected.
      - `send_input` function(self, input): This is meant for 
        `termopen_previewer` and it can be used to send input to the terminal 
        application, like less.
      - `scroll_fn` function(self, direction): Used to make scrolling work.



previewers.new()                                            *previewers.new()*
    A shorthand for creating a new Previewer. The provided table will be
    forwarded to `Previewer:new(...)`



previewers.new_termopen_previewer()      *previewers.new_termopen_previewer()*
    Is a wrapper around Previewer and helps with creating a new
    `termopen_previewer`.

    It requires you to specify one table entry `get_command(entry, status)`.
    This `get_command` function has to return the terminal command that will be
    executed for each entry. Example:
      get_command = function(entry, status)
        return { 'bat', entry.path }
      end

    It's an easy way to get your first previewer going and it integrates well
    with `bat` and `less`. Providing out of the box scrolling if the command
    uses less.

    Furthermore, it will forward all `config.set_env` environment variables to
    that terminal process.

    While this interface is a good start, it was replaced with the way more
    flexible `buffer_previewer` and is now deprecated.



previewers.cat()                                            *previewers.cat()*
    Provides a `termopen_previewer` which has the ability to display files. It
    will always show the top of the file and has support for `bat`(prioritized)
    and `cat`. Each entry has to provide either the field `path` or `filename`
    in order to make this previewer work.

    The preferred way of using this previewer is like this
    `require('telescope.config').values.cat_previewer` This will respect user
    configuration and will use `buffer_previewers` in case it's configured that
    way.



previewers.vimgrep()                                    *previewers.vimgrep()*
    Provides a `termopen_previewer` which has the ability to display files at
    the provided line. It has support for `bat`(prioritized) and `cat`. Each
    entry has to provide either the field `path` or `filename` and a `lnum`
    field in order to make this previewer work.

    The preferred way of using this previewer is like this
    `require('telescope.config').values.grep_previewer` This will respect user
    configuration and will use `buffer_previewers` in case it's configured that
    way.



previewers.qflist()                                      *previewers.qflist()*
    Provides a `termopen_previewer` which has the ability to display files at
    the provided line or range. It has support for `bat`(prioritized) and
    `cat`. Each entry has to provide either the field `path` or `filename`,
    `lnum` and a `start` and `finish` range in order to make this previewer
    work.

    The preferred way of using this previewer is like this
    `require('telescope.config').values.qflist_previewer` This will respect
    user configuration and will use buffer previewers in case it's configured
    that way.



previewers.new_buffer_previewer()          *previewers.new_buffer_previewer()*
    An interface to instantiate a new `buffer_previewer`. That means that the
    content actually lives inside a vim buffer which enables us more control
    over the actual content. For example, we can use `vim.fn.search` to jump to
    a specific line or reuse buffers/already opened files more easily. This
    interface is more complex than `termopen_previewer` but offers more
    flexibility over your content. It was designed to display files but was
    extended to also display the output of terminal commands.

    In the following options, state table and general tips are mentioned to
    make your experience with this previewer more seamless.


    options:
      - `define_preview = function(self, entry, status)` (required) Is called
        for each selected entry, after each selection_move (up or down) and is
        meant to handle things like reading file, jump to line or attach a
        highlighter.
      - `setup = function(self)` (optional) Is called once at the beginning,
        before the preview for the first entry is displayed. You can return a
        table of vars that will be available in `self.state` in each
        `define_preview` call.
      - `teardown = function(self)` (optional) Will be called at the end, when
        the picker is being closed and is meant to cleanup everything that was
        allocated by the previewer. The `buffer_previewer` will automatically
        cleanup all created buffers. So you only need to handle things that
        were introduced by you.
      - `keep_last_buf = true` (optional) Will not delete the last selected
        buffer. This would allow you to reuse that buffer in the select action.
        For example, that buffer can be opened in a new split, rather than
        recreating that buffer in an action. To access the last buffer number: 
        `require('telescope.state').get_global_key("last_preview_bufnr")`
      - `get_buffer_by_name = function(self, entry)` Allows you to set a unique
        name for each buffer. This is used for caching purpose.
        `self.state.bufname` will be nil if the entry was never loaded or the
        unique name when it was loaded once. For example, useful if you have
        one file but multiple entries. This happens for grep and lsp builtins.
        So to make the cache work only load content if `self.state.bufname ~=
        entry.your_unique_key`

    `self.state` table:
      - `self.state.bufnr` Is the current buffer number, in which you have to
        write the loaded content. Don't create a buffer yourself, otherwise
        it's not managed by the buffer_previewer interface and you will
        probably be better off writing your own interface.
      - self.state.winid Current window id. Useful if you want to set the
        cursor to a provided line number.
      - self.state.bufname Will return the current buffer name, if
        `get_buffer_by_name` is defined. nil will be returned if the entry was
        never loaded or when `get_buffer_by_name` is not set.

    Tips:
      - If you want to display content of a terminal job, use: 
        `require('telescope.previewers.utils').job_maker(cmd, bufnr, opts)`
          - `cmd` table: for example { 'git', 'diff', entry.value }
          - `bufnr` number: in which the content will be written
          - `opts` table: with following keys
            - `bufname` string: used for cache
            - `value` string: used for cache
            - `mode` string: either "insert" or "append". "insert" is default
            - `env` table: define environment variables. Example:
              - `{ ['PAGER'] = '', ['MANWIDTH'] = 50 }`
            - `cwd` string: define current working directory for job
            - `callback` function(bufnr, content): will be called when job is
              done. Content will be nil if job is already loaded. So you can do
              highlighting only the first time the previewer is created for
              that entry. Use the returned `bufnr` and not `self.state.bufnr`
              in callback, because state can already be changed at this point
              in time.
      - If you want to attach a highlighter use:
        - `require('telescope.previewers.utils').highlighter(bufnr, ft)`
          - This will prioritize tree sitter highlighting if available for 
            environment and language.
        - `require('telescope.previewers.utils').regex_highlighter(bufnr, ft)`
        - `require('telescope.previewers.utils').ts_highlighter(bufnr, ft)`
      - If you want to use `vim.fn.search` or similar you need to run it in 
        that specific buffer context. Do
          vim.api.nvim_buf_call(bufnr, function()
            -- for example `search` and `matchadd`
          end)
        to achieve that.
      - If you want to read a file into the buffer it's best to use 
        `buffer_previewer_maker`. But access this function with 
        `require('telescope.config').values.buffer_previewer_maker` because it
        can be redefined by users.



previewers.buffer_previewer_maker({filepath}, {bufnr}, {opts})*previewers.buffer_previewer_maker()*
    A universal way of reading a file into a buffer previewer. It handles async
    reading, cache, highlighting, displaying directories and provides a
    callback which can be used, to jump to a line in the buffer.


    Parameters: ~
        {filepath} (string)  String to the filepath, will be expanded
        {bufnr}    (number)  Where the content will be written
        {opts}     (table)   keys: `use_ft_detect`, `bufname` and `callback`


previewers.vim_buffer_cat()                      *previewers.vim_buffer_cat()*
    A previewer that is used to display a file. It uses the `buffer_previewer`
    interface and won't jump to the line. To integrate this one into your own
    picker make sure that the field `path` or `filename` is set for each entry.
    The preferred way of using this previewer is like this
    `require('telescope.config').values.file_previewer` This will respect user
    configuration and will use `termopen_previewer` in case it's configured
    that way.



previewers.vim_buffer_vimgrep()              *previewers.vim_buffer_vimgrep()*
    A previewer that is used to display a file and jump to the provided line.
    It uses the `buffer_previewer` interface. To integrate this one into your
    own picker make sure that the field `path` or `filename` and `lnum` is set
    in each entry. If the latter is not present, it will default to the first
    line. The preferred way of using this previewer is like this
    `require('telescope.config').values.grep_previewer` This will respect user
    configuration and will use `termopen_previewer` in case it's configured
    that way.



previewers.vim_buffer_qflist()                *previewers.vim_buffer_qflist()*
    Is the same as `vim_buffer_vimgrep` and only exist for consistency with
    `term_previewers`.

    The preferred way of using this previewer is like this
    `require('telescope.config').values.qflist_previewer` This will respect
    user configuration and will use `termopen_previewer` in case it's
    configured that way.



previewers.display_content()                    *previewers.display_content()*
    A deprecated way of displaying content more easily. Was written at a time,
    where the buffer_previewer interface wasn't present. Nowadays it's easier
    to just use this. We will keep it around for backwards compatibility
    because some extensions use it. It doesn't use cache or some other clever
    tricks.




================================================================================
                                                              *telescope.layout*

Layout strategies are different functions to position telescope.

All layout strategies are functions with the following signature:

  function(picker, columns, lines)
    -- Do some calculations here...
    return {
      preview = preview_configuration
      results = results_configuration,
      prompt = prompt_configuration,
    }
  end

  Parameters: ~
    - picker  : A Picker object. (docs coming soon)
    - columns : number Columns in the vim window
    - lines   : number Lines in the vim window


TODO: I would like to make these link to `telescope.layout_strategies.*`, but
it's not yet possible.

Available layout strategies include:
  - horizontal:
    - See |layout_strategies.horizontal|

  - vertical:
    - See |layout_strategies.vertical|

  - flex:
    - See |layout_strategies.flex|

Available tweaks to the settings in layout defaults include (can be applied to
horizontal and vertical layouts):
  - mirror (default is `false`):
    - Flip the view of the current layout:
      - If using horizontal: if `true`, swaps the location of the 
        results/prompt window and preview window
      - If using vertical: if `true`, swaps the location of the results and 
        prompt windows

  - width_padding:
    - How many cells to pad the width of Telescope's layout window

  - height_padding:
    - How many cells to pad the height of Telescope's layout window

  - preview_width:
    - Change the width of Telescope's preview window

  - scroll_speed:
    - Change the scrolling speed of the previewer

layout_strategies.horizontal()                *layout_strategies.horizontal()*
    Horizontal previewer

      +-------------+--------------+
      |             |              |
      |   Results   |              |
      |             |    Preview   |
      |             |              |
      +-------------|              |
      |   Prompt    |              |
      +-------------+--------------+



layout_strategies.center()                        *layout_strategies.center()*
    Centered layout wih smaller default sizes (I think)

       +--------------+
       |    Preview   |
       +--------------+
       |    Prompt    |
       +--------------+
       |    Result    |
       |    Result    |
       |    Result    |
       +--------------+



layout_strategies.vertical()                    *layout_strategies.vertical()*
    Vertical perviewer stacks the items on top of each other.

       +-----------------+
       |    Previewer    |
       |    Previewer    |
       |    Previewer    |
       +-----------------+
       |     Result      |
       |     Result      |
       |     Result      |
       +-----------------+
       |     Prompt      |
       +-----------------+



layout_strategies.flex()                            *layout_strategies.flex()*
    Swap between `horizontal` and `vertical` strategies based on the window
    width
     - Supports `vertical` or `horizontal` features

    Uses:
     - flip_columns
     - flip_lines




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