Merge pull request #37 from alopezlago/alopezlago/public_v1

Merged PR 241: v1.0.0.0 - API changes
alopezlago · Apr 18, 2022 · d098623 · d098623
2 parents f089ece + 4f4e6b7
commit d098623
Show file tree

Hide file tree

Showing 43 changed files with 121 additions and 783 deletions.
diff --git a/YetAnotherPacketParser/YetAnotherPacketParser.sln b/YetAnotherPacketParser/YetAnotherPacketParser.sln
@@ -9,9 +9,7 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "YetAnotherPacketParserComma
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "YetAnotherPacketParserTests", "YetAnotherPacketParserTests\YetAnotherPacketParserTests.csproj", "{811B7F2E-1E9C-486C-9B26-62B99C239CE0}"
 EndProject
-Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "YetAnotherPacketParserAzureFunction", "YetAnotherPacketParserAzureFunction\YetAnotherPacketParserAzureFunction.csproj", "{B594E98C-9772-40F8-93BA-F641AE397140}"
-EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "YetAnotherPacketParserAPI", "YetAnotherPacketParserAPI\YetAnotherPacketParserAPI.csproj", "{90AD57C5-763C-494E-AE92-F90BB0BB5A88}"
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "YetAnotherPacketParserAPI", "YetAnotherPacketParserAPI\YetAnotherPacketParserAPI.csproj", "{90AD57C5-763C-494E-AE92-F90BB0BB5A88}"
 EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
@@ -31,10 +29,6 @@ Global
 		{811B7F2E-1E9C-486C-9B26-62B99C239CE0}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{811B7F2E-1E9C-486C-9B26-62B99C239CE0}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{811B7F2E-1E9C-486C-9B26-62B99C239CE0}.Release|Any CPU.Build.0 = Release|Any CPU
-		{B594E98C-9772-40F8-93BA-F641AE397140}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
-		{B594E98C-9772-40F8-93BA-F641AE397140}.Debug|Any CPU.Build.0 = Debug|Any CPU
-		{B594E98C-9772-40F8-93BA-F641AE397140}.Release|Any CPU.ActiveCfg = Release|Any CPU
-		{B594E98C-9772-40F8-93BA-F641AE397140}.Release|Any CPU.Build.0 = Release|Any CPU
 		{90AD57C5-763C-494E-AE92-F90BB0BB5A88}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
 		{90AD57C5-763C-494E-AE92-F90BB0BB5A88}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{90AD57C5-763C-494E-AE92-F90BB0BB5A88}.Release|Any CPU.ActiveCfg = Release|Any CPU

