Merge branch 'student' into solution

Author: Frederic Vogels

PiCross/Domain/PiCross/IGameData.cs

@@ -64,22 +64,57 @@ public interface IPlayerProfile
         string Name { get; }
     }
 
+    /// <summary>
+    /// An IPlayerPuzzleInformation object contains
+    /// the information for one specific player
+    /// about one specific puzzle.
+    /// </summary>
     public interface IPlayerPuzzleInformation
     {
+        /// <summary>
+        /// Best time the player has achieved for the puzzle.
+        /// TimeSpan is value type like int, so it cannot be null.
+        /// We can make it nullable though by using TimeSpan?
+        /// If this property is null, the player hasn't solved
+        /// the puzzle yet.
+        /// </summary>
         TimeSpan? BestTime { get; set; }
     }
 
     public interface IPuzzleLibrary
     {
+        /// <summary>
+        /// Returns a list of all puzzles in the library.
+        /// Note that this returns an IEnumerable, which
+        /// offers limited functionality. Use
+        /// its ToList() to turn it into a list (make sure
+        /// using System.Linq is present at the top of your source file.)
+        /// </summary>
         IEnumerable<IPuzzleLibraryEntry> Entries { get; }
 
+        /// <summary>
+        /// Adds a new puzzle to the library.
+        /// </summary>
+        /// <param name="puzzle">Puzzle.</param>
+        /// <param name="author">Author of the puzzle.</param>
+        /// <returns>Entry that has been added to the library.</returns>
         IPuzzleLibraryEntry Create( Puzzle puzzle, string author );
     }
 
+    /// <summary>
+    /// A IPuzzleLibraryEntry is an object that
+    /// pairs up a Puzzle and its author.
+    /// </summary>
     public interface IPuzzleLibraryEntry
     {
+        /// <summary>
+        /// Puzzle.
+        /// </summary>
         Puzzle Puzzle { get; set; }
 
+        /// <summary>
+        /// Author of the puzzle.
+        /// </summary>
         string Author { get; set; }
     }
 }

PiCross/Domain/PiCross/IPlayablePuzzle.cs

@@ -45,20 +45,20 @@ public interface IPlayablePuzzle
 
         /// <summary>
         /// Contains true if the Grid contains no more unknown squares,
-        /// and all squares are correct.
+        /// and all squares are correct. This property is observable.
         /// </summary>
         Cell<bool> IsSolved { get; }
 
         /// <summary>
         /// Number of squares that are left unknown (i.e. have not been determined to be
-        /// filled or empty.)
+        /// filled or empty.) This property is observable.
         /// </summary>
         Cell<int> UnknownCount { get; }
 
         /// <summary>
         /// True if there are unknowns left, false otherwise. Note:
         /// this does not correspond to a successfully solved puzzle.
-        /// The player might have made mistakes.
+        /// The player might have made mistakes. This property is observable.
         /// </summary>
         Cell<bool> ContainsUnknowns { get; }
     }

PiCross/Domain/PiCross/PiCrossFacade.cs

@@ -39,9 +39,11 @@ public IGameData CreateDummyGameData()
 
         /// <summary>
         /// Loads data from the given file.
-        /// When the data is modified, changes are automatically written to the file.
+        /// When the data is modified, changes are automatically written to the file,
+        /// so you do not need to explicitly write changes back to file.
         /// </summary>
         /// <param name="path">Path to the file.</param>
+        /// <param name="createIfNotExistent">If true, creates an new empty game data file if none is present at the given path.</param>
         /// <returns>An IGameData object.</returns>
         public IGameData LoadGameData( string path, bool createIfNotExistent = false )
         {

PiCross/Domain/PiCross/PlayablePuzzle.cs

@@ -20,7 +20,7 @@ internal class PlayablePuzzle : IPlayablePuzzle
         public PlayablePuzzle( ISequence<Constraints> columnConstraints, ISequence<Constraints> rowConstraints )
             : this( new PlayGrid( columnConstraints: columnConstraints, rowConstraints: rowConstraints ) )
         {
-            // NOP            
+            // NOP
         }
 
         public PlayablePuzzle( PlayGrid playGrid )

PiCross/Domain/PiCross/Puzzle.cs

@@ -50,6 +50,38 @@ public static Puzzle FromConstraints( ISequence<Constraints> columnConstraints,
             }
         }
 
