Documentation
¶
Overview ¶
Package ygen contains a library to generate Go structs from a YANG model. The Goyang parsing library is used to parse YANG. The output can consider OpenConfig-specific conventions such that the schema is compressed.
Index ¶
Constants ¶
const ( // DefaultYgotImportPath is the default import path used for the ygot library // in the generated code. DefaultYgotImportPath string = "github.com/openconfig/ygot/ygot" // DefaultYtypesImportPath is the default import path used for the ytypes library // in the generated code. DefaultYtypesImportPath string = "github.com/openconfig/ygot/ytypes" // DefaultGoyangImportPath is the default path for the goyang/pkg/yang library that // is used in the generated code. DefaultGoyangImportPath string = "github.com/openconfig/goyang/pkg/yang" )
const ( // DefaultBasePackageName defines the default base package that is // generated when generating proto3 code. DefaultBasePackageName = "openconfig" // DefaultEnumPackageName defines the default package name that is // used for the package that defines enumerated types that are // used throughout the schema. DefaultEnumPackageName = "enums" // DefaultYwrapperPath defines the default import path for the ywrapper.proto file, // excluding the filename. DefaultYwrapperPath = "github.com/openconfig/ygot/proto/ywrapper" // DefaultYextPath defines the default import path for the yext.proto file, excluding // the filename. DefaultYextPath = "github.com/openconfig/ygot/proto/yext" )
Constants defining the defaults for Protobuf package generation. These constants can be referred to by calling applications as defaults that are presented to a user.
Variables ¶
This section is empty.
Functions ¶
func BytesToGoByteSlice ¶
BytesToGoByteSlice takes an input slice of bytes and outputs it as a slice of strings corresponding to lines of Go source code that define the byte slice. Each string within the slice contains up to 16 bytes of the output byte array, with each byte represented as a two digit hex character.
func WriteGzippedByteSlice ¶
WriteGzippedByteSlice takes an input slice of bytes, gzips it and returns the resulting compressed output as a byte slice.
Types ¶
type GeneratedGoCode ¶
type GeneratedGoCode struct {
Structs []string // Structs is the generated set of structs representing containers or lists in the input YANG models.
Enums []string // Enums is the generated set of enum definitions corresponding to identities and enumerations in the input YANG models.
Header string // Header is the package-level header or the generated code.
EnumMap string // EnumMap is a Go map that allows the YANG string values of enumerated types to be resolved.
// JSONSchemaCode contains code defining a variable storing a serialised JSON schema for the
// generated Go structs. When deserialised it consists of a map[string]*yang.Entry. The
// entries are the root level yang.Entry definitions along with their corresponding
// hierarchy (i.e., the yang.Entry for /foo contains /foo/... - all of foo's descendents).
// Each yang.Entry which corresponds to a generated Go struct has two extra fields defined:
// - schemapath - the path to this entry within the schema. This is provided since the Path() method of
// the deserialised yang.Entry does not return the path since the Parent pointer is not
// populated.
// - structname - the name of the struct that was generated for the schema element.
JSONSchemaCode string
// RawJSONSchema stores the JSON document which is serialised and stored in JSONSchemaCode.
// It is populated only if the StoreRawSchema YANGCodeGenerator boolean is set to true.
RawJSONSchema []byte
// EnumTypeMap is a Go map that allows YANG schemapaths to be mapped to reflect.Type values.
EnumTypeMap string
}
GeneratedGoCode contains generated code snippets that can be processed by the calling application. The generated code is divided into two types of objects - both represented as a slice of strings: Structs contains a set of Go structures that have been generated, and Enums contains the code for generated enumerated types (corresponding to identities, or enumerated values within the YANG models for which code is being generated). Additionally the header with package comment of the generated code is returned in Header, along with the a slice of strings containing the packages that are required for the generated Go code to be compiled is returned.
For schemas that contain enumerated types (identities, or enumerations), a code snippet is returned as the EnumMap field that allows the string values from the YANG schema to be resolved. The keys of the map are strings corresponding to the name of the generated type, with the map values being maps of the int64 identifier for each value of the enumeration to the name of the element, as used in the YANG schema.
type GeneratedProto3 ¶
type GeneratedProto3 struct {
// Packages stores a map, keyed by the Protobuf package name, and containing the contents of the protobuf3
// messages defined within the package. The calling application can write out the defined packages to the
// files expected by the protoc tool.
Packages map[string]Proto3Package
}
GeneratedProto3 stores a set of generated Protobuf packages.
type GeneratorConfig ¶
type GeneratorConfig struct {
// CompressOCPaths indicates whether paths should be compressed in the output
// of an OpenConfig schema.
CompressOCPaths bool
// ExcludeModules specifies any modules that are included within the set of
// modules that should have code generated for them that should be ignored during
// code generation. This is due to the fact that some schemas (e.g., OpenConfig
// interfaces) currently result in overlapping entities (e.g., /interfaces).
ExcludeModules []string
// PackageName is the name that should be used for the generating package.
PackageName string
// Caller is the name of the binary calling the generator library, it is
// included in the header of output files for debugging purposes. If a
// string is not specified, the location of the library is utilised.
Caller string
// YANGParseOptions provides the options that should be handed to the
// //third_party/golang/goyang/pkg/yang library. These specify how the
// input YANG files should be parsed.
YANGParseOptions yang.Options
// GenerateFakeRoot specifies whether an entity that represents the
// root of the YANG schema tree should be generated in the generated
// code.
GenerateFakeRoot bool
// FakeRootName specifies the name of the struct that should be generated
// representing the root.
FakeRootName string
// GenerateJSONSchema stores a boolean which defines whether to generate
// the JSON corresponding to the YANG schema parsed to generate the
// output code.
GenerateJSONSchema bool
// StoreRawSchema the raw JSON schema should be returned by the code
// generation function, such that it can be handled by an external
// library.
StoreRawSchema bool
// GoOptions stores a struct which stores Go code generation specific
// options for the code generaton.
GoOptions GoOpts
// ProtoOptions stores a struct which contains Protobuf specific options.
ProtoOptions ProtoOpts
}
GeneratorConfig stores the configuration options used for code generation.
type GoOpts ¶
type GoOpts struct {
// SchemaVarName is the name for the variable which stores the compressed
// JSON schema in the generated Go code. JSON schema output is only
// produced if the GenerateJSONSchema YANGCodeGenerator field is set to
// true.
SchemaVarName string
// GoyangImportPath specifies the path that should be used in the generated
// code for importing the goyang/pkg/yang package.
GoyangImportPath string
// YgotImportPath specifies the path to the ygot library that should be used
// in the generated code.
YgotImportPath string
// YtypesImportPath specifies the path to ytypes library that should be used
// in the generated code.
YtypesImportPath string
}
GoOpts stores Go specific options for the code generation library.
type Proto3Package ¶
type Proto3Package struct {
FilePath []string // FilePath is the path to the file that this package should be written to.
Header string // Header is the header text to be used in the package.
Messages []string // Messages is a slice of strings containing the set of messages that are within the generated package.
Enums []string // Enums is a slice of string containing the generated set of enumerations within the package.
}
Proto3Package stores the code for a generated protobuf3 package.
type ProtoOpts ¶
type ProtoOpts struct {
// BaseImportPath stores the root URL or path for imports that are
// relative within the imported protobufs.
BaseImportPath string
// EnumPackageName stores the package name that should be used
// for the package that defines enumerated types that are used
// in multiple parts of the schema (identityrefs, and enumerations)
// that fall within type definitions.
EnumPackageName string
// YwrapperPath is the path to the ywrapper.proto file that stores
// the definition of the wrapper messages used to ensure that unset
// fields can be distinguished from those that are set to their
// default value. The path excluds the filename.
YwrapperPath string
// YextPath is the path to the yext.proto file that stores the
// definition of the extension messages that are used to annotat the
// generated protobuf messages.
YextPath string
// AnnotateSchemaPaths specifies whether the extensions defined in
// yext.proto should be used to annotate schema paths into the output
// protobuf file. See
// https://github.com/openconfig/ygot/blob/master/docs/yang-to-protobuf-transformations-spec.md#annotation-of-schema-paths
AnnotateSchemaPaths bool
// AnnotateEnumNames specifies whether the extensions defined in
// yext.proto should be used to annotate enum values with their
// original YANG names in the output protobuf file.
// See https://github.com/openconfig/ygot/blob/master/docs/yang-to-protobuf-transformations-spec.md#annotation-of-enums
AnnotateEnumNames bool
// NestedMessages indicates whether nested messages should be
// output for the protobuf schema. If false, a separate package
// is generated per package.
NestedMessages bool
}
ProtoOpts stores Protobuf specific options for the code generation library.
type YANGCodeGenerator ¶
type YANGCodeGenerator struct {
// Config stores the configuration parameters used for code generation.
Config GeneratorConfig
// contains filtered or unexported fields
}
YANGCodeGenerator is a structure that is used to pass arguments as to how the output Go code should be generated.
func NewYANGCodeGenerator ¶
func NewYANGCodeGenerator(c *GeneratorConfig) *YANGCodeGenerator
NewYANGCodeGenerator returns a new instance of the YANGCodeGenerator struct to the calling function.
func (*YANGCodeGenerator) GenerateGoCode ¶
func (cg *YANGCodeGenerator) GenerateGoCode(yangFiles, includePaths []string) (*GeneratedGoCode, *YANGCodeGeneratorError)
GenerateGoCode takes a slice of strings containing the path to a set of YANG files which contain YANG modules, and a second slice of strings which specifies the set of paths that are to be searched for associated models (e.g., modules that are included by the specified set of modules, or submodules of those modules). It extracts the set of modules that are to be generated, and returns a GeneratedGoCode struct which contains:
- A struct definition for each container or list that is within the specified set of models.
- Enumerated values which correspond to the set of enumerated entities (leaves of type enumeration, identities, typedefs that reference an enumeration) within the specified models.
If errors are encountered during code generation, an error is returned.
func (*YANGCodeGenerator) GenerateProto3 ¶
func (cg *YANGCodeGenerator) GenerateProto3(yangFiles, includePaths []string) (*GeneratedProto3, *YANGCodeGeneratorError)
GenerateProto3 generates Protobuf 3 code for the input set of YANG files. The YANG schemas for which protobufs are to be created is supplied as the yangFiles argument, with included modules being searched for in includePaths. It returns a GeneratedProto3 struct containing the messages that are to be output, along with any associated values (e.g., enumerations).
type YANGCodeGeneratorError ¶
type YANGCodeGeneratorError struct {
Errors []error
}
YANGCodeGeneratorError is a type implementing error that is returned to the caller of the library when errors are encountered during code generation. It implements error such that idiomatic if err != nil testing can be used, and contains a list of errors associted with the code generation call.
func NewYANGCodeGeneratorError ¶
func NewYANGCodeGeneratorError() *YANGCodeGeneratorError
NewYANGCodeGeneratorError returns a new instance of the YANGCodeGeneratorError struct with the relevant fields initialised.
func (*YANGCodeGeneratorError) Error ¶
func (yangErr *YANGCodeGeneratorError) Error() string
Error is a method of YANGCodeGeneratorError which returns a concatenated string of the errors that are stored within the YANGCodeGeneratorError struct. Its implementation allows a YANGCodeGeneratorError to implement the error interface.
Source Files