https://github.com/origadmin/adptool
https://github.com/origadmin/adptool
Last synced: 3 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/origadmin/adptool
- Owner: origadmin
- License: mit
- Created: 2025-08-06T12:47:36.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-12-29T21:31:33.000Z (6 months ago)
- Last Synced: 2026-01-02T04:25:57.005Z (6 months ago)
- Language: Go
- Size: 521 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# adptool
[](https://github.com/origadmin/adptool/actions/workflows/ci.yml)
[](https://github.com/origadmin/adptool/releases/latest)
[](https://goreportcard.com/report/github.com/origadmin/adptool)
[](https://opensource.org/licenses/MIT)
`adptool` is a powerful and highly configurable Go code generator that automates the creation of adapter code. It helps
you seamlessly integrate third-party libraries and internal modules by generating type aliases, function wrappers, and
method proxies based on a clear and powerful configuration system.
## Core Features
- **Automated Adapter Generation**: Eliminates boilerplate code by automatically generating type-safe adapters.
- **Flexible Configuration**: Use YAML, JSON, or TOML to define your code generation rules.
- **Hierarchical Rule System**: Apply rules globally, per-package, or for specific types, functions, and members.
- **Granular Renaming Control**: Precisely control naming with prefixes, suffixes, regular expressions, and explicit
from/to mappings.
- **Simple Source-Code Directives**: Use simple `//go:adapter` comments to mark packages for adaptation without
cluttering your code.
- **Dependency Decoupling**: Isolate your core logic from specific third-party implementations, making upgrades and
replacements easier.
## Installation
#### From Source
```bash
go install github.com/origadmin/adptool/cmd/adptool@latest
```
#### Pre-compiled Binaries
Visit the [**Releases Page**](https://github.com/origadmin/adptool/releases) to download a pre-compiled binary for your
platform.
---
## Quick Start
Let's adapt a fictional third-party library `github.com/foo/bar` into our project.
**1. Add a Directive**
Create a file (e.g., `adapters/directives.go`) to tell `adptool` which package you want to adapt.
```go
// adapters/directives.go
package myapp
//go:adapter:package github.com/foo/bar
```
**2. Create a Configuration File**
`adptool` needs rules to work. Create an `.adptool.yaml` file in your project root.
```yaml
# .adptool.yaml
# Set the package name for the generated file.
package_name: "myapp"
# Define a global rule: add the prefix "MyApp_" to all types from the adapted package.
types:
- prefix: "MyApp_"
```
**3. Run adptool**
Execute the tool, pointing it to the directory containing your directive file.
```bash
adptool ./adapters
```
**4. Get the Generated Code**
`adptool` will create a new file `adapters/generate.adapter.go` in the same directory, containing the adapted code:
```go
// Code generated by adptool. DO NOT EDIT.
//
// This file is generated from directives.go.
// Package myapp contains generated code by adptool.
package myapp
import (
bar "github.com/foo/bar"
)
// Renamed from "Client" with the "MyApp_" prefix.
type MyApp_Client = bar.Client
// Renamed from "Config" with the "MyApp_" prefix.
type MyApp_Config = bar.Config
// ... and so on for all other types in the package.
```
---
## Usage
### Command-Line Interface (CLI)
```sh
adptool [flags] [arguments...]
```
**Arguments**
- `[arguments...]` (required): One or more Go source files or directories to scan for directives. Supports `...`
wildcard syntax (e.g., `./...`).
**Flags**
- `-c, --config `
- Specifies the path to a configuration file (YAML, JSON, or TOML). If not provided, `adptool` automatically
searches for `.adptool.yaml` (or `.json`, `.toml`) in the current directory and a `./configs` subdirectory.
- `--copyright-holder `
- Injects a copyright notice into the generated file's header.
- `-o, --output ` (Planned)
- Specifies a single file path for all generated output code. Currently, output files are generated automatically
alongside their source directive files.
- `-v, --verbose` (Planned)
- Enables verbose logging for debugging.
### Directives
Directives are comments in your Go source code that `adptool` uses as entry points.
- `//go:adapter:package [alias]`
- This is the primary directive. It tells `adptool` to adapt the package specified by ``.
- You can optionally provide a custom `[alias]` for the package in the generated code.
```go
// Adapt the package, letting the generator create an alias.
//go:adapter:package github.com/spf13/viper
// Adapt the package and give it a specific alias.
//go:adapter:package github.com/google/uuid custom_uuid
```
## Configuration
`adptool` is controlled by a configuration file (e.g., `.adptool.yaml`). For fully-commented examples, see the [*
*`./examples`**](./examples) directory.
Here is a high-level overview of the main configuration sections:
- `package_name`: Sets the package name for the generated file.
- `ignores`: A list of symbol names to exclude from generation. Supports wildcards (`*`).
- `defaults`: Sets the default behavior for how rules are applied (e.g., `prepend` or `replace` for prefixes).
- `props`: A list of key-value pairs that can be used as variables in other parts of the configuration.
- `packages`: A list of package-specific rules that override the global rules.
- `types`, `functions`, `variables`, `constants`: These sections contain the core renaming rules for different kinds of
Go declarations.
### Rule Priority
For any given symbol, rules are resolved and applied in the following order:
1. **Ignore**: If a symbol matches an `ignores` rule, it is skipped entirely.
2. **Explicit**: If an `explicit` rule (`from`/`to`) matches the symbol, it is renamed, and **no further rules apply**.
3. **Prefix & Suffix**: If no explicit rule matches, the resolved `prefix` and `suffix` are applied.
4. **Regex**: The resolved `regex` rules are applied to the result of the previous step.
## Contributing
Contributions are welcome! Please feel free to submit an Issue or Pull Request.
## License
`adptool` is released under the [MIT License](LICENSE).