├── vstruct2
    ├── tests
    │   ├── __init__.py
    │   ├── test_compat.py
    │   ├── test_sizes.py
    │   └── test_types.py
    ├── __init__.py
    ├── compat.py
    ├── bases.py
    └── types.py
├── .gitignore
├── .travis.yml
├── .appveyor.yml
├── setup.py
├── README.rst
└── LICENSE


/vstruct2/tests/__init__.py:
--------------------------------------------------------------------------------
1 | 


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | *.pyc
2 | *.swp
3 | *.py~
4 | .hg*
5 | __pycache__
6 | build
7 | dist
8 | vstruct2.egg-info
9 | 


--------------------------------------------------------------------------------
/.travis.yml:
--------------------------------------------------------------------------------
1 | os:
2 |     - linux
3 | language: python
4 | python:
5 |     - "2.7"
6 |     - "3.4"
7 | script: py.test
8 | 


--------------------------------------------------------------------------------
/vstruct2/__init__.py:
--------------------------------------------------------------------------------
1 | '''
2 | Vivisect Structure Definition/Parsing Library
3 | 
4 | https://github.com/vivisect/vstruct
5 | 
6 | '''
7 | version = (2,0,2)
8 | 


--------------------------------------------------------------------------------
/.appveyor.yml:
--------------------------------------------------------------------------------
 1 | environment:
 2 | 
 3 |   matrix:
 4 | 
 5 |     - PYTHON: "C:\\Python27"
 6 | 
 7 |     - PYTHON: "C:\\Python27-x64"
 8 | 
 9 |     - PYTHON: "C:\\Python34"
10 | 
11 |     - PYTHON: "C:\\Python34-x64"
12 | 
13 | install:
14 |   # Check that we have the expected version and architecture for Python
15 |   - "%PYTHON%\\python.exe --version"
16 |   - "%PYTHON%\\python.exe -c \"import struct; print(struct.calcsize('P') * 8)\""
17 | 
18 |   # Upgrade to the latest version of pip to avoid it displaying warnings
19 |   # about it being out of date.
20 |   - "%PYTHON%\\Scripts\\pip.exe install --disable-pip-version-check --user --upgrade pip"
21 |   - "%PYTHON%\\Scripts\\pip.exe install --upgrade setuptools"
22 | 
23 |   # for now...  should somehow be managed via setup.py
24 |   - "%PYTHON%\\Scripts\\pip.exe install msgpack-python"
25 | 
26 | # no msbuild phase in the project
27 | build: off
28 | 
29 | test_script:
30 |   # Run the project tests
31 |   - "%CMD_IN_ENV% %PYTHON%\\python.exe -m unittest discover -v --fail"
32 | 


--------------------------------------------------------------------------------
/setup.py:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env python
 2 | #from distutils.core import setup
 3 | 
 4 | import io
 5 | import os
 6 | 
 7 | from setuptools import setup,find_packages
 8 | 
 9 | # For Testing:
10 | #
11 | # python3.4 setup.py register -r https://testpypi.python.org/pypi
12 | # python3.4 setup.py bdist_wheel upload -r https://testpypi.python.org/pypi
13 | # python3.4 -m pip install -i https://testpypi.python.org/pypi
14 | #
15 | # For Realz:
16 | #
17 | # python3.4 setup.py register
18 | # python3.4 setup.py bdist_wheel upload
19 | # python3.4 -m pip install
20 | 
21 | here = os.path.dirname(__file__)
22 | 
23 | def read(fname, encoding='utf-8'):
24 |     with io.open(os.path.join(here, fname), encoding=encoding) as f:
25 |         return f.read()
26 | 
27 | setup(
28 |     name='vstruct2',
29 |     version='2.0.2',
30 |     description='Vivisect Structure Definition/Parsing Library',
31 |     long_description=read('README.rst'),
32 |     author='Invisigoth Kenshoto',
33 |     author_email='visi@vertex.link',
34 |     url='https://github.com/vivisect/vstruct2',
35 |     license='Apache License 2.0',
36 | 
37 |     packages=find_packages(exclude=['*.tests','*.tests.*']),
38 | 
39 |     classifiers=[
40 |         'Development Status :: 5 - Production/Stable',
41 |         'License :: OSI Approved :: Apache Software License',
42 |         'Programming Language :: Python :: 3.4',
43 |         'Programming Language :: Python :: 2.7',
44 |     ],
45 | 
46 | )
47 | 


--------------------------------------------------------------------------------
/README.rst:
--------------------------------------------------------------------------------
 1 | vstruct2 ( Mark II )
 2 | ===================
 3 | 
 4 | Vivisect Structure Definition/Parsing Library
 5 | |Build Status|
 6 | 
 7 | Installing
 8 | ==========
 9 | 
10 | .. code::
11 | 
12 |     python3.4 -m pip install vstruct2
13 | 
14 | vstruct2 can now be installed via pip!
15 | 
16 | Additionally, a repository of existing structure definitions
17 | is available as a seperate package named fracture.
18 | 
19 | Examples
20 | ========
21 | 
22 | Basic Parsing
23 | -------------
24 | 
25 | Simple vstruct2 byte parsing:
26 | 
27 | .. code:: python
28 | 
29 |     from vstruct2.types import *
30 | 
31 |     class Foo(VStruct):
32 | 
33 |         def __init__(self):
34 |             VStruct.__init__(self)
35 |             self.bar    = uint32()
36 |             self.baz    = vbytes(20)
37 | 
38 | 
39 |     foo = Foo()
40 | 
41 |     # read in byts from somewhere...
42 |     foo.vsParse(byts)
43 | 
44 |     # access struct fields by name
45 |     if foo.bar == 30:
46 |         print('bar == 30!')
47 | 
48 |     # assign fields by name
49 |     foo.bar = 90
50 | 
51 |     # emit modified bytes back out
52 |     byts = bytes(foo) # same as foo.vsEmit()
53 | 
54 | Parser Callbacks
55 | ----------------
56 | 
57 | WriteBack Bytes/Files
58 | ---------------------
59 | 
60 | vstruct2 supports "writeback" functionality for both files and mutable
61 | bytearray types, allowing field assignments to change the underlying file
62 | or bytearray immediately.
63 | 
64 | .. code:: python
65 | 
66 |     class Foo(VStruct):
67 | 
68 |         def __init__(self):
69 |             VStruct.__init__(self)
70 |             self.bar    = uint32()
71 |             self.baz    = uint32()
72 | 
73 | 
74 |     foo = Foo()
75 | 
76 |     # ba is a bytearray
77 |     foo.vsParse(ba, writeback=True)
78 | 
79 |     # if bar is 30, set baz to 99
80 |     if foo.bar == 30:
81 |         foo.baz = 99
82 | 
83 |     # ba bytearray has now been modified
84 | 
85 | Enum Types
86 | ----------
87 | 
88 | .. |Build Status| image:: https://travis-ci.org/vivisect/vstruct2.svg
89 |    :target: https://travis-ci.org/vivisect/vstruct2
90 | 


--------------------------------------------------------------------------------
/vstruct2/tests/test_compat.py:
--------------------------------------------------------------------------------
 1 | import unittest
 2 | 
 3 | from vstruct2.compat import *
 4 | 
 5 | class CompatTest(unittest.TestCase):
 6 | 
 7 |     def test_compat_b2i(self):
 8 | 
 9 |         self.assertEqual( bytes2int(b'\xff\x56', 2, byteorder='big'), 0xff56 )
