Set up boilerplate framework for adding subgames as type

This adds to C++ and Python the generic "boilerplate" code that makes
the new planned explicit representation of subgames `GameSubgameRep`
a type of `GameObject` (with its invalidation mechanism), and
the Python wrapper class `Subgame`.

A stub entry into the Python API index has also been added.

Now all that is left to do is to actually implement tests and functionality!!!!

Author: tturocy

doc/pygambit.api.rst

@@ -19,6 +19,7 @@ Representation of games
    Node
    Infoset
    Action
+   Subgame
    Strategy
 
 
@@ -152,7 +153,6 @@ Information about the game
    Node.own_prior_action
 
 .. autosummary::
-
    :toctree: api/
 
    Infoset.label
@@ -167,7 +167,6 @@ Information about the game
    Infoset.own_prior_actions
 
 .. autosummary::
-
    :toctree: api/
 
    Action.label
@@ -177,7 +176,12 @@ Information about the game
    Action.plays
 
 .. autosummary::
+   :toctree: api/
 
+   Subgame.game
+   Subgame.root
+
+.. autosummary::
    :toctree: api/
 
    Strategy.label

src/games/game.h

@@ -58,6 +58,9 @@ using GamePlayer = GameObjectPtr<GamePlayerRep>;
 class GameNodeRep;
 using GameNode = GameObjectPtr<GameNodeRep>;
 
+class GameSubgameRep;
+using GameSubgame = GameObjectPtr<GameSubgameRep>;
+
 class GameRep;
 using Game = std::shared_ptr<GameRep>;
 
@@ -593,6 +596,26 @@ inline GameNodeRep::Actions::iterator::iterator(GameInfosetRep::Actions::iterato
 
 inline GameNode GameNodeRep::Actions::iterator::GetOwner() const { return m_child_it.GetOwner(); }
 
+class GameSubgameRep : public std::enable_shared_from_this<GameSubgameRep> {
+  bool m_valid{true};
+  GameRep *m_game;
+  GameNodeRep *m_root;
+
+public:
+  GameSubgameRep(GameRep *p_game, GameNodeRep *p_root) : m_game(p_game), m_root(p_root) {}
+  ~GameSubgameRep() = default;
+
+  bool IsValid() const { return m_valid; }
+  void Invalidate() { m_valid = false; }
+
+  GameNode GetRoot() const { return m_root->shared_from_this(); }
+  Game GetGame() const;
+
+  // Functions to implement suitably:
+  // GetParent()
+  // GetChildren()
+};
+
 inline void ValidateDistribution(const Array<Number> &p_probs, const bool p_normalized = true)
 {
   if (std::any_of(p_probs.begin(), p_probs.end(),
@@ -1246,6 +1269,8 @@ inline GamePlayerRep::Infosets GamePlayerRep::GetInfosets() const
   return Infosets(std::const_pointer_cast<GamePlayerRep>(shared_from_this()), &m_infosets);
 }
 
+inline Game GameSubgameRep::GetGame() const { return m_game->shared_from_this(); }
+
 //=======================================================================
 
 /// Factory function to create new game tree

src/pygambit/gambit.pxd

@@ -50,6 +50,7 @@ cdef extern from "games/game.h":
     cdef cppclass c_GamePlayerRep "GamePlayerRep"
     cdef cppclass c_GameOutcomeRep "GameOutcomeRep"
     cdef cppclass c_GameNodeRep "GameNodeRep"
+    cdef cppclass c_GameSubgameRep "GameSubgameRep"
 
     cdef cppclass c_Game "Game":
         c_GameRep *deref "operator->"() except +RuntimeError
@@ -67,6 +68,10 @@ cdef extern from "games/game.h":
         bool operator !=(c_GameNode) except +
         c_GameNodeRep *deref "get"() except +RuntimeError
 
+    cdef cppclass c_GameSubgame "GameObjectPtr<GameSubgameRep>":
+        bool operator !=(c_GameSubgame) except +
+        c_GameSubgameRep *deref "get"() except +RuntimeError
+
     cdef cppclass c_GameAction "GameObjectPtr<GameActionRep>":
         bool operator !() except +
         bool operator !=(c_GameAction) except +
@@ -218,6 +223,12 @@ cdef extern from "games/game.h":
         c_GameAction GetPriorAction() except +
         c_GameAction GetOwnPriorAction() except +
 
+    cdef cppclass c_GameSubgameRep "GameSubgameRep":
+        c_Game GetGame() except +
+        c_GameNode GetRoot() except +
+        # GetParent()
+        # GetChildren()
+
     cdef cppclass c_GameRep "GameRep":
         cppclass Players:
             cppclass iterator:

src/pygambit/node.pxi

@@ -259,3 +259,40 @@ class Node:
         """Returns a list of all terminal `Node` objects consistent with it.
         """
         return [Node.wrap(n) for n in self.node.deref().GetGame().deref().GetPlays(self.node)]
+
+
+@cython.cclass
+class Subgame:
+    """A subgame in a ``Game``."""
+    subgame = cython.declare(c_GameSubgame)
+
+    def __init__(self, *args, **kwargs) -> None:
+        raise ValueError("Cannot create a Subgame outside a Game.")
+
+    @staticmethod
+    @cython.cfunc
+    def wrap(subgame: c_GameSubgame) -> Subgame:
+        obj: Subgame = Subgame.__new__(Subgame)
+        obj.subgame = subgame
+        return obj
+
+    # needs a __repr__
+
+    def __eq__(self, other: typing.Any) -> bool:
+        return (
+            isinstance(other, Subgame) and
+            self.subgame.deref() == cython.cast(Subgame, other).subgame.deref()
+        )
+
+    def __hash__(self) -> long:
+        return cython.cast(long, self.subgame.deref())
+
+    @property
+    def game(self) -> Game:
+        """Gets the ``Game`` to which the subgame belongs."""
+        return Game.wrap(self.subgame.deref().GetGame())
+
+    @property
+    def root(self) -> Node:
+        """The root node of the subgame."""
+        return Node.wrap(self.subgame.deref().GetRoot())