Code Monkey home page Code Monkey logo

binstruct's Introduction

Go Report Card CodeCov GoDoc License: MIT

binstruct

Golang binary decoder to structure

Install

go get -u github.com/ghostiam/binstruct

Examples

ZIP decoder
PNG decoder

Use

For struct

From file or other io.ReadSeeker:

package main

import (
	"encoding/binary"
	"fmt"
	"log"
	"os"

	"github.com/ghostiam/binstruct"
)

func main() {
	file, err := os.Open("testdata/file.bin")
	if err != nil {
		log.Fatal(err)
	}

	type dataStruct struct {
		Arr []int16 `bin:"len:4"`
	}

	var actual dataStruct
	decoder := binstruct.NewDecoder(file, binary.BigEndian)
	// decoder.SetDebug(true) // you can enable the output of bytes read for debugging
	err = decoder.Decode(&actual)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("%+v", actual)

	// Output:
	// {Arr:[1 2 3 4]}
}

From bytes

package main

import (
	"fmt"
	"log"
	
	"github.com/ghostiam/binstruct"
)

func main() {
	data := []byte{
		0x00, 0x01,
		0x00, 0x02,
		0x00, 0x03,
		0x00, 0x04,
	}

	type dataStruct struct {
		Arr []int16 `bin:"len:4"`
	}

	var actual dataStruct
	err := binstruct.UnmarshalBE(data, &actual) // UnmarshalLE() or Unmarshal()
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("%+v", actual)

	// Output: {Arr:[1 2 3 4]}
}

or just use reader without mapping data into the structure

You can not use the functionality for mapping data into the structure, you can use the interface to get data from the stream (io.ReadSeeker)

reader.go

type Reader interface {
	io.ReadSeeker

	// Peek returns the next n bytes without advancing the reader.
	Peek(n int) ([]byte, error)

	// ReadBytes reads up to n bytes. It returns the number of bytes
	// read, bytes and any error encountered.
	ReadBytes(n int) (an int, b []byte, err error)
	// ReadAll reads until an error or EOF and returns the data it read.
	ReadAll() ([]byte, error)

	// ReadByte read and return one byte
	ReadByte() (byte, error)
	// ReadBool read one byte and return boolean value
	ReadBool() (bool, error)

	// ReadUint8 read one byte and return uint8 value
	ReadUint8() (uint8, error)
	// ReadUint16 read two bytes and return uint16 value
	ReadUint16() (uint16, error)
	// ReadUint32 read four bytes and return uint32 value
	ReadUint32() (uint32, error)
	// ReadUint64 read eight bytes and return uint64 value
	ReadUint64() (uint64, error)
	// ReadUintX read X bytes and return uint64 value
	ReadUintX(x int) (uint64, error)

	// ReadInt8 read one byte and return int8 value
	ReadInt8() (int8, error)
	// ReadInt16 read two bytes and return int16 value
	ReadInt16() (int16, error)
	// ReadInt32 read four bytes and return int32 value
	ReadInt32() (int32, error)
	// ReadInt64 read eight bytes and return int64 value
	ReadInt64() (int64, error)
	// ReadIntX read X bytes and return int64 value
	ReadIntX(x int) (int64, error)

	// ReadFloat32 read four bytes and return float32 value
	ReadFloat32() (float32, error)
	// ReadFloat64 read eight bytes and return float64 value
	ReadFloat64() (float64, error)

	// Unmarshal parses the binary data and stores the result
	// in the value pointed to by v.
	Unmarshal(v interface{}) error

	// WithOrder changes the byte order for the new Reader
	WithOrder(order binary.ByteOrder) Reader
}

Example:

package main

import (
	"encoding/binary"
	"fmt"
	"log"
	
	"github.com/ghostiam/binstruct"
)

func main() {
	data := []byte{0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x0E, 0x0F}

	reader := binstruct.NewReaderFromBytes(data, binary.BigEndian, false)

	i16, err := reader.ReadInt16()
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(i16)

	i32, err := reader.ReadInt32()
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(i32)

	b, err := reader.Peek(4)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("Peek bytes: %#v\n", b)

	an, b, err := reader.ReadBytes(4)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("Read %d bytes: %#v\n", an, b)

	other, err := reader.ReadAll()
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("Read all: %#v\n", other)

	// Output:
	// 258
	// 50595078
	// Peek bytes: []byte{0x7, 0x8, 0x9, 0xa}
	// Read 4 bytes: []byte{0x7, 0x8, 0x9, 0xa}
	// Read all: []byte{0xb, 0xc, 0xd, 0xe, 0xf}
}

Decode to fields

