.. raw:: html

    <style> .greenbox {color:white;background-color:#2c9a43;font-weight: normal; padding: 2px 5px 1px 5px;border-radius: 5px} </style>
    <style> .whitebox {color:black;background-color:white;font-weight: normal; padding: 2px 5px 1px 5px;border-radius: 5px} </style>

.. role:: greenbox
.. role:: whitebox


.. _03history:

Ajouter un historique
=====================

La première modification du jeu de base à consisté à étendre la map et à ajouter des directions pour augmenter le game play.

L'objectif de cette partie est de commencer à ajouter des fonctionnalités supplémentaires pour rendre le jeu plus intéressant.

GitHub stuff
------------

Ouvrir la ``[REPOSITORY_HOMEPAGE]`` et démarrer le codespace associé :

:greenbox:`Code`  :greenbox:`Codespaces` 

A partir du terminal du codespace, récupérer la dernière version du jeu depuis votre dépôt ::

    $ git pull

Utiliser l'extension ``GitLens`` pour examiner l'historique des commits, et en particulier les différences entre la version actuelle et la version précédente.

Construire un historique
------------------------

Pour conserver l'historique des lieux visités, et donner au joueur la possibilité de revenir sur ses pas automatiquement, on va ajouter une structure de données permettant de mémoriser les lieux visités.

.. quiz:: quizz-01
    :title: Construire un historique

    #. :quiz:`{"type":"FB","answer":"Player", "size":15}` Quelle est la classe concernée par cette modification ?
    #. :quiz:`{"type":"FB","answer":"list", "size":15}` Quelle est le type d'objet le plus adaptée pour mettre en oeuvre un historique ?
    #. :quiz:`{"type":"FB","answer":"append()", "size":15}` Sur cette structure de données, quelle est la méthode adaptée pour ajouter un lieu à l'historique ?
    #. :quiz:`{"type":"FB","answer":"pop()", "size":15}` Sur cette structure de données, quelle est la méthode adaptée pour revenir en arrière ?
    #. :quiz:`{"type":"FB","answer":"len()", "size":15}` Quelle fonction retournant une propriété essentielle de la structure de données faut il utiliser lors de multiples retours en arrière ?
    #. :quiz:`{"type":"FB","answer":"current_room", "size":15}` Si le retour est possible, quel attribut de la classe concernée par la modification faut il mettre à jour ?
    #. :quiz:`{"type":"TF","answer":"F"}` Au démarrage du jeu, l'historique doit il être initialisé avec le lieu dans lequel se trouve le joueur ? Pourquoi ?
    #. :quiz:`{"type":"TF","answer":"T"}` Au démarrage du jeu, l'historique doit il être vide ? La raison est la même que celle invoquée à la question précédente.

.. admonition:: A faire

    Après avoir répondu aux questions ci dessus, implémentez les modifications correspondantes :

    - ajouter un attribut ``history`` à la classe pertinente. Laquelle est ce ?
    - utilisez les réponses ci dessus pour savoir comment il doit être initialisé ;
    - comment doit il être mis à jour lors d'un déplacement du joueur ?
    - l'historique contient il la pièce dans laquelle démarre le joueur ? Pourquoi ?

    .. Player.__init__
        self.history = []

    .. Player.move
        self.history.append(self.current_room)

    .. non, le player est créé avant dêtre placé dans la pièce de départ

Une fois l'implémentation effectuée, répondez aux questions du quiz qui auraient été laissées en suspens.

.. admonition:: A faire

    Ecrire une méthode ``get_history()`` qui retourne une chaine de caractères représentative de l'affichage des pièces visitées. Il est pertinent de faire un appel à ``get_history()`` après chaque déplacement du joueur. Un exemple d'exécution est donné ci-dessous. Notez que l'historique est mis à jour à chaque tour.

    .. code-block:: text

        Vous êtes dans un marécage sombre et ténébreux. L'eau bouillonne, les abords sont vaseux.

        Sorties: N, O

        > go n

        Vous êtes dans une immense tour en pierre qui s'élève au dessus des nuages.

        Sorties: N, S, O

        Vous avez déja visité les pièces suivantes: 
            - un marécage sombre et ténébreux

        > go n

        Vous êtes dans un petit chalet pittoresque avec un toit de chaume. Une épaisse fumée verte sort de la cheminée.

        Sorties: S, O

        Vous avez déja visité les pièces suivantes: 
            - un marécage sombre et ténébreux
            - une immense tour en pierre qui s'élève au dessus des nuages

    Déplacez vous dans la map pour vérifier que l'historique est bien mis à jour à chaque tour.

.. admonition:: A faire

    Associer une commande ``history``, associée à la méthode ``get_history()`` écrite précédemment, pour permettre au joueur de consulter son historique à tout moment. La commande ``history`` doit être déclarée dans la liste des commandes disponibles.

Retourner en arrière
--------------------

Pour permettre au joueur de revenir en arrière, on va exploiter la structure de données identifiée à l'étape précédente en ajoutant une commande ``back`` à la disposition du joueur. A l'issue de cette modification, les commandes disponibles seront donc :

- ``go`` : pour se déplacer dans une direction
- ``back`` : pour revenir en arrière
- ``quit`` : pour quitter le jeu
- ``help`` : pour afficher l'aide

.. quiz:: quizz-02
    :title: Revenir en arrière

    .. warning::
    
        Les énumérations doivent être séparées par une virgule suivie d'un seul espace. Exemple : ``a, b, c``.

    #. :quiz:`{"type":"FB","answer":"Actions", "size":15}` Quelle est la classe concernée par la définition de la commande ``back`` ?
    #. :quiz:`{"type":"FB","answer":"game, list_of_words, number_of_parameters", "size":20}` Quels sont ses paramètres ?
    #. :quiz:`{"type":"FB","answer":"player", "size":20}` Quel est l'objet impacté directement par la commande ``back`` ?
    #. :quiz:`{"type":"TF","answer":"F"}` Peut on l'atteindre directement ?
    #. :quiz:`{"type":"TF","answer":"T"}` ou doit on l'atteindre en tant qu'attribut d'un autre objet ?
    #. :quiz:`{"type":"FB","answer":"game", "size":10}` Quel est cet objet ? Utiliser la chaine vide ``""`` pour indiquer qu'on peut atteindre cet objet directement.
    #. :quiz:`{"type":"TF","answer":"F"}` Peut on activer la commande ``back`` sans limite ?
    #. :quiz:`{"type":"FB","answer":"len()", "size":10}` Sinon, quelle fonction doit on utiliser sur l'historique pour vérifier que le retour en arrière est possible ? 


.. admonition:: A faire

    Après avoir répondu à ces questions, implémentez les modifications correspondantes en vous inspirant des fonctions déjà écrites.

    .. Actions.back
        def back(game, list_of_words, number_of_parameters):
            """
            Move the player in the opposite direction of the last move.
            """

            # If the number of parameters is incorrect, print an error message and return False.
            l = len(list_of_words)
            if l != number_of_parameters + 1:
                command_word = list_of_words[0]
                print(MSG0.format(command_word=command_word))
                return False
            
            # If the history is empty, print an error message and return False.
            if not game.player.history:
                print("\nVous êtes de retour dans le lieu de départ.\n")
                return False
            
            player = game.player
            player.current_room = player.history.pop()
            print(player.current_room.get_long_description())
            player.print_history()
            return True


    Ne pas oublier de déclarer la commande ``back`` dans la liste des commandes disponibles.

    .. Game.setup
        back = Command("back", "revenir sur ses pas", Actions.back, 0)
        self.commands["back"] = back

.. admonition:: A faire

    Il est pertinent d'appeler également ``get_history()`` après chaque retour en arrière. Un exemple d'exécution est donné ci-dessous. Notez que le joueur ne peut revenir en arrière que si il a déjà effectué un déplacement.

        .. code-block:: text
            
            Vous êtes dans une forêt enchantée. Vous entendez une brise légère à travers la cime des arbres.

            Sorties: N, E, S

            Vous avez déja visité les pièces suivantes: 
                - un marécage sombre et ténébreux
                - une immense tour en pierre qui s'élève au dessus des nuages
                - un petit chalet pittoresque avec un toit de chaume
                - une grotte profonde et sombre

            > back

            Vous êtes dans une grotte profonde et sombre. Des voix semblent provenir des profondeurs.

            Sorties: E, S

            Vous avez déja visité les pièces suivantes: 
                - un marécage sombre et ténébreux
                - une immense tour en pierre qui s'élève au dessus des nuages
                - un petit chalet pittoresque avec un toit de chaume
       

Vérification
------------


    Déplacez vous dans la map et vérifier que l'historique est correctement utilisé lors des appels à ``back``.

    Que se passe t-il lorsqu'on est revenu au point de départ après une suite de ``back`` ?

La suite...
-----------

A cette étape, votre dépôt doit contenir les seuls fichiers suivants :

- ``actions.py``
- ``command.py``
- ``game.py``
- ``player.py``
- ``room.py``

Le jeu doit être fonctionnel et avoir intégré les consignes précédentes. La commande ::

    $ python game.py

doit pouvoir permettre d'activer la fonction ``back`` sans erreur.

GitHub stuff
------------

Enregistrer les modifications apportées aux fichiers dans le repo local au codespace ::

    $ git add .
    $ git commit -m "Ajouter un historique"

Pour référencer plus facilement cette version dans le futur, créer un tag ::

    $ git tag v3

Synchroniser votre codespace avec votre dépôt GitHub ::

    $ git push

Vérifier que les modifications sont bien présentes dans le dépôt GitHub.