10 |         self.assertEqual( bytes2int(b'\xff\x56', 2, byteorder='little'), 0x56ff )
11 | 
12 |         self.assertEqual( bytes2int(b'\xff\xff\xff\xff', 4, signed=True), -1 )
13 |         self.assertEqual( bytes2int(b'\xff\xff\xff\xff', 4, signed=False), 0xffffffff )
14 |         
15 |         self.assertEqual( bytes2int(b'\xff\xff\xff\xff\xff\xff\xff\xff', 8, signed=True), -1 )
16 |         self.assertEqual( bytes2int(b'\xff\xff\xff\xff\xff\xff\xff\xff', 8, signed=False), 0xffffffffffffffff )
17 |         
18 |         bytes16 = b'\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff'
19 |         self.assertEqual( bytes2int(bytes16, 16, signed=True), -1 )
20 |         self.assertEqual( bytes2int(bytes16, 16, byteorder='big', signed=True), -1 )
21 |         self.assertEqual( bytes2int(bytes16, 16), 0xffffffffffffffffffffffffffffffff )
22 |         
23 |         bytes16_2 = b'\xff\xff\xff\xff\xff\xff\xff\xff\xf0\xf0\xf0\xf0\xf0\xf0\xf0\xf0'
24 |         self.assertEqual( bytes2int(bytes16_2, 16, byteorder='big'), 0xfffffffffffffffff0f0f0f0f0f0f0f0 )
25 |         self.assertEqual( bytes2int(bytes16_2, 16), 0xf0f0f0f0f0f0f0f0ffffffffffffffff )
26 | 
27 |     def test_compat_i2b(self):
28 | 
29 |         self.assertEqual( int2bytes(-1, 2, signed=True), b'\xff\xff' )
30 | 
31 |         self.assertEqual( int2bytes(0x102030, 3, byteorder='big'), b'\x10\x20\x30')
32 |         self.assertEqual( int2bytes(0x102030, 3, byteorder='little'), b'\x30\x20\x10')
33 | 
34 |         self.assertEqual( int2bytes(0x0080, 2, byteorder='big'), b'\x00\x80' )
35 |         self.assertEqual( int2bytes(0x0080, 2, byteorder='little'), b'\x80\x00' )
36 | 
37 |         self.assertEqual( int2bytes(0x008000800080008000800080, 12, byteorder='big'), b'\x00\x80\x00\x80\x00\x80\x00\x80\x00\x80\x00\x80' )
38 |         self.assertEqual( int2bytes(0x008000800080008000800080, 12, byteorder='little'), b'\x80\x00\x80\x00\x80\x00\x80\x00\x80\x00\x80\x00' )
39 | 


--------------------------------------------------------------------------------
/vstruct2/tests/test_sizes.py:
--------------------------------------------------------------------------------
 1 | import unittest
 2 | 
 3 | from vstruct2.bases import *
 4 | from vstruct2.types import *
 5 | 
 6 | class SizesTest(unittest.TestCase):
 7 | 
 8 |     def test_int8(self):
 9 |         i = int8()
10 |         self.assertEqual(len(i.vsEmit()), 1)
11 |         i.vsParse(b"\x00" * 8)
12 |         self.assertEqual(len(i.vsEmit()), 1)
13 | 
14 |     def test_int16(self):
15 |         i = int16()
16 |         self.assertEqual(len(i.vsEmit()), 2)
17 |         i.vsParse(b"\x00" * 8)
18 |         self.assertEqual(len(i.vsEmit()), 2)
19 | 
20 |     def test_int32(self):
21 |         i = int32()
22 |         self.assertEqual(len(i.vsEmit()), 4)
23 |         i.vsParse(b"\x00" * 8)
24 |         self.assertEqual(len(i.vsEmit()), 4)
25 | 
26 |     def test_int64(self):
27 |         i = int64()
28 |         self.assertEqual(len(i.vsEmit()), 8)
29 |         i.vsParse(b"\x00" * 8)
30 |         self.assertEqual(len(i.vsEmit()), 8)
31 | 
32 |     def test_vbytes(self):
33 |         i = vbytes(size=4)
34 |         self.assertEqual(len(i.vsEmit()), 4)
35 |         i.vsParse(b"\x00" * 8)
36 |         self.assertEqual(len(i.vsEmit()), 4)
37 | 
38 |     def test_cstr(self):
39 |         i = cstr(size=4)
40 |         self.assertEqual(len(i.vsEmit()), 4)
41 |         i.vsParse(b"\x00" * 8)
42 |         self.assertEqual(len(i.vsEmit()), 4)
43 | 
44 |     def test_zstr(self):
45 |         # zstr automatic resizing is documented,
46 |         # so we'll allow it to not emit `size` bytes
47 |         i = zstr(size=4)
48 |         self.assertEqual(len(i.vsEmit()), 1)
49 |         i.vsParse(b"\x00" * 8)
50 |         self.assertEqual(len(i.vsEmit()), 1)
51 | 
52 |     def test_varray_int8(self):
53 |         i = varray(4, int8)()
54 |         self.assertEqual(len(i.vsEmit()), 4)
55 |         i.vsParse(b"\x00" * 8)
56 |         self.assertEqual(len(i.vsEmit()), 4)
57 | 
58 |     def test_varray_vbytes(self):
59 |         i = VArray(fields=[vbytes(size=1) for _ in range(4)])
60 |         self.assertEqual(len(i.vsEmit()), 4)
61 |         i.vsParse(b"\x00" * 8)
62 |         self.assertEqual(len(i.vsEmit()), 4)
63 | 
64 | 
65 | def test():
66 |     try:
67 |         unittest.main()
68 |     except SystemExit:
69 |         pass
70 | 
71 | 
72 | if __name__ == '__main__':
73 |     test()
74 | 