type test struct {
	// Read 1 byte
	Field bool
	Field byte
	Field [1]byte
	Field int8
	Field uint8

	// Read 2 bytes
	Field int16
	Field uint16
	Field [2]byte

	// Read 4 bytes
	Field int32
	Field uint32
	Field [4]byte

	// Read 8 bytes
	Field int64
	Field uint64
	Field [8]byte

	// You can override length
	Field int64 `bin:"len:2"`
	// Or even use very weird byte lengths for int
	Field int64 `bin:"len:3"`
	Field int64 `bin:"len:5"`
	Field int64 `bin:"len:7"`

	// Fields of type int, uint and string are not read automatically 
	// because the size is not known, you need to set it manually
	Field int    `bin:"len:2"`
	Field uint   `bin:"len:4"`
	Field string `bin:"len:42"`
	
	// Can read arrays and slices
	Array [2]int32              // read 8 bytes (4+4byte for 2 int32)
	Slice []int32 `bin:"len:2"` // read 8 bytes (4+4byte for 2 int32)
	
	// Also two-dimensional slices work (binstruct_test.go:307 Test_SliceOfSlice)
	Slice2D [][]int32 `bin:"len:2,[len:2]"`
	// and even three-dimensional slices (binstruct_test.go:329 Test_SliceOfSliceOfSlice)
	Slice3D [][][]int32 `bin:"len:2,[len:2,[len:2]]"`
	
	// Structures and embedding are also supported.
	Struct struct {
		...
	}
	OtherStruct Other
	Other // embedding
}

type Other struct {
	...
}

Tags

type test struct {
	IgnoredField []byte `bin:"-"`          // ignore field
	CallMethod   []byte `bin:"MethodName"` // Call method "MethodName"
	ReadLength   []byte `bin:"len:42"`     // read 42 bytes

	// Offsets test binstruct_test.go:9
	Offset      byte `bin:"offset:42"`      // move to 42 bytes from current position and read byte
	OffsetStart byte `bin:"offsetStart:42"` // move to 42 bytes from start position and read byte
	OffsetEnd   byte `bin:"offsetEnd:-42"`  // move to -42 bytes from end position and read byte
	OffsetStart byte `bin:"offsetStart:42, offset:10"` // also worked and equally `offsetStart:52`
	OffsetWithRestore byte `bin:"offset:42, offsetRestore"` // move to 42 bytes from current position and read byte, then restore position to the previous one (before offset)

	// Calculations supported +,-,/,* and are performed from left to right that is 2+2*2=8 not 6!!!
	CalcTagValue []byte `bin:"len:10+5+2+3"` // equally len:20

	// You can refer to another field to get the value.
	DataLength              int    // actual length
	ValueFromOtherField     string `bin:"len:DataLength"`
	CalcValueFromOtherField string `bin:"len:DataLength+10"` // also work calculations

	// Also supported nested structures.
	Inner struct {
		DataLength int // actual length for ValueFromInnerField and CalcValueFromInnerField
	}
	ValueFromInnerField string `bin:"len:Inner.DataLength"`
	CalcValueFromInnerField string `bin:"len:Inner.DataLength+10"`

	// You can change the byte order directly from the tag
	UInt16LE uint16 `bin:"le"`
	UInt16BE uint16 `bin:"be"`
	// Or when you call the method, it will contain the Reader with the byte order you need
	CallMethodWithLEReader uint16 `bin:"MethodNameWithLEReader,le"`
	CallMethodWithBEReader uint16 `bin:"be,MethodNameWithBEReader"`
} 

// Method can be:
func (*test) MethodName(r binstruct.Reader) (error) {}
// or
func (*test) MethodName(r binstruct.Reader) (FieldType, error) {}

See the tests and examples for more information.

License

MIT License

binstruct's People

Contributors

ghostiam avatar rdhite avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar

binstruct's Issues

function tag on nested struct

type Bin struct {
	...
	Pin           struct {
		Pin1         []byte `bin:"len:4"` // LE
		Pin1Unknown  []byte `bin:"len:4"`
		Pin1Checksum uint16 `bin:"Uint16l,len:2"`
		Pin2         []byte `bin:"len:4"` // LE
		Pin2Unknown  []byte `bin:"len:4"`
		Pin2Checksum uint16 `bin:"Uint16l,len:2"`
	} // 20 bytes
        ...
}
// Uint16l returns a uint16 read as little endian
func (*Bin) Uint16l(r binstruct.Reader) (uint16, error) {
	var out uint16
	if err := binary.Read(r, binary.LittleEndian, &out); err != nil {
		return 0, err
	}
	return out, nil
}
2021/12/25 16:05:41 main.go:21: failed set value to field "Pin": unmarshal struct: failed set value to field "Pin1Checksum": call custom func: 
failed call method, expected methods:
        func (*) Uint16l(r binstruct.Reader) error {} 
