added a way to specify custom mapper

The custom mapper can be secified in `load`, `loads`, `parse` routines
via using keyword `mapper`. For example, to preserve key order one
can specify `OrderedDict` as a mapper. Another custom class could be
used to handle files with duplicate keys.

fix #1

Related to:
#2
rossengeorgiev/vdf-parser#3

Author: rossengeorgiev

README.rst

@@ -7,11 +7,15 @@ https://developer.valvesoftware.com/wiki/KeyValues
 The module works just like ``json`` to convert VDF to a dict, and vise-versa.
 
 
-Known Issues
+Poblems & solutions
 ------------
 
-- order is not preserved due to using ``dict``
-- there are known files that contain duplicate keys
+- There are known files that contain duplicate keys. This can be solved by
+  creating a class inherating from `dict` and implementing a way to handle
+  duplicate keys.
+
+- By default the module uses `dict`, so key order is preserved. If key order
+  is important then I suggest using `collections.OrderedDict`. See example.
 
 
 Install
@@ -24,7 +28,7 @@ You can grab the latest release from https://pypi.python.org/pypi/vdf or via ``p
     pip install vdf
 
 
-Usage
+Example usage
 -----------
 
 .. code:: python
@@ -45,6 +49,18 @@ Usage
     vdf.dump(d, open('file2.txt','w'), pretty=True)
 
 
+Using `OrderedDict` to preserve key order.
+
+.. code:: python
+
+    import vdf
+    from collections import OrderedDict
+
+    # parsing vdf from file or string
+    d = vdf.load(open('file.txt'), mapper=OrderedDict)
+    d = vdf.loads(vdf_text, mapper=OrderedDict)
+
+
 .. |pypi| image:: https://img.shields.io/pypi/v/vdf.svg?style=flat&label=latest%20version
     :target: https://pypi.python.org/pypi/vdf
     :alt: Latest version released on PyPi

tests/test_vdf.py

@@ -34,6 +34,21 @@ def test_routine_load(self, mock_parse):
         vdf.load(self.f)
         mock_parse.assert_called_with(self.f)
 
+    @mock.patch("vdf.parse")
+    def test_routines_mapper_passing(self, mock_parse):
+        vdf.load(sys.stdin, mapper=dict)
+        mock_parse.assert_called_with(sys.stdin, mapper=dict)
+        vdf.loads("", mapper=dict)
+        mock_parse.assert_called_with("", mapper=dict)
+
+        class CustomDict(dict):
+            pass
+
+        vdf.load(sys.stdin, mapper=CustomDict)
+        mock_parse.assert_called_with(sys.stdin, mapper=CustomDict)
+        vdf.loads("", mapper=CustomDict)
+        mock_parse.assert_called_with("", mapper=CustomDict)
+
     def test_routine_load_assert(self):
         for t in [5, 5.5, 1.0j, None, [], (), {}, lambda: 0, '']:
             self.assertRaises(AssertionError, vdf.load, t)
@@ -57,16 +72,20 @@ def test_routine_dump_asserts(self):
                 self.assertRaises(ValueError, vdf.dump, x, y)
 
     def test_routine_dump_writing(self):
-        src = {"asd": "123"}
-        expected = vdf.dumps(src)
+        class CustomDict(dict):
+            pass
 
-        vdf.dump(src, self.f)
-        self.f.seek(0)
+        for mapper in (dict, CustomDict):
+            src = mapper({"asd": "123"})
+            expected = vdf.dumps(src)
+
+            vdf.dump(src, self.f)
+            self.f.seek(0)
 
         self.assertEqual(expected, self.f.read())
 
 
-class testcase_parse_routine(unittest.TestCase):
+class testcase_routine_parse(unittest.TestCase):
     def test_parse_bom_removal(self):
         result = vdf.loads(vdf.BOMS + '"asd" "123"')
         self.assertEqual(result, {'asd': '123'})
@@ -75,13 +94,21 @@ def test_parse_bom_removal(self):
             result = vdf.loads(vdf.BOMS_UNICODE + '"asd" "123"')
             self.assertEqual(result, {'asd': '123'})
 
-    def test_parse_asserts(self):
+    def test_parse_source_asserts(self):
         for t in [5, 5.5, 1.0j, True, None, (), {}, lambda: 0]:
             self.assertRaises(ValueError, vdf.parse, t)
 
+    def test_parse_mapper_assert(self):
+        self.assertRaises(TypeError, vdf.parse, "", mapper=list)
+
     def test_parse_file_source(self):
         self.assertEqual(vdf.parse(StringIO(" ")), {})
 
+        class CustomDict(dict):
+            pass
+
+        self.assertEqual(vdf.parse(StringIO(" "), mapper=CustomDict), {})
+
 
 class testcase_VDF(unittest.TestCase):
     def test_format(self):

vdf/__init__.py

@@ -43,19 +43,21 @@ def strip_bom(line):
 ###############################################
 
 
-def parse(source):
+def parse(source, mapper=dict):
+    if not issubclass(mapper, dict):
+        raise TypeError("Expected mapper to be subclass of dict, got %s", type(mapper))
     if isinstance(source, file_type):
         lines = source.readlines()
     elif isinstance(source, string_type):
         lines = source.split('\n')
     else:
-        raise ValueError("Expected parametar to be file or str")
+        raise ValueError("Expected source to be file or str")
 
     # strip annoying BOMS
     lines[0] = strip_bom(lines[0])
 
     # init
-    obj = dict()
+    obj = mapper()
     stack = [obj]
     expect_bracket = False
 
@@ -111,7 +113,7 @@ def parse(source):
 
                     key = m.group(1)
 
-                    stack[-1][key] = dict()
+                    stack[-1][key] = mapper()
                     stack.append(stack[-1][key])
                     expect_bracket = True
 
@@ -124,14 +126,14 @@ def parse(source):
     return obj
 
 
-def loads(fp):
+def loads(fp, **kwargs):
     assert isinstance(fp, string_type)
-    return parse(fp)
+    return parse(fp, **kwargs)
 
 
-def load(fp):
+def load(fp, **kwargs):
     assert isinstance(fp, file_type)
-    return parse(fp)
+    return parse(fp, **kwargs)
 
 ###############################################
 #