--------------------------------------------------------------------------------
/vstruct2/compat.py:
--------------------------------------------------------------------------------
  1 | '''
  2 | A place to isolate the py27 compat filth.
  3 | '''
  4 | import sys
  5 | 
  6 | major = sys.version_info.major
  7 | minor = sys.version_info.minor
  8 | micro = sys.version_info.micro
  9 | 
 10 | version = (major,minor,micro)
 11 | 
 12 | if version < (3,0,0):
 13 | 
 14 |     import struct
 15 |     fmtchars = {
 16 |         (1,'big',False):'B',
 17 |         (1,'little',False):'B',
 18 | 
 19 |         (2,'big',False):'>H',
 20 |         (2,'little',False):'<H',
 21 | 
 22 |         (4,'big',False):'>I',
 23 |         (4,'little',False):'<I',
 24 | 
 25 |         (8,'big',False):'>Q',
 26 |         (8,'little',False):'<Q',
 27 | 
 28 |         (1,'big',True):'b',
 29 |         (1,'little',True):'b',
 30 | 
 31 |         (2,'big',True):'>h',
 32 |         (2,'little',True):'<h',
 33 | 
 34 |         (4,'big',True):'>i',
 35 |         (4,'little',True):'<i',
 36 | 
 37 |         (8,'big',True):'>q',
 38 |         (8,'little',True):'<q',
 39 |     }
 40 |     
 41 |     ''' Stolen from vivisect/envi/bits.py to keep vstruct dependency free. '''
 42 |     MAX_WORD = 32 # usually no more than 8, 16 is for SIMD register support
 43 | 
 44 |     # Masks to use for unsigned anding to size
 45 |     u_maxes = [ (2 ** (8*i)) - 1 for i in range(MAX_WORD+1) ]
 46 |     u_maxes[0] = 0 # powers of 0 are 1, but we need 0
 47 | 
 48 |     # Masks of just the sign bit for different sizes
 49 |     sign_bits = [ (2 ** (8*i)) >> 1 for i in range(MAX_WORD+1) ]
 50 |     sign_bits[0] = 0 # powers of 0 are 1, but we need 0
 51 | 
 52 |     def unsigned(value, size):
 53 |         ''' Stolen from vivisect/envi/bits.py to keep vstruct dependency free. '''
 54 |         return value & u_maxes[size]
 55 | 
 56 |     def signed(value, size):
 57 |         ''' Stolen from vivisect/envi/bits.py to keep vstruct dependency free. '''
 58 |         x = unsigned(value, size)
 59 |         if x & sign_bits[size]:
 60 |             x = (x - u_maxes[size]) - 1
 61 |         return x
 62 |     
 63 |     def slowparsebytes(byts, offset, size, sign=False, byteorder='little'):
 64 |         ''' Stolen from vivisect/envi/bits.py to keep vstruct dependency free. '''
 65 |         if byteorder == 'big':
 66 |             begin = offset
 67 |             inc = 1
 68 |         else:
 69 |             begin = offset + (size-1)
 70 |             inc = -1
 71 | 
 72 |         ret = 0
 73 |         ioff = 0
 74 |         for x in range(size):
 75 |             ret = ret << 8
 76 |             ret |= ord(byts[begin+ioff])
 77 |             ioff += inc
 78 |         if sign:
 79 |             ret = signed(ret, size)
 80 |         return ret
 81 | 
 82 |     def bytes2int(byts, size, off=0, byteorder='little', signed=False):
 83 |         """
 84 |         Mostly for pulling immediates out of strings...
 85 |         """
 86 |         if size > 8:
 87 |             return slowparsebytes(byts, off, size, sign=signed, byteorder=byteorder)
 88 | 
 89 |         fmt = fmtchars.get( (size,byteorder,signed) )
 90 |         if fmt != None:
 91 |             return struct.unpack(fmt, byts[off:off+size])[0]
 92 | 
 93 |         valu = 0
 94 |         vals = [ ord(c) for c in byts[off:off+size] ]
 95 | 
 96 |         if byteorder == 'little':
 97 |             vals.reverse()
 98 | 
 99 |         for i in range(size):
100 |             valu <<= 8
101 |             valu += vals[i]
102 | 
103 |         return valu
104 | 
105 |     def int2bytes(valu, size, byteorder='little', signed=False):
106 |         fmt = fmtchars.get( (size,byteorder,signed) )
107 |         if fmt != None:
108 |             return struct.pack(fmt, valu)
109 | 
110 |         ords = []
111 |         for i in range(size):
112 |             ords.append( (valu >> (8*i) ) & 0xff )
113 | 
114 |         if byteorder == 'big':
115 |             ords.reverse()
116 | 
117 |         return ''.join([ chr(o) for o in ords ])
118 | 
119 | else:
120 | 
121 |     def int2bytes(valu, size, byteorder='little', signed=False):
122 |         return valu.to_bytes(size, byteorder=byteorder, signed=signed)
123 | 
124 |     def bytes2int(byts, size, byteorder='little', signed=False, off=0):
125 |         return int.from_bytes(byts[off:off+size], byteorder=byteorder, signed=signed)
126 | 


--------------------------------------------------------------------------------
/vstruct2/tests/test_types.py:
--------------------------------------------------------------------------------
  1 | import io
  2 | import unittest
  3 | 
  4 | from ..types import *
  5 | 
  6 | class S1(VStruct):
  7 | 
  8 |     def __init__(self):
  9 |         VStruct.__init__(self)
 10 | 
 11 |         self.i8     = int8()
 12 |         self.i16    = int16()
 13 |         self.i32    = int32()
 14 |         self.i64    = int64()
 15 | 
 16 |         self.u8     = uint8()
 17 |         self.u16    = uint16()
 18 |         self.u32    = uint32()
 19 |         self.u64    = uint64()
 20 | 
 21 |         self.by6    = vbytes(6)
 22 |         self.cs6    = cstr(6)
 23 |         self.zs     = zstr()
 24 | 
 25 | s1bytes = b'\xff' * 36 + b'qwerty' + b'asdf\x00\x00\x00\x00'
 26 | 
 27 | class S2(VStruct):
 28 | 
 29 |     def __init__(self):
 30 |         VStruct.__init__(self)
 31 |         self.size   = uint16().vsOnset( self.setBytesSize )
 32 |         self.string = cstr()
 33 | 
 34 |     def setBytesSize(self):
 35 |         self['string'].vsResize( self.size )
 36 | 
 37 | class S3(VStruct):
 38 |     def __init__(self):
 39 |         VStruct.__init__(self)
 40 |         self.x      = uint8()
 41 |         self.y      = vbytes(6)
 42 | 
 43 | class S4(VStruct):
 44 |     def __init__(self):
 45 |         VStruct.__init__(self)
 46 |         self.w      = uint8()
 47 |         self.x      = vbytes(3)
 48 |         self.y      = zstr()
 49 |         self.z      = uint16()
 50 | 
 51 | class TypesTest(unittest.TestCase):
 52 | 
 53 |     def test_vstruct_basic(self):
 54 |         s1 = S1()
 55 |         s1.vsParse(s1bytes)
 56 | 
 57 |         self.assertEqual( s1.i8,  -1 )
 58 |         self.assertEqual( s1.i16, -1 )
 59 |         self.assertEqual( s1.i32, -1 )
 60 |         self.assertEqual( s1.i64, -1 )
 61 | 
 62 |         self.assertEqual( s1.u8,  0xff)
 63 |         self.assertEqual( s1.u16, 0xffff)
 64 |         self.assertEqual( s1.u32, 0xffffffff)
 65 |         self.assertEqual( s1.u64, 0xffffffffffffffff)
 66 | 
 67 |         self.assertEqual( s1.by6, b'\xff' * 6 )
 68 |         self.assertEqual( s1.cs6, 'qwerty')
 69 |         self.assertEqual( s1.zs,  'asdf')
 70 | 
 71 |         self.assertEqual( len(s1['zs']), 5 )
 72 | 
 73 |     def test_vstruct_resize_onparse(self):
 74 | 
 75 |         s2 = S2()
 76 |         s2.vsParse(b'\x04\x00ASDFGGGGGGGGGGGGG')
 77 | 
 78 |         self.assertEqual( s2.size, 4 )
 79 |         self.assertEqual( s2.string, 'ASDF' )
 80 | 
 81 |     def test_vstruct_resize_onset(self):
 82 | 
 83 |         s2 = S2()
 84 |         self.assertEqual( s2.vsEmit(), b'\x00\x00')
 85 | 
 86 |         s2.size = 3
 87 |         self.assertEqual( s2.vsEmit(), b'\x03\x00\x00\x00\x00')
 88 | 
 89 |     def test_vstruct_lazy(self):
 90 | 
 91 |         s1 = S1()
 92 |         s1.vsParse(s1bytes)
 93 | 
 94 |         self.assertIsNone( s1['i8']._vs_value )
 95 |         self.assertIsNone( s1['u8']._vs_value )
 96 |         self.assertIsNone( s1['by6']._vs_value )
 97 |         self.assertIsNone( s1['cs6']._vs_value )
 98 | 
 99 |     def test_vstruct_writeback(self):
