Merge pull request square#113 from square/loganj/pop_pop

Give History.Builder some more useful pop ops

flow/src/main/java/flow/History.java

@@ -246,6 +246,29 @@ public Object pop() {
       return entry.state;
     }
 
+    /**
+     * Pops the history until the given state is at the top.
+     *
+     * @throws IllegalArgumentException if the given state isn't in the history.
+     * */
+    public Builder popTo(Object state) {
+      while (!isEmpty() && !peek().equals(state)) {
+        pop();
+      }
+      checkArgument(!isEmpty(), String.format("%s not found in history", state));
+      return this;
+    }
+
+    public Builder pop(int count) {
+      final int size = history.size();
+      checkArgument(count <= size,
+          String.format("Cannot pop %d elements, history only has %d", count, size));
+      while (count-- > 0) {
+        pop();
+      }
+      return this;
+    }
+
     public History build() {
       return new History(history);
     }

flow/src/test/java/flow/FlowTest.java

@@ -92,6 +92,53 @@ class FlowDispatcher implements Flow.Dispatcher {
     }
   }
 
+  @Test public void builderCanPopTo() {
+    History.Builder builder = History.emptyBuilder();
+    builder.push(able);
+    builder.push(baker);
+    builder.push(charlie);
+    builder.popTo(able);
+    assertThat(builder.peek()).isSameAs(able);
+  }
+
+  @Test public void builderPopToExplodesOnMissingState() {
+    History.Builder builder = History.emptyBuilder();
+    builder.push(able);
+    builder.push(baker);
+    builder.push(charlie);
+    try {
+      builder.popTo(new Object());
+      fail("Missing state object, should have thrown");
+    } catch (IllegalArgumentException ignored) {
+      // Correct!
+    }
+  }
+
+  @Test public void builderCanPopCount() {
+    History.Builder builder = History.emptyBuilder();
+    builder.push(able);
+    builder.push(baker);
+    builder.push(charlie);
+    builder.pop(1);
+    assertThat(builder.peek()).isSameAs(baker);
+    builder.pop(2);
+    assertThat(builder.isEmpty());
+  }
+
+  @Test public void builderPopExplodesIfCountIsTooLarge() {
+    History.Builder builder = History.emptyBuilder();
+    builder.push(able);
+    builder.push(baker);
+    builder.push(charlie);
+    try {
+      builder.pop(4);
+      fail("Count is too large, should have thrown");
+    } catch (IllegalArgumentException ignored) {
+      // Success!
+    }
+
+  }
+
   @Test public void historyChangesAfterListenerCall() {
     final History firstHistory = History.single(new Uno());