please.txt

*please.txt*                A plugin for interacting with Please repositories.
*please.nvim*
                                       Type |gO| to see the table of contents.

==============================================================================
INTRODUCTION                                                    *please-intro*

please.nvim enables you to interact with Please repositories from the comfort
of Neovim.

                                                             *please-features*
Features ~
  • Build, run, test, and debug a target with |:Please-build|, |:Please-run|,
    |:Please-test|, and |:Please-debug|.
  • Run an arbitrary plz command in a popup with |:Please-command|.
  • Display history of previous commands and run any of them again with
    |:Please-history|.
  • Set the profile to use with |:Please-set_profile|.
  • Jump from a source file to its target's definition with
    |:Please-jump_to_target|.
  • Look up a target by its build label with |:Please-look_up_target|.
  • Yank a target's build label with |:Please-yank|.
  • `please` configured as the `'filetype'` for build files: `*.build`,
    `*.build_defs`, and the build file names set as `parse.buildfilename` in
    `.plzconfig` (defaults to `BUILD` and `BUILD.plz`).
  • `ini` configured as the |'filetype'| for `.plzconfig` files to enable better
    syntax highlighting.
  • `please` LSP client configured to use `plz tool lps` for `please` files.
    See |please-lsp-client|.
  • Python tree-sitter parser configured to be used for please files to enable
    better syntax highlighting and use of all tree-sitter features in BUILD
    files.
  • Language servers gopls, golangci-lint-langserver, basedpyright, and
    pyright configured for use in a Please repository. See |please-gopls|,
    |please-golangci-lint-langserver|, |please-basedpyright|, and
    |please-pyright|.
  • Runs `puku fmt` when a Go file is saved. See |please-puku|.

==============================================================================
QUICKSTART                                                 *please-quickstart*

1. Open a test file in a Please repository.
2. Execute `:Please test` to test the target corresponding to the test file in
   a popup.

==============================================================================
USAGE                                                           *please-usage*

                                                         *please-requirements*
Requirements ~
please.nvim requires:
  • Neovim >= 0.11.0
  • https://please.build

please.nvim supports the latest two Neovim minor versions. CI tests against
the minimum supported version and the latest patch of each supported minor.

Additional dependencies are required for some features:
  • https://github.com/tree-sitter/tree-sitter-go for
    |:Please-test-under_cursor| and |:Please-debug-under_cursor| in Go files
  • https://github.com/tree-sitter/tree-sitter-python for
    |:Please-test-under_cursor| and |:Please-debug-under_cursor| in Python
    files, |:Please-jump_to_target|, |:Please-look_up_target|, and
    |:Please-build|, |:Please-run|, |:Please-test|, |:Please-debug|, and
    |:Please-yank| in BUILD files
  • https://github.com/mfussenegger/nvim-dap for |:Please-debug|

Execute `:checkhealth please` to verify that the required dependencies are
available and to see whether any feature-specific dependencies are missing.

                                                           *please-interfaces*
Command interface and Lua API ~
please.nvim provides a command interface and a Lua API. All functionality is
available through both. To use the command interface, invoke the appropriate
`:Please` command. To use the Lua API, import the `please` module and invoke
the appropriate function.

For example, these are two equivalent ways to execute the test under the
cursor.

Command interface: >vim
    Please test under_cursor
<
Lua API: >lua
    local please = require('please')
    please.test({ under_cursor = true })
<
See |please-commands| and |please-lua| for full documentation of the two
interfaces.

                                                             *please-mappings*