100 | 
101 |         buf = bytearray(b'\x00' * 8)
102 | 
103 |         s3 = S3()
104 |         s3.vsParse( buf, writeback=True )
105 | 
106 |         s3.x = 20
107 |         self.assertEqual( bytes(buf), b'\x14' + b'\x00' * 7)
108 | 
109 |     def test_vstruct_load(self):
110 |         s4 = S4()
111 | 
112 |         fd = io.BytesIO(b'\xffQQQabcd\x00VV')
113 |         off = s4.vsLoad(fd, writeback=True)
114 | 
115 |         self.assertEqual(s4.w, 0xff)
116 |         self.assertEqual(s4.x, b'QQQ')
117 |         self.assertEqual(s4.y, 'abcd')
118 |         self.assertEqual(s4.z, 0x5656)
119 | 
120 |         self.assertEqual(off,11)
121 | 
122 |         s4.x = b'RRR'
123 |         fd.seek(0)
124 | 
125 |         self.assertEqual( fd.read(), b'\xffRRRabcd\x00VV')
126 | 
127 |     def test_vstruct_enum(self):
128 | 
129 |         foo = venum()
130 |         foo.one = 1
131 |         foo.two = 2
132 | 
133 |         class Bar(VStruct):
134 |             def __init__(self):
135 |                 VStruct.__init__(self)
136 |                 self.baz = uint16(enum=foo)
137 | 
138 |         bar = Bar()
139 |         bar.baz = 2
140 | 
141 |         self.assertEqual( repr(bar['baz']), 'two')
142 | 
143 |         self.assertEqual( foo.one, 1 )
144 |         self.assertEqual( foo.two, 2 )
145 | 
146 |         self.assertEqual( foo[1], 'one')
147 |         self.assertEqual( foo[2], 'two')
148 |         self.assertEqual( foo['one'], 1 )
149 |         self.assertEqual( foo['two'], 2 )
150 | 
151 |     def test_vstruct_endian(self):
152 | 
153 |         class Foo(VStruct):
154 |             def __init__(self):
155 |                 VStruct.__init__(self)
156 |                 self._vs_endian = 'big'
157 |                 self.bar    = uint16()
158 |                 self.baz    = uint32()
159 | 
160 |         foo = Foo()
161 |         foo.vsParse(b'\x01\x02\x03\x04\x05\x06')
162 |         self.assertEqual( foo.bar, 0x0102 )
163 |         self.assertEqual( foo.baz, 0x03040506 )
164 | 


--------------------------------------------------------------------------------
/vstruct2/bases.py:
--------------------------------------------------------------------------------
  1 | import traceback
  2 | from vstruct2.compat import int2bytes, bytes2int
  3 | 
  4 | # This routine was coppied from vivisect to allow vstruct
  5 | # to be free from dependencies
  6 | MAX_WORD = 16
  7 | def initmask(bits):
  8 |     return (1<<bits)-1
  9 | 
 10 | bitmasks = [ initmask(i) for i in range(MAX_WORD*8) ]
 11 | def bitmask(value,bits):
 12 |     return value & bitmasks[bits]
 13 | 
 14 | class v_base:
 15 |     '''
 16 |     Base class for all VStruct types
 17 |     '''
 18 |     def __init__(self):
 19 |         self._vs_onset = []
 20 |         self._vs_isprim = True
 21 | 
 22 |     def __len__(self):
 23 |         return self.vsSize()
 24 | 
 25 |     def __bytes__(self):
 26 |         return self.vsEmit()
 27 | 
 28 |     def vsOnset(self, callback, *args, **kwargs):
 29 |         '''
 30 |         Trigger a callback when the fields value is updated.
 31 | 
 32 |         NOTE: this callback is triggered during parse() as well
 33 |               as during value updates.
 34 |         '''
 35 |         self._vs_onset.append( (callback,args,kwargs) )
 36 |         return self
 37 | 
 38 |     def _fire_onset(self):
 39 |         for cb,args,kwargs in self._vs_onset:
 40 |             try:
 41 |                 cb(*args,**kwargs)
 42 |             except Exception as e:
 43 |                 traceback.print_exc()
 44 | 
 45 | class v_prim(v_base):
 46 |     '''
 47 |     Base class for all vstruct primitive types
 48 |     '''
 49 |     def __init__(self, size=None, valu=None):
 50 |         v_base.__init__(self)
 51 |         self._vs_size = size
 52 |         self._vs_bits = size * 8
 53 |         self._vs_value = self._prim_norm(valu)
 54 |         self._vs_parent = None
 55 | 
 56 |         # on-demand field parsing
 57 |         self._vs_backfd = None
 58 |         self._vs_backoff = None
 59 |         self._vs_backbytes = None
 60 |         self._vs_writeback = False
 61 | 
 62 |     def __repr__(self):
 63 |         return repr(self._prim_getval())
 64 | 
 65 |     def vsGetTypeName(self):
 66 |         return self.__class__.__name__
 67 | 
 68 |     def vsParse(self, bytez, offset=0, writeback=False):
 69 |         '''
 70 |         Byte parsing method for VStruct primitives.
 71 |         '''
 72 |         self._vs_value = None
 73 |         self._vs_backoff = offset
 74 |         self._vs_backbytes = bytez
 75 |         self._vs_writeback = writeback
 76 |         retval = offset + self.vsSize()
 77 |         self._fire_onset()
 78 |         return retval
 79 | 
 80 |     def vsLoad(self, fd, offset=0, writeback=False):
 81 |         self._vs_value = None
 82 |         self._vs_backfd = fd
 83 |         self._vs_backoff = offset
 84 |         self._vs_writeback = writeback
 85 |         retval = offset + self.vsSize()
 86 |         self._fire_onset()
 87 |         return retval
 88 | 
 89 |     def vsSize(self):
 90 |         '''
 91 |         Return the size of the field.
 92 |         '''
 93 |         return self._vs_size
 94 | 
 95 |     def vsResize(self, size):
 96 |         '''
 97 |         Resizing callback which can dynamically change the size
 98 |         of a primitive.
 99 |         '''
