Merge pull request #21 from chickensoft-games/feat/start-stop-api

feat: restore start and stop api

Author: Joanna May

.gitignore

@@ -1,4 +1,5 @@
 Chickensoft.LogicBlocks/nupkg/
+Chickensoft.LogicBlocks.Generator/nupkg/
 
 Chickensoft.LogicBlocks.Tests/coverage/*
 !Chickensoft.LogicBlocks.Tests/coverage/.gdignore

Chickensoft.LogicBlocks.Generator/Chickensoft.LogicBlocks.Generator.csproj

@@ -9,6 +9,7 @@
     <RootNamespace>Chickensoft.LogicBlocks.Generator</RootNamespace>
     <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
     <NoWarn>NU5128</NoWarn>
+    <OutputPath>./nupkg</OutputPath>
 
     <Title>LogicBlocks Generator</Title>
     <Version>3.2.0</Version>

Chickensoft.LogicBlocks.Tests/badges/branch_coverage.svg

@@ -89,6 +89,13 @@ public OnEnterState(IContext context, Action<State?> onEnter) :
         OnEnter<OnEnterState>(onEnter);
       }
     }
+
+    public record OnExitState : State {
+      public OnExitState(IContext context, Action<State?> onExit) :
+        base(context) {
+        OnExit<OnExitState>(onExit);
+      }
+    }
   }
 
   public static class Output {

Chickensoft.LogicBlocks.Tests/badges/line_coverage.svg

@@ -7,6 +7,7 @@ state "FakeLogicBlock State" as Chickensoft_LogicBlocks_Tests_Fixtures_FakeLogic
   state "NothingState" as Chickensoft_LogicBlocks_Tests_Fixtures_FakeLogicBlock_State_NothingState
   state "Custom" as Chickensoft_LogicBlocks_Tests_Fixtures_FakeLogicBlock_State_Custom
   state "OnEnterState" as Chickensoft_LogicBlocks_Tests_Fixtures_FakeLogicBlock_State_OnEnterState
+  state "OnExitState" as Chickensoft_LogicBlocks_Tests_Fixtures_FakeLogicBlock_State_OnExitState
   Chickensoft_LogicBlocks_Tests_Fixtures_FakeLogicBlock_State : OnInputOne → OutputOne
   Chickensoft_LogicBlocks_Tests_Fixtures_FakeLogicBlock_State : OnInputTwo → OutputTwo
   Chickensoft_LogicBlocks_Tests_Fixtures_FakeLogicBlock_State : OnNoNewState → OutputOne

Chickensoft.LogicBlocks.Tests/test/fixtures/FakeLogicBlock.cs

@@ -89,6 +89,13 @@ public OnEnterState(IContext context, Func<State?, Task> onEnter) :
         OnEnter<OnEnterState>(onEnter);
       }
     }
+
+    public record OnExitState : State {
+      public OnExitState(IContext context, Func<State?, Task> onExit) :
+        base(context) {
+        OnExit<OnExitState>(onExit);
+      }
+    }
   }
 
   public static class Output {

Chickensoft.LogicBlocks.Tests/test/fixtures/FakeLogicBlock.g.puml

@@ -217,4 +217,42 @@ public async Task StartsManuallyAndIgnoresStartWhenProcessing() {
 
     enterCalled.ShouldBeTrue();
   }
+
+  [Fact]
+  public async Task StartEntersState() {
+    var enterCalled = false;
+    var block = new FakeLogicBlockAsync() {
+      InitialState = (context) =>
+        new FakeLogicBlockAsync.State.OnEnterState(
+          context, (previous) => {
+            enterCalled = true;
+            return Task.CompletedTask;
+          })
+    };
+
+    enterCalled.ShouldBeFalse();
+
+    await block.Start();
+
+    enterCalled.ShouldBeTrue();
+  }
+
+  [Fact]
+  public async Task StopExitsState() {
+    var exitCalled = false;
+    var block = new FakeLogicBlockAsync() {
+      InitialState = (context) =>
+        new FakeLogicBlockAsync.State.OnExitState(
+          context, (previous) => {
+            exitCalled = true;
+            return Task.CompletedTask;
+          })
+    };
+
+    exitCalled.ShouldBeFalse();
+
+    await block.Stop();
+
+    exitCalled.ShouldBeTrue();
+  }
 }

Chickensoft.LogicBlocks.Tests/test/fixtures/FakeLogicBlockAsync.cs

@@ -328,4 +328,38 @@ public void StartsManuallyAndIgnoresStartWhenProcessing() {
 
     enterCalled.ShouldBeTrue();
   }
+
+  [Fact]
+  public void StartEntersState() {
+    var enterCalled = false;
+    var block = new FakeLogicBlock() {
+      InitialState = (context) =>
+        new FakeLogicBlock.State.OnEnterState(
+          context, (previous) => enterCalled = true
+        )
+    };
+
+    enterCalled.ShouldBeFalse();
+
+    block.Start();
+
+    enterCalled.ShouldBeTrue();
+  }
+
+  [Fact]
+  public void StopExitsState() {
+    var exitCalled = false;
+    var block = new FakeLogicBlock() {
+      InitialState = (context) =>
+        new FakeLogicBlock.State.OnExitState(
+          context, (previous) => exitCalled = true
+        )
+    };
+
+    exitCalled.ShouldBeFalse();
+
+    block.Stop();
+
+    exitCalled.ShouldBeTrue();
+  }
 }

Chickensoft.LogicBlocks.Tests/test/src/LogicBlockAsyncTest.cs

@@ -26,6 +26,21 @@ public interface ILogicBlock<TState> :
   TState GetInitialState(Logic<
     TState, Func<object, TState>, TState, Action<TState?>
   >.IContext context);
+
+  /// <summary>
+  /// Starts the logic block by entering the current state. If the logic block
+  /// hasn't initialized yet, this will create the initial state before entering
+  /// it.
+  /// </summary>
+  void Start();
+
+  /// <summary>
+  /// Stops the logic block by exiting the current state. For best results,
+  /// don't continue to give inputs to the logic block after stopping it.
+  /// Otherwise, you might end up firing the exit handler of a state more than
+  /// once.
+  /// </summary>
+  void Stop();
 }
 
 /// <summary>
@@ -108,6 +123,13 @@ internal override TState Process() {
     return Value;
   }
 
+  /// <inheritdoc />
+  public void Start() =>
+    Value.Enter(previous: null, onError: (e) => AddError(e));
+
+  /// <inheritdoc />
+  public void Stop() => Value.Exit(next: null, onError: (e) => AddError(e));
+
   internal override Func<object, TState> GetInputHandler<TInputType>()
     => (input) => {
       if (Value is IGet<TInputType> stateWithHandler) {

Chickensoft.LogicBlocks.Tests/test/src/LogicBlockTest.cs

@@ -31,6 +31,21 @@ TState GetInitialState(
       Func<TState?, Task>
     >.IContext context
   );
+
+  /// <summary>
+  /// Starts the logic block by entering the current state. If the logic block
+  /// hasn't initialized yet, this will create the initial state before entering
+  /// it.
+  /// </summary>
+  Task Start();
+
+  /// <summary>
+  /// Stops the logic block by exiting the current state. For best results,
+  /// don't continue to give inputs to the logic block after stopping it.
+  /// Otherwise, you might end up firing the exit handler of a state more than
+  /// once.
+  /// </summary>
+  Task Stop();
 }
 
 /// <summary>
@@ -136,6 +151,13 @@ private async Task<TState> ProcessInputs() {
     return Value;
   }
 
+  /// <inheritdoc />
+  public Task Start() =>
+    Value.Enter(previous: null, onError: (e) => AddError(e));
+
+  /// <inheritdoc />
+  public Task Stop() => Value.Exit(next: null, onError: (e) => AddError(e));
+
   internal override Func<object, Task<TState>> GetInputHandler<TInputType>()
     => (input) => {
       if (Value is IGet<TInputType> stateWithHandler) {

Chickensoft.LogicBlocks/src/LogicBlock.cs

@@ -678,6 +678,18 @@ Or, in the case of an async logic block:
 await logic.Start();
 ```
 
+Likewise, when you are done with your logic block, you can run the exit callbacks for the final state by calling `Stop`.
+
+```csharp
+logic.Stop(); // Runs OnExit callbacks for the current (presumably final) state.
+```
+
+Or, for an async logic block:
+
+```csharp
+await logic.Stop();
+```
+
 ### 🧪 Testing
 
 You can mock a logic block, its bindings, and its context.