State Saver (#15)

* Added state saving logic

Instead of relying on the _save_idx and _resotre_idx functions, we introduced a context manager to handle the state storing and restoring for us.

* Added _Source

Added special unicode class that handles iterating through the source text. This unicode class provides all of the functionality (and speed) of the prior solution but also allows the parser to more easily restore to a previous point in the source text without needing to copy/tee the generator.

* Update variable name

Updated marker variable to save_marker to be more descriptive of which marker variable this is.

* Switch index back to idx

Preserving prior variable conventions.

* Cleanup state handler

Moved state handler into src since it is directly related to the source text.

* Added back generators

After testing found that generators performed significantly better than indexing implementation that perserved TOMLChars.

* Addressed  minor bugs

Some bugs related to reverting back to the generator implementation.

* Fixed state saving to properly handle various restore cases

Modified state preserver to only restore unless explicitly configured to restore or if an exception was raised during parsing. Introduced a new exception (Restore) which when raised within a state handler will cause the state to be restored, but then the exception is silently consumed by the state handler.

* Moved Source into a standalone file

Looking forward into the potential development of a more modular parsing. This shift further seeks to seperate the functionality between the source text handling and the actual parsing itself.

* Added consume method

Add a convenience method that is of great value to simplifying and streamlining the parsing functions.

tomlkit/exceptions.py

@@ -137,3 +137,15 @@ def __init__(self, key):
         message = 'Key "{}" already exists.'.format(key)
 
         super(KeyAlreadyPresent, self).__init__(message)
+
+
+class Restore(TOMLKitError):
+    """
+    The current parsing path failed, restore to the previous state. This should only
+    be raised within a with the state handler context manager.
+    """
+
+    def __init__(self):  # type: () -> None
+        message = "Restore to the previous state."
+
+        super(Restore, self).__init__(message)