protogen

Documentation

Overview

Package protogen contains code for generating proto code given YANG input.

Index

• Constants
• type CodeGenerator
  • func New(callerName string, opts ygen.IROptions, protoOpts ProtoOpts) *CodeGenerator
  • func (cg *CodeGenerator) Generate(yangFiles, includePaths []string) (*GeneratedCode, util.Errors)
• type GeneratedCode
• type Proto3Package
• type ProtoLangMapper
  • func NewProtoLangMapper(basePackageName, enumPackageName string) *ProtoLangMapper
  • func (s *ProtoLangMapper) DirectoryName(e *yang.Entry, cb genutil.CompressBehaviour) (string, error)
  • func (s *ProtoLangMapper) FieldName(e *yang.Entry) (string, error)
  • func (s *ProtoLangMapper) KeyLeafType(e *yang.Entry, opts ygen.IROptions) (*ygen.MappedType, error)
  • func (s *ProtoLangMapper) LeafType(e *yang.Entry, opts ygen.IROptions) (*ygen.MappedType, error)
  • func (s *ProtoLangMapper) PackageName(e *yang.Entry, compressBehaviour genutil.CompressBehaviour, ...) (string, error)
• type ProtoOpts

Constants

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.

Types

type CodeGenerator

type CodeGenerator struct {
	// 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
	// IROptions stores the configuration parameters used for IR generation.
	IROptions ygen.IROptions
	// ProtoOptions stores a struct which contains Protobuf specific
	// options for code generation post IR generation.
	ProtoOptions ProtoOpts
}

CodeGenerator is a structure that is used to pass arguments as to how the output protobuf code should be generated.

func New

func New(callerName string, opts ygen.IROptions, protoOpts ProtoOpts) *CodeGenerator

New returns a new instance of the CodeGenerator struct to the calling function.

func (*CodeGenerator) Generate

func (cg *CodeGenerator) Generate(yangFiles, includePaths []string) (*GeneratedCode, util.Errors)

Generate 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 GeneratedCode struct containing the messages that are to be output, along with any associated values (e.g., enumerations).

type GeneratedCode

type GeneratedCode 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
}

GeneratedCode stores a set of generated Protobuf packages.

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.
	UsesYwrapperImport bool     // UsesYwrapperImport indicates whether the ywrapper proto package is used within the generated package.
	UsesYextImport     bool     // UsesYextImport indicates whether the yext proto package is used within the generated package.
}

Proto3Package stores the code for a generated protobuf3 package.

type ProtoLangMapper

type ProtoLangMapper struct {
	// LangMapperBase being embedded is a requirement for ProtoLangMapper
	// to implement the LangMapper interface, and also gives it access to
	// built-in methods.
	ygen.LangMapperBase

	// UnimplementedLangMapperExt ensures GoLangMapper implements the
	// LangMapperExt interface for forwards compatibility.
	ygen.UnimplementedLangMapperExt
	// contains filtered or unexported fields
}

ProtoLangMapper contains the functionality and state for generating proto names for the generated code.

func NewProtoLangMapper

func NewProtoLangMapper(basePackageName, enumPackageName string) *ProtoLangMapper

NewProtoLangMapper creates a new ProtoLangMapper instance, initialised with the default state required for code generation.

func (*ProtoLangMapper) DirectoryName

func (s *ProtoLangMapper) DirectoryName(e *yang.Entry, cb genutil.CompressBehaviour) (string, error)

DirectoryName generates the proto message name to be used for a particular YANG schema element in the generated code. Since this conversion is lossy, a later step should resolve any naming conflicts between different fields.

func (*ProtoLangMapper) FieldName

func (s *ProtoLangMapper) FieldName(e *yang.Entry) (string, error)

FieldName maps the input entry's name to what the proto name of the field would be. Since this conversion is lossy, a later step should resolve any naming conflicts between different fields.

func (*ProtoLangMapper) KeyLeafType

func (s *ProtoLangMapper) KeyLeafType(e *yang.Entry, opts ygen.IROptions) (*ygen.MappedType, error)

LeafType maps the input list key entry to a ygen.MappedType object containing the type information about the key field.

func (*ProtoLangMapper) LeafType

func (s *ProtoLangMapper) LeafType(e *yang.Entry, opts ygen.IROptions) (*ygen.MappedType, error)

LeafType maps the input leaf entry to a ygen.MappedType object containing the type information about the field.

func (*ProtoLangMapper) PackageName

func (s *ProtoLangMapper) PackageName(e *yang.Entry, compressBehaviour genutil.CompressBehaviour, nestedMessages bool) (string, error)

PackageName determines the package that the particular output protobuf should reside in. In the case that nested messages are being output, the package name is derived based on the top-level module that the message is within.

type ProtoOpts

type ProtoOpts struct {
	// PackageName is the name that should be used for the generating package.
	PackageName string
	// 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
	// GoPackageBase specifies the base of the names that are used in
	// the go_package file option for generated protobufs. Additional
	// package identifiers are appended to the go_package - such that
	// the format <base>/<path>/<to>/<package> is used.
	GoPackageBase string
}

ProtoOpts stores Protobuf specific options for the code generation library.