or
        func (*) Uint16l(r binstruct.Reader) (uint16, error) {}
exit status 1

a question

package main

import (
	"fmt"
	"log"

	"github.com/ghostiam/binstruct"
)

func main() {
	data := []byte{
		0xbf, 0x81, 0xb7, 0xa, 0xd9, 0x5e, 0xd8, 0xb9, 0xff, 0x7f, 0xe9, 0x11, 0x85, 0xbd, 0x90, 0x29, 0xbc, 0x6, 0x80, 0x0, 0xaf,
	}

	type dataStruct struct {

		First []byte `bin:"len:2"`
		Mid   []byte `bin:"len:6"`
		Last  []byte `bin:"len:"`
	}

	var actual dataStruct
	err := binstruct.UnmarshalBE(data, &actual) // UnmarshalLE() or Unmarshal()
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("%+v", actual)

	// Output: {Arr:[1 2 3 4]}
}

result :

main.dataStruct{First:[]uint8{0xbf, 0x81}, Mid:[]uint8{0xb7, 0xa, 0xd9, 0x5e, 0x
d8, 0xb9}, Last:[]uint8(nil)}

how UnmarshalBE above dataStruct with last of []byte with dont set lenght of []byte ?

i need Last is []byte{0x11, 0x85, 0xbd, 0x90, 0x29, 0xbc, 0x6, 0x80, 0x0, 0xaf}

Thanks.

Reference array of structs subfield

Hi again, is there a plan to add possibility to reference fields of array of structs?
Or maybe it's way out of scope of this package? I mean it's achievable via custom function without much of a hassle.

I have a following example:

type ChunkHeader struct {
	Size uint8
}
type Entry struct {
	Count   uint8
	Headers []ChunkHeader `bin:"len:Count"`
	Chunks  [][]byte      `bin:"ReadChunks"`
	// desired ("_currentIndex" or maybe "$", not sure)
	// Chunks [][]byte `bin:"len:Count,[len:Headers[_currentIndex].Size]"`
}

func (entry *Entry) ReadChunks(r binstruct.Reader) error {
	entry.Chunks = make([][]byte, len(entry.Headers))
	for i, header := range entry.Headers {
		buf := make([]byte, header.Size)
		read, err := r.Read(buf)
		if err != nil {
			return errors.Join(
				fmt.Errorf("failed to read chunk %d", i),
				err,
			)
		}
		if read != int(header.Size) {
			return fmt.Errorf("not enough data to read chunk %d", i)
		}
		entry.Chunks[i] = buf
	}
	return nil
}

func main() {
	data := []byte{
		0x02, // count of headers
		0x01, // header 1 size=1
		0x02, // header 2 size=2
		0x10, // chunk 1 data byte 1
		0x20, // chunk 2 data byte 1
		0x21, // chunk 2 data byte 2
	}
	reader := binstruct.NewReaderFromBytes(data, binary.LittleEndian, false)
	var entry Entry
	err := reader.Unmarshal(&entry)
	if err != nil {
		fmt.Printf("failed to parse: %s\n", err)
	}
	fmt.Println("data", entry)
}

Read value on a given offset and return pointer back.

Hi, thank you for the great package!

It would be nice to have a flag for offset options to be able to restore offset after reading referenced chunk.

I have an archive structure that have sparsely referenced buffers. I'm using the following reader method:

type File struct {
	Offset uint64
	Size uint32
	
	InlineBuffer []byte `bin:"FileReadInlineBuffer"`
	// desired
	// InlineBuffer []byte `bin:"offsetStart:Offset, len:Size, restoreOffsetOrSomeBetterNameForThisFlag:true"`
}

func (file *File) FileReadInlineBuffer(r binstruct.Reader) error {
	oldPos, err := r.Seek(0, io.SeekCurrent)
	if err != nil {
		return err
	}

	_, err = r.Seek(int64(file.Offset), io.SeekStart)
	if err != nil {
		return err
	}

	size := int(file.Size)
	file.InlineBuffer = make([]byte, size)
	n, err := r.Read(file.InlineBuffer)
	if err != nil {
		return err
	}
	if n != size {
		return fmt.Errorf("failed to read inline buffer: expected %d bytes, got: %d", size, n)
	}

	_, err = r.Seek(oldPos, io.SeekStart)
	if err != nil {
		return err
	}
	return nil
}

Benchmark

Would be nice to have a benchmark comparison with other libraries (e.g. lunixbochs/struc)

I'd like to know if this repo offers better performances

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.