gopher.nvim/doc/gopher.nvim.txt

*gopher.nvim*

==============================================================================

gopher.nvim is a minimalistic plugin for Go development in Neovim written in Lua.
It's not an LSP tool, the main goal of this plugin is add go tooling support in Neovim.

------------------------------------------------------------------------------
                                                 *gopher.nvim-table-of-contents*
Table of Contents
  Setup....................................................|gopher.nvim-setup|
  Install dependencies..............................|gopher.nvim-install-deps|
  Configuration...........................................|gopher.nvim-config|
  Modify struct tags.................................|gopher.nvim-struct-tags|
  Auto implementation of interface methods..................|gopher.nvim-impl|
  Generating unit tests boilerplate......................|gopher.nvim-gotests|
  Iferr....................................................|gopher.nvim-iferr|
  Generate comments.....................................|gopher.nvim-comments|

------------------------------------------------------------------------------
                                                             *gopher.nvim-setup*
                         `gopher.setup`({user_config})
Setup function. This method simply merges default config with opts table.
You can read more about configuration at |gopher.nvim-config|
Calling this function is optional, if you ok with default settings. Look |gopher.nvim.config-defaults|

Usage ~
`require("gopher").setup {}` (replace `{}` with your `config` table)
Parameters ~
{user_config} `(gopher.Config)`

------------------------------------------------------------------------------
                                                      *gopher.nvim-install-deps*
                             `gopher.install_deps`
Gopher.nvim implements most of its features using third-party tools.
To install these tools, you can run `:GoInstallDeps` command
or call `require("gopher").install_deps()` if you want to use lua api.


==============================================================================
------------------------------------------------------------------------------
                                                            *gopher.nvim-config*
config it is the place where you can configure the plugin.
also this is optional is you're ok with default settings.
You can look at default options |gopher.nvim-config-defaults|

------------------------------------------------------------------------------
                                                   *gopher.nvim-config-defaults*
                                `default_config`
>lua
  local default_config = {
    --minidoc_replace_end

    -- log level, you might consider using DEBUG or TRACE for debugging the plugin
    ---@type number
    log_level = vim.log.levels.INFO,

    -- timeout for running commands
    ---@type number
    timeout = 2000,

    -- user specified paths to binaries
    ---@class gopher.ConfigCommand
    commands = {
      go = "go",
      gomodifytags = "gomodifytags",
      gotests = "gotests",
      impl = "impl",
      iferr = "iferr",
      dlv = "dlv",
    },
    ---@class gopher.ConfigGotests
    gotests = {
      -- gotests doesn't have template named "default" so this plugin uses "default" to set the default template
      template = "default",
      -- path to a directory containing custom test code templates
      ---@type string|nil
      template_dir = nil,
      -- switch table tests from using slice to map (with test name for the key)
      -- works only with gotests installed from develop branch
      named = false,
    },
    ---@class gopher.ConfigGoTag
    gotag = {
      ---@type gopher.ConfigGoTagTransform
      transform = "snakecase",

      -- default tags to add to struct fields
      default_tag = "json",
    },
    iferr = {
      -- choose a custom error message
      ---@type string|nil
      message = nil,
    },
  }
<
Class ~
{gopher.Config}


==============================================================================
------------------------------------------------------------------------------
                                                       *gopher.nvim-struct-tags*
struct-tags is utilizing the `gomodifytags` tool to add or remove tags to struct fields.
Usage ~

How to add/remove tags to struct fields:

------------------------------------------------------------------------------
2. Run `:GoTagAdd json` to add json tags to struct fields
3. Run `:GoTagRm json` to remove json tags to struct fields

NOTE: if you dont specify the tag it will use `json` as default

Example:
>go
   // before
   type User struct {
   // ^ put your cursor here
   // run `:GoTagAdd yaml`
       ID int
       Name string
   }

   // after
   type User struct {
       ID int      `yaml:id`
       Name string `yaml:name`
   }
<
------------------------------------------------------------------------------
                                                             *struct_tags.add()*
                            `struct_tags.add`({...})
tags to a struct under the cursor
Parameters ~
{...} `(string)` Tags to add to the struct fields. If not provided, it will use [config.tag.default_tag]

------------------------------------------------------------------------------
                                                          *struct_tags.remove()*
                          `struct_tags.remove`({...})
tags from a struct under the cursor
Parameters ~
{...} `(string)` Tags to add to the struct fields. If not provided, it will use [config.tag.default_tag]

------------------------------------------------------------------------------
                                                           *struct_tags.clear()*
                             `struct_tags.clear`()
all tags from a struct under the cursor


==============================================================================
------------------------------------------------------------------------------
                                                              *gopher.nvim-impl*
impl is utilizing the `impl` tool to generate method stubs for interfaces.
Usage ~

1. Automatically implement an interface for a struct:
   - Place your cursor on the struct where you want to implement the interface.
   - Run `:GoImpl io.Reader`
   - This will automatically determine the receiver and implement the `io.Reader` interface.

2. Specify a custom receiver:
   - Place your cursor on the struct
   - Run `:GoImpl w io.Writer`, where:
     - `w` is the receiver.
     - `io.Writer` is the interface to implement.

3. Explicitly specify the receiver, struct, and interface:
   - No need to place the cursor on the struct if all arguments are provided.
   - Run `:GoImpl r RequestReader io.Reader`, where:
     - `r` is the receiver.
     - `RequestReader` is the struct.
     - `io.Reader` is the interface to implement.

Example:
>go
   type BytesReader struct{}
   //    ^ put your cursor here
   // run `:GoImpl b io.Reader`

   // this is what you will get
   func (b *BytesReader) Read(p []byte) (n int, err error) {
       panic("not implemented") // TODO: Implement
   }
<

==============================================================================
------------------------------------------------------------------------------
                                                           *gopher.nvim-gotests*
gotests is utilizing the `gotests` tool to generate unit tests boilerplate.
Usage ~

- Generate unit test for specific function/method:
  1. Place your cursor on the desired function/method.
  2. Run `:GoTestAdd`

- Generate unit tests for *all* functions/methods in current file:
  - run `:GoTestsAll`

- Generate unit tests *only* for *exported(public)* functions/methods:
  - run `:GoTestsExp`

You can also specify the template to use for generating the tests. See |gopher.nvim-config|
More details about templates can be found at: https://github.com/cweill/gotests

------------------------------------------------------------------------------
                                                     *gopher.nvim-gotests-named*

You can enable named tests in the config if you prefer using named tests.
But you must install `gotests@develop` because the stable version doesn't support this feature.

>lua
  -- simply run go get in your shell:
  go install github.com/cweill/gotests/...@develop

  -- if you want to install it within neovim, you can use one of this:
  -- if you choose to install gotests this way i reocmmend adding it to your `build` section in your |lazy.nvim|

  vim.fn.jobstart("go install github.com/cweill/gotests/...@develop")

  -- or if you want to use mason:
  require("mason-tool-installer").setup {
    ensure_installed = {
      { "gotests", version = "develop" },
    }
  }
<

==============================================================================
------------------------------------------------------------------------------
                                                             *gopher.nvim-iferr*
If you're using `iferr` tool, this module provides a way to automatically insert `if err != nil` check.
Usage ~
Execute `:GoIfErr` near any `err` variable to insert the check


==============================================================================
------------------------------------------------------------------------------
                                                          *gopher.nvim-comments*
Usage ~
Execute `:GoCmt` to generate a comment for the current function/method/struct/etc on this line.
This module provides a way to generate comments for Go code.


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