diff --git a/README.md b/README.md index a4a96c5..1243b6c 100644 --- a/README.md +++ b/README.md @@ -44,7 +44,7 @@ NAME colf — compile Colfer schemas SYNOPSIS - colf [-b ] [-p ] [-v] [ ...] + colf [ options ] language [ file ... ] DESCRIPTION Generates source code for the given language. The options are: Go, @@ -54,25 +54,30 @@ DESCRIPTION the working directory. A package can have multiple schema files. +OPTIONS -b directory Use a specific destination base directory. (default ".") - -f Normalizes the format of the schemas on the fly. + -f Normalizes schemas on the fly. -l expression - Sets the list limit expression. (default "64 * 1024") + Sets the default upper limit for the number of elements in a + list. The expression is applied to the target language under the + name ColferListMax. (default "64 * 1024") -p prefix Adds a package prefix. Use slash as a separator when nesting. -s expression - Sets the size limit expression. (default "16 * 1024 * 1024") - -v Enables verbose reporting to the standard output. + Sets the default upper limit for serial byte sizes. The + expression is applied to the target language under the name + ColferSizeMax. (default "16 * 1024 * 1024") + -v Enables verbose reporting to the standard error. EXIT STATUS - The command exits 0 on succes, 1 on compilation failure and 2 when - invoked without arguments. + The command exits 0 on succes, 1 on compilation failure and 2 + when invoked without arguments. EXAMPLES - Compile ./src/main/colfer/*.colf into ./target/ as Java: + Compile ./api/*.colf into ./src/ as Java: - colf -p com/example -b target java src/main/colfer + colf -p com/example -b src java api BUGS Report bugs at https://github.com/pascaldekloe/colfer/issues @@ -93,33 +98,36 @@ Maven users may [disagree](https://github.com/pascaldekloe/colfer/wiki/Java#mave Data structures are defined in `.colf` files. The format is quite conventional. ``` -// Package example offers a quick demonstration. +// Package demo offers a demonstration. // These comment lines will end up in the generated code. -package example +package demo // Coarse is the grounds where the game of golf is played. type coarse struct { ID uint64 name text holes []hole - map binary + image binary tags []text } type hole struct { // Lat is the latitude of the cup. - lat float64 + lat float64 // Lon is the longitude of the cup. - lon float64 + lon float64 // Par is the difficulty index. - par uint8 + par uint8 // Water marks the presence of water. water bool // Sand marks the presence of sand. - sand bool + sand bool } ``` +[See](https://gist.github.com/pascaldekloe/f5f15729cceefe430c9858d58e0dd1a3) +what the generated code looks like. + The following table shows how Colfer data types are applied per language. | Colfer | ECMAScript | Go | Java | @@ -191,6 +199,7 @@ lists. Data is represented in a big-endian manner. The format relies on *varints* also known as a [variable-length quantity](https://en.wikipedia.org/wiki/Variable-length_quantity). +Bits reserved for future use (*RFU*) must be set to 0. #### Value Definiton @@ -199,23 +208,30 @@ Each definition starts with an 8-bit header. The 7 least significant bits identify the field by its (0-based position) index in the schema. The most significant bit is used as a *flag*. -Boolean occurrences set the value to `true`. +Boolean occurrences set the value to `true`. The flag is RFU. + +Unsigned 8-bit integer values just follow the header byte and the flag is RFU. +Unsigned 16-bit integer values greather than 255 also follow the header byte. +Smaller values are encoded in one byte with the header flag set. +Unsigned 32-bit integer values less than 1<<21 are encoded as varints and +larger values set the header flag for fixed length encoding. +Unsigned 64-bit integer values less than 1<<49 are encoded as varints and +larger values set the header flag for fixed length encoding. -Integers are encoded as varints. The header flag indicates negative for signed -types and fixed size for unsigned types. The tenth byte for 64-bit integers is -skipped for encoding since its value is fixed to `0x01`. +Signed 32- and 64-bit integers are encoded as varints. The flag stands for +negative. The tenth byte for 64-bit integers is skipped for encoding since its +value is fixed to `0x01`. -Floating points are encoded conform IEEE 754. +Floating points are encoded conform IEEE 754. The flag is RFU. Timestamps are encoded as a 32-bit unsigned integer for the number of seconds that have elapsed since 00:00:00 UTC, Thursday, 1 January 1970, not counting leap seconds. When the header flag is set then the number of seconds is encoded as a 64-bit two's complement integer. In both cases the value is followed with -32 bits for the nanosecond fraction. Note that the first two bits are not in use -(reserved). +32 bits for the nanosecond fraction. Note that the first two bits are RFU. The data for text and binaries is prefixed with a varint byte size declaration. -Text is encoded as UTF-8. +Text is encoded as UTF-8. The flag is RFU. Lists of floating points, text, binaries and data structures are prefixed with a -varint element size declaration. +varint element size declaration. The flag is RFU. diff --git a/cmd/colf/main.go b/cmd/colf/main.go index 48692ef..37bd223 100644 --- a/cmd/colf/main.go +++ b/cmd/colf/main.go @@ -15,11 +15,11 @@ import ( var ( basedir = flag.String("b", ".", "Use a specific destination base `directory`.") prefix = flag.String("p", "", "Adds a package `prefix`. Use slash as a separator when nesting.") - format = flag.Bool("f", false, "Normalizes the format of the schemas on the fly.") - verbose = flag.Bool("v", false, "Enables verbose reporting to the standard output.") + format = flag.Bool("f", false, "Normalizes schemas on the fly.") + verbose = flag.Bool("v", false, "Enables verbose reporting to the standard error.") - sizeMax = flag.String("s", "16 * 1024 * 1024", "Sets the size limit `expression`.") - listMax = flag.String("l", "64 * 1024", "Sets the list limit `expression`.") + sizeMax = flag.String("s", "16 * 1024 * 1024", "Sets the default upper limit for serial byte sizes. The\n \t`expression` is applied to the target language under the name\n \tColferSizeMax.") + listMax = flag.String("l", "64 * 1024", "Sets the default upper limit for the number of elements in a\n \tlist. The `expression` is applied to the target language under the\n \tname ColferListMax.") ) var report = log.New(ioutil.Discard, "", 0) @@ -137,11 +137,8 @@ func init() { help := bold + "NAME\n\t" + cmd + clear + " \u2014 compile Colfer schemas\n\n" help += bold + "SYNOPSIS\n\t" + cmd + clear - help += " [" + bold + "-b" + clear + " <" + underline + "dir" + clear + ">]" - help += " [" + bold + "-p" + clear + " <" + underline + "path" + clear + ">]" - help += " [" + bold + "-v" + clear + "]" - help += " <" + underline + "language" + clear - help += "> [<" + underline + "file" + clear + "> " + underline + "..." + clear + "]\n\n" + help += " [ " + underline + "options" + clear + " ] " + underline + "language" + clear + help += " [ " + underline + "file" + clear + " " + underline + "..." + clear + " ]\n\n" help += bold + "DESCRIPTION\n\t" + clear help += "Generates source code for the given " + underline + "language" + clear help += ". The options are: " + bold + "Go" + clear + ",\n" @@ -150,13 +147,14 @@ func init() { help += "\tfiles with the colf extension. If " + underline + "file" + clear + " is absent, " + cmd + " includes\n" help += "\tthe working directory.\n" help += "\tA package can have multiple schema files.\n\n" + help += bold + "OPTIONS\n" + clear tail := "\n" + bold + "EXIT STATUS" + clear + "\n" - tail += "\tThe command exits 0 on succes, 1 on compilation failure and 2 when\n" - tail += "\tinvoked without arguments.\n" + tail += "\tThe command exits 0 on succes, 1 on compilation failure and 2\n" + tail += "\twhen invoked without arguments.\n" tail += "\n" + bold + "EXAMPLES" + clear + "\n" - tail += "\tCompile ./src/main/colfer/*.colf into ./target/ as Java:\n\n" - tail += "\t\t" + cmd + " -p com/example -b target java src/main/colfer\n" + tail += "\tCompile ./api/*.colf into ./src/ as Java:\n\n" + tail += "\t\t" + cmd + " -p com/example -b src java api\n" tail += "\n" + bold + "BUGS" + clear + "\n" tail += "\tReport bugs at https://github.com/pascaldekloe/colfer/issues\n\n" tail += bold + "SEE ALSO\n\t" + clear + "protoc(1)\n"