Skip to content

Latest commit

 

History

History
116 lines (89 loc) · 5 KB

README.md

File metadata and controls

116 lines (89 loc) · 5 KB
Raw

Go XDR compiler (goxdr)

goxdr compiles the RFC4506 eXternal Data Representation IDL down to go data structures. It also creates go interfaces for RFC5531 RPC interfaces. goxdr has several features that together make it an attractive alternative to other go XDR compilers for many situations:

  • Fully RFC4506 compliant, including nested structure and union declarations.

  • Fully RFC5531 compliant, including procedures that take multiple arguments.

  • Output code is highly readable, with data structures segregated from messier marshaling code. The generated go source is a convenient reference when programming with the data structures. Autogenerated comments remind you of vector and string bounds as well as the mapping between union discriminants and bodies.

  • The compiler copies godoc-formatted comments from the XDR source code into the generated go file. If your XDR source is appropriately commented, the output will render nicely with godoc, providing self-contained documentation for libraries that include XDR types.

  • Generated data types use the most natural go representations, such as arrays for arrays, slices for vectors, strings for strings. Union discriminants are ordinary fields, while arms (case statements) are methods that lazily allocate the necessary body based on the discriminant. Unlike some approaches that waste memory by transforming unions into structs, memory is only required for one arm of a union at a time.

  • String, vector, and variable opaque bounds are strictly enforced by generated marshaling functions, rather than being encoded in the types (which would make assignment annoying) or in struct field tags (which requires use of reflection and doesn't work for typedefs).

  • You can generically traverse XDR data structures using simple interface methods. Marshaling and traversal make no use of reflection, and hence avoid incurring the associated overhead and complexity.

  • In addition to standard binary XDR serialization, generic traversal allows concise implementation of pretty printing, or extraction of all occurrences of a particular type at any level of struct/union nesting. Traversal functions have access to field names.

  • Traversal can special-case particular typdefs. Even though typedefs are compiled to type aliases, their XDR functions return types that return the type name used via the XdrTypeName()string method.

  • An option to make comments on enum constants available at runtime allows you to specify things like human-readable error messages for error codes right in the source code of your XDR file, avoiding the need for manual synchronization between your XDR and go sources.

  • Tiny XDR runtime package dependency is optional. For small projects the compiler can instead emit boilerplate code directly into its output.

  • Also includes a thread-safe RFC5531 RPC library. For simplicity, server side calls are handled non-concurrently by default, but functions can choose to detach from the main event loop to reply asynchronously.

Installation

To install goxdr, run:

go get github.com/xdrpp/goxdr/cmd/goxdr

To use the latest development version within a go module (i.e., below a directory with a go.mod file), run:

go get github.com/xdrpp/goxdr/cmd/goxdr@go1

Documentation

The compiler's command-line usage and its generated code are both detailed in the goxdr(1) man page.

Building goxdr for developers

goxdr uses autogenerated source files. Hence, the master branch is intended to be compiled using make. Doing so requires goyacc, which (if you don't already have it) you can install or update in your gopath by running:

make depend

Disclaimer

There is no warranty for the program, to the extent permitted by applicable law. Except when otherwise stated in writing the copyright holders and/or other parties provide the program "as is" without warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. The entire risk as to the quality and performance of the program is with you. Should the program prove defective, you assume the cost of all necessary servicing, repair or correction.

In no event unless required by applicable law or agreed to in writing will any copyright holder, or any other party who modifies and/or conveys the program as permitted above, be liable to you for damages, including any general, special, incidental or consequential damages arising out of the use or inability to use the program (including but not limited to loss of data or data being rendered inaccurate or losses sustained by you or third parties or a failure of the program to operate with any other programs), even if such holder or other party has been advised of the possibility of such damages.