github.com/davecgh/go-xdr@v0.0.0-20161123171359-e6a2ba005892/README.md (about)

     1  go-xdr
     2  ======
     3  
     4  [![Build Status](https://travis-ci.org/davecgh/go-xdr.png?branch=master)]
     5  (https://travis-ci.org/davecgh/go-xdr) [![Coverage Status]
     6  (https://coveralls.io/repos/davecgh/go-xdr/badge.png?branch=master)]
     7  (https://coveralls.io/r/davecgh/go-xdr?branch=master)
     8  
     9  Go-xdr implements the data representation portion of the External Data
    10  Representation (XDR) standard protocol as specified in RFC 4506 (obsoletes RFC
    11  1832 and RFC 1014) in Pure Go (Golang).  A comprehensive suite of tests are
    12  provided to ensure proper functionality.  It is licensed under the liberal ISC
    13  license, so it may be used in open source or commercial projects.
    14  
    15  NOTE: Version 1 of this package is still available via the
    16  github.com/davecgh/go-xdr/xdr import path to avoid breaking existing clients.  However, it is highly recommended that all old clients upgrade to version 2
    17  and all new clients use version 2.  In addition to some speed optimizations,
    18  version 2 has been been updated to work with standard the io.Reader and
    19  io.Writer interfaces instead of raw byte slices.  This allows it to be much more
    20  flexible and work directly with files, network connections, etc.
    21  
    22  ## Documentation
    23  
    24  [![GoDoc](https://godoc.org/github.com/davecgh/go-xdr/xdr2?status.png)]
    25  (http://godoc.org/github.com/davecgh/go-xdr/xdr2)
    26  
    27  Full `go doc` style documentation for the project can be viewed online without
    28  installing this package by using the excellent GoDoc site here:
    29  http://godoc.org/github.com/davecgh/go-xdr/xdr2
    30  
    31  You can also view the documentation locally once the package is installed with
    32  the `godoc` tool by running `godoc -http=":6060"` and pointing your browser to
    33  http://localhost:6060/pkg/github.com/davecgh/go-xdr/xdr2/
    34  
    35  ## Installation
    36  
    37  ```bash
    38  $ go get github.com/davecgh/go-xdr/xdr2
    39  ```
    40  
    41  ## Sample Decode Program
    42  
    43  ```Go
    44  package main
    45  
    46  import (
    47  	"bytes"
    48      "fmt"
    49  
    50      "github.com/davecgh/go-xdr/xdr2"
    51  )
    52  
    53  func main() {
    54  	// Hypothetical image header format.
    55  	type ImageHeader struct {
    56  		Signature   [3]byte
    57  		Version     uint32
    58  		IsGrayscale bool
    59  		NumSections uint32
    60  	}
    61  
    62  	// XDR encoded data described by the above structure.  Typically this would
    63  	// be read from a file or across the network, but use a manual byte array
    64  	// here as an example.
    65  	encodedData := []byte{
    66  		0xAB, 0xCD, 0xEF, 0x00, // Signature
    67  		0x00, 0x00, 0x00, 0x02, // Version
    68  		0x00, 0x00, 0x00, 0x01, // IsGrayscale
    69  		0x00, 0x00, 0x00, 0x0A, // NumSections
    70  	}
    71  
    72  	// Declare a variable to provide Unmarshal with a concrete type and instance
    73  	// to decode into.
    74  	var h ImageHeader
    75  	bytesRead, err := xdr.Unmarshal(bytes.NewReader(encodedData), &h)
    76  	if err != nil {
    77  		fmt.Println(err)
    78  		return
    79  	}
    80    
    81  	fmt.Println("bytes read:", bytesRead)
    82  	fmt.Printf("h: %+v", h)
    83  }
    84  ```
    85  
    86  The struct instance, `h`, will then contain the following values:
    87  
    88  ```Go
    89  h.Signature = [3]byte{0xAB, 0xCD, 0xEF}
    90  h.Version = 2
    91  h.IsGrayscale = true
    92  h.NumSections = 10
    93  ```
    94  
    95  ## Sample Encode Program
    96  
    97  ```Go
    98  package main
    99  
   100  import (
   101  	"bytes"
   102      "fmt"
   103  
   104      "github.com/davecgh/go-xdr/xdr2"
   105  )
   106  
   107  func main() {
   108  	// Hypothetical image header format.
   109  	type ImageHeader struct {
   110  		Signature   [3]byte
   111  		Version     uint32
   112  		IsGrayscale bool
   113  		NumSections uint32
   114  	}
   115  
   116  	// Sample image header data.
   117  	h := ImageHeader{[3]byte{0xAB, 0xCD, 0xEF}, 2, true, 10}
   118  
   119  	// Use marshal to automatically determine the appropriate underlying XDR
   120  	// types and encode.
   121  	var w bytes.Buffer
   122  	bytesWritten, err := xdr.Marshal(&w, &h)
   123  	if err != nil {
   124  		fmt.Println(err)
   125  		return
   126  	}
   127  
   128  	encodedData := w.Bytes()
   129  	fmt.Println("bytes written:", bytesWritten)
   130  	fmt.Println("encoded data:", encodedData)
   131  }
   132  ```
   133  
   134  The result, `encodedData`, will then contain the following XDR encoded byte
   135  sequence:
   136  
   137  ```
   138  0xAB, 0xCD, 0xEF, 0x00,
   139  0x00, 0x00, 0x00, 0x02,
   140  0x00, 0x00, 0x00, 0x01,
   141  0x00, 0x00, 0x00, 0x0A,
   142  ```
   143  
   144  ## License
   145  
   146  Go-xdr is licensed under the liberal ISC License.