Mappings ~
please.nvim doesn't come with any mappings defined out of the box so that you
can customise how you use it. Below are a set of mappings for each available
command to get you started.
>lua
    vim.keymap.set('n', '<leader>pb', '<Cmd>Please build<CR>')
    vim.keymap.set('n', '<leader>pr', '<Cmd>Please run<CR>')
    vim.keymap.set('n', '<leader>pt', '<Cmd>Please test<CR>')
    vim.keymap.set('n', '<leader>pct', '<Cmd>Please test under_cursor<CR>')
    vim.keymap.set('n', '<leader>pd', '<Cmd>Please debug<CR>')
    vim.keymap.set('n', '<leader>pcd', '<Cmd>Please debug under_cursor<CR>')
    vim.keymap.set('n', '<leader>ph', '<Cmd>Please history<CR>')
    vim.keymap.set('n', '<leader>pch', '<Cmd>Please clear_history<CR>')
    vim.keymap.set('n', '<leader>pp', '<Cmd>Please set_profile<CR>')
    vim.keymap.set('n', '<leader>pm', '<Cmd>Please maximise_popup<CR>')
    vim.keymap.set('n', '<leader>pj', '<Cmd>Please jump_to_target<CR>')
    vim.keymap.set('n', '<leader>pl', '<Cmd>Please look_up_target<CR>')
    vim.keymap.set('n', '<leader>py', '<Cmd>Please yank<CR>')
<
                                                                *please-setup*
Setup ~
please.nvim does not require any setup to be used. However, you can customise
the behaviour of the plugin by calling |please.setup()|.

                                                     *please-ui-customisation*
UI Customisation ~
Some commands may prompt you to either choose from a list of options or input
some text. For example, when building a file which is an input to multiple
targets, you'll be prompted to choose which target to build.

Input and selection prompts are provided by |vim.ui.input()| and
|vim.ui.select()| respectively. This enables you to customise the appearance
of these prompts to your taste by overriding |vim.ui.input()| or
|vim.ui.select()|. There are various plugins now which provide alternative
implementations of these hooks. Some (possibly outdated) examples are:
  • https://github.com/ibhagwan/fzf-lua
  • https://github.com/folke/snacks.nvim
  • https://github.com/stevearc/dressing.nvim
  • https://github.com/nvim-telescope/telescope-ui-select.nvim

                                                  *please-recommended-plugins*
Recommended additional plugins ~
  • https://github.com/nvim-treesitter/nvim-treesitter - Tree-sitter
    configurations and abstraction layer for Neovim. This enables you to
    install tree-sitter parsers.
  • https://github.com/ibhagwan/fzf-lua - Highly extendable fuzzy finder. This
    provides a good `vim.ui.select` implementation.
  • https://github.com/rcarriga/nvim-dap-ui - UI for nvim-dap.

==============================================================================
LSP CONFIGURATION                                          *please-lsp-config*

please.nvim configures various aspects of your LSP setup.

                                                           *please-lsp-client*
Please LSP Client ~
please.nvim configures the `please` LSP client to use `plz tool lps` for
`please` files using |vim.lsp.config()|. Call |vim.lsp.enable| to enable it:
>lua
    vim.lsp.enable('please')
<
                                                                *please-gopls*
gopls ~
please.nvim detects when `gopls` has been started in a Please repository and
restarts it with the following configuration changes:
  • Append `-plz-out` to the `gopls.directoryFilters` setting to exclude
    `plz-out` from the workspace.
  • Prepend the bin directory of the Go toolchain (i.e. `$GOROOT/bin`)
    configured by the `plugin.go.gotool` `.plzconfig` setting to its `PATH`.
    The go-rules Please plugin allows configuring the `go` executable to use
    via `plugin.go.gotool` and `gopls` uses the `go` executable found on its
    `PATH` to determine where the standard library is located. So this `PATH`
    change means that operations like jumping to a definition or listing
    references with standard library packages will refer to the correct
    location for the Go toolchain configured for the repository.

This behaviour can be disabled by passing `configure_gopls = false` to
|please.setup()|.

See also:
  • https://go.dev/gopls/settings
  • https://github.com/please-build/go-rules/blob/master/.plzconfig

                                             *please-golangci-lint-langserver*
golangci-lint-langserver ~
please.nvim detects when `golangci-lint-langserver` has been started in a
Please repository and restarts it with the following configuration changes:
  • Prepend the bin directory of the Go toolchain (i.e. `$GOROOT/bin`)
    configured by the `plugin.go.gotool` `.plzconfig` setting to its `PATH`.
    The go-rules Please plugin allows configuring the `go` executable to use
    via `plugin.go.gotool` and `golangci-lint-langserver` uses the `go`
    executable found on its `PATH` to determine where the standard library is
    located. So this `PATH` change means that checks will be performed against
    the standard library packages in the Go toolchain configured for the
    repository.

