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), and returns how many operations it found.
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. 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.