protobuf

Documentation

Overview

Package protobuf defines functionality for parsing protocol buffer definitions and instances.

Protobuf definitions can be annotated with CUE constraints that are included in the generated CUE:

(cue.val)     string        CUE expression defining a constraint for this
                            field. The string may refer to other fields
                            in a message definition using their JSON name.

(cue.opt)     FieldOptions
   required   bool          Defines the field is required. Use with
                            caution.

Index

• func Extract(filename string, src interface{}, c *Config) (f *ast.File, err error)
• type Config
• type Extractor
  • func NewExtractor(c *Config) *Extractor
  • func (b *Extractor) AddFile(filename string, src interface{}) error
  • func (b *Extractor) Err() error
  • func (b *Extractor) Files() (files []*ast.File, err error)
  • func (b *Extractor) Instances() (instances []*build.Instance, err error)

Examples

• Extract

Functions

func Extract

func Extract(filename string, src interface{}, c *Config) (f *ast.File, err error)

Extract parses a single proto file and returns its contents translated to a CUE file. If src is not nil, it will use this as the contents of the file. It may be a string, []byte or io.Reader. Otherwise Extract will open the given file name at the fully qualified path.

Extract assumes the proto file compiles with protoc and may not report an error if it does not. Imports are resolved using the paths defined in Config.

Example

package main

import (
	"fmt"
	"log"
	"os"
	"path/filepath"

	"cuelang.org/go/cue/format"
	"cuelang.org/go/encoding/protobuf"
)

func main() {
	cwd, _ := os.Getwd()
	var paths = []string{}
	paths = append(paths, cwd)
	paths = append(paths, filepath.Join(cwd, "testdata"))

	f, err := protobuf.Extract("examples/basic/basic.proto", nil, &protobuf.Config{
		Paths: paths,
	})

	if err != nil {
		log.Fatal(err, "")
	}

	b, _ := format.Node(f)
	fmt.Println(string(b))

}

Output:

//  Package basic is just that: basic.
package basic

//  This is my type.
MyType: {
	stringValue?: string @protobuf(1,name=string_value) //  just any 'ole string

	//  A method must start with a capital letter.
	method?: [...string] @protobuf(2)
	method?: [...=~"^[A-Z]"]
}

Types

type Config

type Config struct {
	// Root specifies the root of the CUE project, which typically coincides
	// with, for example, a version control repository root or the Go module.
	// Any imports of proto files within the directory tree of this of this root
	// are considered to be "project files" and are generated at the
	// corresponding location with this hierarchy. Any other imports are
	// considered to be external. Files for such imports are rooted under the
	// $Root/pkg/, using the Go package path specified in the .proto file.
	Root string

	// Module is the Go package import path of the module root. It is the value
	// as after "module" in a go.mod file, if a module file is present.
	Module string // TODO: determine automatically if unspecified.

	// Paths defines the include directory in which to search for imports.
	Paths []string
}

Config specifies the environment into which to parse a proto definition file.

type Extractor

type Extractor struct {
	// contains filtered or unexported fields
}

An Extractor converts a collection of proto files, typically belonging to one repo or module, to CUE. It thereby observes the CUE package layout.

CUE observes the same package layout as Go and requires .proto files to have the go_package directive. Generated CUE files are put in the same directory as their corresponding .proto files if the .proto files are located in the specified Root (or current working directory if none is specified). All other imported files are assigned to the CUE pkg dir ($Root/pkg) according to their Go package import path.

func NewExtractor

func NewExtractor(c *Config) *Extractor

NewExtractor creates an Extractor. If the configuration contained any errors it will be observable by the Err method fo the Extractor. It is safe, however, to only check errors after building the output.

func (*Extractor) AddFile

func (b *Extractor) AddFile(filename string, src interface{}) error

AddFile adds a proto definition file to be converted into CUE by the builder. Relatives paths are always taken relative to the Root with which the b is configured.

AddFile assumes that the proto file compiles with protoc and may not report an error if it does not. Imports are resolved using the paths defined in Config.

func (*Extractor) Err

func (b *Extractor) Err() error

Err returns the errors accumulated during testing. The returned error may be of type cuelang.org/go/cue/errors.List.

func (*Extractor) Files

func (b *Extractor) Files() (files []*ast.File, err error)

Files returns a File for each proto file that was added or imported, recursively.

func (*Extractor) Instances

func (b *Extractor) Instances() (instances []*build.Instance, err error)

Instances creates a build.Instances for every package for which a proto file was added to the builder. This includes transitive dependencies. It does not write the generated files to disk.

The returned instances can be passed to cue.Build to generated the corresponding CUE instances.

All import paths are located within the specified Root, where external packages are located under $Root/pkg. Instances for builtin (like time) packages may be omitted, and if not will have no associated files.