misc/vim: inform the user when no results are found
[nit.git] / lib / bucketed_game.nit
index b680079..ae0d792 100644 (file)
@@ -24,18 +24,28 @@ module bucketed_game
 
 # Something acting on the game
 class Turnable[G: Game]
+
+       # Execute `turn` for this instance.
        fun do_turn(turn: GameTurn[G]) is abstract
 end
 
 # Something acting on the game from time to time
 class Bucketable[G: Game]
        super Turnable[G]
-       private var act_at: Int = 0
+       private var act_at: nullable Int = null
+
+       # Cancel the previously registered acting turn
+       #
+       # Once called, `self.do_turn` will not be invoked until `GameTurn::act_next`
+       # or `GameTurn::act_in` are called again.
+       fun cancel_act do act_at = null
 end
 
-# Optiomized organization of `Bucketable` instances
+# Optimized organization of `Bucketable` instances
 class Buckets[G: Game]
        super Turnable[G]
+
+       # Bucket type used in this implementation.
        type BUCKET: HashSet[Bucketable[G]]
 
        private var buckets: Array[BUCKET] is noinit
@@ -53,6 +63,7 @@ class Buckets[G: Game]
                end
        end
 
+       # Add the Bucketable event `e` at `at_tick`.
        fun add_at(e: Bucketable[G], at_tick: Int)
        do
                var at_key = key_for_tick(at_tick)
@@ -76,24 +87,29 @@ class Buckets[G: Game]
                current_bucket_key = key_for_tick(turn.tick)
                var current_bucket = buckets[current_bucket_key]
 
-               next_bucket = new HashSet[Bucketable[G]]
+               var next_bucket = new HashSet[Bucketable[G]]
+               buckets[current_bucket_key] = next_bucket
+               self.next_bucket = next_bucket
 
                for e in current_bucket do
-                       if e.act_at == turn.tick then
-                               e.do_turn(turn)
-                       else if e.act_at > turn.tick and
-                               key_for_tick(e.act_at) == current_bucket_key
-                       then
-                               next_bucket.as(not null).add(e)
+                       var act_at = e.act_at
+                       if act_at != null then
+                               if turn.tick == act_at then
+                                       e.do_turn(turn)
+                               else if act_at > turn.tick and
+                                       key_for_tick(act_at) == current_bucket_key
+                               then
+                                       next_bucket.add(e)
+                               end
                        end
                end
-
-               buckets[current_bucket_key] = next_bucket.as(not null)
        end
 end
 
 # Game related event
 interface GameEvent
+
+       # Apply `self` to `game` logic.
        fun apply( game : ThinGame ) is abstract
 end
 
@@ -104,39 +120,43 @@ end
 
 # Game logic on the client
 class ThinGame
+
+       # Game tick when `self` should act.
+       #
+       # Default is 0.
        var tick: Int = 0 is protected writable
 end
 
 # Game turn on the client
 class ThinGameTurn[G: ThinGame]
-       var tick: Int = 0 is protected writable
 
-       var events: List[GameEvent] = new List[GameEvent] is protected writable
+       # Game tick when `self` should act.
+       var tick: Int is protected writable
 
-       init (t: Int) do tick = t
+       # List of game events occured for `self`.
+       var events = new List[GameEvent] is protected writable
 end
 
 # Game turn on the full logic
 class GameTurn[G: Game]
        super ThinGameTurn[G]
+
+       # Game that `self` belongs to.
        var game: G
 
-       init (g: G)
-       do
-               super(g.tick)
-               game = g
+       # Create a new game turn for `game`.
+       init (game: G) is old_style_init do
+               super(game.tick)
+               self.game = game
        end
 
-       fun act_next(e: Bucketable[G])
-       do
-               game.buckets.add_at(e, tick + 1)
-       end
+       # Insert the Bucketable event `e` to be executed at next tick.
+       fun act_next(e: Bucketable[G]) do game.buckets.add_at(e, tick + 1)
 
-       fun act_in(e: Bucketable[G], t: Int)
-       do
-               game.buckets.add_at(e, tick + t)
-       end
+       # Insert the Bucketable event `e` to be executed at tick `t`.
+       fun act_in(e: Bucketable[G], t: Int) do game.buckets.add_at(e, tick + t)
 
+       # Add and `apply` a game `event`.
        fun add_event( event : GameEvent )
        do
                event.apply( game )
@@ -147,8 +167,11 @@ end
 # Full game logic
 class Game
        super ThinGame
+
+       # Game type used in this implementation.
        type G: Game
 
+       # Bucket list in this game.
        var buckets: Buckets[G] = new Buckets[G]
 
        # Last turn executed in this game
@@ -156,8 +179,10 @@ class Game
        # but cannot be used to add new Events.
        var last_turn: nullable ThinGameTurn[G] = null
 
-       init do end
-
+       # Execute and return a new GameTurn.
+       #
+       # This method calls `do_pre_turn` before executing the GameTurn
+       # and `do_post_turn` after.
        fun do_turn: GameTurn[G]
        do
                var turn = new GameTurn[G](self)
@@ -173,6 +198,15 @@ class Game
                return turn
        end
 
+       # Execute something before executing the current GameTurn.
+       #
+       # Should be redefined by clients to add a pre-turn behavior.
+       # See `Game::do_turn`.
        fun do_pre_turn(turn: GameTurn[G]) do end
+
+       # Execute something after executing the current GameTurn.
+       #
+       # Should be redefined by clients to add a post-turn behavior.
+       # See `Game::do_turn`.
        fun do_post_turn(turn: GameTurn[G]) do end
 end