Documentation
¶
Overview ¶
Package generator writes a Go SDK package from a service's definitions, the way Pandora's generator-go-sdk writes go-azure-sdk: it reads nothing but the definitions, and every decision it makes about the API was already made by the importer.
One package per server (BaseItemDto is everywhere, so per-tag packages would all import one another), laid out by tag in file names:
client.go Client and New
client_test.go the canned server the tests share
doc.go the package documentation
<tag>_method_<operation>.go one per operation: the method, its
<Name>Response, its
<Name>Options, and for list
operations a <Name>Complete pager
<tag>_method_<operation>_test.go the operation's test (tests.go)
<tag>_model_<model>.go one per model
<tag>_constants.go the tag's enums
Requests go through a base client, named in Options.ClientImport: pandorest's own (the client package), which this package's tests build and run a generated package against, or one a repository keeps of its own, with what the README says generated code calls.
Index ¶
- Constants
- func Check(svc *definitions.Service, dir string) (int, error)
- func Generate(svc *definitions.Service, opts Options) (int, error)
- func Generated(src []byte) bool
- func Render(svc *definitions.Service, opts Options) (map[string][]byte, error)
- func Uncalled(svc *definitions.Service, root string, skip ...string) (uncalled []string, total int, err error)
- type Options
Constants ¶
const Header = "// Code generated by pandorest; DO NOT EDIT.\n"
Header starts every generated file but doc.go; Generated is how to tell a generated file from one written by hand.
Variables ¶
This section is empty.
Functions ¶
func Check ¶
func Check(svc *definitions.Service, dir string) (int, error)
Check verifies that the package in dir, or the packages under it in the grouped layout, have a method on a Client for every operation in the definitions (and a Complete method for every list, a To method for a call answering a file), and returns how many operations it found. In the grouped layout each operation's method is looked for on the Client of its own group's package, as groups.json names it, under the name it is generated with there: a call drops its group's name (c.Pool.Query).
func Generate ¶
func Generate(svc *definitions.Service, opts Options) (int, error)
Generate writes the package and removes generated files it no longer produces. It returns the number of files written. A hand-written Go file where a generated one goes (a doc.go moved beside the types, say) is refused rather than overwritten.
func Generated ¶
Generated reports whether src is a file pandorest generated, which is how a stale one is recognised for removal and a hand-written one beside it left alone: every generated file starts with the header but the package's doc.go, which starts by saying pandorest generated it.
func Render ¶
Render produces every file of the package, formatted, by name: a path under Dir with slashes, for the grouped layout.
func Uncalled ¶ added in v0.7.0
func Uncalled(svc *definitions.Service, root string, skip ...string) (uncalled []string, total int, err error)
Uncalled lists the generated methods of a service that no hand-written Go file under root names, with how many methods there are: what the repository's own code never reaches, for a reader deciding what no tool wraps. A name counts wherever it is used as a selector, so a tool calling c.Items.GetItems counts, and a method of the same name on another type counts too, since the parse does not resolve types; a test file does not count, since a test naming a method is not a tool wrapping it. A call whose method drops its namespace in a package per namespace counts by its group and short name together, c.Pool.Query, since Query alone is every namespace's. Generated files, by their header, are left out, as is what is under skip.
Types ¶
type Options ¶
type Options struct {
// Dir is the package directory.
Dir string
// Definitions is the definitions directory, named in the package doc.
Definitions string
// Version is the version the document's file is named by, which the
// package declares as DocumentVersion; empty declares none.
Version string
// ClientImport is the import path of the base client the package sends
// its requests through.
ClientImport string
// Client, when set, is the source of client.go after its APIVersion
// constant, in place of the default (see config.Service.Client).
Client string
// ClientService, when set, names the client.Service in the package
// that the default client.go makes its client from.
ClientService string
// Credential and NewDoc word the default client.go's New in the
// service's own way (see config.Service).
Credential string
NewDoc string
// Notes is a paragraph added to the package documentation.
Notes string
// Grouped lays the SDK out as packages (see config.Service.Grouped):
// the types in Dir, a package per tag under it, and client. ImportPath
// is then Dir's import path, which the packages import one another by,
// and Packages names a tag's package where its lowercased name will not
// do.
Grouped bool
ImportPath string
Packages map[string]string
// ClientPackage names the grouped layout's client package; empty is
// client.
ClientPackage string
// InlineSingleOptions has an operation with one option take it as an
// argument in place of the struct (see config.Service).
InlineSingleOptions bool
}
Options says where a service's package goes, where it came from and what it is built on.