ygen

package
v0.7.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 19, 2020 License: Apache-2.0 Imports: 20 Imported by: 24

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

View Source 
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.

View Source 
const (

	// DefaultAnnotationPrefix is the default string that is used to prefix the name
	// of metadata fields in the output Go structs.
	DefaultAnnotationPrefix string = "Λ"
)

Variables

This section is empty.

Functions

func BytesToGoByteSlice 

func BytesToGoByteSlice(b []byte) []string

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 FindSchemaPath added in v0.7.0 

func FindSchemaPath(parent *Directory, fieldName string, absolutePaths bool) ([]string, error)

FindSchemaPath finds the relative or absolute schema path of a given field of a Directory. The Field is specified as a name in order to guarantee its existence before processing.

func GetOrderedDirectories added in v0.7.0 

func GetOrderedDirectories(directory map[string]*Directory) ([]string, map[string]*Directory, error)

GetOrderedDirectories returns an alphabetically-ordered slice of Directory names and a map of Directories keyed by their names instead of their paths, so that each directory can be processed in alphabetical order. This helps produce deterministic generated code, and minimize diffs when compared with expected output (i.e., diffs don't appear simply due to reordering of the Directory maps). If the names of the directories are not unique, which is unexpected, an error is returned.

func GetOrderedFieldNames added in v0.7.0 

func GetOrderedFieldNames(directory *Directory) []string

GetOrderedFieldNames returns the field names of a Directory in alphabetical order.

func GoFieldNameMap added in v0.7.0 

func GoFieldNameMap(directory *Directory) map[string]string

GoFieldNameMap returns a map containing the Go name for a field (key is the field schema name). Camelcase and uniquification is done to ensure compilation. Naming uniquification is done deterministically.

func IsFakeRoot added in v0.7.0 

func IsFakeRoot(e *yang.Entry) bool

IsFakeRoot checks whether a given entry is the generated fake root.

func IsScalarField added in v0.7.0 

func IsScalarField(field *yang.Entry, t *MappedType) bool

IsScalarField determines which fields should be converted to pointers when outputting structs; this is done to allow checks against nil.

func IsYgenDefinedGoType added in v0.7.0 

func IsYgenDefinedGoType(t *MappedType) bool

IsYgenDefinedGoType returns true if the native type of a MappedType is a Go type that's defined by ygen's generated code.

func MakeFakeRoot added in v0.7.0 

func MakeFakeRoot(rootName string) *yang.Entry

MakeFakeRoot creates and returns a fakeroot *yang.Entry with rootName as its name. It has an empty, but initialized Dir.

func WriteGzippedByteSlice 

func WriteGzippedByteSlice(b []byte) ([]byte, error)

WriteGzippedByteSlice takes an input slice of bytes, gzips it and returns the resulting compressed output as a byte slice.

Types

type Directory added in v0.7.0 

type Directory struct {
	Name       string                 // Name is the name of the struct to be generated.
	Entry      *yang.Entry            // Entry is the yang.Entry that corresponds to the schema element being converted to a struct.
	Fields     map[string]*yang.Entry // Fields is a map, keyed by the YANG node identifier, of the entries that are the struct fields.
	Path       []string               // Path is a slice of strings indicating the element's path.
	ListAttr   *YangListAttr          // ListAttr is used to store characteristics of structs that represent YANG lists.
	IsFakeRoot bool                   // IsFakeRoot indicates that the struct is a fake root struct, so specific mapping rules should be implemented.
}

Directory stores information needed for outputting a data node of the generated code. When viewed as a collection of entries that is generated from an entire YANG schema, they serve the purpose of mapping the YANG schema tree to a directory tree (connected through implicit yang.Entry edges) where each directory corresponds to a data node of the Go version of the schema, and where digested data is stored that is friendly to the code generation algorithm.

type DirectoryGenConfig added in v0.7.0 

type DirectoryGenConfig struct {
	// ParseOptions contains parsing options for a given set of schema files.
	ParseOptions ParseOpts
	// TransformationOptions contains options for how the generated code
	// may be transformed from a simple 1:1 mapping with respect to the
	// given YANG schema.
	TransformationOptions TransformationOpts
}

DirectoryGenConfig contains the configuration necessary to generate a set of Directory objects for a given schema. The set of Directory objects is the intermediate representation generated by ygen, which can be useful for external code generation libraries which can make use of it.

func (*DirectoryGenConfig) GetDirectoriesAndLeafTypes added in v0.7.0 

func (dcg *DirectoryGenConfig) GetDirectoriesAndLeafTypes(yangFiles, includePaths []string) (map[string]*Directory, map[string]map[string]*MappedType, util.Errors)

GetDirectoriesAndLeafTypes parses YANG files and returns two path-keyed maps. The first contains Directory entries that is the intermediate representation used by ygen for subsequent code generation, and the second contains the *MappedType for each field of the same corresponding Directory entries, with non-leafs having a nil value. This representation may be useful to external code generation libraries that make use of such information, e.g. if their output code depends on a ygen-generated type. yangFiles is a slice of strings containing the path to a set of YANG files which contain YANG modules, includePaths is 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). Any errors encountered during code generation are returned.

