goinject

README

goinject

goinject is a wrapper library for creating Go preprocessors.

Usage

goinject allows you to create custom preprocessors by defining a struct that satisfies the Modifier interface. This interface has only one method, Modify, which accepts a (*dst.File, *decorator.Decorator, *decorator.Restorer) representing the AST of a Go source file, file decorator and imports restorer. This method must return a modified *dst.File.

Process Function

The goinject.Process function represents the generalized approach to preprocessing Go code. It performs the following steps:

1. Checks if we are at the right stage of compilation.
2. If not, runs the original command and returns.
3. Extracts the files that Go is about to compile.
4. Makes changes to the AST of all the files (without modifying the original source code).
5. Writes the modified files to a temporary directory.
6. Resolves all missing imports that were added as part of the modification.
7. Substitutes the path to the original files with the path to the modified files and passes them to the compiler command.
8. Runs the original command with the substituted files to be compiled.

Example

Here's an example of how you can use goinject to modify a Go source file:

package main

import (
	"github.com/pijng/goinject"
)

// CustomModifier implements the Modifier interface
type CustomModifier struct{}

// Modify implements the Modify method of the Modifier interface
func (cm CustomModifier) Modify(f *dst.File, dec *decorator.Decorator, res *decorator.Restorer) *dst.File {
	// Add custom modification logic here
	return f
}

func main() {
	// Call goinject.Process with an instance of your modifier struct
	goinject.Process(CustomModifier{})
}

In this example, CustomModifier is a struct that satisfies the Modifier interface. It implements the Modify method, where you can define your custom modification logic.

Demonstration

• go_otel_auto_instrument: go_otel_auto_instrument is a preprocessor that automatically inject Opentelemtry tracing into your Go code.
• prep: prep is a small Go tool that enables compile-time function evaluation.
• go-ifdef: go-ifdef is a preprocessor that allows you to use trivial #ifdef and #else directives based on the GOOS environment variable.

Documentation

Index

• func Process(modifier Modifier, opts ...Option)
• func ResolvePkg(pkgName string) (map[string]string, error)
• type Logger
• type Modifier
• type Option
  • func WithLogger(logger Logger) Option

Functions

func Process

func Process(modifier Modifier, opts ...Option)

How to use this library to build you own preprocessor:

1. Create a new project for your own preprocessor.

2. Define a struct that will satisfy Modifier interface. Modifier has only one method [Modify] that must accept (*dst.File, *decorator.Decorator, *decorator.Restorer) as arguments, and must return a modified *dst.File.

   All the modifications you want to make should be called inside your Modify method.

3. In a main function of your preprocessor project simply call:

   goinject.Process(YourModifierStruct{})

4. Build your preprocessor with just a `go build`

5. Call a newly compiled preprocessor on your target project like this:

   go build -toolexec="absolute/path/to/your/preprocessor/binary" main.go

Process function represents the generalized approach to preprocessing go code. It:

1. Checks if we are at the right stage of compilation;
2. If not, runs the original command and return;
3. Extract the files that go is about to compile;
4. Make the changes to the AST of all the files (this won't affect the source code);
5. Writes the modified files to the temporary directory;
6. Resolve all missing imports that were added as part of the modification;
7. Substitutes the path to the original files with the path to modified files and pass them to the compiler command;
8. Runs the original command with an already substituted files to be compiled.

func ResolvePkg

func ResolvePkg(pkgName string) (map[string]string, error)

ResolvePkg will try to collect all the named go packages. It utilizes `go list -deps -export -json -- <pkgName>` command. The most important part here is the -export flag, because it will give us the actual path to the compiled package by its name. Then, we can use this path as a value when adding missing package to importcfg in form of `packagefile {pkgName}={path}`

Types

type Logger

type Logger interface {
	Printf(format string, v ...any)
}

type Modifier

type Modifier interface {
	Modify(*dst.File, *decorator.Decorator, *decorator.Restorer) *dst.File
}

type Option

type Option func(*config)

func WithLogger

func WithLogger(logger Logger) Option