+        /// <summary>
+        /// Creates a puzzle from constraints in string format.
+        /// Constraints on the same row/column should be separated by a single space,
+        /// while rows/columns should be separated by a semicolon. For example,
+        /// "2 1;1;;4 1".
+        /// </summary>
+        /// <param name="columnConstraints">Column constraints.</param>
+        /// <param name="rowConstraints">Row constraints.</param>
+        /// <returns></returns>
+        public static Puzzle FromConstraints( string columnConstraints, string rowConstraints )
+        {
+            var parsedColumnConstraints = ParseConstraints( columnConstraints );
+            var parsedRowConstraints = ParseConstraints( rowConstraints );
+
+            return FromConstraints( columnConstraints: parsedColumnConstraints, rowConstraints: parsedRowConstraints );
+        }
+
+        private static int[][] ParseConstraints(string constraints)
+        {
+            return constraints.Split( ';' ).Select( part =>
+              {
+                  if ( part == "" )
+                  {
+                      return new int[0];
+                  }
+                  else
+                  {
+                      return part.Split( ' ' ).Select( int.Parse ).ToArray();
+                  }
+              } ).ToArray();
+        }
+
         /// <summary>
         /// Creates a Puzzle from the constraints.
         /// Internally, the puzzle is automatically solved.

PiCross/Tests/PuzzleCreationTests.cs

@@ -0,0 +1,59 @@
+using System;
+using System.Linq;
+using Microsoft.VisualStudio.TestTools.UnitTesting;
+
+namespace PiCross.Tests
+{
+    [TestClass]
+    public class PuzzleCreationTests
+    {
+        [TestMethod]
+        [TestCategory( "Puzzle Creation" )]
+        public void FromStringConstraints()
+        {
+            // x.x
+            // .x.
+            // ...
+            var puzzle = Puzzle.FromConstraints( columnConstraints: "1;1;1", rowConstraints: "1 1;1;" );
+            var columnConstraints = puzzle.ColumnConstraints.Select( c => c.Values.ToArray() ).ToArray();
+            var rowConstraints = puzzle.RowConstraints.Select( c => c.Values.ToArray() ).ToArray();
+
+            Assert.AreEqual( 3, columnConstraints.Length );
+            Assert.AreEqual( 3, rowConstraints.Length );
+            Assert.IsTrue( Enumerable.SequenceEqual( columnConstraints[0], new int[] { 1 } ) );
+            Assert.IsTrue( Enumerable.SequenceEqual( columnConstraints[1], new int[] { 1 } ) );
+            Assert.IsTrue( Enumerable.SequenceEqual( columnConstraints[2], new int[] { 1 } ) );
+            Assert.IsTrue( Enumerable.SequenceEqual( rowConstraints[0], new int[] { 1, 1 } ) );
+            Assert.IsTrue( Enumerable.SequenceEqual( rowConstraints[1], new int[] { 1 } ) );
+            Assert.IsTrue( Enumerable.SequenceEqual( rowConstraints[2], new int[] { } ) );
+        }
+
+        [TestMethod]
+        [TestCategory( "Puzzle Creation" )]
+        public void FromRowStrings()
+        {
+            var puzzle = Puzzle.FromRowStrings(
+                    ".....",
+                    ".x...",
+                    ".xx..",
+                    "x.xx.",
+                    "..xxx"
+                );
+            var columnConstraints = puzzle.ColumnConstraints.Select( c => c.Values.ToArray() ).ToArray();
+            var rowConstraints = puzzle.RowConstraints.Select( c => c.Values.ToArray() ).ToArray();
+
+            Assert.AreEqual( 5, columnConstraints.Length );
+            Assert.AreEqual( 5, rowConstraints.Length );
+            Assert.IsTrue( Enumerable.SequenceEqual( columnConstraints[0], new int[] { 1 } ) );
+            Assert.IsTrue( Enumerable.SequenceEqual( columnConstraints[1], new int[] { 2 } ) );
+            Assert.IsTrue( Enumerable.SequenceEqual( columnConstraints[2], new int[] { 3 } ) );
+            Assert.IsTrue( Enumerable.SequenceEqual( columnConstraints[3], new int[] { 2 } ) );
+            Assert.IsTrue( Enumerable.SequenceEqual( columnConstraints[4], new int[] { 1 } ) );
+            Assert.IsTrue( Enumerable.SequenceEqual( rowConstraints[0], new int[] { } ) );
+            Assert.IsTrue( Enumerable.SequenceEqual( rowConstraints[1], new int[] { 1 } ) );
+            Assert.IsTrue( Enumerable.SequenceEqual( rowConstraints[2], new int[] { 2 } ) );
+            Assert.IsTrue( Enumerable.SequenceEqual( rowConstraints[3], new int[] { 1, 2 } ) );
+            Assert.IsTrue( Enumerable.SequenceEqual( rowConstraints[4], new int[] { 3 } ) );
+        }
+    }
+}

