codegen

Documentation

Overview

Package codegen is a simple program, designed to be run from go:generate, that helps generate the annoying boilerplate to implement boardgame.PropertyReader and boardgame.PropertyReadSetter, as well as generating the boilerplate for enums.

You typically don't use this package directly, but instead use the `boardgame-util codegen` command. See `boardgam-util help codegen` for more.

Index

• func ProcessEnums(packageName string) (enumOutput string, err error)
• func ProcessReaders(location string) (output string, testOutput string, err error)

Functions

func ProcessEnums

func ProcessEnums(packageName string) (enumOutput string, err error)

ProcessEnums processes the given package and outputs the contents of a file representing the auto-generated boilerplate for those enums. If it finds a const() block at the top-level decorated with the magic comment (boardgame:codegen) it will generate enum boilerplate. See the package doc of enum for more on what you need to include.

auto-generated enums will automatically have values like prefixVeryLongName set to have a string value of "Very Long Name"; that is title-case will be taken to mean word boundaries. Enum values can be package-private (start with lower-case) or package public, but the two different types will be considered parts of different enums. If you want to transform the created values to lowercase or uppercase, include a line of `transform:lower` or `transform:upper`, respectively, in the comment lines immediately before the constant. `transform:none` means default behavior, leave as title case. If you want to change the default transform for an entire const group, have the transform line in the comment block above the constant block. If you want to override a specific item in the enum's name, include a comment immediately above that matches that pattern `display:"myVal"`, where myVal is the exact string to use. myVal may be zero-length, and may include quoted quotes. If your enum has a key that is named with the prefix of the rest of the enum values, and evaluates to 0, then a TreeEnum will be created. See the documentation in the enum package for how to control nesting in a TreeEnum. If enums are autogenerated, and the struct in your package that appears to be your gameDelegate doesn't already have a ConfigureEnums(), one will be generated for you.

If your enum contains a comment in its documentation like `combine:Foo` then set.Combine() will be additionally created, where each enum with that same combine name is combined together. As a special case, if the name is 'group' (the default group enum name), then boardgame.BaseGroupEnum will also be included into the group. Remember that enums that are combined can't overlap in any int or string keys. It's idiomatic to start the nth enum not with iota but `lastEnumMaxVal + 1 + iota` to automatically ensure no overlap.

func ProcessReaders

func ProcessReaders(location string) (output string, testOutput string, err error)

ProcessReaders operates on the package at the given relative location, and produces two strings, one that is appropriate to be saved in auto_reader.go, and one that is appropriate to be saved in auto_reader_test.go.

ProcessReaders processes a package of go files, searching for structs that have a comment immediately above their declaration that begins with "boardgame:codegen". For each such struct, it creates a Reader(), ReadSetter(), and ReadSetConfigurer() method that implement boardgame.Reader, boardgame.ReadSetter, and boardgame.ReadSetConfigurer, respectively.

Producing a ReadSetConfigurator requires a ReadSetter, and producing a ReadSetter requires a Reader. By default if you have the magic comment of `boardgame:codegen` it with produce all three. However, if you want only some of the methods, include an argument for the highest one you want, e.g. `boardgame:codegen readsetter` to generate a Reader() and ReadSetter().

This package will automatically create additional type transform methods to handle fields whose literal type is boardgame.ImmutableSizedStack, boardgame.SizedStack, boardgame.MergedStack, enum.RangeValue, and enum.TreeValue.

The outputted readers, readsetters, and readsetconfigurers use a hard- coded list of fields for performance (reflection would be about 30% slower under normal usage). You should re-generate output every time you add a struct or modify the fields on a struct.