https://github.com/weastur/replacer
Replacer is a go generator to find-and-replace in go source files
https://github.com/weastur/replacer
code-generation go-generate golang regex
Last synced: 9 months ago
JSON representation
Replacer is a go generator to find-and-replace in go source files
- Host: GitHub
- URL: https://github.com/weastur/replacer
- Owner: weastur
- License: mpl-2.0
- Created: 2025-03-17T15:13:43.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-04-01T17:32:24.000Z (9 months ago)
- Last Synced: 2025-04-01T18:41:02.867Z (9 months ago)
- Topics: code-generation, go-generate, golang, regex
- Language: Go
- Homepage:
- Size: 85.9 KB
- Stars: 10
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Citation: CITATION.cff
- Security: SECURITY.md
- Authors: AUTHORS
Awesome Lists containing this project
README
# Replacer
[](https://goreportcard.com/report/github.com/weastur/replacer)
[](https://codecov.io/gh/weastur/replacer)
[](https://github.com/weastur/replacer/actions/workflows/test.yaml)
[](https://github.com/weastur/replacer/actions/workflows/lint.yaml)
[](https://github.com/weastur/replacer/actions/workflows/gitlint.yaml)
[](https://results.pre-commit.ci/latest/github/weastur/replacer/main)
**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](https://github.com/swaggo/swag) 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:
```go
// @COMMON-HEADERS
```
run `go generate`, which is a part of my build pipeline, and get:
```go
// @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](https://pkg.go.dev/regexp)), including [expands](https://pkg.go.dev/regexp#Regexp.Expand)
- 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:
```bash
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](https://github.com/weastur/replacer/releases)
## 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`.
```yaml
---
rules:
- regex: '(?m)^\/\/ MY RULE$'
repl: |-
// MY NEW AWESOME
// MULTI-LINE REPLACEMENT
- regex: '(?m)^\/\/ MY 2 RULE$'
repl: |-
// REPLACEMENT No2
- regex: '(?m)^\/\/ (?P\w+) are also work$'
repl: |-
// ${group} are great
```
1. Add a `//go:generate` directive to your source file.
Despite [config search mechanism](#configuration-file-search), the transformation
rules will be applied **only** to the file
where the directive is placed.
```go
//go:generate replacer
```
1. Run `go generate` to apply the transformations.
```bash
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.
1. 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.
1. Parent directories, moving up one level at a time.
1. Stops searching when it reaches the root directory or encounters a go.mod file.
## Development
See [CONTRIBUTING.md](CONTRIBUTING.md) for information on how to contribute to `replacer`.
### tl;dr
```bash
# 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](SECURITY.md) file for more information.
## License
Mozilla Public License 2.0
Refer to the [LICENSE](LICENSE) file for more information.