PiCross/Tests/Tests.csproj

@@ -59,6 +59,7 @@
     <Compile Include="GridSelectionHelperTests.cs" />
     <Compile Include="Constraints_Generate.cs" />
     <Compile Include="Constraints_Superposition.cs" />
+    <Compile Include="PuzzleCreationTests.cs" />
     <Compile Include="PuzzleIOTests.cs" />
     <Compile Include="Constraints_IsSatisfied.cs" />
     <Compile Include="Constraints_SatisfiedPrefix.cs" />

README.md

@@ -0,0 +1,9 @@
+# PiCross Project
+
+Work in progress. Watch the repo (see setup instructions) to be notified whenever we update this.
+
+* [Setup Instructions](docs/setup.md)
+* [Overall Structure](docs/overall-structure.md)
+* [First Steps](docs/first-steps.md)
+* [Functionality](docs/functionality.md)
+* [Rules and Expectations](docs/rules.md)

docs/cookbook.md

@@ -0,0 +1,94 @@
+# Cookbook
+
+This page contains some short samples of how you can interact with the domain.
+
+## `IGameData`
+
+```C#
+// Creating a dummy `IGameData` object
+var facade = new PiCrossFacade();
+var gameData = facade.CreateDummyGameData();
+
+// Reading an `IGameData` object from file, fails if file does not exist
+var facade = new PiCrossFacade();
+var gameData = facade.LoadGameData(path);
+
+// Reading an `IGameData` object from file, creates new file if no file is present at path
+var facade = new PiCrossFacade();
+var gameData = facade.LoadGameData( path, createIfNotExistent: true );
+```
+
+## Puzzle Library
+
+```C#
+// Creating a Puzzle object from constraints for
+//   .....
+//   .x...
+//   .xx..
+//   x.xx.
+//   ..xxx
+var puzzle = Puzzle.FromConstraints(columnConstraints: "1;2;3;2;1",
+                                    rowConstraints: ";1;2;1 2;3");
+
+// Creating a Puzzle object from solution
+var puzzle = Puzzle.FromRowStrings(
+        ".....",
+        ".x...",
+        ".xx..",
+        "x.xx.",
+        "..xxx"
+    );
+
+// Getting a list of puzzle entries in the puzzle library
+var puzzleEntries = gameData.PuzzleLibrary.Entries;
+
+// Adding a new puzzle to the Puzzle Library
+var puzzleEntry = gameData.PuzzleLibrary.Create(puzzle, author);
+```
+
+## Playing
+
+```C#
+// Creating an IPlayablePuzzle
+var facade = new PiCrossFacade();
+var puzzle = GetHoldOfAPuzzleSomehow();
+var playablePuzzle = facade.CreatePlayablePuzzle(puzzle);
+
+// Marking the upper left square as filled
+var position = new Vector(0, 0);
+var square = playablePuzzle.Grid[position];
+square.Contents.Value = Square.FILLED; // square.Contents is a Cell and therefore observable
+
+// Checking if puzzle is solved (observable)
+if ( playablePuzzle.IsSolved.Value ) { ... }
+
+// Checking if there are cells marked unknown left (observable)
+if ( playablePuzzle.ContainsUnknowns.Value ) { ... }
+
+// Number of cells marked unknown left (observable)
+var count = playablePuzzle.UnknownCount.Value;
+
+// Checking if upper row constraints are satisfied (observable)
+if ( playablePuzzle.RowConstraints[0].IsSatisfied.Value ) { ... }
+
+// Getting the values in the upper row constraints
+var values = playablePuzzle.RowConstraints[0].Values;
+```
+
+## Player Database
+
+```C#
+// Get player names
+var facade = new PiCrossFacade();
+var playerNames = facade.PlayerDatabase.PlayerNames;
+
+// Get player profile
+var playerProfile = facade.PlayerDatabase[playerName];
+
+// Find out if player has played puzzle before
+var puzzleEntry = facade.PuzzleLibrary.Entries.First();
+if ( playerProfile[puzzleEntry].BestTime.HasValue ) { ... }
+
+// Get player's best time
+if ( playerProfile[puzzleEntry].BestTime.Value ) { ... }
+```