collections-gen

collections-gen

Code generator for mutable and immutable golang collections. collections-gen is built on top of gengo and can generate collections code based on tags in the doc blocks preceeding a type. It identifies the types needing code generation by the comment tag +collections-gen.

If you are looking for ready-to-use collections for builtin types and generic slices, check out the collections-go package.

Simple example

Given you have a type Foo, add the +collections-gen=true tag to the 1st or 2nd doc block preceeding the type definition:

// +collections-gen=true
//
// Foo is a custom type.
type Foo struct {
    ...
}

To generate a collection for the Foo type, run collections-gen with the input and output packages as arguments:

collections-gen -i pkg/path/to/foo -o pkg/path/to/generated/collection

For example:

collections-gen -i github.com/martinohmann/mylib/foo -o github.com/martinohmann/mylib/foo/collections

The code generator will generate the file foo_collection.go containing the FooCollection type in github.com/martinohmann/mylib/foo/collections.

Check out examples/simple for the example code.

Hint: You can also make use of go generate by adding a machine readable comment to your source files:

//go:generate collections-gen -i pkg/path/to/foo -o pkg/path/to/generated/collection

Afterwards you can generate your custom collections by running:

go generate ./...

Naming

By default the generated collections are named ElementTypeCollection and ImmutableElementTypeCollection for immutable collections, where ElementType is the element type of the collection. The default output files follow the same convention just in snake case: element_type_collection.go and immutable_element_type_collection.go. For overriding the naming behaviour have a look at the name and out-name options in the customizing generated collections section.

Customizing generated collections

To customize the generator behaviour for a given type, the comment tag +collections-gen:options can be added. Adding it multiple times causes the generation of multiple collection types. The +collections-gen:options tag accepts configuration flags of the following form:

// +collections-gen:options=flag1=value1,boolflag1,flag2=value2,boolflag2

Supported flags

Custom options example

// +collections-gen=true
//
// Generate FooCollection with *Foo element type.
//
// +collections-gen:options=pointer
//
// Generate an immutable collection with Foo element type and name
// BarCollection and write it into collection.go in the output package.
//
// +collections-gen:options=immutable,name=BarCollection,out-name=collection
//
// Foo is a custom type.
type Foo struct {
	Bar string
}

Check out the examples in the examples directory to see all options in action.

License

The source code of collections-gen is released under the MIT License. See the bundled LICENSE file for details.