Documentation ¶
Overview ¶
Package protobuf defines functionality for parsing protocol buffer definitions and instances.
Proto definition mapping follows the guidelines of mapping Proto to JSON as discussed in https://developers.google.com/protocol-buffers/docs/proto3, and carries some of the mapping further when possible with CUE.
Package Paths ¶
If a .proto file contains a go_package directive, it will be used as the destination package fo the generated .cue files. A common use case is to generate the CUE in the same directory as the .proto definition. If a destination package is not within the current CUE module, it will be written relative to the pkg directory.
If a .proto file does not specify go_package, it will convert a proto package "google.parent.sub" to the import path "googleapis.com/google/parent/sub". It is safe to mix package with and without a go_package within the same project.
Type Mappings ¶
The following type mappings of defintions apply:
Proto type CUE type/def Comments message struct Message fields become CUE fields, whereby names are mapped to lowerCamelCase. enum e1 | e2 | ... Where ex are strings. A separate mapping is generated to obtain the numeric values. map<K, V> { <>: V } All keys are converted to strings. repeated V [...V] null is accepted as the empty list []. bool bool string string bytes bytes A base64-encoded string when converted to JSON. int32, fixed32 int32 An integer with bounds as defined by int32. uint32 uint32 An integer with bounds as defined by uint32. int64, fixed64 int64 An integer with bounds as defined by int64. uint64 uint64 An integer with bounds as defined by uint64. float float32 A number with bounds as defined by float32. double float64 A number with bounds as defined by float64. Struct struct See struct.proto. Value _ See struct.proto. ListValue [...] See struct.proto. NullValue null See struct.proto. BoolValue bool See struct.proto. StringValue string See struct.proto. NumberValue number See struct.proto. StringValue string See struct.proto. Empty close({}) Timestamp time.Time See struct.proto. Duration time.Duration See struct.proto.
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 ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Extract ¶ added in v0.0.4
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]"] exmapleMap?: { [string]: string } @protobuf(3,type=map<string,string>,exmaple_map) }
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 cue.mod/modules.cue 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 // PkgName specifies the package name for a generated CUE file. A value // will be derived from the Go package name if undefined. PkgName string }
Config specifies the environment into which to parse a proto definition file.
type Extractor ¶ added in v0.0.4
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 ¶ added in v0.0.4
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 ¶ added in v0.0.4
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 ¶ added in v0.0.4
Err returns the errors accumulated during testing. The returned error may be of type cuelang.org/go/cue/errors.List.
func (*Extractor) Files ¶ added in v0.0.4
Files returns a File for each proto file that was added or imported, recursively.
func (*Extractor) Instances ¶ added in v0.0.4
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.