doc/please.txt

*please.txt* A plugin to make you more productive in Neovim when using Please.
*please.nvim*
                                       Type |gO| to see the table of contents.

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

please.nvim is a plugin which allows you interact with your Please repository
from the comfort of Neovim. The aim is to remove the need to switch from your
editor to the shell when performing routine actions.

Features ~
  • Build, run, test, and debug a target with |please.build()|,
    |please.run()|, |please.test()|, and |please.debug()|.
  • 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 build target definition with
    |please.jump_to_target()|.
  • Yank a target's label with |please.yank()|.
  • `please` configured as the 'filetype' for `BUILD`, `BUILD.plz`, and
    `*.build_defs` files
  • `ini` configured as the 'filetype' for `.plzconfig` files to enable better
    syntax highlighting
  • 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

==============================================================================
USAGE                                                           *please-usage*
                                                                     *:Please*
Lua and VimL APIs ~
please.nvim commands can be called either through the Lua or the VimL API.
  • Commands are written in Lua and as such the Lua API should be preferred.
    It can't be guaranteed that all features available through the Lua API
    will also available through the VimL API.
  • The VimL API is mostly provided to make it easy to call commands from the
    command line.

To use the Lua API, you need to import the required module which will usually
be `please`. For instance, |please.jump_to_target()| is executed with
>lua
    require('please').jump_to_target()
<
All available VimL API commands are autocompletable as arguments to the
`:Please` command. For instance, |please.jump_to_target()| is executed with
>
    :Please jump_to_target
<
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
build 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. Doing so allows you to customise the
appearance of them to your taste. See |vim.ui| and the fantastic
https://github.com/stevearc/dressing.nvim for more information.

==============================================================================
SETUP                                                           *please-setup*

please.nvim does not require any setup to be used. However, you can customise
the behaviour of the plugin by calling |please.setup()|.

==============================================================================
MAPPINGS                                                     *please-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', require('please').build)
    vim.keymap.set('n', '<leader>pr', require('please').run)
    vim.keymap.set('n', '<leader>pt', require('please').test)
    vim.keymap.set('n', '<leader>pct', function()
      require('please').test({ under_cursor = true })
    end)
    vim.keymap.set('n', '<leader>pd', require('please').debug)
    vim.keymap.set('n', '<leader>pcd', function()
      require('please').debug({ under_cursor = true })
    end)
    vim.keymap.set('n', '<leader>ph', require('please').history)
    vim.keymap.set('n', '<leader>pch', require('please').clear_history)
    vim.keymap.set('n', '<leader>pp', require('please').set_profile)
    vim.keymap.set('n', '<leader>pm', require('please').maximise_popup)
    vim.keymap.set('n', '<leader>pj', require('please').jump_to_target)
    vim.keymap.set('n', '<leader>py', require('please').yank)
<
==============================================================================
Lua module: please                                                    *please*

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.

    Example: >lua
        local please = require('please')
        please.setup({
          max_history_items = 20,
        })
<

    Parameters: ~
      • {opts}  (`table`) A table with the following fields:
                • {max_history_items} (`integer?`) The maximum number of
                  history items to store for each repository.

build()                                                       *please.build()*
    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.

run()                                                           *please.run()*
    If the current file is a `BUILD` file, run the target which is under the
    cursor. Otherwise, run the target which takes the current file as an
    input.

test({opts})                                                   *please.test()*
    If the current file is a `BUILD` file, test the target which is under the
    cursor. Otherwise, test 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

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

debug({opts})                                                 *please.debug()*
    If the current file is a `BUILD` file, debug the target which is under the
    cursor. Otherwise, debug 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()|.

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

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

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

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

history()                                                   *please.history()*
    Display a history of previous commands. Selecting one of them will run it
    again.

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

set_profile()                                           *please.set_profile()*
    Sets the profile that will be used by |please.build()|, |please.run()|,
    |please.test()|, |please.debug()|, and |please.command()|. Profiles will
    be searched for in `/etc/please`, `~/.config/please`, and the current
    repository.

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

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

    The cursor will be moved to where the build 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.

yank()                                                         *please.yank()*
    If the current file is a `BUILD` file, yank the label of the target which
    is under the cursor. Otherwise, yank the label of the target which takes
    the current file as an input.


==============================================================================
Lua module: please.logging                                    *please.logging*

toggle_debug()                                 *please.logging.toggle_debug()*
    Toggles debug logs containing which functions are being called with which
    arguments. This should provide enough information to debug most issues. To
    toggle debug logs from the command line, use `:Please toggle_debug_logs`.


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