Add POK file format and public comments

Author: voytas

.github/workflows/build.yml

@@ -13,6 +13,8 @@ jobs:
 
     steps:
     - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
 
     - name: Setup .NET
       uses: actions/setup-dotnet@v4

Spectron.Files.sln.DotSettings

@@ -8,6 +8,7 @@
 	<s:String x:Key="/Default/CodeStyle/Naming/CSharpNaming/Abbreviations/=IY/@EntryIndexedValue">IY</s:String>
 	<s:String x:Key="/Default/CodeStyle/Naming/CSharpNaming/Abbreviations/=PC/@EntryIndexedValue">PC</s:String>
 	<s:String x:Key="/Default/CodeStyle/Naming/CSharpNaming/Abbreviations/=SP/@EntryIndexedValue">SP</s:String>
+	<s:Boolean x:Key="/Default/UserDictionary/Words/=amstrad/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=covox/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=currah/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=Kempston/@EntryIndexedValue">True</s:Boolean>

src/Spectron.Files/Extensions/TapFileExtensions.cs

@@ -5,6 +5,9 @@
 
 namespace OldBit.Spectron.Files.Extensions;
 
+/// <summary>
+/// Extensions for converting between TapFile and TzxFile.
+/// </summary>
 public static class TapFileExtensions
 {
     /// <summary>

src/Spectron.Files/Pok/PokeFile.cs

@@ -0,0 +1,120 @@
+namespace OldBit.Spectron.Files.Pok;
+
+/// <summary>
+/// Represents a poke that needs to be applied to a game.
+/// </summary>
+/// <param name="MemoryBank">Bits 0-2 specify a memory bank for 128K games or bit 3
+/// is always set for 48K games</param>
+/// <param name="Address">The address (16384-65535).</param>
+/// <param name="Value">Poke value (0-255). If it is 256, a requester should pop up where the user can enter a value</param>
+/// <param name="OriginalValue">Original value at the address.</param>
+public record Poke(int MemoryBank, Word Address, int Value, byte OriginalValue);
+
+/// <summary>
+/// Represents a trainer that contains a list of pokes.
+/// </summary>
+/// <param name="Name">The name of the trainer.</param>
+/// <param name="Pokes">A list of pokes.</param>
+public record Trainer(string Name, List<Poke> Pokes);
+
+/// <summary>
+/// Represents a POKE file.
+/// </summary>
+public sealed class PokeFile
+{
+    /// <summary>
+    /// Gets the list of trainers in the POKE file.
+    /// </summary>
+    public List<Trainer> Trainers { get; } = [];
+
+    private PokeFile()
+    {
+    }
+
+    /// <summary>
+    /// Loads a POKE file from the specified file and parses its contents into a PokeFile object.
+    /// </summary>
+    /// <param name="fileName">The path to the POKE file to be loaded.</param>
+    /// <returns>A <see cref="PokeFile"/> instance containing the trainers and pokes parsed from the file.</returns>
+    public static PokeFile Load(string fileName)
+    {
+        var lines = File.ReadAllLines(fileName);
+
+        var pokeFile = new PokeFile();
+        Trainer? trainer = null;
+
+        foreach (var line in lines)
+        {
+            if (IsNextTrainer(line))
+            {
+                trainer = new Trainer(line[1..], []);
+            }
+
+            if (line.StartsWith('M'))
+            {
+                var poke = ParsePoke(line);
+
+                if (poke != null)
+                {
+                    trainer?.Pokes.Add(poke);
+                }
+            }
+
+            if (line.StartsWith('Z'))
+            {
+                var poke = ParsePoke(line);
+
+                if (poke != null && trainer != null)
+                {
+                    trainer.Pokes.Add(poke);
+                    pokeFile.Trainers.Add(trainer);
+
+                    trainer = null;
+                }
+            }
+
+            if (IsLastLine(line))
+            {
+                break;
+            }
+        }
+
+        return pokeFile;
+    }
+
+    private static Poke? ParsePoke(string line)
+    {
+        var parts = line.Split(' ');
+
+        if (parts.Length != 5)
+        {
+            return null;
+        }
+
+        if (!int.TryParse(parts[1].Trim(), out var memoryBank))
+        {
+            return null;
+        }
+
+        if (!Word.TryParse(parts[2].Trim(), out var address))
+        {
+            return null;
+        }
+
+        if (!int.TryParse(parts[3].Trim(), out var value))
+        {
+            return null;
+        }
+
+        if (!byte.TryParse(parts[4].Trim(), out var originalValue))
+        {
+            return null;
+        }
+
+        return new Poke(memoryBank, address, value, originalValue);
+    }
+
+    private static bool IsNextTrainer(string line) => line.StartsWith('N');
+
+    private static bool IsLastLine(string line) => line.StartsWith('Y');
+}

src/Spectron.Files/Serialization/IDataSerializer.cs

@@ -1,6 +1,6 @@
 namespace OldBit.Spectron.Files.Serialization;
 
-public interface IDataSerializer
+internal interface IDataSerializer
 {
     byte[] Serialize();
 }

src/Spectron.Files/Spectron.Files.csproj

@@ -9,12 +9,14 @@
         <Version>0.9.2</Version>
         <Title>ZX Spectrum emulator files parser</Title>
         <Authors>Wojciech Sobieszek</Authors>
-        <Description>This package allows reading and writing files used by ZX Spectrum emulators such as TAP, TZX, SNA, SZX and Z80.</Description>
+        <Description>This package allows reading and writing files used by ZX Spectrum emulators such as TAP, TZX, SNA, SZX, POK and Z80.</Description>
         <PackageProjectUrl>https://github.com/oldbit-com/Spectron.Files</PackageProjectUrl>
-        <PackageTags>TAP TZX SNA SZX Z80</PackageTags>
+        <PackageTags>TAP TZX SNA SZX Z80 POK</PackageTags>
         <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
         <PackageIcon>icon.png</PackageIcon>
         <PackageReadmeFile>README.md</PackageReadmeFile>
+        <GenerateDocumentationFile>True</GenerateDocumentationFile>
+        <PackageLicenseExpression>MIT</PackageLicenseExpression>
     </PropertyGroup>
 
     <ItemGroup>

src/Spectron.Files/Szx/SzxHeader.cs

@@ -8,24 +8,94 @@ namespace OldBit.Spectron.Files.Szx;
 /// </summary>
 public sealed class SzxHeader
 {
+    /// <summary>
+    /// ZX Spectrum 16K.
+    /// </summary>
     public const byte MachineId16K = 0;
+
+    /// <summary>
+    /// ZX Spectrum 48K.
+    /// </summary>
     public const byte MachineId48K = 1;
+
+    /// <summary>
+    /// ZX Spectrum 128K.
+    /// </summary>
     public const byte MachineId128K = 2;
+
+    /// <summary>
+    /// ZX Spectrum +2.
+    /// </summary>
     public const byte MachineIdPlus2 = 3;
+
+    /// <summary>
+    /// ZX Spectrum +2A.
+    /// </summary>
     public const byte MachineIdPlus2A = 4;
+
+    /// <summary>
+    /// ZX Spectrum +3.
+    /// </summary>
     public const byte MachineIdPlus3 = 5;
+
+    /// <summary>
+    /// ZX Spectrum +3E.
+    /// </summary>
     public const byte MachineIdPlus3E = 6;
+
+    /// <summary>
+    /// Pentagon 128.
+    /// </summary>
     public const byte MachineIdPentagon128 = 7;
+
+    /// <summary>
+    /// Timex TC2048.
+    /// </summary>
     public const byte MachineIdTc2048 = 8;
+
+    /// <summary>
+    /// Timex TC2068.
+    /// </summary>
     public const byte MachineIdTc2068 = 9;
+
+    /// <summary>
+    /// Scorpion.
+    /// </summary>
     public const byte MachineIdScorpion = 10;
+
+    /// <summary>
+    /// ZX Spectrum SE.
+    /// </summary>
     public const byte MachineIdSe = 11;
+
+    /// <summary>
+    /// Timex TS2068.
+    /// </summary>
     public const byte MachineIdTs2068 = 12;
+
+    /// <summary>
+    /// Pentagon 512K.
+    /// </summary>
     public const byte MachineIdPentagon512 = 13;
+
+    /// <summary>
+    /// Pentagon 1024K.
+    /// </summary>
     public const byte MachineIdPentagon1024 = 14;
+
+    /// <summary>
+    /// ZX Spectrum 48K NTSC.
+    /// </summary>
     public const byte MachineIdNtsc48K = 15;
+
+    /// <summary>
+    /// ZX Spectrum 128 KE.
+    /// </summary>
     public const byte MachineId128Ke = 16;
 
+    /// <summary>
+    /// Alternate timings.
+    /// </summary>
     public const byte FlagsAlternateTimings = 1;
 
     /// <summary>

src/Spectron.Files/Tap/Extensions/TapeHeaderExtensions.cs

@@ -1,7 +1,15 @@
 namespace OldBit.Spectron.Files.Tap.Extensions;
 
+/// <summary>
+/// Extensions for the TapHeader class.
+/// </summary>
 public static class TapeHeaderExtensions
 {
+    /// <summary>
+    /// Retrieves the name of the data type based on the header's data type.
+    /// </summary>
+    /// <param name="header">The TapHeader instance containing the data type information.</param>
+    /// <returns>A string representing the name of the data type, such as "Program", "Number Array", "Character Array", "Bytes", or "Unknown" if the data type is unrecognized.</returns>
     public static string GetDataTypeName(this TapHeader header)
     {
         return header.DataType switch

src/Spectron.Files/Tzx/ArchiveInfo.cs

@@ -1,16 +1,58 @@
 namespace OldBit.Spectron.Files.Tzx;
 
+/// <summary>
+/// Represents a utility class for handling archive information properties in the TZX file format.
+/// </summary>
 public static class ArchiveInfo
 {
+    /// <summary>
+    /// Represents the identifier for the "Title" property in the archive information section of a TZX file.
+    /// </summary>
     public const byte Title = 0x00;
+
+    /// <summary>
+    /// Represents the identifier for the "Publisher" property in the archive information section of a TZX file.
+    /// </summary>
     public const byte Publisher = 0x01;
+
+    /// <summary>
+    /// Represents the identifier for the "Author" property in the archive information section of a TZX file.
+    /// </summary>
     public const byte Author = 0x02;
+
+    /// <summary>
+    /// Represents the identifier for the "Year" property in the archive information section of a TZX file.
+    /// </summary>
     public const byte Year = 0x03;
+
+    /// <summary>
+    /// Represents the identifier for the "Language" property in the archive information section of a TZX file.
+    /// </summary>
     public const byte Language = 0x04;
+
+    /// <summary>
+    /// Represents the identifier for the "Type" property in the archive information section of a TZX file.
+    /// </summary>
     public const byte Type = 0x05;
+
+    /// <summary>
+    /// Represents the identifier for the "Price" property in the archive information section of a TZX file.
+    /// </summary>
     public const byte Price = 0x06;
+
+    /// <summary>
+    /// Represents the identifier for the "Protection" property in the archive information section of a TZX file.
+    /// </summary>
     public const byte Protection = 0x07;
+
+    /// <summary>
+    /// Represents the identifier for the "Origin" property in the archive information section of a TZX file.
+    /// </summary>
     public const byte Origin = 0x08;
+
+    /// <summary>
+    /// Represents the identifier for the "Comments" property in the archive information section of a TZX file.
+    /// </summary>
     public const byte Comments = 0xFF;
 
     /// <summary>

src/Spectron.Files/Tzx/BlockCode.cs

@@ -1,5 +1,12 @@
 namespace OldBit.Spectron.Files.Tzx;
 
+/// <summary>
+/// Contains constant values representing different types of TZX block codes used in the system.
+/// </summary>
+/// <remarks>
+/// These block codes correspond to various data types and operations defined in the TZX file format.
+/// They are used to identify the type of block in TZX-related operations and processes.
+/// </remarks>
 public static class BlockCode
 {
     /// <summary>