autogenpb/auto.proto

syntax = "proto3";

// here are some docs, but probably it's just easier to run
// autogenpb on this file and see what gets autogenerated
// in this directory. All autogenerated files are named *.pb.go

// the 'uuid' standard at the end is an experiment
// establish a way to identify arbitrary .pb files

// You can generate Marshal & Unmarshal for any struct (message) you want
// You can generate SortBy and Append functions ONLY FOR 'repeated <message>'
// Also, those structs must be defined in the same file
// Additionally, you must use `autogenpb:mutex` on the parent struct. 
// The autogenerated code requires a RW mutex and autogenpb will insert it into the struct

package main;

message Apple {	       	        	// `autogenpb:marshal`
	string   name           = 1;    // `autogenpb:unique` // generates SortByxxx() and AppendUnique() functions
	string   genus          = 2;    // `autogenpb:unique` // generates same thing here but SortByGenus()
}

message Apples {	        	// `autogenpb:marshal` `autogenpb:mutex`
	string   uuid	        = 1;    // `autogenpb:default:b2a2de35-07b6-443b-8188-709e27bee8a7`
	string   version        = 2;    // `autogenpb:default:2`
        repeated Apple Apples   = 3;    // `autogenpb:sort`
        repeated Pears  More    = 4;    // `autogenpb:sort`
        repeated string  Color  = 5;    // `autogenpb:sort` `autogenpb:unique`
}

message Pears {
	string   name	        = 1;    //
	string   favorite       = 2;    // `autogenpb:sort`
}

// above is an example

//
// below are the actual structs autogen uses
// autogen parses the .proto file and then store the information
// it needs in these protobuf files, then it processes the
// protobuf files to write out *.sort.pb.go and *.marshal.pb.go files
//
message MsgName {
        // If you have:
        //
        // "Shelf" for msgname
        // "Books" for name
        //
        // Then in the proto file, that would mean it would look like:
        //
        // message Shelf {
        // and then 
        //      repeated string Books = 42;
        //
        // autogenpb will then generate sort functions for each 'name'
        // things like:
        //
        // for _, b := range all.Book {
        //
        // and sort functions like:
        //
        // func (a ShelfBook) Less(i, j int) bool { return a[i].Book < a[j].Book }
        //

        string   name	        = 1;    // the name of the message aka struct. for this example: "Shelf"
        string   lockname	= 2;    // ShelfMU
        bool     doMarshal      = 3;    // if "Shelf" should have Marshal & Unmarshal functions
        bool     doMutex        = 4;    // true if a mutex is needed for the message struct
        bool     doProtocMutex  = 5;    // an experiment to insert a mutex into the protoc generated msg struct (bad idea?)
        bool     mutexFound     = 6;    // true if the mutex was added to the protoc pb.go file
        repeated string sort	= 7;    // "Book", "Picture", etc
        repeated string unique	= 8;    // if the fields should have AppendUnique() functions
}

message File {                                  // `autogenpb:nomarshal`
        string   Package 	   = 1;    // whatever the package name is at the top of the .go file
        string   filename	   = 2;    // yellow.proto
        string   pbfilename	   = 3;    // yellow.pb.go
        string   filebase	   = 4;    // yellow
        string   uuid	           = 5;    // the uuid to use in a func NewMsgName()
        int64    version           = 6;    // the version to use in a func NewMsgName()

        // every struct in this proto file, this file has: "Apple", "Apples", ... "File", etc...
        repeated MsgName msgNames  = 7;    // `autogenpb:unique`  // in this file
}

// I know, I know, the whole point of using protobuf
// is so you don't need a uuid or versions because it's
// inherently forward compatable. nonetheless, a simple stubbed out
// trivial and empty protobuf message can marshal and identify all the files
// also, this could be used to modify /usr/bin/file /usr/share/magic to identify the files
// maybe this is already been done and is pointless, but it seems like a good idea
message Files {                           // `autogenpb:marshal`
        string   uuid	          = 1;    // if you use this scheme, autogen will be able to identify your
        int64    version          = 2;    // protobuf files from the command line.
        repeated File Files       = 3;    // an array of each .proto file in the working directory
}

// this generic message is used by autogen to identify and
// then dump the uuid and version from any arbitrary .pb file
message Identify {                        // `autogenpb:marshal`
        string   uuid	          = 1;    //
        int64    version          = 2;    //
}