100 |         self._vs_size = size
101 | 
102 |     def _prim_setval(self, newval):
103 |         valu = self._prim_norm(newval)
104 |         self._vs_value = valu
105 | 
106 |         # if requested, write changes back to bytearray / fd
107 |         if self._vs_writeback:
108 |             byts = self._prim_emit(valu)
109 |             if self._vs_backbytes != None:
110 |                 self._vs_backbytes[ self._vs_backoff:self._vs_backoff + len(byts) ] = byts
111 | 
112 |             if self._vs_backfd != None:
113 |                 self._vs_backfd.seek( self._vs_backoff )
114 |                 self._vs_backfd.write( byts )
115 | 
116 |         self._fire_onset()
117 | 
118 |     def _prim_getval(self):
119 |         # trigger on-demand parsing if needed
120 |         if self._vs_value == None:
121 |             if self._vs_backfd:
122 |                 self._vs_value = self._prim_load(self._vs_backfd, self._vs_backoff)
123 |             elif self._vs_backbytes:
124 |                 self._vs_value = self._prim_parse(self._vs_backbytes, self._vs_backoff)
125 | 
126 |         return self._vs_value
127 | 
128 |     def _prim_load(self, fd, offset):
129 |         # easy base case...
130 |         fd.seek(offset)
131 |         byts = fd.read(self._vs_size)
132 |         return self._prim_parse(byts, 0)
133 | 
134 |     def vsEmit(self):
135 |         return self._prim_emit( self._prim_getval() )
136 | 
137 |     def _prim_norm(self, x):
138 |         raise Exception('Implement Me')
139 | 
140 |     def _prim_emit(self, x):
141 |         raise Exception('Implement Me')
142 | 
143 |     def _prim_parse(self, bytez, offset):
144 |         raise Exception('Implement Me')
145 | 
146 | class v_int(v_prim):
147 | 
148 |     def __init__(self,valu=0,size=4,endian='little',signed=False,enum=None):
149 |         v_prim.__init__(self,valu=valu,size=size)
150 |         self._vs_enum = enum
151 |         self._vs_endian = endian
152 |         self._vs_signed = signed
153 | 
154 |     def __int__(self):
155 |         return self._prim_getval()
156 | 
157 |     def __repr__(self):
158 |         valu = self._prim_getval()
159 |         if self._vs_enum != None:
160 |             enum = self._vs_enum[valu]
161 |             if enum != None:
162 |                 return enum
163 |         return repr(valu)
164 | 
165 |     def vsResize(self, size):
166 |         self._vs_bits = size * 8
167 |         return v_prim.vsResize(self,size)
168 | 
169 |     def _prim_emit(self,x):
170 |         return int2bytes(x, self._vs_size, byteorder=self._vs_endian, signed=self._vs_signed)
171 | 
172 |     def _prim_norm(self,x):
173 |         return bitmask(x,self._vs_bits)
174 | 
175 |     def _prim_parse(self, byts, offset):
176 |         return bytes2int(byts, self._vs_size, byteorder=self._vs_endian, signed=self._vs_signed, off=offset)
177 | 


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
  1 |                                  Apache License
  2 |                            Version 2.0, January 2004
  3 |                         http://www.apache.org/licenses/
  4 | 
  5 |    TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
  6 | 
  7 |    1. Definitions.
  8 | 
  9 |       "License" shall mean the terms and conditions for use, reproduction,
 10 |       and distribution as defined by Sections 1 through 9 of this document.
 11 | 
 12 |       "Licensor" shall mean the copyright owner or entity authorized by
 13 |       the copyright owner that is granting the License.
 14 | 
 15 |       "Legal Entity" shall mean the union of the acting entity and all
 16 |       other entities that control, are controlled by, or are under common
 17 |       control with that entity. For the purposes of this definition,
 18 |       "control" means (i) the power, direct or indirect, to cause the
 19 |       direction or management of such entity, whether by contract or
 20 |       otherwise, or (ii) ownership of fifty percent (50%) or more of the
 21 |       outstanding shares, or (iii) beneficial ownership of such entity.
 22 | 
 23 |       "You" (or "Your") shall mean an individual or Legal Entity
 24 |       exercising permissions granted by this License.
 25 | 
 26 |       "Source" form shall mean the preferred form for making modifications,
 27 |       including but not limited to software source code, documentation
 28 |       source, and configuration files.
 29 | 
 30 |       "Object" form shall mean any form resulting from mechanical
 31 |       transformation or translation of a Source form, including but
 32 |       not limited to compiled object code, generated documentation,
 33 |       and conversions to other media types.
 34 | 
 35 |       "Work" shall mean the work of authorship, whether in Source or
 36 |       Object form, made available under the License, as indicated by a
 37 |       copyright notice that is included in or attached to the work
 38 |       (an example is provided in the Appendix below).
 39 | 
 40 |       "Derivative Works" shall mean any work, whether in Source or Object
 41 |       form, that is based on (or derived from) the Work and for which the
 42 |       editorial revisions, annotations, elaborations, or other modifications
 43 |       represent, as a whole, an original work of authorship. For the purposes
 44 |       of this License, Derivative Works shall not include works that remain
 45 |       separable from, or merely link (or bind by name) to the interfaces of,
 46 |       the Work and Derivative Works thereof.
 47 | 
 48 |       "Contribution" shall mean any work of authorship, including
 49 |       the original version of the Work and any modifications or additions
 50 |       to that Work or Derivative Works thereof, that is intentionally
 51 |       submitted to Licensor for inclusion in the Work by the copyright owner
 52 |       or by an individual or Legal Entity authorized to submit on behalf of
 53 |       the copyright owner. For the purposes of this definition, "submitted"
 54 |       means any form of electronic, verbal, or written communication sent
 55 |       to the Licensor or its representatives, including but not limited to
 56 |       communication on electronic mailing lists, source code control systems,
 57 |       and issue tracking systems that are managed by, or on behalf of, the
 58 |       Licensor for the purpose of discussing and improving the Work, but
 59 |       excluding communication that is conspicuously marked or otherwise
 60 |       designated in writing by the copyright owner as "Not a Contribution."
 61 | 
 62 |       "Contributor" shall mean Licensor and any individual or Legal Entity
 63 |       on behalf of whom a Contribution has been received by Licensor and
 64 |       subsequently incorporated within the Work.
 65 | 
 66 |    2. Grant of Copyright License. Subject to the terms and conditions of
 67 |       this License, each Contributor hereby grants to You a perpetual,
 68 |       worldwide, non-exclusive, no-charge, royalty-free, irrevocable
 69 |       copyright license to reproduce, prepare Derivative Works of,
 70 |       publicly display, publicly perform, sublicense, and distribute the
 71 |       Work and such Derivative Works in Source or Object form.
 72 | 
 73 |    3. Grant of Patent License. Subject to the terms and conditions of
 74 |       this License, each Contributor hereby grants to You a perpetual,
 75 |       worldwide, non-exclusive, no-charge, royalty-free, irrevocable
 76 |       (except as stated in this section) patent license to make, have made,
 77 |       use, offer to sell, sell, import, and otherwise transfer the Work,
 78 |       where such license applies only to those patent claims licensable
 79 |       by such Contributor that are necessarily infringed by their
 80 |       Contribution(s) alone or by combination of their Contribution(s)
 81 |       with the Work to which such Contribution(s) was submitted. If You
 82 |       institute patent litigation against any entity (including a
 83 |       cross-claim or counterclaim in a lawsuit) alleging that the Work
 84 |       or a Contribution incorporated within the Work constitutes direct
 85 |       or contributory patent infringement, then any patent licenses
 86 |       granted to You under this License for that Work shall terminate
 87 |       as of the date such litigation is filed.
 88 | 
 89 |    4. Redistribution. You may reproduce and distribute copies of the
 90 |       Work or Derivative Works thereof in any medium, with or without
 91 |       modifications, and in Source or Object form, provided that You
 92 |       meet the following conditions:
 93 | 
 94 |       (a) You must give any other recipients of the Work or
 95 |           Derivative Works a copy of this License; and
 96 | 
 97 |       (b) You must cause any modified files to carry prominent notices
 98 |           stating that You changed the files; and
 99 | 