diff --git a/YetAnotherPacketParser/YetAnotherPacketParser/Ast/BonusNode.cs b/YetAnotherPacketParser/YetAnotherPacketParser/Ast/BonusNode.cs
@@ -3,7 +3,7 @@
 
 namespace YetAnotherPacketParser.Ast
 {
-    public class BonusNode
+    internal class BonusNode
     {
         public BonusNode(
             int number, FormattedText leadin, IEnumerable<BonusPartNode> parts, string? metadata)

diff --git a/YetAnotherPacketParser/YetAnotherPacketParser/Ast/BonusPartNode.cs b/YetAnotherPacketParser/YetAnotherPacketParser/Ast/BonusPartNode.cs
@@ -2,7 +2,7 @@
 
 namespace YetAnotherPacketParser.Ast
 {
-    public class BonusPartNode
+    internal class BonusPartNode
     {
         public BonusPartNode(QuestionNode question, int value, char? difficultyModifier)
         {

diff --git a/YetAnotherPacketParser/YetAnotherPacketParser/Ast/PacketNode.cs b/YetAnotherPacketParser/YetAnotherPacketParser/Ast/PacketNode.cs
@@ -4,7 +4,7 @@
 
 namespace YetAnotherPacketParser.Ast
 {
-    public class PacketNode
+    internal class PacketNode
     {
         public PacketNode(IEnumerable<TossupNode> tossups, IEnumerable<BonusNode>? bonuses)
         {

diff --git a/YetAnotherPacketParser/YetAnotherPacketParser/Ast/QuestionNode.cs b/YetAnotherPacketParser/YetAnotherPacketParser/Ast/QuestionNode.cs
@@ -2,7 +2,7 @@
 
 namespace YetAnotherPacketParser.Ast
 {
-    public class QuestionNode
+    internal class QuestionNode
     {
         public QuestionNode(FormattedText question, FormattedText answer)
         {

diff --git a/YetAnotherPacketParser/YetAnotherPacketParser/Ast/TossupNode.cs b/YetAnotherPacketParser/YetAnotherPacketParser/Ast/TossupNode.cs
@@ -2,7 +2,7 @@
 
 namespace YetAnotherPacketParser.Ast
 {
-    public class TossupNode
+    internal class TossupNode
     {
         public TossupNode(int number, QuestionNode question, string? metadata = null)
         {

diff --git a/YetAnotherPacketParser/YetAnotherPacketParser/Compiler/Html/HtmlCompiler.cs b/YetAnotherPacketParser/YetAnotherPacketParser/Compiler/Html/HtmlCompiler.cs
@@ -6,7 +6,7 @@
 
 namespace YetAnotherPacketParser.Compiler.Html
 {
-    public class HtmlCompiler : ICompiler
+    internal class HtmlCompiler : ICompiler
     {
         public Task<string> CompileAsync(PacketNode packet)
         {

diff --git a/YetAnotherPacketParser/YetAnotherPacketParser/Compiler/ICompiler.cs b/YetAnotherPacketParser/YetAnotherPacketParser/Compiler/ICompiler.cs
@@ -3,7 +3,7 @@
 
 namespace YetAnotherPacketParser.Compiler
 {
-    public interface ICompiler
+    internal interface ICompiler
     {
         /// <summary>
         /// Convert the packet into the output format

diff --git a/YetAnotherPacketParser/YetAnotherPacketParser/Compiler/Json/JsonCompiler.cs b/YetAnotherPacketParser/YetAnotherPacketParser/Compiler/Json/JsonCompiler.cs
@@ -6,7 +6,7 @@
 
 namespace YetAnotherPacketParser.Compiler.Json
 {
-    public class JsonCompiler : ICompiler
+    internal class JsonCompiler : ICompiler
     {
         public JsonCompiler(JsonCompilerOptions? options = null)
         {

diff --git a/YetAnotherPacketParser/YetAnotherPacketParser/Compiler/Json/PascalCaseJsonNamingPolicy.cs b/YetAnotherPacketParser/YetAnotherPacketParser/Compiler/Json/PascalCaseJsonNamingPolicy.cs
@@ -4,12 +4,8 @@
 
 namespace YetAnotherPacketParser.Compiler.Json
 {
-    public class PascalCaseJsonNamingPolicy : JsonNamingPolicy
+    internal class PascalCaseJsonNamingPolicy : JsonNamingPolicy
     {
-        [SuppressMessage(
-            "Globalization",
-            "CA1308:Normalize strings to uppercase",
-            Justification = "Pascal case requires lowercasing strings")]
         public override string ConvertName(string name)
         {
             Verify.IsNotNull(name, nameof(name));

diff --git a/YetAnotherPacketParser/YetAnotherPacketParser/Compiler/SanitizeHtmlTransformer.cs b/YetAnotherPacketParser/YetAnotherPacketParser/Compiler/SanitizeHtmlTransformer.cs
@@ -6,7 +6,7 @@
 
 namespace YetAnotherPacketParser.Compiler
 {
-    public class SanitizeHtmlTransformer
+    internal class SanitizeHtmlTransformer
     {
         private const int MaxCachedFragmentLength = 10;
 

diff --git a/YetAnotherPacketParser/YetAnotherPacketParser/ConvertResult.cs b/YetAnotherPacketParser/YetAnotherPacketParser/ConvertResult.cs
@@ -4,14 +4,26 @@ namespace YetAnotherPacketParser
 {
     public class ConvertResult
     {
-        public ConvertResult(string filename, IResult<string> result)
+        /// <summary>
+        /// Creates a wrapper of a conversion result that links it to the original input packet
+        /// </summary>
+        /// <param name="filename">Filename of the original input packet</param>
+        /// <param name="result">Result of the conversion operation</param>
+        /// <exception cref="ArgumentNullException">If <c>filename</c> or <c>result</c> are null.</exception>
+        internal ConvertResult(string filename, IResult<string> result)
         {
             this.Result = result ?? throw new ArgumentNullException(nameof(result));
             this.Filename = filename ?? throw new ArgumentNullException(nameof(filename));
         }
 
+        /// <summary>
+        /// The result of the conversion as a <see cref="System.String">String</see>.
+        /// </summary>
         public IResult<string> Result { get; }
 
+        /// <summary>
+        /// The filename of the input packet.
+        /// </summary>
         public string Filename { get; }
     }
 }
diff --git a/YetAnotherPacketParser/YetAnotherPacketParser/FormattedText.cs b/YetAnotherPacketParser/YetAnotherPacketParser/FormattedText.cs
@@ -3,7 +3,7 @@
 
 namespace YetAnotherPacketParser
 {
-    public class FormattedText
+    internal class FormattedText
     {
         public FormattedText(IEnumerable<FormattedTextSegment> formattedTexts)
         {

diff --git a/YetAnotherPacketParser/YetAnotherPacketParser/FormattedTextSegment.cs b/YetAnotherPacketParser/YetAnotherPacketParser/FormattedTextSegment.cs
@@ -2,7 +2,7 @@
 
 namespace YetAnotherPacketParser
 {
-    public class FormattedTextSegment
+    internal class FormattedTextSegment
     {
         public FormattedTextSegment(string text, bool italic = false, bool bolded = false, bool underlined = false)
         {

diff --git a/YetAnotherPacketParser/YetAnotherPacketParser/HtmlPacketCompilerOptions.cs b/YetAnotherPacketParser/YetAnotherPacketParser/HtmlPacketCompilerOptions.cs
@@ -22,8 +22,16 @@ public HtmlPacketCompilerOptions()
 
         public int MaximumPacketSizeInBytes { get; set; }
 
+        /// <exception cref="System.NotSupportedException"></exception>
+        /// <summary>
+        /// Not supported.
+        /// </summary>
         public bool ModaqFormat => throw new NotSupportedException();
 
+        /// <exception cref="System.NotSupportedException"></exception>
+        /// <summary>
+        /// Not supported.
+        /// </summary>
         public bool PrettyPrint => throw new NotSupportedException();
 
         public Action<LogLevel, string>? Log { get; set; }

diff --git a/YetAnotherPacketParser/YetAnotherPacketParser/IPacketConverterOptions.cs b/YetAnotherPacketParser/YetAnotherPacketParser/IPacketConverterOptions.cs
@@ -4,21 +4,44 @@ namespace YetAnotherPacketParser
 {
     public interface IPacketConverterOptions
     {
+        /// <summary>
+        /// The name of the input packet. This is often the filename of the packet.
+        /// </summary>
         public string StreamName { get; }
 
+        /// <summary>
+        /// The format of the output string after conversion, such as JSON or HTML.
+        /// </summary>
         public OutputFormat OutputFormat { get; }
 
         [Obsolete("No longer used")]
         public int MaximumLineCountBeforeNextStage { get; }
 
+        /// <summary>
+        /// The maximum number of packets the converter is allowed to convert. If the converter is required to convert more packets than this
+        /// value, the conversion will fail.
+        /// </summary>
         public int MaximumPackets { get; }
 
+        /// <summary>
+        /// The largest size an input packet can be in bytes. If the converter sees a packet larger than this value,
+        /// then the conversion fails.
+        /// </summary>
         public int MaximumPacketSizeInBytes { get; }
 
+        /// <summary>
+        /// When <c>true</c>, don't include sanitized fields in the output string.
+        /// </summary>
         public bool ModaqFormat { get; }
 
+        /// <summary>
+        /// When <c>true</c>, pretty prints the output.
+        /// </summary>
         public bool PrettyPrint { get; }
 
+        /// <summary>
+        /// Callback for logs during the conversion process.
+        /// </summary>
         public Action<LogLevel, string>? Log { get; }
     }
 }
diff --git a/YetAnotherPacketParser/YetAnotherPacketParser/IResult.cs b/YetAnotherPacketParser/YetAnotherPacketParser/IResult.cs
@@ -4,12 +4,23 @@ namespace YetAnotherPacketParser
 {
     public interface IResult<T>
     {
+        /// <summary>
+        /// <c>true</c> if we were able to get a result, <c>false</c> otherwise. When <c>true</c>, Value is
+        /// defined. When <c>false</c>, ErrorMessages is defined.
+        /// </summary>
         bool Success { get; }
 
-        // If Success is true, ErrorMessages should throw
+        /// <exception cref="System.NotSupportedException">Thrown when Success is <c>true</c>.</exception>
+        /// <summary>
+        /// When Success is <c>false</c>, the list of errors encountered when trying to get the result.
+        /// </summary>
         IEnumerable<string> ErrorMessages { get; }
 
         // If Sucess if false, Value should throw
+        /// <exception cref="System.NotSupportedException">Thrown when Success is <c>false</c>.</exception>
+        /// <summary>
+        /// When Success is <c>true</c>, the value of the operation.
+        /// </summary>
         T Value { get; }
     }
 }
diff --git a/YetAnotherPacketParser/YetAnotherPacketParser/JsonPacketCompilerOptions.cs b/YetAnotherPacketParser/YetAnotherPacketParser/JsonPacketCompilerOptions.cs
@@ -24,7 +24,6 @@ public JsonPacketCompilerOptions()
 
         public int MaximumPacketSizeInBytes { get; set; }
 
-        // Only emit the fields MODAQ uses, e.g. remove all the *_sanitized fields
         public bool ModaqFormat { get; set; }
 
         public bool PrettyPrint { get; set; }

diff --git a/YetAnotherPacketParser/YetAnotherPacketParser/Lexer/AnswerLine.cs b/YetAnotherPacketParser/YetAnotherPacketParser/Lexer/AnswerLine.cs
@@ -1,6 +1,6 @@
 namespace YetAnotherPacketParser.Lexer
 {
-    public class AnswerLine : ILine
+    internal class AnswerLine : ILine
     {
         public AnswerLine(FormattedText text)
         {

diff --git a/YetAnotherPacketParser/YetAnotherPacketParser/Lexer/BonusPartLine.cs b/YetAnotherPacketParser/YetAnotherPacketParser/Lexer/BonusPartLine.cs
@@ -1,6 +1,6 @@
 namespace YetAnotherPacketParser.Lexer
 {
-    public class BonusPartLine : ILine
+    internal class BonusPartLine : ILine
     {
         public BonusPartLine(FormattedText text, int value, char? difficultyModifier)
         {

diff --git a/YetAnotherPacketParser/YetAnotherPacketParser/Lexer/DocxLexer.cs b/YetAnotherPacketParser/YetAnotherPacketParser/Lexer/DocxLexer.cs
@@ -10,7 +10,7 @@
 
 namespace YetAnotherPacketParser.Lexer
 {
-    public class DocxLexer : ILexer
+    internal class DocxLexer : ILexer
     {
         // No part should be greater than 2 million characters
         private const int MaximumCharactersInPart = 2 * 1024 * 1024;

diff --git a/YetAnotherPacketParser/YetAnotherPacketParser/Lexer/ILexer.cs b/YetAnotherPacketParser/YetAnotherPacketParser/Lexer/ILexer.cs
@@ -4,7 +4,7 @@
 
 namespace YetAnotherPacketParser.Lexer
 {
-    public interface ILexer
+    internal interface ILexer
     {
         Task<IResult<IEnumerable<ILine>>> GetLines(Stream stream);
     }

diff --git a/YetAnotherPacketParser/YetAnotherPacketParser/Lexer/ILine.cs b/YetAnotherPacketParser/YetAnotherPacketParser/Lexer/ILine.cs
@@ -1,6 +1,6 @@
 namespace YetAnotherPacketParser.Lexer
 {
-    public interface ILine
+    internal interface ILine
     {
         public LineType Type { get; }
 

diff --git a/YetAnotherPacketParser/YetAnotherPacketParser/Lexer/Line.cs b/YetAnotherPacketParser/YetAnotherPacketParser/Lexer/Line.cs
@@ -1,6 +1,6 @@
 namespace YetAnotherPacketParser.Lexer
 {
-    public class Line : ILine
+    internal class Line : ILine
     {
         public Line(FormattedText text)
         {

diff --git a/YetAnotherPacketParser/YetAnotherPacketParser/Lexer/LineType.cs b/YetAnotherPacketParser/YetAnotherPacketParser/Lexer/LineType.cs
@@ -1,6 +1,6 @@
 namespace YetAnotherPacketParser.Lexer
 {
-    public enum LineType
+    internal enum LineType
     {
         Unclassified,
         Answer,

diff --git a/YetAnotherPacketParser/YetAnotherPacketParser/Lexer/NumberedQuestionLine.cs b/YetAnotherPacketParser/YetAnotherPacketParser/Lexer/NumberedQuestionLine.cs
@@ -1,6 +1,6 @@
 namespace YetAnotherPacketParser.Lexer
 {
-    public class NumberedQuestionLine : ILine
+    internal class NumberedQuestionLine : ILine
     {
         public NumberedQuestionLine(FormattedText text, int number)
         {

diff --git a/YetAnotherPacketParser/YetAnotherPacketParser/PacketConverter.cs b/YetAnotherPacketParser/YetAnotherPacketParser/PacketConverter.cs
@@ -16,15 +16,39 @@ namespace YetAnotherPacketParser
     // TODO: make this easier to unit test. That requires making CompilePacketAsync accessible or mockable.
     public static class PacketConverter
     {
+        /// <exception cref="System.ArgumentNullException">If <c>stream</c> or <c>options</c> is <c>null</c>.</exception>
         /// <summary>
         /// Converts the file encoded in the stream to a packet in the output format specified in the options
         /// </summary>
         /// <param name="stream">Stream representing the packet. This can either represent a .docx Microsoft Word file
         /// or a zip file containing .docx files.</param>
         /// <param name="options">Options for converting the packets, such as the output format and the maximum size
         /// of packets.</param>
-        /// <returns>An enumerable of the converted results. If conversion succeeded, the element will have a string
-        /// of the packet in the requested format. If conversion failed, the element will have an error message explaining
+        /// <returns>If conversion succeeded, then this returns the packet in the requested format. If conversion
+        /// failed, then the element will have an error message explaining the cause of the failure.</returns>
+        /// <remarks>This has undefined behavior if a non-.docx zip file is passed in.</remarks>
+        public static async Task<ConvertResult> ConvertPacketAsync(Stream stream, IPacketConverterOptions options)
+        {
+            IEnumerable<ConvertResult> results = await ConvertPacketsAsync(stream, options);
+            ConvertResult result = results.FirstOrDefault();
+            if (result == null)
+            {
+                return new ConvertResult(string.Empty, new FailureResult<string>("No packet was found"));
+            }
+
+            return result;
+        }
+
+        /// <exception cref="System.ArgumentNullException">If <c>stream</c> or <c>options</c> is <c>null</c>.</exception>
+        /// <summary>
+        /// Converts the file encoded in the stream to a packet in the output format specified in the options
+        /// </summary>
+        /// <param name="stream">Stream representing the packet. This can either represent a .docx Microsoft Word file
+        /// or a zip file containing .docx files.</param>
+        /// <param name="options">Options for converting the packets, such as the output format and the maximum size
+        /// of packets.</param>
+        /// <returns>An enumerable of the converted results. If conversion succeeded, then the element will have a string
+        /// of the packet in the requested format. If conversion failed, then the element will have an error message explaining
         /// the cause of the failure.</returns>
         public static async Task<IEnumerable<ConvertResult>> ConvertPacketsAsync(
             Stream stream, IPacketConverterOptions options)
@@ -155,10 +179,7 @@ private static ConvertResult CreateFailedCompileResult(string streamName, string
 
             options.Log?.Invoke(LogLevel.Verbose, Strings.LexingComplete(packetName));
 
-            LinesParserOptions parserOptions = new LinesParserOptions()
-            {
-            };
-            LinesParser parser = new LinesParser(parserOptions);
+            LinesParser parser = new LinesParser();
             IResult<PacketNode> packetNodeResult = parser.Parse(linesResult.Value);
 
             long timeInMsParse = stopwatch.ElapsedMilliseconds;

diff --git a/YetAnotherPacketParser/YetAnotherPacketParser/Parser/IParser.cs b/YetAnotherPacketParser/YetAnotherPacketParser/Parser/IParser.cs
@@ -4,7 +4,7 @@
 
 namespace YetAnotherPacketParser.Parser
 {
-    public interface IParser
+    internal interface IParser
     {
         IResult<PacketNode> Parse(IEnumerable<ILine> lines);
     }