#
# A template class representing the interactions that the end-user has
# with the filesystem in a z-machine.
#
# Third-party programs are expected to subclass ZFilesystem and
# override all the methods, then pass an instance of their class to be
# driven by the main z-machine engine.
#
# For the license of this file, please consult the LICENSE file in the
# root directory of this distribution.
#


class ZFilesystem:
    """Encapsulates the interactions that the end-user has with the
    filesystem."""

    def save_game(self, data, suggested_filename=None):
        """Prompt for a filename (possibly using suggested_filename), and
        attempt to write DATA as a saved-game file.  Return True on
        success, False on failure.

        Note that file-handling errors such as 'disc corrupt' and 'disc
        full' should be reported directly to the player by the method in
        question method, and they should also cause this function to
        return False.  If the user clicks 'cancel' or its equivalent,
        this function should return False."""

        raise NotImplementedError()

    def restore_game(self):
        """Prompt for a filename, and return file's contents.  (Presumably
        the interpreter will attempt to use those contents to restore a
        saved game.)  Returns None on failure.

        Note that file-handling errors such as 'disc corrupt' and 'disc
        full' should be reported directly to the player by the method in
        question method, and they should also cause this function to
        return None. The error 'file not found' should cause this function
        to return None.  If the user clicks 'cancel' or its equivalent,
        this function should return None."""

        raise NotImplementedError()

    def open_transcript_file_for_writing(self):
        """Prompt for a filename in which to save either a full game
        transcript or just a list of the user's commands.  Return standard
        python file object that can be written to.

        If an error occurs, or if the user clicks 'cancel' or its
        equivalent, return None."""

        raise NotImplementedError()

    def open_transcript_file_for_reading(self):
        """Prompt for a filename contain user commands, which can be used
        to drive the interpreter.  Return standard python file object that
        can be read from.

        If an error occurs, or if the user clicks 'cancel' or its
        equivalent, return None."""

        raise NotImplementedError()