code improvements; removed deprecated flags; added perf metrics; added interface gen support

Author: mobiletoly

README.md

@@ -56,16 +56,21 @@ person := Person{
 
 ## Installation
 
-Install **gobetter** and its dependency:
+Install **gobetter** as standalone utility:
 
 ```bash
-# Install goimports (for code formatting)
-go install golang.org/x/tools/cmd/goimports@latest
-
-# Install gobetter
 go install github.com/mobiletoly/gobetter@latest
 ```
 
+or (even better) install **gobetter** to use as tool in your go.mod:
+
+```
+tool (
+    github.com/mobiletoly/gobetter
+)
+```
+
+
 ## Quick Start
 
 ### 1. Annotate Your Structs
@@ -75,52 +80,64 @@ Add annotations to your Go structs:
 ```go
 package main
 
+// Put on top of the file
 //go:generate gobetter -input $GOFILE
 
 type Person struct { //+gob:Constructor
-    firstName   string  //+gob:getter
-    lastName    string  //+gob:getter
-    dob         string  //+gob:getter +gob:acronym
-    Score       int
-    Description string  //+gob:_
+	FirstName   string
+	LastName    string
+	email       string //+gob:getter
+	dob         string //+gob:getter +gob:acronym
+	Score       int
+	Description string //+gob:_
 }
 ```
 
+IMPORTANT: +gob:getter annotation must be used for private fields (starting with lowercase letter)
+only.
+
 ### 2. Generate Code
 
-Run the generator:
+Run the generator to generate all annotated structs:
 
 ```bash
 go generate ./...
 ```
 
+it will result in creating files with suffix `_gob.go` for each of your file that contains 
+annotated structs.
+
 ### 3. Use the Generated Builder
 
 ```go
 person := NewPersonBuilder().
     FirstName("John").
     LastName("Doe").
+	Email("john.doe@example.com").
     DOB("01/01/1990").
     Score(85).
     Build()
 
 // Set optional fields after building
 person.Description = "Software engineer"
 
-// Access private fields through getters
-fmt.Println(person.FirstName()) // "John"
-fmt.Println(person.DOB())       // "01/01/1990" (acronym handling)
+fmt.Println(person.FirstName)   // "John"
+fmt.Println(person.LastName)    // "Doe"
+fmt.Println(person.Email())     // "john.doe@example.com" (getter function to call from outside)
+fmt.Println(person.DOB())       // "01/01/1990" (getter function, acronym is DOB instead of dob)
+fmt.Println(person.Score)       // 85 (public field, no function needed)
+fmt.Println(person.Description) // "Software engineer"
 ```
 
 ## 📝 Annotations Reference
 
-| Annotation | Description | Example |
-|------------|-------------|---------|
-| `//+gob:Constructor` | Generate builder for struct | `type Person struct { //+gob:Constructor` |
-| `//+gob:constructor` | Generate package-level builder | `type person struct { //+gob:constructor` |
-| `//+gob:getter` | Generate getter for private field | `name string //+gob:getter` |
-| `//+gob:acronym` | Treat field as acronym (DOB vs Dob) | `dob string //+gob:getter +gob:acronym` |
-| `//+gob:_` | Mark field as optional (skip in builder) | `description string //+gob:_` |
+| Annotation           | Description                              | Example                                   |
+|----------------------|------------------------------------------|-------------------------------------------|
+| `//+gob:Constructor` | Generate builder for struct              | `type Person struct { //+gob:Constructor` |
+| `//+gob:constructor` | Generate package-level builder           | `type person struct { //+gob:constructor` |
+| `//+gob:getter`      | Generate getter for private field        | `name string //+gob:getter`               |
+| `//+gob:acronym`     | Treat field as acronym (DOB vs Dob)      | `dob string //+gob:getter +gob:acronym`   |
+| `//+gob:_`           | Mark field as optional (skip in builder) | `description string //+gob:_`             |
 
 ## 🏗️ Nested Structs Support
 
@@ -155,16 +172,22 @@ config := NewConfigBuilder().
     Build()
 ```
 
+Run:
+
+```bash
+go generate ./...
+go test -bench . -benchmem -run ^$ -count 5 ./...
+```
+
 ## Configuration Options
 
 ### Command Line Flags
 
-| Flag | Values | Description |
-|------|--------|-------------|
-| `-input` | `<file>` | Input file to process |
-| `-output` | `<file>` | Output file (default: `<input>_gob.go`) |
-| `-generate-for` | `all\|exported\|annotated` | Which structs to process |
-| `-constructor` | `exported\|package\|none` | Constructor visibility level |
+| Flag            | Values                     | Description                  |
+|-----------------|----------------------------|------------------------------|
+| `-input`        | `<path>`                   | Input file or directory      |
+| `-generate-for` | `all\|exported\|annotated` | Which structs to process     |
+| `-constructor`  | `exported\|package\|none`  | Constructor visibility level |
 
 ### Examples
 
@@ -179,11 +202,11 @@ gobetter -input=models.go -generate-for=exported
 gobetter -input=models.go -generate-for=all -constructor=package
 ```
 
-## IDE Integration
+## Optional IDE Integration
 
 ### IntelliJ IDEA / GoLand
 
-Set up a File Watcher for automatic generation:
+Set up a File Watcher for automatic generation (no need to run `go generate`):
 
 1. Go to **Preferences → Tools → File Watchers**
 2. Add **Custom** watcher:
@@ -193,4 +216,67 @@ Set up a File Watcher for automatic generation:
    - **Arguments**: `generate`
    - **Scope**: Create scope with pattern `file:*.go&&!file:*_gob.go`
 
-Now builders regenerate automatically when you save Go files!
+Now builders regenerate automatically when you save Go files
+
+
+## Performance
+
+**Summary:** For typical structs, gobetter’s step-builder is *as fast* as direct struct
+initialization and has the *same* allocation profile.
+
+- **CPU:** Direct literal ~19.8–20.8 ns/op; Builder chain ~20.1–24.1 ns/op in our latest run (
+  averages ≈ **20.18 ns/op** vs **21.64 ns/op**, respectively). The single-digit ns delta is within
+  typical microbenchmark variance and both approaches remain essentially equivalent for real
+  workloads.
+- **Allocations:** **1 alloc/op** (the single `*T` instance you ultimately build), **~96 B/op** for
+  the `Person` example. Step structs are tiny (a single pointer to the root) and stay on the **stack
+  **.
+- **Why it’s fast:**
+    - Setters are trivial field assignments that the compiler **inlines**.
+    - Step structs are returned **by value** and typically do **not escape** (escape analysis keeps
+      them on stack).
+    - `Build()` returns the same `*T` allocated once at the start of the chain — identical to
+      `&T{...}`.
+
+### Reproduce the benchmark
+
+```go
+func BenchmarkDirectLiteral(b *testing.B) {
+    b.ReportAllocs()
+    for i := 0; i < b.N; i++ {
+        p := &Person{firstName: "John", lastName: "Doe", dob: tDOB, Email: "john.doe@example.com"}
+        sink = p
+    }
+}
+
+func BenchmarkBuilderChain(b *testing.B) {
+    b.ReportAllocs()
+    for i := 0; i < b.N; i++ {
+        p := NewPersonBuilder().
+            FirstName("John").
+            LastName("Doe").
+            DOB(tDOB).
+            Email("john.doe@example.com").
+            GobFinalizer().
+            Build()
+        sink = p
+    }
+}
+```
+
+**Sample results (one machine):**
+
+```
+BenchmarkDirectLiteral-12    	57792015        	20.02 ns/op     	96 B/op  	1 allocs/op
+BenchmarkDirectLiteral-12    	59628193        	19.77 ns/op     	96 B/op  	1 allocs/op
+BenchmarkDirectLiteral-12    	59373484        	20.78 ns/op     	96 B/op  	1 allocs/op
+BenchmarkDirectLiteral-12    	57435504        	19.94 ns/op     	96 B/op  	1 allocs/op
+BenchmarkDirectLiteral-12    	55259538        	20.38 ns/op     	96 B/op  	1 allocs/op
+BenchmarkBuilderChain-12     	58040876        	20.08 ns/op     	96 B/op  	1 allocs/op
+BenchmarkBuilderChain-12     	57155670        	21.04 ns/op     	96 B/op  	1 allocs/op
+BenchmarkBuilderChain-12     	49360202        	22.16 ns/op     	96 B/op  	1 allocs/op
+BenchmarkBuilderChain-12     	54273560        	24.14 ns/op     	96 B/op  	1 allocs/op
+BenchmarkBuilderChain-12     	55646794        	20.80 ns/op     	96 B/op  	1 allocs/op
+```
+
+(Results vary by CPU/Go version and flags; use multiple runs with `-count` for stability.)

benchmark_test.go

@@ -12,7 +12,7 @@ func BenchmarkGenerateCode(b *testing.B) {
 	// Create a test input file
 	inputContent := `package test
 
-//go:generate gobetter -input $GOFILE
+//go:generate` + /*to avoid go:generate comment being executed*/ `gobetter -input $GOFILE
 
 type Person struct { //+gob:Constructor
 	firstName string //+gob:getter
@@ -51,10 +51,8 @@ type Company struct { //+gob:Constructor
 	}
 
 	config := &Config{
-		InputFile:             inputFile,
-		OutputFile:            filepath.Join(tmpDir, "test_gob.go"),
+		InputPath:             inputFile,
 		GenerateFor:           nil,
-		UsePtrReceiver:        false,
 		ConstructorVisibility: ConstructorExported,
 	}
 
@@ -72,7 +70,6 @@ func BenchmarkStructFieldGeneration(b *testing.B) {
 	sf := &StructField{
 		StructFlags: &StructFlags{
 			ProcessStruct: true,
-			PtrReceiver:   false,
 			Visibility:    ExportedVisibility,
 		},
 		StructName:    "Person",

constants.go

@@ -16,7 +16,6 @@ const (
 // Command line flag names
 const (
 	FlagInput       = "input"
-	FlagOutput      = "output"
 	FlagGenerateFor = "generate-for"
 	FlagReceiver    = "receiver"
 	FlagConstructor = "constructor"

example/person_bench_test.go

@@ -0,0 +1,39 @@
+package example
+
+import (
+	"testing"
+	"time"
+)
+
+var (
+	sink *Person
+	tDOB = time.Date(1990, 7, 1, 0, 0, 0, 0, time.UTC)
+)
+
+func BenchmarkDirectLiteral(b *testing.B) {
+	b.ReportAllocs()
+	for i := 0; i < b.N; i++ {
+		p := &Person{
+			firstName: "John",
+			lastName:  "Doe",
+			dob:       tDOB,
+			Email:     "john@example.com",
+			// Phone, Bio left nil (optional)
+		}
+		// prevent compiler from optimizing it away
+		sink = p
+	}
+}
+
+func BenchmarkBuilderChain(b *testing.B) {
+	b.ReportAllocs()
+	for i := 0; i < b.N; i++ {
+		p := NewPersonBuilder().
+			FirstName("John").
+			LastName("Doe").
+			DOB(tDOB).
+			Email("john@example.com").
+			Build()
+		sink = p
+	}
+}

example/structs.go

@@ -4,7 +4,15 @@ import (
 	"time"
 )
 
-//go:generate gobetter -input $GOFILE
+//go:generate ../gobetter -input $GOFILE
+
+type S struct { //+gob:Constructor
+	Identifier string
+	IO         interface {
+		Read([]byte) (int, error)
+		Close() error
+	}
+}
 
 // Person represents a person with basic information
 type Person struct { //+gob:Constructor