Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 39 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,9 @@ func (dst *Request) CopyFrom(src *Request) {

*dst = *src
dst.Data = append(keepData, src.Data...)
if dst.Data == nil && src.Data != nil {
dst.Data = make([]byte, 0)
}
dst.Inner = keepInner
dst.Inner.CopyFrom(&src.Inner)
}
Expand All @@ -44,12 +47,29 @@ A `CopyFrom` into a pooled, already-sized `dst` allocates nothing.

| Field | Copy |
|---|---|
| slice | `append(dst.F[:0], src.F...)` — into dst's own array |
| slice | `append(dst.F[:0], src.F...)` — into dst's own array (nil only when src is nil and dst was: see below) |
| map | entry by entry into dst's own map (`clear` first; a nil dst map is made, a nil src leaves dst empty) |
| struct with `CopyFrom(*T)` | `dst.F.CopyFrom(&src.F)` |
| pointer to struct with `CopyFrom(*T)` | into dst's own object; a nil dst gets a new one, a nil src gives nil |
| array of slices / of structs with `CopyFrom` | element by element |
| array | element by element, when the elements need a copy of their own |
| slice of slices, maps, structs with `CopyFrom` or pointers to them | element by element into dst's own elements, up to its capacity (a larger src gets a new array) |
| map of slices, maps, structs with `CopyFrom` or pointers to them | each value a new copy (dst's old values are dropped with `clear`) |
| everything else (numbers, strings, pointers, interfaces, chans, funcs, plain structs) | assigned as it is |
| a type parameter `T` of a generic struct | assigned as it is, whatever the type argument (`Box[[]byte]` shares it) |

A non-nil src slice or map gives a non-nil dst one, even when empty, so
`[]` stays `[]` in JSON. A nil src slice or map empties dst's but leaves it
non-nil when it was — dst keeps its memory for the next copy — so after
`CopyFrom` a nil and an empty one are not told apart; `Copy` starts from a
zero dst and keeps them apart.

The rules apply at any depth: `[][]byte`, `map[string][]Inner` and
`[2][3][]byte` share nothing with src. A type that contains itself through
slices or maps (`type Tree []Tree`) has no end to copy: such a field needs a
tag. Map keys are assigned.

A generic struct gets `func (dst *Box[T]) CopyFrom(src *Box[T])`; a
`[]T` or `map[K]V` field is still copied as a slice or a map.

Struct tags change the treatment of a field:

Expand All @@ -58,8 +78,12 @@ Struct tags change the treatment of a field:
| `copy:"-"` | dst keeps its own value |
| `copy:"shallow"` | assigned as it is, even if it is a slice or a map — on purpose, and visibly |

A field holding a `sync` or `sync/atomic` type (also inside a nested struct
or array, by value) **must** carry one of the two tags; an array of maps too.
A field holding a lock **must** carry one of the two tags. A lock is what
`go vet` copylocks calls one — a type whose pointer is a `sync.Locker` while
the value is not, so a custom `noCopy` counts — and any other `sync` or
`sync/atomic` type except an interface (`sync.Locker` itself is assigned),
also inside a nested struct or array, by value. Blank (`_`) fields are never
copied: dst keeps its own.

## Two modes

Expand Down Expand Up @@ -99,16 +123,24 @@ type Request struct {
This writes `request_copy.gen.go` and `response_copy.gen.go` in the same
package. `-dir` points the generator at another package.

The generator is also a library — [`gocopy.Load`](https://pkg.go.dev/github.com/darxnet/gocopy#Load)
and [`Package.Generate`](https://pkg.go.dev/github.com/darxnet/gocopy#Package.Generate) —
The generator is also a library — [`gocopy.Load`](https://pkg.go.dev/github.com/darxnet/gocopy#Load),
[`Package.Generate`](https://pkg.go.dev/github.com/darxnet/gocopy#Package.Generate) and
[`Package.GenerateAll`](https://pkg.go.dev/github.com/darxnet/gocopy#Package.GenerateAll) —
for tools that want the source without the file.

## Rules of the generated CopyFrom

- `src` and `dst` must not be the same value or share slices: `dst`'s
arrays are overwritten.
- A nested type's `CopyFrom` is found by its method set when the generator
runs: generate (or write) the inner type's first.
runs, or because the same run generates it: name all the types of a package
in one `-type` list (one `go:generate` line), and the output does not depend
on their order or on the files already there. A type generated by another
directive is seen only once its file exists, so the first `go generate`
and the second could differ.
- A pointer to the type itself (`Next *Node`) is copied recursively, from
the first run: a long chain costs as much stack, and cyclic data (a ring)
never ends — tag such a field `copy:"shallow"` to share it instead.
- Pointers other than "pointer to a struct with CopyFrom" are shared with
`src`. That is usually right for references to long-lived objects; for
an owned object, give its type a `CopyFrom`.
Expand Down
22 changes: 13 additions & 9 deletions cmd/gocopy/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -49,22 +49,26 @@ func run(args []string, stderr io.Writer) int {
return 1
}

var typeNames []string

for typeName := range strings.SplitSeq(*typeFlag, ",") {
typeName = strings.TrimSpace(typeName)
if typeName == "" {
continue
if typeName = strings.TrimSpace(typeName); typeName != "" {
typeNames = append(typeNames, typeName)
}
}

src, err := pkg.Generate(typeName)
if err != nil {
say("%v", err)
// one run: the types see each other's CopyFrom before it is written
srcs, err := pkg.GenerateAll(typeNames...)
if err != nil {
say("%v", err)

return 1
}
return 1
}

for i, typeName := range typeNames {
name := filepath.Join(*dirFlag, gocopy.FileName(typeName))

if err := os.WriteFile(name, src, 0o600); err != nil {
if err := os.WriteFile(name, srcs[i], 0o600); err != nil {
say("gocopy: write %s: %v", name, err)

return 1
Expand Down
87 changes: 87 additions & 0 deletions cmd/gocopy/main_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,9 @@ package main
import (
"bytes"
"os"
"os/exec"
"path/filepath"
"slices"
"strings"
"testing"
)
Expand Down Expand Up @@ -120,3 +122,88 @@ func TestRunWriteError(t *testing.T) {
t.Fatalf("exit code %d, stderr %q, want a write error", code, stderr.String())
}
}

// TestRunIdempotent checks that a second run writes what the first did: a
// type sees the CopyFrom of a type generated in the same run (even listed
// after it), and of itself.
func TestRunIdempotent(t *testing.T) {
t.Parallel()

dir := t.TempDir()

for name, content := range map[string]string{
"go.mod": "module example.com/c\n\ngo 1.24\n",
"c.go": `package c

type Request struct {
In Inner
Ptr *Inner
}

type Inner struct{ B []byte }

type Node struct {
Next *Node
Data []byte
}
`,
"c_test.go": `package c

import "testing"

func TestCopy(t *testing.T) {
src := Request{In: Inner{B: []byte("a")}, Ptr: &Inner{B: []byte("b")}}
dst := src.Copy()
src.In.B[0], src.Ptr.B[0] = 'X', 'X'

if string(dst.In.B) != "a" || string(dst.Ptr.B) != "b" {
t.Fatalf("dst = %+v", dst)
}

list := Node{Next: &Node{Data: []byte("n")}}
cp := list.Copy()
list.Next.Data[0] = 'X'

if cp.Next == list.Next || string(cp.Next.Data) != "n" {
t.Fatal("Next must be copied")
}
}
`,
} {
if err := os.WriteFile(filepath.Join(dir, name), []byte(content), 0o600); err != nil {
t.Fatal(err)
}
}

files := []string{"request_copy.gen.go", "inner_copy.gen.go", "node_copy.gen.go"}
runs := make([][]string, 2)

for i := range runs {
var stderr bytes.Buffer

if code := run([]string{"-dir", dir, "-type", "Request,Inner,Node"}, &stderr); code != 0 {
t.Fatalf("run %d: exit code %d: %s", i, code, stderr.String())
}

for _, name := range files {
src, err := os.ReadFile(filepath.Join(dir, name)) //nolint:gosec // a path under t.TempDir()
if err != nil {
t.Fatal(err)
}

runs[i] = append(runs[i], string(src))
}
}

if !slices.Equal(runs[0], runs[1]) {
t.Fatalf("the second run differs:\n%s\n--- first run ---\n%s",
strings.Join(runs[1], "\n"), strings.Join(runs[0], "\n"))
}

cmd := exec.Command("go", "test", "-count=1", ".")
cmd.Dir = dir

if out, err := cmd.CombinedOutput(); err != nil {
t.Fatalf("go test: %v\n%s\n%s", err, out, strings.Join(runs[0], "\n"))
}
}
18 changes: 12 additions & 6 deletions doc.go
Original file line number Diff line number Diff line change
Expand Up @@ -5,21 +5,27 @@
// A generated CopyFrom(src) is one bulk assignment (*dst = *src) followed by
// fixes for the fields that would otherwise share memory: slices are copied
// into dst's own backing arrays (reusing their capacity), maps entry by entry
// into dst's own map, nested values with a CopyFrom through it. Pointers,
// interfaces, channels and funcs are assigned as they are. Struct tags choose
// a different treatment per field:
// into dst's own map, nested values with a CopyFrom through it — at any depth:
// the elements of a [][]byte or the values of a map[string][]byte get their
// own copies too. Pointers, interfaces, channels and funcs are assigned as
// they are. Struct tags choose a different treatment per field:
//
// Buf []byte `copy:"-"` // dst keeps its own value
// Table []byte `copy:"shallow"` // assigned as it is, on purpose
//
// A struct holding a lock or an atomic (also nested, by value) cannot be
// assigned as a whole: such fields must be tagged, the type is copied field
// by field, and it gets no Copy method.
// by field, and it gets no Copy method. A lock is what go vet copylocks calls
// one (a type whose pointer is a sync.Locker and value is not, so a custom
// noCopy too) and any other sync or sync/atomic type except an interface.
//
// The usual way to run it is a go:generate directive next to the type:
//
// //go:generate go tool gocopy -type=Request
//
// which writes request_copy.gen.go in the same package. [Load] and
// [Package.Generate] expose the generator to other tools.
// which writes request_copy.gen.go in the same package. Name all the types of
// a package in one -type list: a type sees the CopyFrom of another (or of
// itself) generated in the same run, so the output does not depend on their
// order or on the files already generated. [Load], [Package.Generate] and
// [Package.GenerateAll] expose the generator to other tools.
package gocopy
3 changes: 3 additions & 0 deletions export_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
package gocopy

var IsLocalName = isLocalName
Loading
Loading