gopher.nvim @ c0b2834

*gopher.nvim* Enhance your golang experience

MIT License Copyright (c) 2025 Oleksandr Smirnov

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

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.

Table of Contents
  Setup..................................................|gopher.nvim-setup()|
  Install dependencies..............................|gopher.nvim-dependencies|
  Config..................................................|gopher.nvim-config|
  Commands..............................................|gopher.nvim-commands|
  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.
See |gopher.nvim.config|

Usage ~
>lua
 require("gopher").setup {} -- use default config or replace {} with your own
<
Parameters ~
{user_config} `(gopher.Config)` See |gopher.nvim-config|

------------------------------------------------------------------------------
                                                      *gopher.nvim-dependencies*
                             `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.
By default dependencies will be installed asynchronously,
to install them synchronously pass `{sync = true}` as an argument.


==============================================================================
------------------------------------------------------------------------------
                                                            *gopher.nvim-config*
                                `default_config`
>lua
  local default_config = {
    -- log level, you might consider using DEBUG or TRACE for debugging the plugin
    ---@type number
    log_level = vim.log.levels.INFO,

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

    -- user specified paths to binaries
    ---@class gopher.ConfigCommand
    commands = {
      go = "go",
      gomodifytags = "gomodifytags",
      gotests = "gotests",
      impl = "impl",
      iferr = "iferr",
    },
    ---@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)
      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-commands*

If don't want to automatically register plugins' commands,
you can set `vim.g.gopher_register_commands` to `false`, before loading the plugin.


==============================================================================
------------------------------------------------------------------------------
                                                       *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:
1. Place cursor on the struct
2. Run `:GoTagAdd json` to add json tags to struct fields
3. Run `:GoTagRm json` to remove json tags to struct fields

To clear all tags from struct run: `:GoTagClear`

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`
   }
<

==============================================================================
------------------------------------------------------------------------------
                                                              *gopher.nvim-impl*

Integration of `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

If you prefer named tests, you can enable them in |gopher.nvim-config|.


==============================================================================
------------------------------------------------------------------------------
                                                             *gopher.nvim-iferr*

`iferr` provides a way to way to automatically insert `if err != nil` check.
If you want to change `-message` option of `iferr` tool, see |gopher.nvim-config|

Usage ~
Execute `:GoIfErr` near any `err` variable to insert the check


==============================================================================
------------------------------------------------------------------------------
                                                          *gopher.nvim-comments*

This module provides a way to generate comments for Go code.

Usage ~
Set cursor on line with function/method/struct/etc and run `:GoCmt` to generate a comment.


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