sparsefieldsgen

Overview ¶

Command sparsefieldsgen generates typed string enums and per-list containers for v3 sparse fieldsets.

It scans a Go package for struct type declarations that carry either of two markers on their doc comment:

• sparsefields:gen [=CustomTypeName] Marks an entity struct (e.g. Task, Project). Emits a named string type plus one constant per JSON-tagged field on the struct (same-package embedded structs are flattened).

• sparsefields:list [=CustomTypeName] Marks a *ListResponse struct. Emits a typed container struct (e.g. TaskListFields) whose fields mirror the response's main slice and each entry of its Included sub-struct, plus an `apply(url.Values)` method that writes the appropriate fields[entityKey]=… query parameters via twapi.ApplySparseFields.

A third marker applies to individual fields of a marked *ListResponse:

• sparsefields:key=entityName Overrides the fields[...] entity key for that slot. The key otherwise defaults to the field's json tag, which is right whenever the response envelope key matches the entity name the API recognises. A handful of endpoints break that assumption — /projects/api/v3/projects/budgets.json wraps its payload in "budgets" while the entity is "projectBudgets" — and this marker is how they declare the divergence.

Usage (typically invoked via //go:generate from the target package):

//go:generate go run github.com/teamwork/twapi-go-sdk/internal/sparsefieldsgen

By default it scans the current working directory and writes `sparse_fields_gen.go` next to the sources. Both can be overridden with the -src and -out flags.