This behaviour can be disabled by passing
`configure_golangci_lint_langserver = false` to |please.setup()|.

See also:
  • https://github.com/nametake/golangci-lint-langserver
  • https://github.com/please-build/go-rules/blob/master/.plzconfig

                                                         *please-basedpyright*
basedpyright ~
please.nvim detects when `basedpyright` has been started in a Please
repository and sends a `workspace/didChangeConfiguration` notification after
making the following setting changes:
  • Append `plz-out` to `basedpyright.analysis.exclude` to exclude `plz-out`
    from the workspace.
  • Prepend `plz-out/python/venv` to `basedpyright.analysis.extraPaths`. The
    `python_wheel` and `pip_library` rules from the python-rules Please plugin
    symlink the downloaded packages into `plz-out/python/venv` so this means
    that `basedpyright` will be able to find them.

This behaviour can be disabled by passing `configure_basedpyright = false` to
|please.setup()|.

See also:
  • https://docs.basedpyright.com/latest/configuration/language-server-settings
  • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_didChangeConfiguration
  • https://github.com/please-build/python-rules/blob/master/build_defs/python.build_defs

                                                              *please-pyright*
pyright ~
please.nvim detects when `pyright` has been started in a Please repository and
sends a `workspace/didChangeConfiguration` notification after making the
following setting changes:
  • Append `plz-out` to `python.analysis.exclude` to exclude `plz-out`
    from the workspace.
  • Prepend `plz-out/python/venv` to `python.analysis.extraPaths`. The
    `python_wheel` and `pip_library` rules from the python-rules Please plugin
    symlink the downloaded packages into `plz-out/python/venv` so this means
    that pyright` will be able to find them.

This behaviour can be disabled by passing `configure_pyright = false` to
|please.setup()|.

See also:
  • https://microsoft.github.io/pyright/#/settings
  • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_didChangeConfiguration
  • https://github.com/please-build/python-rules/blob/master/build_defs/python.build_defs

==============================================================================
PUKU                                                             *please-puku*

If `puku_command` has been set via |please.setup()|, please.nvim will run
`puku fmt` when a Go file is saved. Puku is a tool for maintaining Go build
targets and `puku fmt` updates BUILD files based on the imports in Go source
files.

To configure a different `puku_command` for different repositories, consider
enabling |'exrc'| and calling |please.setup()| with a different `puku_command`
in `.nvim.lua`.

See also:
  • https://github.com/please-build/puku

==============================================================================
COMMANDS                                           *:Please* *please-commands*

:Please build                                                  *:Please-build*
    Builds a target.

    If the current file is a `BUILD` file, builds the target which is under
    the cursor. Otherwise, builds the target which takes the current file as
    an input.

    See |please.build()| for the equivalent Lua function.

:Please run                                                      *:Please-run*
    Runs a target.

    If the current file is a `BUILD` file, runs the target which is under the
    cursor. Otherwise, runs the target which takes the current file as an
    input.

    See |please.run()| for the equivalent Lua function.

:Please test [under_cursor]         *:Please-test* *:Please-test-under_cursor*
    Tests a target.

    If the current file is a `BUILD` file, tests the target which is under the
    cursor. Otherwise, tests the target which takes the current file as an
    input.

    Optionally (when in a source file), you can run only the test which is
    under the cursor by passing [under_cursor]. This is supported for the
    following languages:
    • Go - test functions, subtests, table tests, testify suite methods,
      testify suite subtests, testify suite table tests
    • Python - unittest test classes, unittest test methods

    See |please.test()| for the equivalent Lua function.

:Please debug [under_cursor]      *:Please-debug* *:Please-debug-under_cursor*
    Debugs a target.

    If the current file is a `BUILD` file, debugs the target which is under
    the cursor. Otherwise, debugs the target which takes the current file as
    an input.

    Debug support is provided by https://github.com/mfussenegger/nvim-dap.
    This is supported for the following languages:
    • Go (Delve)
    • Python (debugpy)

    Optionally (when in a source file), you can debug only the test which is
    under the cursor by passing [under_cursor]. The supported languages and
    test types are the same as for |please.test()|.

    See |please.debug()| for the equivalent Lua function.

:Please command {arg}...                                     *:Please-command*
    Runs an arbitrary plz command and displays the output in a popup.

    Example: >vim
        Please command build //foo/bar/...
<
    See |please.command()| for the equivalent Lua function.

:Please history                                              *:Please-history*
    Displays a history of previous commands run in the current repository.
    Selecting one runs it again.

    See |please.history()| for the equivalent Lua function.

:Please clear_history                                  *:Please-clear_history*
    Clears the command history for the current repository.

    See |please.clear_history()| for the equivalent Lua function.

:Please set_profile                                      *:Please-set_profile*
    Sets the profile used by |please.build()|, |please.run()|,
    |please.test()|, |please.debug()|, and |please.command()|.

    Profiles are searched for in `/etc/please`, `~/.config/please`, and the
    current repository.

    See |please.set_profile()| for the equivalent Lua function.

:Please maximise_popup                                *:Please-maximise_popup*
    Maximises the popup which was most recently quit or minimised.

    See |please.maximise_popup()| for the equivalent Lua function.

:Please jump_to_target                                *:Please-jump_to_target*
    Jumps to the location of the target which takes the current file as an
    input.

    The cursor is moved to where the target is created if it can be found
    which should be the case for all targets except for those with names which
    are generated when the `BUILD` file is executed.

    See |please.jump_to_target()| for the equivalent Lua function.

:Please look_up_target                                *:Please-look_up_target*
    Looks up a target by its build label and jumps to its location.

    If the cursor is already on a build label, then this is used. Otherwise,
    you'll be prompted for one.

    The cursor is moved to where the target is created if it can be found
    which should be the case for all targets except for those with names which
    are generated when the `BUILD` file is executed.

    See |please.look_up_target()| for the equivalent Lua function.

:Please yank                                                    *:Please-yank*
    Yanks a target's build label.

    If the current file is a `BUILD` file, yanks the build label of the target
    which is under the cursor. Otherwise, yanks the build label of the target
    which takes the current file as an input.

    See |please.yank()| for the equivalent Lua function.

:Please toggle_debug_logging                    *:Please-toggle_debug_logging*
    Toggles debug logging.

    The debug logs mostly contain which functions are being called with which
    arguments. This should provide enough information to debug most issues.

    See |please.toggle_debug_logging()| for the equivalent Lua function.

==============================================================================
Lua module: please                                                *please-lua*

setup({opts})                                                 *please.setup()*
    Updates the configuration with the provided {opts}.

    Should only be called if you want to change the defaults which are shown
    below.

    Execute `:checkhealth please` to view the current configuration.

    Example: >lua
        local please = require('please')
        please.setup({
           max_history_items = 20,
           configure_gopls = true,
           configure_golangci_lint_langserver = true,
           configure_basedpyright = true,
           configure_pyright = true,
           puku_command = nil,
        })
<

    Parameters: ~
      • {opts}  (`table`) A table with the following fields:
                • {max_history_items} (`integer?`) The maximum number of
                  history items to store for each repository. Defaults to 20.
                • {configure_gopls} (`boolean?`) Whether to configure the
                  gopls language server for use in a Please repository.
                  Defaults to true.
                • {configure_golangci_lint_langserver} (`boolean?`) Whether to
                  configure the golangci-lint-langserver language server for
                  use in a Please repository. Defaults to true.
                • {configure_basedpyright} (`boolean?`) Whether to configure
                  the basedpyright language server for use in a Please
                  repository. Defaults to true.
                • {configure_pyright} (`boolean?`) Whether to configure the
                  pyright language server for use in a Please repository.
                  Defaults to true.
                • {puku_command} (`string[]?`) Command to execute puku.
                  Defaults to nil which means that puku formatting is not
                  enabled.

build()                                                       *please.build()*
    Builds a target.

    If the current file is a `BUILD` file, builds the target which is under
    the cursor. Otherwise, builds the target which takes the current file as
    an input.

    See |:Please-build| for the equivalent `:Please` command.

run()                                                           *please.run()*
    Runs a target.

    If the current file is a `BUILD` file, runs the target which is under the
    cursor. Otherwise, runs the target which takes the current file as an
    input.

    See |:Please-run| for the equivalent `:Please` command.

test({opts})                                                   *please.test()*
    Tests a target.

    If the current file is a `BUILD` file, tests the target which is under the
    cursor. Otherwise, tests the target which takes the current file as an
    input.

    Optionally (when in a source file), you can run only the test which is
    under the cursor. This is supported for the following languages:
    • Go - test functions, subtests, table tests, testify suite methods,
      testify suite subtests, testify suite table tests
    • Python - unittest test classes, unittest test methods

    See |:Please-test| for the equivalent `:Please` command.

    Parameters: ~
      • {opts}  (`table?`) optional keyword arguments
                • {under_cursor} (`boolean`) run the test under the cursor

debug({opts})                                                 *please.debug()*
    Debugs a target.

    If the current file is a `BUILD` file, debugs the target which is under
    the cursor. Otherwise, debugs the target which takes the current file as
    an input.

    Debug support is provided by https://github.com/mfussenegger/nvim-dap.
    This is supported for the following languages:
    • Go (Delve)
    • Python (debugpy)

    Optionally (when in a source file), you can debug only the test which is
    under the cursor. The supported languages and test types are the same as
    for |please.test()|.

    See |:Please-debug| for the equivalent `:Please` command.

    Parameters: ~
      • {opts}  (`table?`) optional keyword arguments
                • {under_cursor} (`boolean`) debug the test under the cursor

command({...})                                              *please.command()*
    Runs an arbitrary plz command and displays the output in a popup.

    Example: >lua
        local please = require('please')
        please.command('build', '//foo/bar/...')
<

    See |:Please-command| for the equivalent `:Please` command.

    Parameters: ~
      • {...}  (`string`) Arguments to pass to plz

history()                                                   *please.history()*
    Displays a history of previous commands run in the current repository.
    Selecting one runs it again.

    See |:Please-history| for the equivalent `:Please` command.

clear_history()                                       *please.clear_history()*
    Clears the command history for the current repository.

    See |:Please-clear_history| for the equivalent `:Please` command.

set_profile()                                           *please.set_profile()*
    Sets the profile used by |please.build()|, |please.run()|,
    |please.test()|, |please.debug()|, and |please.command()|.

    Profiles are searched for in `/etc/please`, `~/.config/please`, and the
    current repository.

    See |:Please-set_profile| for the equivalent `:Please` command.

maximise_popup()                                     *please.maximise_popup()*
    Maximises the popup which was most recently quit or minimised.

    See |:Please-maximise_popup| for the equivalent `:Please` command.

jump_to_target()                                     *please.jump_to_target()*
    Jumps to the location of the target which takes the current file as an
    input.

    The cursor is moved to where the target is created if it can be found
    which should be the case for all targets except for those with names which
    are generated when the `BUILD` file is executed.

    See |:Please-jump_to_target| for the equivalent `:Please` command.

look_up_target()                                     *please.look_up_target()*
    Looks up a target by its build label and jumps to its location.

    If the cursor is already on a build label, then this is used. Otherwise,
    you'll be prompted for one.

    The cursor is moved to where the target is created if it can be found
    which should be the case for all targets except for those with names which
    are generated when the `BUILD` file is executed.

    See |:Please-look_up_target| for the equivalent `:Please` command.

yank()                                                         *please.yank()*
    Yanks a target's build label.

    If the current file is a `BUILD` file, yanks the build label of the target
    which is under the cursor. Otherwise, yanks the build label of the target
    which takes the current file as an input.

    See |:Please-yank| for the equivalent `:Please` command.

toggle_debug_logging()                         *please.toggle_debug_logging()*
    Toggles debug logging.

    The debug logs mostly contain which functions are being called with which
    arguments. This should provide enough information to debug most issues.

    See |:Please-toggle_debug_logging| for the equivalent `:Please` command.


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