Package protobuf

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.

(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.

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.

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))

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

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

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

type Config ¶

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

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

    // EnumMode defines whether enums should be set as integer values, instead
    // of strings.
    //
    //    json    value is a string, corresponding to the standard JSON mapping
    //            of Protobuf. The value is associated with a #enumValue
    //            to allow the json+pb interpretation to interpret integers
    //            as well.
    //
    //    int     value is an integer associated with an #enumValue definition
    //            The json+pb interpreter uses the definition names in the
    //            disjunction of the enum to interpret strings.
    //
    EnumMode string
}

type Extractor ¶

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.

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

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.

Subdirectories