3.1.0 Release

Build.ps1

@@ -13,7 +13,7 @@ if(Test-Path .\artifacts) {
 
 $branch = @{ $true = $env:APPVEYOR_REPO_BRANCH; $false = $(git symbolic-ref --short -q HEAD) }[$env:APPVEYOR_REPO_BRANCH -ne $NULL];
 $revision = @{ $true = "{0:00000}" -f [convert]::ToInt32("0" + $env:APPVEYOR_BUILD_NUMBER, 10); $false = "local" }[$env:APPVEYOR_BUILD_NUMBER -ne $NULL];
-$suffix = @{ $true = ""; $false = "$($branch.Substring(0, [math]::Min(10,$branch.Length)))-$revision"}[$branch -eq "main" -and $revision -ne "local"]
+$suffix = @{ $true = ""; $false = "$($branch.Substring(0, [math]::Min(10,$branch.Length)).Replace("/", "-"))-$revision"}[$branch -eq "main" -and $revision -ne "local"]
 
 echo "build: Version suffix is $suffix"
 

README.md

@@ -1,4 +1,4 @@
-# Superpower [![Build status](https://ci.appveyor.com/api/projects/status/7bj6if6tyc68urpy?svg=true)](https://ci.appveyor.com/project/datalust/superpower)  [![Join the chat at https://gitter.im/datalust/superpower](https://img.shields.io/gitter/room/datalust/superpower.svg)](https://gitter.im/datalust/superpower) [![NuGet Version](https://img.shields.io/nuget/vpre/Superpower.svg?style=flat)](https://www.nuget.org/packages/Superpower/) [![Stack Overflow](https://img.shields.io/badge/stackoverflow-superpower-orange.svg)](http://stackoverflow.com/questions/tagged/superpower)
+# Superpower [![Build status](https://ci.appveyor.com/api/projects/status/7bj6if6tyc68urpy?svg=true)](https://ci.appveyor.com/project/datalust/superpower) [![NuGet Version](https://img.shields.io/nuget/vpre/Superpower.svg?style=flat)](https://www.nuget.org/packages/Superpower/) [![Stack Overflow](https://img.shields.io/badge/stackoverflow-superpower-orange.svg)](http://stackoverflow.com/questions/tagged/superpower)
 
 A [parser combinator](https://en.wikipedia.org/wiki/Parser_combinator) library based on
 [Sprache](https://github.com/sprache/Sprache). Superpower generates friendlier error messages through its support for
@@ -71,7 +71,7 @@ public enum ArithmeticExpressionToken
 ```
 
 A major benefit of driving parsing from tokens, instead of individual characters, is that errors can be reported in
-terms of tokens - _unexpected identifier \`frm\`, expected keyword \`from\`_ - instead of the cryptic _unexpected `m`_.
+terms of tokens - _unexpected identifier \`frm\`, expected keyword \`from\`_ - instead of the cryptic _unexpected \`m\`_.
 
 Token-driven parsing takes place in two distinct steps:
 
@@ -170,8 +170,8 @@ class ArithmeticExpressionParser
     static readonly TokenListParser<ArithmeticExpressionToken, Expression> Expr =
         Parse.Chain(Add.Or(Subtract), Term, Expression.MakeBinary);
 
-    public static readonly TokenListParser<ArithmeticExpressionToken, Expression<Func<int>>> Lambda =
-        Expr.AtEnd().Select(body => Expression.Lambda<Func<int>>(body));
+    public static readonly TokenListParser<ArithmeticExpressionToken, Expression<Func<int>>>
+        Lambda = Expr.AtEnd().Select(body => Expression.Lambda<Func<int>>(body));
 }
 ```
 
@@ -244,14 +244,15 @@ Superpower is introduced, with a worked example, in [this blog post](https://nbl
 
 **Real-world** projects built with Superpower:
 
-* [_Serilog.Filters.Expressions_](https://github.com/serilog/serilog-filters-expressions) uses Superpower to implement a filtering language for structured log events
+* [_Serilog.Expressions_](https://github.com/serilog/serilog-expressions) uses Superpower to implement an expression and templating language for structured log events
 * The query language of [Seq](https://datalust.co/seq) is implemented using Superpower
 * `seqcli` [extraction patterns](https://github.com/datalust/seqcli#extraction-patterns) use Superpower for plain-text log parsing
+* [_PromQL.Parser_](https://github.com/djluck/PromQL.Parser) is a parser for the Prometheus Query Language
 
 _Have an example we can add to this list? [Let us know](https://github.com/datalust/superpower/issues/new)._
 
 ### Getting help
 
-Please post issues [to the issue tracker](https://github.com/datalust/superpower/issues), visit our [Gitter chat](https://gitter.im/datalust/superpower), or tag your [question on StackOverflow](http://stackoverflow.com/questions/tagged/superpower) with `superpower`.
+Please post issues [to the issue tracker](https://github.com/datalust/superpower/issues), or tag your [question on StackOverflow](http://stackoverflow.com/questions/tagged/superpower) with `superpower`.
 
 _The repository's title arose out of a talk_ "Parsing Text: the Programming Superpower You Need at Your Fingertips" _given at [DDD Brisbane](http://dddbrisbane.com/) 2015._

appveyor.yml

@@ -1,6 +1,6 @@
 version: '{build}'
 skip_tags: true
-image: Visual Studio 2019
+image: Visual Studio 2022
 build_script:
 - ps: ./Build.ps1
 test: off
@@ -9,7 +9,7 @@ artifacts:
 deploy:
 - provider: NuGet
   api_key:
-    secure: h13+FoLtFJdwNtYdIUsr0xJZCtxwTBKsFKCp5jFjyx5DxqeZN4MwWZhgL+enTOJq
+    secure: kkMZ/vegQUkZw6TKvA+zdG3o9sI7bY7IwtDQzxD37wFyoMC+qg5rIsuUyHbq1Qcb
   skip_symbols: true
   on:
     branch: /^(main|dev)$/

global.json

@@ -1,6 +1,6 @@
 {
   "sdk": {
-    "version": "5.0.100",
+    "version": "8.0.300",
     "rollForward": "latestFeature"
   }
 }

sample/DateTimeTextParser/DateTimeParser.csproj

@@ -2,7 +2,7 @@
 
   <PropertyGroup>
     <OutputType>Exe</OutputType>
-    <TargetFramework>net5.0</TargetFramework>
+    <TargetFramework>net6.0</TargetFramework>
     <Nullable>enable</Nullable>
   </PropertyGroup>
 

sample/IntCalc/ArithmeticExpressionToken.cs

@@ -18,7 +18,7 @@ enum ArithmeticExpressionToken
         [Token(Category = "operator", Example = "*")]
         Times,
 
-        [Token(Category = "operator", Example = "-")]
+        [Token(Category = "operator", Example = "/")]
         Divide,
 
         [Token(Example = "(")]

sample/IntCalc/IntCalc.csproj

@@ -2,7 +2,7 @@
 
   <PropertyGroup>
     <OutputType>Exe</OutputType>
-    <TargetFramework>net5.0</TargetFramework>
+    <TargetFramework>net6.0</TargetFramework>
     <Nullable>enable</Nullable>
   </PropertyGroup>
 

sample/JsonParser/JsonParser.csproj

@@ -2,7 +2,7 @@
 
   <PropertyGroup>
     <OutputType>Exe</OutputType>
-    <TargetFramework>net5.0</TargetFramework>
+    <TargetFramework>net6.0</TargetFramework>
     <Nullable>enable</Nullable>
   </PropertyGroup>
 

src/Superpower/Combinators.cs

@@ -224,7 +224,7 @@ public static TokenListParser<TKind, T[]> Repeat<TKind, T>(this TokenListParser<
                     remainder = r.Remainder;
                 }
 
-                return TokenListParserResult.Value(result ?? new T[0], input, remainder);
+                return TokenListParserResult.Value(result ?? Array.Empty<T>(), input, remainder);
             };
         }
 
@@ -257,7 +257,7 @@ public static TextParser<T[]> Repeat<T>(this TextParser<T> parser, int count)
                     remainder = r.Remainder;
                 }
 
-                return Result.Value(result ?? new T[0], input, remainder);
+                return Result.Value(result ?? Array.Empty<T>(), input, remainder);
             };
         }
 
@@ -507,11 +507,11 @@ public static TokenListParser<TKind, T[]> ManyDelimitedBy<TKind, T, U>(
                 return parser
                     .AtLeastOnceDelimitedBy(delimiter)
                     .Then(p => end.Value(p))
-                    .Or(end.Value(new T[0]));
+                    .Or(end.Value(Array.Empty<T>()));
 
             return parser
                 .Then(first => delimiter.IgnoreThen(parser).Many().Select(rest => ArrayEnumerable.Cons(first, rest)))
-                .OptionalOrDefault(new T[0]);
+                .OptionalOrDefault(Array.Empty<T>());
         }
 
         /// <summary>
@@ -528,9 +528,25 @@ public static TextParser<T[]> ManyDelimitedBy<T, U>(this TextParser<T> parser, T
             if (delimiter == null) throw new ArgumentNullException(nameof(delimiter));
 
             return parser.Then(first => delimiter.IgnoreThen(parser).Many().Select(rest => ArrayEnumerable.Cons(first, rest)))
-                .OptionalOrDefault(new T[0]);
+                .OptionalOrDefault(Array.Empty<T>());
         }
 
+        /// <summary>
+        /// Constructs a parser that converts a char[]-parser to a string-parser.
+        /// </summary>
+        /// <param name="parser">The parser.</param>
+        /// <returns>The resulting parser.</returns>
+        public static TextParser<string> Text(this TextParser<char[]> parser)
+            => parser.Select(chars => new string(chars));
+
+        /// <summary>
+        /// Constructs a parser that converts a TextSpan-parser to a string-parser.
+        /// </summary>
+        /// <param name="parser">The parser.</param>
+        /// <returns>The resulting parser.</returns>
+        public static TextParser<string> Text(this TextParser<TextSpan> parser)
+            => parser.Select(textSpan => textSpan.ToStringValue());
+
         /// <summary>
         /// Construct a parser that fails with error message <paramref name="errorMessage"/> when <paramref name="parser"/> fails.
         /// </summary>

src/Superpower/Model/TextSpan.cs

@@ -270,5 +270,52 @@ public bool EqualsValueIgnoreCase(string otherValue)
             }
             return true;
         }
+
+        /// <summary>
+        /// Gets the character at the specified index in the text span.
+        /// </summary>
+        /// <param name="index">
+        /// The zero-based index of the character to get.
+        /// </param>
+        /// <returns>
+        /// The character at the specified index in the text span.
+        /// </returns>
+        public char this[int index]
+        {
+            get
+            {
+                this.EnsureHasValue();
+#if CHECKED
+                if ((uint)index >= (uint)Length)
+                    throw new ArgumentOutOfRangeException(nameof(index), index, "Index exceeds the source span's length.");
+#endif
+                return Source![Position.Absolute + index];
+            }
+        }
+
+        /// <summary>
+        /// Forms a slice out of the current text span starting at the specified index.
+        /// </summary>
+        /// <param name="index">
+        /// The index at which to begin the slice.
+        /// </param>
+        /// <returns>
+        /// An text span that consists of all elements of the current array segment from <paramref name="index"/> to the end of the text span.
+        /// </returns>
+        public TextSpan Slice(int index)
+        {
+            return Skip(index);
+        }
+
+        /// <summary>
+        /// Forms a slice of the specified length out of the current text span starting at the specified index.
+        /// </summary>
+        /// <param name="index">The index at which to begin the slice.</param>
+        /// <param name="count">The desired length of the slice.</param>
+        /// <returns>An text span of <paramref name="count"/> elements starting at <paramref name="index"/>.</returns>
+        public TextSpan Slice(int index, int count)
+        {
+            return Skip(index).First(count);
+        }
     }
 }

src/Superpower/Superpower.csproj

@@ -1,8 +1,8 @@
 <Project Sdk="Microsoft.NET.Sdk">
   <PropertyGroup>
-    <TargetFrameworks>netstandard2.0;net5.0</TargetFrameworks>
+    <TargetFrameworks>netstandard2.0;net6.0;net8.0</TargetFrameworks>
     <Description>A parser combinator library for C#</Description>
-    <VersionPrefix>3.0.0</VersionPrefix>
+    <VersionPrefix>3.1.0</VersionPrefix>
     <Authors>Datalust;Superpower Contributors;Sprache Contributors</Authors>
     <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>

test/Superpower.Benchmarks/Superpower.Benchmarks.csproj

@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
-    <TargetFramework>net5.0</TargetFramework>
+    <TargetFrameworks>net6.0;net8.0</TargetFrameworks>
     <GenerateRuntimeConfigurationFiles>true</GenerateRuntimeConfigurationFiles>
     <Nullable>enable</Nullable>
   </PropertyGroup>

test/Superpower.Tests/Combinators/TextCombinatorTests.cs

@@ -0,0 +1,20 @@
+using Superpower.Parsers;
+using Superpower.Tests.Support;
+using Xunit;
+
+namespace Superpower.Tests.Combinators;
+
+public class TextCombinatorTests
+{
+    [Fact]
+    public void TextSucceedsWithAnyCharArrayInput()
+    {
+        AssertParser.SucceedsWith(Character.AnyChar.Many().Text(), "ab", "ab");
+    }
+
+    [Fact]
+    public void TextSucceedsWithTextSpanInput()
+    {
+        AssertParser.SucceedsWith(Span.Length(2).Text(), "ab", "ab");
+    }
+}

test/Superpower.Tests/StringSpanTests.cs

@@ -90,5 +90,38 @@ public void ASpanIsNotEqualToADifferentString(string str, int offset, int length
             var span = new TextSpan(str, new Position(offset, 1, offset + 1), length);
             Assert.False(span.EqualsValue(value));
         }
+
+        [Theory]
+        [InlineData("Hello", 0, 5)]
+        [InlineData("Hello", 0, 3)]
+        [InlineData("Hello", 1, 3)]
+        public void SliceWithLengthExtractsCorrectCharacters(string input, int index, int end)
+        {
+            var inputSpan = new TextSpan(input, new Position(0, 1, 1), input.Length);
+            var slice = inputSpan[index..end];
+            Assert.Equal(expected: input[index..end], actual: slice.ToStringValue());
+        }
+
+        [Theory]
+        [InlineData("Hello", 0)]
+        [InlineData("Hello", 2)]
+        [InlineData("Hello", 5)]
+        public void SliceWithoutLengthExtractsCorrectCharacters(string input, int index)
+        {
+            var inputSpan = new TextSpan(input, new Position(0, 1, 1), input.Length);
+            var slice = inputSpan[index..];
+            Assert.Equal(expected: input[index..], actual: slice.ToStringValue());
+        }
+
+        [Theory]
+        [InlineData("Hello", 0)]
+        [InlineData("Hello", 2)]
+        [InlineData("Hello", 4)]
+        public void IndexerExtractsCorrectCharacter(string input, int index)
+        {
+            var inputSpan = new TextSpan(input, new Position(0, 1, 1), input.Length);
+            var ch = inputSpan[index];
+            Assert.Equal(expected: input[index], actual: ch);
+        }
     }
 }

test/Superpower.Tests/Superpower.Tests.csproj

@@ -1,6 +1,6 @@
 <Project Sdk="Microsoft.NET.Sdk">
   <PropertyGroup>
-    <TargetFramework>net5.0</TargetFramework>
+    <TargetFrameworks>net6.0;net8.0</TargetFrameworks>
     <AssemblyName>Superpower.Tests</AssemblyName>
     <AssemblyOriginatorKeyFile>../../asset/Superpower.snk</AssemblyOriginatorKeyFile>
     <SignAssembly>true</SignAssembly>