type GeneratedGoCode 

type GeneratedGoCode struct {
	Structs      []GoStructCodeSnippet // 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.
	CommonHeader string                // CommonHeader is the header that should be used for all output Go files.
	OneOffHeader string                // OneOffHeader defines the header that should be included in only one output Go file - such as package init statements.
	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 {
	// 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
	// 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
	// ParseOptions contains parsing options for a given set of schema files.
	ParseOptions ParseOpts
	// TransformationOptions contains options for how the generated code
	// may be transformed from a simple 1:1 mapping with respect to the
	// given YANG schema.
	TransformationOptions TransformationOpts
	// 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
	// GenerateRenameMethod specifies whether methods for renaming list entries
	// should be generated in the output Go code.
	GenerateRenameMethod bool
	// AddAnnotationFields specifies whether annotation fields should be added to
	// the generated structs. When set to true, a metadata field is added for each
	// struct, and for each field of each struct. Metadata field's names are
	// prefixed by the string specified in the AnnotationPrefix argument.
	AddAnnotationFields bool
	// AnnotationPrefix specifies the string which is prefixed to the name of
	// annotation fields. It defaults to Λ.
	AnnotationPrefix string
	// GenerateGetters specifies whether GetOrCreate* methods should be created
	// for struct pointer (YANG container) and map (YANG list) fields of generated
	// structs.
	GenerateGetters bool
	// GenerateDeleteMethod specifies whether Delete* methods should be created for
	// map (YANG list) fields of generated structs.
	GenerateDeleteMethod bool
	// GenerateAppendList specifies whether Append* methods should be created for
	// list fields of a struct. These methods take an input list member type, extract
	// the key and append the supplied value to the list.
	GenerateAppendMethod bool
	// GenerateLeafGetters specifies whether Get* methods should be created for
	// leaf fields of a struct. Care should be taken with this option since a Get
	// method returns the *Go* zero value for a particular entity if the field is
	// unset. This means that it is not possible for a caller of method to know
	// whether a field has been explicitly set to the zero value (i.e., an integer
	// field is set to 0), or whether the field was actually unset.
	GenerateLeafGetters bool
	// GNMIProtoPath specifies the path to the generated gNMI protobuf, which
	// is used to store the catalogue entries for generated modules.
	GNMIProtoPath string
	// IncludeModelData specifies whether gNMI ModelData messages should be generated
	// in the output code.
	IncludeModelData bool
}

GoOpts stores Go specific options for the code generation library.

type GoStructCodeSnippet added in v0.6.0 

type GoStructCodeSnippet struct {
	// StructName is the name of the struct that is contained within the snippet.
	// It is stored such that callers can identify the struct to control where it
	// is output.
	StructName string
	// StructDef stores the code snippet that represents the struct that is
	// the input when code generation is performed.
	StructDef string
	// ListKeys stores code snippets that are associated with structs that are
	// generated to represent the keys of multi-key lists. In the case that the
	// Go struct for which the code is being generated does not contain a list
	// with multiple keys, this string is empty.
	ListKeys string
	// Methods contains code snippsets that represent functions that have the
	// input struct as a receiver, that help the user create new entries within
	// lists, without needing to populate the keys of the list.
	Methods string
	// Interfaces contains code snippets that represent interfaces that are
	// used within the generated struct. Used when there are interfaces that
	// represent multi-type unions generated.
	Interfaces string
	// contains filtered or unexported fields
}

GoStructCodeSnippet is used to store the generated code snippets associated with a particular Go struct entity (generated from a container or list).

func (GoStructCodeSnippet) String added in v0.6.0 

func (g GoStructCodeSnippet) String() string

String returns the contents of the receiver GoStructCodeSnippet as a string.

type MappedType added in v0.7.0 

type MappedType struct {
	// NativeType is the type which is to be used for the mapped entity.
	NativeType string
	// UnionTypes is a map, keyed by the generated type name, of the types
	// specified as valid for a union. The value of the map indicates the
	// order of the type, since order is important for unions in YANG.
	// Where two types are mapped to the same generated language type
	// (e.g., string) then only the order of the first is maintained. Since
	// the generated code from the structs maintains only type validation,
	// this is not currently a limitation.
	UnionTypes map[string]int
	// IsEnumeratedValue specifies whether the NativeType that is returned
	// is a generated enumerated value. Such entities are reflected as
	// derived types with constant values, and are hence not represented
	// as pointers in the output code.
	IsEnumeratedValue bool
	// ZeroValue stores the value that should be used for the type if
	// it is unset. This is used only in contexts where the nil pointer
	// cannot be used, such as leaf getters.
	ZeroValue string
	// DefaultValue stores the default value for the type if is specified.
	// It is represented as a string pointer to ensure that default values
	// of the empty string can be distinguished from unset defaults.
	DefaultValue *string
}

MappedType is used to store the generated language type that a leaf entity in YANG is mapped to. The NativeType is always populated for any leaf. UnionTypes is populated when the type may have subtypes (i.e., is a union). enumValues is populated when the type is an enumerated type.

The code generation explicitly maps YANG types to corresponding generated language types. In the case that an explicit mapping is not specified, a type will be mapped to an empty interface (interface{}). For an explicit list of types that are supported, see the yangTypeTo*Type functions in this package.

type ParseOpts added in v0.7.0 

type ParseOpts struct {
	// 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
	// YANGParseOptions provides the options that should be handed to the
	// github.com/openconfig/goyang/pkg/yang library. These specify how the
	// input YANG files should be parsed.
	YANGParseOptions yang.Options
	// SkipEnumDeduplication specifies whether leaves of type 'enumeration' that
	// are used in multiple places in the schema should share a common type within
	// the generated code that is output by ygen. By default (false), a common type
	// is used.
	//
	// This behaviour is useful in scenarios where there is no difference between
	// two types, and the leaf is mirrored in a logical way (e.g., the OpenConfig
	// config/state split). For example:
	//
	// grouping foo-config {
	//	leaf enabled {
	//		type enumeration {
	//			enum A;
	//			enum B;
	//			enum C;
	//		}
	//	 }
	// }
	//
	//  container config { uses foo-config; }
	//  container state { uses foo-config; }
	//
	// will result in a single enumeration type (ModuleName_Config_Enabled) being
	// output when de-duplication is enabled.
	//
	// When it is disabled, two different enumerations (ModuleName_(State|Config)_Enabled)
	// will be output in the generated code.
	SkipEnumDeduplication bool
}

ParseOpts contains parsing configuration for a given schema.

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 TransformationOpts added in v0.7.0 

type TransformationOpts struct {
	// CompressBehaviour specifies how the set of direct children of any
	// entry should determined. Specifically, whether compression is
	// enabled, and whether state fields in the schema should be excluded.
	CompressBehaviour genutil.CompressBehaviour
	// 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
	// ExcludeState specifies whether config false values should be
	// included in the generated code output. When set, all values that are
	// not writeable (i.e., config false) within the YANG schema and their
	// children are excluded from the generated code.
	ExcludeState bool
}

TransformationOpts specifies transformations to the generated code with respect to the input schema.

type YANGCodeGenerator 

type YANGCodeGenerator struct {
	// Config stores the configuration parameters used for code generation.
	Config GeneratorConfig
}

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, util.Errors)

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:

  1. A struct definition for each container or list that is within the specified set of models.
  2. 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, util.Errors)

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 YangListAttr added in v0.7.0 

type YangListAttr struct {
	// keys is a map, keyed by the name of the key leaf, with values of the type
	// of the key of a YANG list.
	Keys map[string]*MappedType
	// keyElems is a slice containing the pointers to yang.Entry structs that
	// make up the list key.
	KeyElems []*yang.Entry
}

YangListAttr is used to store the additional elements for a Go struct that are required if the struct represents a YANG list. It stores the name of the key elements, and their associated types, along with pointers to those elements.

Source Files

View all Source files

Directories

Path Synopsis
Package schematest is used for testing with the default OpenConfig generated structs.
 Package schematest is used for testing with the default OpenConfig generated structs.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.