A first crack at the Args kata by Mark Seemann
Test-driven development in C#.
A customer hired me to swing by to demonstrate test-driven development and tactical Git. To make things interesting, we agreed that they'd give me a kata at the beginning of the session. I didn't know which problem they'd give me, so I thought it'd be a good idea to come prepared. I decided to seek out katas that I hadn't done before.
The demonstration session was supposed to be two hours in front of a participating audience. In order to make my preparation aligned to that situation, I decided to impose a two-hour time limit to see how far I could get. At the same time, I'd also keep an eye on didactics, so preferably proceeding in an order that would be explainable to an audience.
Some katas are more complicated than others, so I'm under no illusion that I can complete any, to me unknown, kata in under two hours. My success criterion for the time limit is that I'd like to reach a point that would satisfy an audience. Even if, after two hours, I don't reach a complete solution, I should leave a creative and intelligent audience with a good idea of how to proceed.
The first kata I decided to try was the Args kata. In this article, I'll describe some of the most interesting things that happened along the way. If you want all the details, the code is available on GitHub.
Boolean parser #
In short, the goal of the Args kata is to develop an API for parsing command-line arguments.
When you encounter a new problem, it's common to have a few false starts until you develop a promising plan. This happened to me as well, but after a few attempts that I quickly stashed, I realised that this is really a validation problem - as in parse, don't validate.
The first thing I did after that realisation was to copy verbatim the Validated code from An applicative reservation validation example in C#. I consider it fair game to reuse general-purpose code like this for a kata.
With that basic building block available, I decided to start with a parser that would handle Boolean flags. My reasoning was that this might be the simplest parser, since it doesn't have many failure modes. If the flag is present, the value should be interpreted to be true; otherwise, false.
Over a series of iterations, I developed this parametrised xUnit.net test:
[Theory] [InlineData('l', "-l", true)] [InlineData('l', " -l ", true)] [InlineData('l', "-l -p 8080 -d /usr/logs", true)] [InlineData('l', "-p 8080 -l -d /usr/logs", true)] [InlineData('l', "-p 8080 -d /usr/logs", false)] [InlineData('l', "-l true", true)] [InlineData('l', "-l false", false)] [InlineData('l', "nonsense", false)] [InlineData('f', "-f", true)] [InlineData('f', "foo", false)] [InlineData('f', "", false)] public void TryParseSuccess(char flagName, string candidate, bool expected) { var sut = new BoolParser(flagName); var actual = sut.TryParse(candidate); Assert.Equal(Validated.Succeed<string, bool>(expected), actual); }
To be clear, this test started as a [Fact] (single, non-parametrised test) that I subsequently converted to a parametrised test, and then added more and more test cases to.
The final implementation of BoolParser looks like this:
public sealed class BoolParser : IParser<bool> { private readonly char flagName; public BoolParser(char flagName) { this.flagName = flagName; } public Validated<string, bool> TryParse(string candidate) { var idx = candidate.IndexOf($"-{flagName}"); if (idx < 0) return Validated.Succeed<string, bool>(false); var nextFlagIdx = candidate[(idx + 2)..].IndexOf('-'); var bFlag = nextFlagIdx < 0 ? candidate[(idx + 2)..] : candidate.Substring(idx + 2, nextFlagIdx); if (bool.TryParse(bFlag, out var b)) return Validated.Succeed<string, bool>(b); return Validated.Succeed<string, bool>(true); } }
This may not be the most elegant solution, but it passes all tests. Since I was under time pressure, I didn't want to spend too much time polishing the implementation details. As longs as I'm comfortable with the API design and the test cases, I can always refactor later. (I usually say that later is never, which also turned out to be true this time. On the other hand, it's not that the implementation code is awful in any way. It has a cyclomatic complexity of 4 and fits within a 80 x 20 box. It could be much worse.)
The IParser interface came afterwards. It wasn't driven by the above test, but by later developments.
Rough proof of concept #
Once I had a passable implementation of BoolParser, I developed a similar IntParser to a degree where it supported a happy path. With two parsers, I had enough building blocks to demonstrate how to combine them. At that point, I also had some 40 minutes left, so it was time to produce something that might look useful.
At first, I wanted to demonstrate that it's possible to combine the two parsers, so I wrote this test:
[Fact] public void ParseBoolAndIntProofOfConceptRaw() { var args = "-l -p 8080"; var l = new BoolParser('l').TryParse(args).SelectFailure(s => new[] { s }); var p = new IntParser('p').TryParse(args).SelectFailure(s => new[] { s }); Func<bool, int, (bool, int)> createTuple = (b, i) => (b, i); static string[] combineErrors(string[] s1, string[] s2) => s1.Concat(s2).ToArray(); var actual = createTuple.Apply(l, combineErrors).Apply(p, combineErrors); Assert.Equal(Validated.Succeed<string[], (bool, int)>((true, 8080)), actual); }
That's really not pretty, and I wouldn't expect an unsuspecting audience to understand what's going on. It doesn't help that C# is inadequate for applicative functors. While it's possible to implement applicative validation, the C# API is awkward. (There are ways to make it better than what's on display here, but keep in mind that I came into this exercise unprepared, and had to grab what was closest at hand.)
The main point of the above test was only to demonstrate that it's possible to combine two parsers into one. That took me roughly 15 minutes.
Armed with that knowledge, I then proceeded to define this base class:
public abstract class ArgsParser<T1, T2, T> { private readonly IParser<T1> parser1; private readonly IParser<T2> parser2; public ArgsParser(IParser<T1> parser1, IParser<T2> parser2) { this.parser1 = parser1; this.parser2 = parser2; } public Validated<string[], T> TryParse(string candidate) { var l = parser1.TryParse(candidate).SelectFailure(s => new[] { s }); var p = parser2.TryParse(candidate).SelectFailure(s => new[] { s }); Func<T1, T2, T> create = Create; return create.Apply(l, CombineErrors).Apply(p, CombineErrors); } protected abstract T Create(T1 x1, T2 x2); private static string[] CombineErrors(string[] s1, string[] s2) { return s1.Concat(s2).ToArray(); } }
While I'm not a fan of inheritance, this seemed the fasted way to expand on the proof of concept. The class encapsulates the ugly details of the ParseBoolAndIntProofOfConceptRaw test, while leaving just enough room for a derived class:
internal sealed class ProofOfConceptParser : ArgsParser<bool, int, (bool, int)> { public ProofOfConceptParser() : base(new BoolParser('l'), new IntParser('p')) { } protected override (bool, int) Create(bool x1, int x2) { return (x1, x2); } }
This class only defines which parsers to use and how to translate successful results to a single object. Here, because this is still a proof of concept, the resulting object is just a tuple.
The corresponding test looks like this:
[Fact] public void ParseBoolAndIntProofOfConcept() { var sut = new ProofOfConceptParser(); var actual = sut.TryParse("-l -p 8080"); Assert.Equal(Validated.Succeed<string[], (bool, int)>((true, 8080)), actual); }
At this point, I hit the two-hour mark, but I think I managed to produce enough code to convince a hypothetical audience that a complete solution is within grasp.
What remained was to
- add proper error handling to
IntParser - add a corresponding
StringParser - improve the
ArgsParserAPI - add better demo examples of the improved
ArgsParserAPI
While I could leave this as an exercise to the reader, I couldn't just leave the code like that.
Finishing the kata #
For my own satisfaction, I decided to complete the kata, which I did in another hour.
Although I had started with an abstract base class, I know how to refactor it to a sealed class with an injected Strategy. I did that for the existing class, and also added one that supports three parsers instead of two:
public sealed class ArgsParser<T1, T2, T3, T> { private readonly IParser<T1> parser1; private readonly IParser<T2> parser2; private readonly IParser<T3> parser3; private readonly Func<T1, T2, T3, T> create; public ArgsParser( IParser<T1> parser1, IParser<T2> parser2, IParser<T3> parser3, Func<T1, T2, T3, T> create) { this.parser1 = parser1; this.parser2 = parser2; this.parser3 = parser3; this.create = create; } public Validated<string[], T> TryParse(string candidate) { var x1 = parser1.TryParse(candidate).SelectFailure(s => new[] { s }); var x2 = parser2.TryParse(candidate).SelectFailure(s => new[] { s }); var x3 = parser3.TryParse(candidate).SelectFailure(s => new[] { s }); return create .Apply(x1, CombineErrors) .Apply(x2, CombineErrors) .Apply(x3, CombineErrors); } private static string[] CombineErrors(string[] s1, string[] s2) { return s1.Concat(s2).ToArray(); } }
Granted, that's a bit of boilerplate, but if you imagine this as supplied by a reusable library, you only have to write this once.
I was now ready to parse the kata's central example, "-l -p 8080 -d /usr/logs", to a strongly typed value:
private sealed record TestConfig(bool DoLog, int Port, string Directory); [Theory] [InlineData("-l -p 8080 -d /usr/logs")] [InlineData("-p 8080 -l -d /usr/logs")] [InlineData("-d /usr/logs -l -p 8080")] [InlineData(" -d /usr/logs -l -p 8080 ")] public void ParseConfig(string args) { var sut = new ArgsParser<bool, int, string, TestConfig>( new BoolParser('l'), new IntParser('p'), new StringParser('d'), (b, i, s) => new TestConfig(b, i, s)); var actual = sut.TryParse(args); Assert.Equal( Validated.Succeed<string[], TestConfig>( new TestConfig(true, 8080, "/usr/logs")), actual); }
This test parses some variations of the example input into an immutable record.
What happens if the input is malformed? Here's an example of that:
[Fact] public void FailToParseConfig() { var sut = new ArgsParser<bool, int, string, TestConfig>( new BoolParser('l'), new IntParser('p'), new StringParser('d'), (b, i, s) => new TestConfig(b, i, s)); var actual = sut.TryParse("-p aityaity"); Assert.True(actual.Match( onFailure: ss => ss.Contains("Expected integer for flag '-p', but got \"aityaity\"."), onSuccess: _ => false)); Assert.True(actual.Match( onFailure: ss => ss.Contains("Missing value for flag '-d'."), onSuccess: _ => false)); }
Of particular interest is that, as promised by applicative validation, parsing failures don't short-circuit. The input value "-p aityaity" has two problems, and both are reported by TryParse.
At this point I was happy that I had sufficiently demonstrated the viability of the design. I decided to call it a day.
Conclusion #
As I did the Args kata, I found it interesting enough to warrant an article. Once I realised that I could use applicative parsing as the basis for the API, the rest followed.
There's room for improvement, but while doing katas is valuable, there are marginal returns in perfecting the code. Get the main functionality working, learn from it, and move on to another exercise.
