Payshares XDR, for Ruby

Payshares XDR is an open data format, specified in RFC 4506. This library provides a way to read and write XDR data from ruby. It can read/write all of the primitive XDR types and also provides facilities to define readers for the compound XDR types (enums, structs and unions)

Installation

Add this line to your application's Gemfile:

gem 'payshares-xdr'

And then execute:

$ bundle

Or install it yourself as:

$ gem install payshares-xdr

Usage

# Reading/writing a primitive values
XDR::Bool.to_xdr(false)                # => "\x00\x00\x00\x00"
XDR::Bool.from_xdr("\x00\x00\x00\x01") # => true

# Reading/writing arrays
XDR::Array[XDR::Int,2].to_xdr([1,2]) # => "\x00\x00\x00\x01\x00\x00\x00\x02"
XDR::Array[XDR::Int,2].from_xdr("\x00\x00\x00\x03\x00\x00\x00\x04") # => [3,4]

# Defining an enum

class ResultType < XDR::Enum
  member :ok,       0
  member :error,    1
  seal
end

# Using enums

ResultType.ok == ResultType.error # => false
ResultType.to_xdr(ResultType.error) # => "\x00\x00\x00\x01"
ResultType.from_xdr("\x00\x00\x00\x00") # => ResultType.ok(0)

# Defining structs

class MessageWithHash < XDR::Struct
  attribute :message, XDR::String[]
  attribute :hash, XDR::Opaque[20]
end

# Using structs

s = MessageWithHash.new
s.message = "Hello world"
s.hash = Digest::SHA1.digest(s.message)
xdr = s.to_xdr # => "..."

s2 = MessageWithHash.from_xdr(xdr)

# Defining unions

class Result < XDR::Union
  switch_on ResultType, :type

  switch :ok
  switch :error, :message

  attribute :message, XDR::String[]
end

# Constructing unions
Result.ok
Result.error("You didn't say please")

# Using unions

Result.ok.to_xdr # => "\x00\x00\x00\x00"
Result.error("boom").to_xdr # => "\x00\x00\x00\x00\x00\x00\x00\x04boom"

Result.from_xdr("\x00\x00\x00\x00") # => #<Result ...>

Thread safety

Code generated by payshares-xdrgen, which targets this library, uses autoload extensively. Since autoloading is not thread-safe, neither is code generated from xdrgen. To work around this, any module including XDR::Namespace can be forced to load all of it's children by calling load_all! on the module.

Code generation

ruby-xdr by itself does not have any ability to parse XDR IDL files and produce a parser for your custom data types. Instead, that is the responsibility of payshares-xdrgen. xdrgen will take your .x files and produce a set of ruby files that target this library to allow for your own custom types.

See ruby-payshares-base for an example (check out the generated directory)

Contributing

Sign the Contributor License Agreement
Fork it ( https://github.com/payshares/ruby-payshares-xdr/fork )
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create a new Pull Request

payshares-xdr