replacer

README

Replacer

Replacer is a Go code generator that applies regex-based transformations to your source files. It is designed to work with Go's //go:generate directive, allowing you to automate repetitive code modifications.

Why?

I often need to repeat the same set of comments in my Go code. For example, I use swaggo to generate Swagger documentation for an API. My API endpoints always return the same headers, like X-API-Version or X-Request-ID. Unfortunately, there's no way to define common headers for all endpoints yet. Instead of manually copying and pasting these headers every time, I created replacer to automate this process. Now, I can simply write:

// @COMMON-HEADERS

run go generate, which is a part of my build pipeline, and get:

// @Header       all {string} X-Request-ID "UUID of the request"
// @Header       all {string} X-API-Version "API version, e.g. v1alpha"
// @Header       all {int} X-Ratelimit-Limit "Rate limit value"
// @Header       all {int} X-Ratelimit-Remaining "Rate limit remaining"
// @Header       all {int} X-Ratelimit-Reset "Rate limit reset interval in seconds"

Why not use sed or awk?

In short, it's hard to maintain when you have a lot of transformations, rules look more complicated. Also, there is a huge issues with multi-platform support. Even, unix-like macos and linux have different versions of sed and awk.

IDE's snippets?

IDE's snippets are great, but it's hard to maintain them in a team. Also, it's hard to share them between different IDE's.

Features

• Full-featured regex (docs), including expands
• Automatically searches for a configuration file (.replacer.yml or .replacer.yaml) in the current directory and parent directories.
• Stops searching at the root directory or when a go.mod file is encountered.

Installation

To install replacer, run:

go install github.com/weastur/replacer/cmd/replacer@latest

Make sure that $GOPATH/bin is in your $PATH.

Of course, you can also download the binary from the releases page

Usage

1. Create a configuration file (.replacer.yml or .replacer.yaml) in the root of your project or in the directory where you want to run replacer.

   ---
   rules:
   - regex: '(?m)^\/\/ MY RULE$'
     repl: |-
       // MY NEW AWESOME
       // MULTI-LINE REPLACEMENT
   - regex: '(?m)^\/\/ MY 2 RULE$'
     repl: |-
       // REPLACEMENT No2
   - regex: '(?m)^\/\/ (?P<group>\w+) are also work$'
     repl: |-
       // ${group} are great
   

2. Add a //go:generate directive to your source file. Despite config search mechanism, the transformation rules will be applied only to the file where the directive is placed.

   //go:generate replacer
   

3. Run go generate to apply the transformations.

   go generate ./...
   

   Pay attention that generate command will only work if you have the replacer binary in your $PATH.

   Also, the go build command doesn't run go generate automatically. You need to run it manually. Refer to go help generate for more information.

4. Optional Flags:

   • -config - specify the path to the configuration file.

     Example: //go:generate replacer -config my-replacer-config.yml

Configuration file search

If the -config flag is not provided, replacer will search for a configuration file in the following order:

1. The current directory.
2. Parent directories, moving up one level at a time.
3. Stops searching when it reaches the root directory or encounters a go.mod file.

Development

See CONTRIBUTING.md for information on how to contribute to replacer.

tl;dr

# fork/clone the repository
# install go, direnv, pre-commit hooks
# put some config in .replacer.yml
make build
make test
GOFILE=my-test-file.go replacer
# commit/push/PR

Project structure

• cmd/replacer - the main command.
• internal/config - handles configuration file parsing and validation.
• internal/replacer - applies regex-based transformations to source files.

Security

Refer to the SECURITY.md file for more information.

License

Mozilla Public License 2.0

Refer to the LICENSE file for more information.