100 |       (c) You must retain, in the Source form of any Derivative Works
101 |           that You distribute, all copyright, patent, trademark, and
102 |           attribution notices from the Source form of the Work,
103 |           excluding those notices that do not pertain to any part of
104 |           the Derivative Works; and
105 | 
106 |       (d) If the Work includes a "NOTICE" text file as part of its
107 |           distribution, then any Derivative Works that You distribute must
108 |           include a readable copy of the attribution notices contained
109 |           within such NOTICE file, excluding those notices that do not
110 |           pertain to any part of the Derivative Works, in at least one
111 |           of the following places: within a NOTICE text file distributed
112 |           as part of the Derivative Works; within the Source form or
113 |           documentation, if provided along with the Derivative Works; or,
114 |           within a display generated by the Derivative Works, if and
115 |           wherever such third-party notices normally appear. The contents
116 |           of the NOTICE file are for informational purposes only and
117 |           do not modify the License. You may add Your own attribution
118 |           notices within Derivative Works that You distribute, alongside
119 |           or as an addendum to the NOTICE text from the Work, provided
120 |           that such additional attribution notices cannot be construed
121 |           as modifying the License.
122 | 
123 |       You may add Your own copyright statement to Your modifications and
124 |       may provide additional or different license terms and conditions
125 |       for use, reproduction, or distribution of Your modifications, or
126 |       for any such Derivative Works as a whole, provided Your use,
127 |       reproduction, and distribution of the Work otherwise complies with
128 |       the conditions stated in this License.
129 | 
130 |    5. Submission of Contributions. Unless You explicitly state otherwise,
131 |       any Contribution intentionally submitted for inclusion in the Work
132 |       by You to the Licensor shall be under the terms and conditions of
133 |       this License, without any additional terms or conditions.
134 |       Notwithstanding the above, nothing herein shall supersede or modify
135 |       the terms of any separate license agreement you may have executed
136 |       with Licensor regarding such Contributions.
137 | 
138 |    6. Trademarks. This License does not grant permission to use the trade
139 |       names, trademarks, service marks, or product names of the Licensor,
140 |       except as required for reasonable and customary use in describing the
141 |       origin of the Work and reproducing the content of the NOTICE file.
142 | 
143 |    7. Disclaimer of Warranty. Unless required by applicable law or
144 |       agreed to in writing, Licensor provides the Work (and each
145 |       Contributor provides its Contributions) on an "AS IS" BASIS,
146 |       WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
147 |       implied, including, without limitation, any warranties or conditions
148 |       of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
149 |       PARTICULAR PURPOSE. You are solely responsible for determining the
150 |       appropriateness of using or redistributing the Work and assume any
151 |       risks associated with Your exercise of permissions under this License.
152 | 
153 |    8. Limitation of Liability. In no event and under no legal theory,
154 |       whether in tort (including negligence), contract, or otherwise,
155 |       unless required by applicable law (such as deliberate and grossly
156 |       negligent acts) or agreed to in writing, shall any Contributor be
157 |       liable to You for damages, including any direct, indirect, special,
158 |       incidental, or consequential damages of any character arising as a
159 |       result of this License or out of the use or inability to use the
160 |       Work (including but not limited to damages for loss of goodwill,
161 |       work stoppage, computer failure or malfunction, or any and all
162 |       other commercial damages or losses), even if such Contributor
163 |       has been advised of the possibility of such damages.
164 | 
165 |    9. Accepting Warranty or Additional Liability. While redistributing
166 |       the Work or Derivative Works thereof, You may choose to offer,
167 |       and charge a fee for, acceptance of support, warranty, indemnity,
168 |       or other liability obligations and/or rights consistent with this
169 |       License. However, in accepting such obligations, You may act only
170 |       on Your own behalf and on Your sole responsibility, not on behalf
171 |       of any other Contributor, and only if You agree to indemnify,
172 |       defend, and hold each Contributor harmless for any liability
173 |       incurred by, or claims asserted against, such Contributor by reason
174 |       of your accepting any such warranty or additional liability.
175 | 
176 |    END OF TERMS AND CONDITIONS
177 | 
178 |    APPENDIX: How to apply the Apache License to your work.
179 | 
180 |       To apply the Apache License to your work, attach the following
181 |       boilerplate notice, with the fields enclosed by brackets "{}"
182 |       replaced with your own identifying information. (Don't include
183 |       the brackets!)  The text should be enclosed in the appropriate
184 |       comment syntax for the file format. We also recommend that a
185 |       file or class name and description of purpose be included on the
186 |       same "printed page" as the copyright notice for easier
187 |       identification within third-party archives.
188 | 
189 |    Copyright {yyyy} {name of copyright owner}
190 | 
191 |    Licensed under the Apache License, Version 2.0 (the "License");
192 |    you may not use this file except in compliance with the License.
193 |    You may obtain a copy of the License at
194 | 
195 |        http://www.apache.org/licenses/LICENSE-2.0
196 | 
197 |    Unless required by applicable law or agreed to in writing, software
198 |    distributed under the License is distributed on an "AS IS" BASIS,
199 |    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
200 |    See the License for the specific language governing permissions and
201 |    limitations under the License.
202 | 
203 | 


--------------------------------------------------------------------------------
/vstruct2/types.py:
--------------------------------------------------------------------------------
  1 | import io
  2 | import codecs
  3 | 
  4 | from . import bases as vs_bases
  5 | 
  6 | # NOTE: keep this namespace super clean so it's safe to
  7 | #       use this via "from vstruct2.types import *"
  8 | 
  9 | '''
 10 | VStruct types module contains a standard set of working field types
 11 | for use in building VStruct definitions.
 12 | '''
 13 | 
 14 | class VStruct(vs_bases.v_base,object):
 15 |     '''
 16 |     Base class for all structure definitions.
 17 | 
 18 |     The VStruct class facilitates structure definition, parsing, and emiting
 19 |     by allowing users to define fields with specific types.  Once defined, VStruct
 20 |     based structure classes are capable of automagically parsing data structure
 21 |     hierarchies as well as emiting bytes.
 22 | 
 23 |     Example:
 24 | 
 25 |         class woot(VStruct):
 26 | 
 27 |             def __init__(self):
 28 |                 self.x = int8()
 29 |                 self.y = uint32()
 30 |                 self.z = vbytes(6)
 31 | 
 32 |         w = woot()
 33 |         w.vsParse( bytebuffer )
 34 | 
 35 |         # we may now access the structure fields directly from our
 36 |         # object which will return proper pythonic types for the
 37 |         # field accesses:
 38 | 
 39 |         print('x: %d y: %d' % (w.x, w.y))
 40 | 
 41 |         # additionally, we may set pre-defined fields using python types
 42 |         w.y = 90
 43 | 
 44 |         # and re-serialize the newly modified structure back to bytes
 45 |         w.vsEmit()
 46 |     '''
 47 | 
 48 |     def __init__(self, align=0):
 49 |         vs_bases.v_base.__init__(self)
 50 |         self._vs_endian = None
 51 |         self._vs_isprim = False
 52 | 
 53 |         self._vs_fields = {}
 54 |         self._vs_fieldorder = []
 55 | 
 56 |         # from a tiny bit of evil from vstruct1
 57 |         self._vs_name = self.__class__.__name__
 58 | 
 59 |     def vsGetTypeName(self):
 60 |         return self._vs_name
 61 | 
 62 |     def __iter__(self):
 63 |         for name in self._vs_fieldorder:
 64 |             yield ( name, self._vs_fields.get(name) )
 65 | 
 66 |     def vsEmit(self):
 67 |         '''
 68 |         Return bytes for the current values in the structure definition.
 69 |         '''
 70 |         fd = io.BytesIO()
 71 |         for off,prim in self.vsPrims():
 72 |             fd.seek(off)
 73 |             fd.write( prim.vsEmit() )
 74 |         fd.seek(0)
 75 |         return fd.read()
 76 | 
 77 |     def vsParse(self, buf, offset=0, writeback=False):
 78 |         '''
 79 |         Parse the given python bytes into structure values.
 80 |         '''
 81 |         retoff = offset
 82 |         for off,prim in self.vsPrims():
 83 |             retoff = prim.vsParse(buf, offset=offset+off, writeback=writeback)
 84 |         self._fire_onset()
 85 |         return retoff
 86 | 
 87 |     def vsLoad(self, fd, offset=0, writeback=False):
 88 |         retoff = offset
 89 |         for off,prim in self.vsPrims():
 90 |             retoff = prim.vsLoad(fd, offset=offset+off, writeback=writeback)
 91 |         self._fire_onset()
 92 |         return retoff
 93 | 
 94 |     def vsPrint(self, indent=0, addr=0):
 95 |         off = 0
 96 |         pad = ' ' * indent
 97 | 
 98 |         print('%.8x: %s%s' % (addr,pad,self.__class__.__name__))
 99 |         for name,field in self:
