Improve documentation, tests, and assembly signing

Added README.md

Author: clrudolphi

dotnet/README.md

@@ -0,0 +1,5 @@
+[![Maven Central](https://img.shields.io/maven-central/v/io.cucumber/tag-expressions.svg?label=Maven%20Central)](https://search.maven.org/search?q=g:%22io.cucumber%22%20AND%20a:%22tag-expressions%22)
+
+# Cucumber Tag Expressions for .NET
+
+[The docs are here](https://cucumber.io/docs/cucumber/api/#tag-expressions).

dotnet/TagExpressions/InternalsVisibleTo.TagExpressionsTest.cs

@@ -0,0 +1,3 @@
+using System.Runtime.CompilerServices;
+
+[assembly: InternalsVisibleTo("TagExpressionsTest, PublicKey=0024000004800000940000000602000000240000525341310004000001000100bd9b4db256712217f4906b5eb0113e633e319ef574450f83cb837097cac352cfac3a3d3e652c74e2f19e4af0464877e171602bb254fba62c9023894123393ca270ac5c1c01e99e233d0ccdb75f1ebf9b18b66f1618c1d9904658bc7e0a836c5488fb6e54845d9daabbf37594f54bc58f9136fd66cdad9b2761e8710956b2f1ce")]

dotnet/TagExpressions/TagExpression.cs

@@ -4,39 +4,68 @@
 
 namespace TagExpressions;
 
-// Abstract base class implementing the interface
+/// <summary>
+/// Provides an abstract base for tag expressions that can be evaluated against a set of input tags.
+/// </summary>
 public abstract class TagExpression : ITagExpression
 {
-    // Public API
+    /// <summary>
+    /// Evaluates the tag expression against the provided input tags.
+    /// </summary>
+    /// <param name="inputs">A collection of input tags to evaluate against.</param>
+    /// <returns><c>true</c> if the expression matches the inputs; otherwise, <c>false</c>.</returns>
     public bool Evaluate(IEnumerable<string> inputs)
     {
         var inputSet = new HashSet<string>(inputs);
         return EvaluateInternal(inputSet);
     }
 
+    /// <summary>
+    /// Returns the string representation of the tag expression.
+    /// </summary>
+    /// <returns>A string that represents the tag expression.</returns>
     public abstract override string ToString();
 
-    // Internal recursive evaluation method
+    /// <summary>
+    /// Recursively evaluates the tag expression against the provided set of input tags.
+    /// </summary>
+    /// <param name="inputs">A set of input tags.</param>
+    /// <returns><c>true</c> if the expression matches the inputs; otherwise, <c>false</c>.</returns>
     internal abstract bool EvaluateInternal(HashSet<string> inputs);
 }
 
 /// <summary>
 /// Represents an expression that always evaluates to <see langword="true"/>.
 /// </summary>
-/// <remarks>This expression is used as a fallback condition when the expression input is empty.
-/// By convention, an empty tag expression is considered equivalent to <see langword="true"/> regardless of input.</remarks>
+/// <remarks>
+/// This expression is used as a fallback condition when the expression input is empty.
+/// By convention, an empty tag expression is considered equivalent to <see langword="true"/> regardless of input.
+/// </remarks>
 public class NullExpression : TagExpression
 {
+    /// <inheritdoc/>
     public override string ToString() => "true";
+    /// <inheritdoc/>
     internal override bool EvaluateInternal(HashSet<string> inputs) => true;
 }
 
-// Leaf node representing literals (variables)
+/// <summary>
+/// Represents a leaf node for a tag expression, corresponding to a literal tag name.
+/// </summary>
 public class LiteralNode : TagExpression
 {
+    /// <summary>
+    /// Gets the name of the literal tag.
+    /// </summary>
     public string Name { get; }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="LiteralNode"/> class.
+    /// </summary>
+    /// <param name="name">The name of the tag.</param>
     public LiteralNode(string name) => Name = name;
 
+    /// <inheritdoc/>
     public override string ToString()
     {
         var sb = new StringBuilder();
@@ -49,44 +78,75 @@ public override string ToString()
         return sb.ToString();
     }
 
+    /// <inheritdoc/>
     internal override bool EvaluateInternal(HashSet<string> inputs) => inputs.Contains(Name);
 }
 
-// Unary NOT node
+/// <summary>
+/// Represents a unary NOT operation in a tag expression.
+/// </summary>
 public class NotNode : TagExpression
 {
+    /// <summary>
+    /// Gets the operand of the NOT operation.
+    /// </summary>
     public ITagExpression Operand { get; }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="NotNode"/> class.
+    /// </summary>
+    /// <param name="operand">The operand expression to negate.</param>
     public NotNode(ITagExpression operand) => Operand = operand;
 
+    /// <inheritdoc/>
     public override string ToString()
     {
         string operandStr = Operand is not BinaryOpNode ? $"( {Operand} )" : Operand.ToString();
         return $"not {operandStr}";
     }
 
-    internal override bool EvaluateInternal(HashSet<string> inputs) => !( ((TagExpression) Operand).EvaluateInternal(inputs) );
+    /// <inheritdoc/>
+    internal override bool EvaluateInternal(HashSet<string> inputs) => !(((TagExpression)Operand).EvaluateInternal(inputs));
 }
 
-// Binary operator node for AND / OR
+/// <summary>
+/// Represents a binary operator node for AND and OR operations in a tag expression.
+/// </summary>
 public class BinaryOpNode : TagExpression
 {
+    /// <summary>
+    /// Gets the left operand of the binary operation.
+    /// </summary>
     public ITagExpression Left { get; }
+    /// <summary>
+    /// Gets the right operand of the binary operation.
+    /// </summary>
     public ITagExpression Right { get; }
-    public string Op { get; } // "AND" or "OR"
-
+    /// <summary>
+    /// Gets the operator for the binary operation ("AND" or "OR").
+    /// </summary>
+    public string Op { get; }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="BinaryOpNode"/> class.
+    /// </summary>
+    /// <param name="op">The operator ("AND" or "OR").</param>
+    /// <param name="left">The left operand.</param>
+    /// <param name="right">The right operand.</param>
     public BinaryOpNode(string op, ITagExpression left, ITagExpression right)
     {
         Op = op;
         Left = left;
         Right = right;
     }
 
+    /// <inheritdoc/>
     public override string ToString()
     {
         string leftStr = Left is BinaryOpNode leftBin && Precedence(leftBin.Op) < Precedence(Op)
-            ? $"( {Left} )" : Left.ToString();
+        ? $"( {Left} )" : Left.ToString();
         string rightStr = Right is BinaryOpNode rightBin && Precedence(rightBin.Op) < Precedence(Op)
-            ? $"( {Right} )" : Right.ToString();
+        ? $"( {Right} )" : Right.ToString();
         return $"( {leftStr} {Op} {rightStr} )";
     }
 
@@ -95,6 +155,7 @@ private int Precedence(string op) =>
         op == "and" ? 2 :
         op == "or" ? 1 : 0;
 
+    /// <inheritdoc/>
     internal override bool EvaluateInternal(HashSet<string> inputs)
     {
         bool leftVal = ((TagExpression)Left).EvaluateInternal(inputs);

dotnet/TagExpressions/TagExpressionParser.cs

@@ -2,14 +2,22 @@
 
 namespace TagExpressions;
 
-// Recursive descent parser for logical expressions
+/// <summary>
+/// Provides a recursive descent parser for logical tag expressions.
+/// </summary>
 public class TagExpressionParser : ITagExpressionParser
 {
     private string _text;
     private TagLexer _lexer;
     private TagToken _current;
     private int _openParens;
 
+    /// <summary>
+    /// Parses the specified tag expression string into an <see cref="ITagExpression"/>.
+    /// </summary>
+    /// <param name="text">The tag expression string to parse.</param>
+    /// <returns>An <see cref="ITagExpression"/> representing the parsed expression.</returns>
+    /// <exception cref="Exception">Thrown when a syntax error is encountered in the tag expression.</exception>
     public ITagExpression Parse(string text)
     {
         _text = text;
@@ -30,6 +38,9 @@ public ITagExpression Parse(string text)
         return expr;
     }
 
+    /// <summary>
+    /// Advances to the next token in the input stream.
+    /// </summary>
     private void Next()
     {
         _current = _lexer.NextToken();
@@ -43,12 +54,20 @@ private void Next()
         }
     }
 
+    /// <summary>
+    /// Throws a syntax error exception with the specified message.
+    /// </summary>
+    /// <param name="message">The error message.</param>
+    /// <exception cref="Exception">Always thrown to indicate a syntax error.</exception>
     private void ThrowSyntaxError(string message)
     {
         throw new Exception($"Tag expression \"{_text}\" could not be parsed because of syntax error: {message}.");
     }
 
-    // Expression := Term { OR Term }
+    /// <summary>
+    /// Parses an expression consisting of terms separated by the OR operator.
+    /// </summary>
+    /// <returns>The parsed <see cref="ITagExpression"/>.</returns>
     private ITagExpression ParseExpression()
     {
         var left = ParseTerm();
@@ -69,8 +88,10 @@ private ITagExpression ParseExpression()
         return left;
     }
 
-
-    // Term := Factor { AND Factor }
+    /// <summary>
+    /// Parses a term consisting of factors separated by the AND operator.
+    /// </summary>
+    /// <returns>The parsed <see cref="ITagExpression"/>.</returns>
     private ITagExpression ParseTerm()
     {
         var left = ParseFactor();
@@ -92,7 +113,10 @@ private ITagExpression ParseTerm()
         return left;
     }
 
-    // Factor := NOT Factor | (Expression) | Identifier
+    /// <summary>
+    /// Parses a factor, which can be a NOT operation, a parenthesized expression, or an identifier.
+    /// </summary>
+    /// <returns>The parsed <see cref="ITagExpression"/>.</returns>
     private ITagExpression ParseFactor()
     {
         switch (_current.Type)

dotnet/TagExpressions/TagLexer.cs

@@ -1,7 +1,7 @@
 using System.Collections.Generic;
 using System.Text;
 
-public class TagLexer
+internal class TagLexer
 {
     private readonly string _text;
     private int _pos;

dotnet/TagExpressions/TagToken.cs

@@ -1,4 +1,4 @@
-public enum TagTokenType
+internal enum TagTokenType
 {
     Identifier,
     And,
@@ -9,7 +9,7 @@ public enum TagTokenType
     End
 }
 
-public class TagToken
+internal class TagToken
 {
     public TagTokenType Type { get; }
     public string Value { get; }

dotnet/TagExpressionsTest/TagExpressionsTest.csproj

@@ -13,6 +13,8 @@
       For more information, visit https://learn.microsoft.com/dotnet/core/testing/unit-testing-platform-integration-dotnet-test#show-failure-per-test
       -->
     <TestingPlatformShowTestsFailure>true</TestingPlatformShowTestsFailure>
+    <SignAssembly>True</SignAssembly>
+    <AssemblyOriginatorKeyFile>TagExpressionsTest.snk</AssemblyOriginatorKeyFile>
   </PropertyGroup>
 
   <ItemGroup>

dotnet/TagExpressionsTest/TagExpressionsTest.snk

@@ -7,15 +7,30 @@ namespace TagExpressionsTest
     [TestClass]
     public class TagLexerTests
     {
-        [DataTestMethod]
-        [DataRow("AND", TagTokenType.And)]
-        [DataRow("OR", TagTokenType.Or)]
-        [DataRow("NOT", TagTokenType.Not)]
-        public void TokenizesOperators(string input, TagTokenType expectedType)
+        [TestMethod]
+        public void TokenizesOperators_And()
+        {
+            var lexer = new TagLexer("AND");
+            var token = lexer.NextToken();
+            Assert.AreEqual(TagTokenType.And, token.Type);
+            Assert.AreEqual(TagTokenType.End, lexer.NextToken().Type);
+        }
+
+        [TestMethod]
+        public void TokenizesOperators_Or()
+        {
+            var lexer = new TagLexer("OR");
+            var token = lexer.NextToken();
+            Assert.AreEqual(TagTokenType.Or, token.Type);
+            Assert.AreEqual(TagTokenType.End, lexer.NextToken().Type);
+        }
+
+        [TestMethod]
+        public void TokenizesOperators_Not()
         {
-            var lexer = new TagLexer(input);
+            var lexer = new TagLexer("NOT");
             var token = lexer.NextToken();
-            Assert.AreEqual(expectedType, token.Type);
+            Assert.AreEqual(TagTokenType.Not, token.Type);
             Assert.AreEqual(TagTokenType.End, lexer.NextToken().Type);
         }
 
@@ -81,4 +96,4 @@ public void PeekTokenDoesNotAdvancePosition()
             Assert.AreEqual(peeked.Value, next.Value);
         }
     }
-}
+}