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.