100 |             typename = field.__class__.__name__
101 |             print( '%.8x: %s%s %s = %s (%s)' % (addr+off,pad,typename,name,field._prim_getval(),repr(field)) )
102 |             if not field._vs_isprim:
103 |                 field.vsPrint(indent=indent+2,addr=addr+off)
104 | 
105 |             off += len(field)
106 | 
107 |     def _vs_prims(self):
108 |         # recursive primitive *yielder* ( allows resizing while yielding )
109 |         for name in self._vs_fieldorder:
110 |             field = self._vs_fields.get(name)
111 |             # for non-primitives, "recurse"
112 |             if not field._vs_isprim:
113 |                 for f in field._vs_prims():
114 |                     yield f
115 | 
116 |                 continue
117 | 
118 |             yield field
119 | 
120 |     def vsPrims(self):
121 |         '''
122 |         Yield (offset,field) tuples for each contained primitive
123 | 
124 |         NOTE: this is implemented as a yield generator to allow resizing
125 |         '''
126 |         offset = 0
127 |         for prim in self._vs_prims():
128 |             # FIXME do alignment here
129 |             yield (offset,prim)
130 |             offset += prim.vsSize()
131 | 
132 |     def vsSize(self):
133 |         '''
134 |         Returns the current size of the structure in bytes.
135 |         '''
136 |         prims = list( self.vsPrims() )
137 |         if not prims:
138 |             return 0
139 |         off,field = prims[-1]
140 |         return off + field.vsSize()
141 | 
142 |     def vsGetField(self, name):
143 |         x = self._vs_fields.get(name)
144 |         if x == None:
145 |             raise Exception("Invalid field: %s" % name)
146 |         return x
147 | 
148 |     def vsHasField(self, name):
149 |         '''
150 |         Test whether this structure contains a field with the
151 |         given name....
152 |         Example:
153 |         if x.vsHasField('woot'):
154 |             print 'STRUCT HAS WOOT FIELD!'
155 |         '''
156 |         return self._vs_fields.get(name) != None
157 | 
158 |     def _prim_getval(self):
159 |         return self
160 | 
161 |     def __getattr__(self, name):
162 |         ret = self._vs_fields.get(name)
163 |         if ret != None:
164 |             return ret._prim_getval()
165 |         raise AttributeError('%s has no field %s' % (self.__class__.__name__,name))
166 | 
167 |     def __setattr__(self, name, valu):
168 |         if name.startswith('_vs_'):
169 |             return super(VStruct,self).__setattr__(name,valu)
170 | 
171 |         # check for endian-ness override
172 |         if self._vs_endian and isinstance(valu,vs_bases.v_int):
173 |             valu._vs_endian = self._vs_endian
174 | 
175 |         if isinstance(valu,vs_bases.v_base):
176 |             field = self._vs_fields.get(name)
177 |             if field == None:
178 |                 self._vs_fieldorder.append(name)
179 |             self._vs_fields[name] = valu
180 |             return
181 | 
182 |         field = self._vs_fields.get(name)
183 |         if field != None:
184 |             field._prim_setval( valu )
185 |             return
186 | 
187 |         return super(VStruct,self).__setattr__(name,valu)
188 | 
189 |     def __getitem__(self, name):
190 |         return self._vs_fields.get(name)
191 | 
192 |     def __setitem__(self, name, valu):
193 |         field = self._vs_fields.get(name)
194 | 
195 |         if isinstance(valu,vs_bases.v_base):
196 |             self._vs_fields[name] = valu
197 |             if field == None:
198 |                 self._vs_fieldorder.append( name )
199 | 
200 |             return
201 | 
202 |         if field == None:
203 |             raise Exception('Undefined Field: %s' % name)
204 | 
205 |         field._prim_setval( valu )
206 | 
207 | class VArray(VStruct):
208 | 
209 |     def __init__(self, fields=()):
210 |         VStruct.__init__(self)
211 | 
212 |         for i,f in enumerate(fields):
213 |             self[i] = f
214 | 
215 |     def vsAddElement(self, elem):
216 |         """
217 |         Used to add elements to an array
218 |         """
219 |         new_idx = len(self._vs_fields)
220 |         self[new_idx] = elem
221 | 
222 |     def vsAddElements(self, count, eclass):
223 |         for i in xrange(count):
224 |             self.vsAddElement(eclass())
225 | 
226 | class vbytes(vs_bases.v_prim):
227 |     '''
228 |     Fixed width binary bytes field.
229 |     '''
230 |     def __init__(self, size=0,val=b''):
231 |         vs_bases.v_prim.__init__(self, size=size,valu=val)
232 |         self._vs_value  = val
233 |         self._vs_length = size
234 | 
235 |     def _prim_emit(self, x):
236 |         return x.ljust(self.vsSize(), b'\x00')
237 | 
238 |     def _prim_norm(self, x):
239 |         return bytes(x)
240 | 
241 |     def _prim_parse(self, byts, offset):
242 |         return bytes( byts[offset:offset + self.vsSize() ] )
243 | 
244 |     ## FIXME - may need to add function to update length whenever valu is changed?
245 | 
246 | class cstr(vs_bases.v_prim):
247 |     '''
248 |     Fixed width string type.
249 | 
250 |     Assignments will be NULL padded to match size.
251 | 
252 |     Example:
253 | 
254 |         class woot(VStruct):
255 |             def __init__(self):
256 |                 self.x = cstr(8)
257 | 
258 |         w = woot()
259 |         w.x = 'hi'
260 | 
261 |         w.vsEmit() # emit's 8 bytes
262 | 
263 |     '''
264 |     def __init__(self, size=0, valu='', encoding='utf8'):
265 |         self._vs_encoding = encoding
266 |         vs_bases.v_prim.__init__(self,size=size,valu=valu)
267 | 
268 |     def _prim_emit(self, x):
269 |         return x.encode( self._vs_encoding ).ljust( self.vsSize(), b'\x00' )
270 | 
271 |     def _prim_norm(self, x):
272 |         buf = x.encode( self._vs_encoding )
273 |         return buf[:self.vsSize()].decode( self._vs_encoding )
274 | 
275 |     def _prim_parse(self, byts, offset):
276 |         buf = byts[offset:offset + self.vsSize()]
277 |         return buf.decode( self._vs_encoding ).split('\x00')[0]
278 | 
279 | class zstr(vs_bases.v_prim):
280 |     r'''
281 |     A dynamically sized ( NULL terminated ) string type.
282 | 
283 |     Parsing bytes will dynamically resize the object to the first NULL.
284 | 
285 |     Example:
286 |         class woot(VStruct):
287 |             def __init__(self):
288 |                 self.x = zstr()
289 |                 self.y = uint16()
290 | 
291 |         w = woot()
292 |         w.vsParse(b'this is some text\x00\x03\x00')
293 | 
294 |         print(w.y) # prints 3
295 | 
296 |         # assignment auto NULL pads
297 |         w = woot()
298 |         w.x = 'hi there'
299 |         w.y = 0x4141
300 | 
301 |         w.vsEmit() # emits b'hi there\x00AA'
302 |     '''
303 |     def __init__(self, size=0, valu='', encoding='utf8'):
304 |         self._vs_encoding = encoding
305 |         vs_bases.v_prim.__init__(self, size=size, valu=valu)
306 | 
307 |     def vsSize(self):
308 |         self._prim_getval()
309 |         return self._vs_size
310 | 
311 |     def _prim_norm(self, x):
312 |         buf = (x + '\x00').encode( self._vs_encoding )
313 |         self.vsResize( len(buf) )
314 |         return x
315 | 
316 |     def _prim_emit(self, x):
317 |         return (x + '\x00').encode( self._vs_encoding )
318 | 
319 |     def _prim_parse(self, buf, off):
320 |         info = {}
321 |         gen = self._prim_yield_bytes(buf, off, info)
322 |         return self._prim_fromgen(gen,info)
323 | 
324 |     def _prim_load(self, fd, off):
325 |         info = {}
326 |         gen = self._prim_yield_fd(fd,off,info)
327 |         return self._prim_fromgen(gen,info)
328 | 
329 |     def _prim_fromgen(self, yielder, info):
330 |         chars = []
331 |         # not exactly a model of efficiency...
332 |         for c in codecs.iterdecode(yielder, self._vs_encoding):
333 |             if ord(c) == 0:
334 |                 break
335 |             chars.append(c)
336 | 
337 |         self.vsResize(info['size'])
338 |         return ''.join(chars)
339 | 
340 |     def _prim_yield_bytes(self, buf, off, info):
341 |         info['size'] = 0
342 |         for i in range(len(buf) - off):
343 |             offi = off + i
344 |             b = buf[offi:offi+1]
345 |             info['size'] += 1
346 |             yield b
347 | 
348 |     def _prim_yield_fd(self, fd, off,info):
349 |         fd.seek(off)
350 |         info['size'] = 0
351 |         while True:
352 |             b = fd.read(1)
353 |             if not b:
354 |                 break
355 | 
356 |             info['size'] += 1
357 |             yield b
358 | 
359 | class int8(vs_bases.v_int):
360 |     '''
361 |     Signed 8 bit integer type
362 |     '''
363 |     def __init__(self, valu=0, endian='little'):
364 |         vs_bases.v_int.__init__(self, valu=valu, size=1, endian=endian, signed=True)
365 | 
366 | class int16(vs_bases.v_int):
367 |     '''
368 |     Signed 16 bit integer type
369 |     '''
370 |     def __init__(self, valu=0, endian='little'):
371 |         vs_bases.v_int.__init__(self, valu=valu, size=2, endian=endian, signed=True)
372 | 
373 | class int32(vs_bases.v_int):
374 |     '''
375 |     Signed 32 bit integer type
376 |     '''
377 |     def __init__(self, valu=0, endian='little'):
378 |         vs_bases.v_int.__init__(self, valu=valu, size=4, endian=endian, signed=True)
379 | 
380 | class int64(vs_bases.v_int):
381 |     '''
382 |     Signed 64 bit integer type
383 |     '''
384 |     def __init__(self, valu=0, endian='little'):
385 |         vs_bases.v_int.__init__(self, valu=valu, size=8, endian=endian, signed=True)
386 | 
387 | class uint8(vs_bases.v_int):
388 |     '''
389 |     Unsigned 8 bit integer type
390 |     '''
391 |     def __init__(self, valu=0, endian='little', enum=None):
392 |         vs_bases.v_int.__init__(self, valu=valu, size=1, endian=endian, enum=enum)
393 | 
394 | class uint16(vs_bases.v_int):
395 |     '''
396 |     Unsigned 16 bit integer type
397 |     '''
398 |     def __init__(self, valu=0, endian='little', enum=None):
399 |         vs_bases.v_int.__init__(self, valu=valu, size=2, endian=endian, enum=enum)
400 | 
401 | class uint32(vs_bases.v_int):
402 |     '''
403 |     Unsigned 32 bit integer type
404 |     '''
405 |     def __init__(self, valu=0, endian='little', enum=None):
406 |         vs_bases.v_int.__init__(self, valu=valu, size=4, endian=endian, enum=enum)
407 | 
408 | class uint64(vs_bases.v_int):
409 |     '''
410 |     Unsigned 64 bit integer type
411 |     '''
412 |     def __init__(self, valu=0, endian='little', enum=None):
413 |         vs_bases.v_int.__init__(self, valu=valu, size=8, endian=endian, enum=enum)
414 | 
415 | class ptr32(vs_bases.v_int):
416 |     def __init__(self, valu=0, endian='little'):
417 |         vs_bases.v_int.__init__(self, valu=valu, size=4, endian=endian)
418 | 
419 | class ptr64(vs_bases.v_int):
420 |     def __init__(self, valu=0, endian='little'):
421 |         vs_bases.v_int.__init__(self, valu=valu, size=8, endian=endian)
422 | 
423 | def varray(size, cls, *args, **kwargs):
424 |     '''
425 |     Dynamically generate an VArray sublcass with "size" fields of type "cls"
426 | 
427 |     Example:
428 | 
429 |         cls = varray(10,uint32)
430 | 
431 |     # FIXME __mul__ for classes?
432 | 
433 |     '''
434 | 
435 |     def clsinit(self):
436 |         fields = [ cls(*args,**kwargs) for i in range(size) ]
437 |         VArray.__init__(self,fields)
438 | 
439 |     name = '%s_Array_%d' % (cls.__name__,size)
440 |     return type(name,(VArray,),{'__init__':clsinit})
441 | 
442 | class venum(object):
443 |     '''
444 |     A venum class is used to define a set of enumeration values.
445 | 
446 |     Example:
447 | 
448 |         foo = venum()
449 |         foo.TYPE_1  = 1
450 |         foo.TYPE_2  = 2
451 | 
452 |         class woot(VStruct):
453 |             def __init__(self):
454 |                 self.y = uint16(enum=foo)
455 | 
456 |         # foo[2] -> 'TYPE_2'
457 |         # foo['TYPE_2'] -> 2
458 | 
459 |     Notes:
460 | 
461 |         * provide as enum param to int ctors for auto-repr
462 | 
463 |     '''
464 |     def __init__(self):
465 |         object.__setattr__(self, '_vs_enum_map', {})
466 | 
467 |     def __setattr__(self, name, valu):
468 |         self._vs_enum_map[valu] = name
469 |         self._vs_enum_map[name] = valu
470 |         return object.__setattr__(self, name, valu)
471 | 
472 |     def __getitem__(self, item):
473 |         return self._vs_enum_map.get(item)
474 | 


--------------------------------------------------------------------------------