From bd06e37dc9c3e6fbb5b11b8134afb2854a139008 Mon Sep 17 00:00:00 2001
From: jonathanvdc <jonathan.vdc@outlook.com>
Date: Fri, 27 Mar 2026 00:04:16 -0400
Subject: [PATCH 1/3] Add ergonomic command-line parsing APIs

---
 Pixie/Options/CommandLine.cs       | 304 +++++++++++++++++++++++++++++
 Pixie/Options/Option.cs            | 147 +++++++++++++-
 Pixie/Options/OptionForm.cs        |  46 ++++-
 Pixie/Options/OptionParseResult.cs | 149 ++++++++++++++
 Pixie/Options/SequenceOption.cs    |  51 +++++
 Pixie/Options/ValueOption.cs       |  42 ++++
 Tests/GnuOptionSetParserTests.cs   | 186 ++++++++++++++++++
 7 files changed, 923 insertions(+), 2 deletions(-)
 create mode 100644 Pixie/Options/CommandLine.cs
 create mode 100644 Pixie/Options/OptionParseResult.cs

diff --git a/Pixie/Options/CommandLine.cs b/Pixie/Options/CommandLine.cs
new file mode 100644
index 0000000..110a7bf
--- /dev/null
+++ b/Pixie/Options/CommandLine.cs
@@ -0,0 +1,304 @@
+using System.Collections.Generic;
+using Pixie.Markup;
+
+namespace Pixie.Options
+{
+    /// <summary>
+    /// Defines the options accepted by a command-line program and parses
+    /// argument lists into an <see cref="OptionParseResult"/>.
+    /// Use this type when you want one place to describe your options,
+    /// positional arguments, and common built-in behaviors such as
+    /// <c>--help</c> and <c>--version</c>.
+    /// </summary>
+    public sealed class CommandLine
+    {
+        /// <summary>
+        /// Creates a command line that accepts only named options.
+        /// </summary>
+        /// <param name="options">The options accepted by the command line.</param>
+        public CommandLine(params Option[] options)
+            : this(
+                options,
+                new KeyValuePair<Option, OptionForm>[0])
+        { }
+
+        /// <summary>
+        /// Creates a command line with one option that also consumes
+        /// positional arguments.
+        /// </summary>
+        /// <param name="options">The options accepted by the command line.</param>
+        /// <param name="positionalOption">
+        /// The option that should consume bare arguments such as file names.
+        /// </param>
+        public CommandLine(
+            IReadOnlyList<Option> options,
+            Option positionalOption)
+            : this(
+                options,
+                positionalOption,
+                positionalOption.Forms[0])
+        { }
+
+        /// <summary>
+        /// Creates a command line with one option that also consumes
+        /// positional arguments, using a specific option form when Pixie
+        /// needs to describe that positional usage.
+        /// </summary>
+        /// <param name="options">The options accepted by the command line.</param>
+        /// <param name="positionalOption">
+        /// The option that should consume bare arguments such as file names.
+        /// </param>
+        /// <param name="positionalForm">
+        /// The preferred form for the positional option in help and usage text.
+        /// </param>
+        public CommandLine(
+            IReadOnlyList<Option> options,
+            Option positionalOption,
+            OptionForm positionalForm)
+            : this(
+                options,
+                new[]
+                {
+                    new KeyValuePair<Option, OptionForm>(positionalOption, positionalForm)
+                })
+        { }
+
+        /// <summary>
+        /// Creates a command line with explicitly configured positional bindings.
+        /// </summary>
+        /// <param name="options">The options accepted by the command line.</param>
+        /// <param name="positionalOptions">
+        /// The options that should consume bare arguments, in the order they
+        /// should be considered.
+        /// </param>
+        public CommandLine(
+            IReadOnlyList<Option> options,
+            IReadOnlyList<KeyValuePair<Option, OptionForm>> positionalOptions)
+        {
+            this.Options = options;
+            this.PositionalOptions = positionalOptions;
+        }
+
+        private CommandLine(CommandLine other)
+        {
+            this.Options = other.Options;
+            this.PositionalOptions = other.PositionalOptions;
+            this.Summary = other.Summary;
+            this.Usage = other.Usage;
+            this.Version = other.Version;
+            this.HelpOption = other.HelpOption;
+            this.VersionOption = other.VersionOption;
+        }
+
+        /// <summary>
+        /// Gets the options accepted by this command line.
+        /// </summary>
+        /// <returns>The accepted options.</returns>
+        public IReadOnlyList<Option> Options { get; private set; }
+
+        /// <summary>
+        /// Gets the positional option bindings for this command line.
+        /// </summary>
+        /// <returns>The positional option bindings.</returns>
+        public IReadOnlyList<KeyValuePair<Option, OptionForm>> PositionalOptions { get; private set; }
+
+        /// <summary>
+        /// Gets the summary used for generated help output.
+        /// </summary>
+        /// <returns>The summary.</returns>
+        public MarkupNode Summary { get; private set; }
+
+        /// <summary>
+        /// Gets the usage text used for generated help output.
+        /// </summary>
+        /// <returns>The usage text.</returns>
+        public MarkupNode Usage { get; private set; }
+
+        /// <summary>
+        /// Gets the version text emitted by the generated version option.
+        /// </summary>
+        /// <returns>The version text.</returns>
+        public MarkupNode Version { get; private set; }
+
+        /// <summary>
+        /// Gets the generated help option, if any.
+        /// </summary>
+        /// <returns>The help option.</returns>
+        public Option HelpOption { get; private set; }
+
+        /// <summary>
+        /// Gets the generated version option, if any.
+        /// </summary>
+        /// <returns>The version option.</returns>
+        public Option VersionOption { get; private set; }
+
+        /// <summary>
+        /// Creates a copy of this command line that also supports a generated
+        /// help option, typically <c>-h</c> and <c>--help</c>.
+        /// </summary>
+        /// <param name="summary">The summary shown in generated help output.</param>
+        /// <param name="usage">The usage text shown in generated help output.</param>
+        /// <param name="forms">
+        /// The forms accepted by the help option. If omitted, Pixie uses
+        /// <c>-h</c> and <c>--help</c>.
+        /// </param>
+        /// <returns>A new command line.</returns>
+        public CommandLine WithHelp(
+            MarkupNode summary,
+            MarkupNode usage,
+            params string[] forms)
+        {
+            var result = new CommandLine(this);
+            result.HelpOption = Option.Flag(
+                forms.Length == 0
+                    ? new[] { "-h", "--help" }
+                    : forms);
+            result.Summary = summary;
+            result.Usage = usage;
+            result.Options = AppendOption(Options, result.HelpOption);
+            return result;
+        }
+
+        /// <summary>
+        /// Creates a copy of this command line that also supports a generated
+        /// help option, typically <c>-h</c> and <c>--help</c>.
+        /// </summary>
+        /// <param name="summary">The summary shown in generated help output.</param>
+        /// <param name="usage">The usage text shown in generated help output.</param>
+        /// <param name="forms">
+        /// The forms accepted by the help option. If omitted, Pixie uses
+        /// <c>-h</c> and <c>--help</c>.
+        /// </param>
+        /// <returns>A new command line.</returns>
+        public CommandLine WithHelp(
+            string summary,
+            string usage,
+            params string[] forms)
+        {
+            return WithHelp((MarkupNode)summary, usage, forms);
+        }
+
+        /// <summary>
+        /// Creates a copy of this command line that also supports a generated
+        /// version option, typically <c>--version</c>.
+        /// </summary>
+        /// <param name="version">The version text to emit.</param>
+        /// <param name="forms">
+        /// The forms accepted by the version option. If omitted, Pixie uses
+        /// <c>--version</c>.
+        /// </param>
+        /// <returns>A new command line.</returns>
+        public CommandLine WithVersion(
+            MarkupNode version,
+            params string[] forms)
+        {
+            var result = new CommandLine(this);
+            result.VersionOption = Option.Flag(
+                forms.Length == 0
+                    ? new[] { "--version" }
+                    : forms);
+            result.Version = version;
+            result.Options = AppendOption(Options, result.VersionOption);
+            return result;
+        }
+
+        /// <summary>
+        /// Creates a copy of this command line that also supports a generated
+        /// version option, typically <c>--version</c>.
+        /// </summary>
+        /// <param name="version">The version text to emit.</param>
+        /// <param name="forms">
+        /// The forms accepted by the version option. If omitted, Pixie uses
+        /// <c>--version</c>.
+        /// </param>
+        /// <returns>A new command line.</returns>
+        public CommandLine WithVersion(
+            string version,
+            params string[] forms)
+        {
+            return WithVersion((MarkupNode)version, forms);
+        }
+
+        /// <summary>
+        /// Parses a list of command-line arguments and returns both the parsed
+        /// values and any diagnostics Pixie produced while parsing.
+        /// Diagnostics are captured in the result and not forwarded anywhere.
+        /// </summary>
+        /// <param name="arguments">The command-line arguments to parse.</param>
+        /// <returns>A parse result.</returns>
+        public OptionParseResult Parse(IReadOnlyList<string> arguments)
+        {
+            return Parse(arguments, NullLog.Instance);
+        }
+
+        /// <summary>
+        /// Parses a list of command-line arguments, forwarding any diagnostics
+        /// to the supplied log while also capturing them in the result.
+        /// This is the usual entry point for real commands because it lets Pixie
+        /// print parse errors, generated help, or version information immediately
+        /// while still giving the caller structured access to the outcome.
+        /// </summary>
+        /// <param name="arguments">The command-line arguments to parse.</param>
+        /// <param name="log">The log to forward diagnostics to.</param>
+        /// <returns>A parse result.</returns>
+        public OptionParseResult Parse(
+            IReadOnlyList<string> arguments,
+            ILog log)
+        {
+            var recordingLog = new RecordingLog(log);
+            var parser = new GnuOptionSetParser(Options, PositionalOptions);
+            var optionSet = parser.Parse(arguments, recordingLog);
+            bool hasErrors = recordingLog.Contains(Severity.Error);
+            bool helpRequested =
+                !hasErrors
+                && HelpOption != null
+                && optionSet.GetValue<bool>(HelpOption);
+            bool versionRequested =
+                !hasErrors
+                && !helpRequested
+                && VersionOption != null
+                && optionSet.GetValue<bool>(VersionOption);
+
+            bool shouldExit = false;
+            int exitCode = hasErrors ? 1 : 0;
+
+            if (helpRequested)
+            {
+                recordingLog.Log(
+                    new LogEntry(
+                        Severity.Info,
+                        new HelpMessage(
+                            Summary ?? "",
+                            Usage ?? "",
+                            Options)));
+                shouldExit = true;
+            }
+            else if (versionRequested)
+            {
+                recordingLog.Log(new LogEntry(Severity.Info, Version ?? ""));
+                shouldExit = true;
+            }
+
+            return new OptionParseResult(
+                optionSet,
+                recordingLog.RecordedEntries,
+                shouldExit,
+                exitCode,
+                helpRequested,
+                versionRequested);
+        }
+
+        private static IReadOnlyList<Option> AppendOption(
+            IReadOnlyList<Option> options,
+            Option opt)
+        {
+            var result = new Option[options.Count + 1];
+            for (int i = 0; i < options.Count; i++)
+            {
+                result[i] = options[i];
+            }
+            result[options.Count] = opt;
+            return result;
+        }
+    }
+}
diff --git a/Pixie/Options/Option.cs b/Pixie/Options/Option.cs
index c92b16b..8c9acfa 100644
--- a/Pixie/Options/Option.cs
+++ b/Pixie/Options/Option.cs
@@ -1,3 +1,4 @@
+using System;
 using System.Collections.Generic;
 
 namespace Pixie.Options
@@ -7,6 +8,139 @@ namespace Pixie.Options
     /// </summary>
     public abstract class Option
     {
+        /// <summary>
+        /// Creates a simple flag option from command-line spellings such as
+        /// <c>-h</c> or <c>--help</c>.
+        /// </summary>
+        /// <param name="forms">The forms accepted by the option.</param>
+        /// <returns>A flag option.</returns>
+        public static FlagOption Flag(params string[] forms)
+        {
+            return FlagOption.CreateFlagOption(ParseForms(forms));
+        }
+
+        /// <summary>
+        /// Creates a flag option with explicit positive and negative forms.
+        /// </summary>
+        /// <param name="positiveForm">The form that enables the flag.</param>
+        /// <param name="negativeForm">The form that disables the flag.</param>
+        /// <param name="defaultValue">The default value for the flag.</param>
+        /// <returns>A flag option.</returns>
+        public static FlagOption Toggle(
+            string positiveForm,
+            string negativeForm,
+            bool defaultValue = false)
+        {
+            return new FlagOption(
+                OptionForm.Parse(positiveForm),
+                OptionForm.Parse(negativeForm),
+                defaultValue);
+        }
+
+        /// <summary>
+        /// Creates a string option from command-line spellings such as
+        /// <c>--color</c>.
+        /// </summary>
+        /// <param name="defaultValue">The option's default value.</param>
+        /// <param name="forms">The forms accepted by the option.</param>
+        /// <returns>A string option.</returns>
+        public static ValueOption<string> StringWithDefault(
+            string defaultValue,
+            params string[] forms)
+        {
+            return ValueOption.CreateStringOption(ParseForms(forms), defaultValue);
+        }
+
+        /// <summary>
+        /// Creates a string option with an empty-string default value.
+        /// </summary>
+        /// <param name="forms">The forms accepted by the option.</param>
+        /// <returns>A string option.</returns>
+        public static ValueOption<string> String(params string[] forms)
+        {
+            return StringWithDefault("", forms);
+        }
+
+        /// <summary>
+        /// Creates a 32-bit integer option from command-line spellings such as
+        /// <c>-O</c>.
+        /// </summary>
+        /// <param name="defaultValue">The option's default value.</param>
+        /// <param name="forms">The forms accepted by the option.</param>
+        /// <returns>A 32-bit integer option.</returns>
+        public static ValueOption<int> Int32WithDefault(
+            int defaultValue,
+            params string[] forms)
+        {
+            return ValueOption.CreateInt32Option(ParseForms(forms), defaultValue);
+        }
+
+        /// <summary>
+        /// Creates a 32-bit integer option with a default value of zero.
+        /// </summary>
+        /// <param name="forms">The forms accepted by the option.</param>
+        /// <returns>A 32-bit integer option.</returns>
+        public static ValueOption<int> Int32(params string[] forms)
+        {
+            return Int32WithDefault(0, forms);
+        }
+
+        /// <summary>
+        /// Creates a typed value option from command-line spellings.
+        /// </summary>
+        /// <typeparam name="T">The parsed value type.</typeparam>
+        /// <param name="parseArgument">A function that parses the option's argument.</param>
+        /// <param name="defaultValue">The option's default value.</param>
+        /// <param name="forms">The forms accepted by the option.</param>
+        /// <returns>A typed option.</returns>
+        public static ValueOption<T> Value<T>(
+            Func<OptionForm, string, ILog, T> parseArgument,
+            T defaultValue,
+            params string[] forms)
+        {
+            return ValueOption.CreateOption(
+                ParseForms(forms),
+                parseArgument,
+                defaultValue);
+        }
+
+        /// <summary>
+        /// Creates a string sequence option from command-line spellings such as
+        /// <c>--file</c>.
+        /// </summary>
+        /// <param name="forms">The forms accepted by the option.</param>
+        /// <returns>A string sequence option.</returns>
+        public static SequenceOption<string> StringSequence(params string[] forms)
+        {
+            return SequenceOption.CreateStringOption(ParseForms(forms));
+        }
+
+        /// <summary>
+        /// Creates a 32-bit integer sequence option from command-line spellings.
+        /// </summary>
+        /// <param name="forms">The forms accepted by the option.</param>
+        /// <returns>A 32-bit integer sequence option.</returns>
+        public static SequenceOption<int> Int32Sequence(params string[] forms)
+        {
+            return SequenceOption.CreateInt32Option(ParseForms(forms));
+        }
+
+        /// <summary>
+        /// Creates a typed sequence option from command-line spellings.
+        /// </summary>
+        /// <typeparam name="T">The parsed element type.</typeparam>
+        /// <param name="parseArgument">A function that parses each argument.</param>
+        /// <param name="forms">The forms accepted by the option.</param>
+        /// <returns>A typed sequence option.</returns>
+        public static SequenceOption<T> Sequence<T>(
+            Func<OptionForm, string, ILog, T> parseArgument,
+            params string[] forms)
+        {
+            return SequenceOption.CreateOption(
+                ParseForms(forms),
+                parseArgument);
+        }
+
         /// <summary>
         /// Gets the option's documentation.
         /// </summary>
@@ -43,6 +177,17 @@ public abstract class Option
         public abstract ParsedOption MergeValues(
             ParsedOption first,
             ParsedOption second);
+
+        private static IReadOnlyList<OptionForm> ParseForms(
+            IReadOnlyList<string> forms)
+        {
+            var results = new OptionForm[forms.Count];
+            for (int i = 0; i < forms.Count; i++)
+            {
+                results[i] = OptionForm.Parse(forms[i]);
+            }
+            return results;
+        }
     }
 
     /// <summary>
@@ -69,4 +214,4 @@ public abstract class OptionParser
         /// <returns>The resulting value.</returns>
         public abstract object GetValue(ILog log);
     }
-}
\ No newline at end of file
+}
diff --git a/Pixie/Options/OptionForm.cs b/Pixie/Options/OptionForm.cs
index 32b6d89..b0e39c4 100644
--- a/Pixie/Options/OptionForm.cs
+++ b/Pixie/Options/OptionForm.cs
@@ -114,5 +114,49 @@ public static OptionForm Long(string name)
         {
             return new OptionForm(name, false);
         }
+
+        /// <summary>
+        /// Parses an option form from its command-line spelling.
+        /// </summary>
+        /// <param name="text">
+        /// The option form as it appears on the command line,
+        /// for example <c>-h</c> or <c>--help</c>.
+        /// </param>
+        /// <returns>The parsed option form.</returns>
+        public static OptionForm Parse(string text)
+        {
+            if (string.IsNullOrEmpty(text))
+            {
+                throw new ArgumentException(
+                    "Option forms cannot be null or empty.",
+                    nameof(text));
+            }
+
+            if (text.StartsWith("--"))
+            {
+                if (text.Length <= 2)
+                {
+                    throw new ArgumentException(
+                        "Long option forms must include a name after '--'.",
+                        nameof(text));
+                }
+                return Long(text.Substring(2));
+            }
+
+            if (text.StartsWith("-"))
+            {
+                if (text.Length <= 1)
+                {
+                    throw new ArgumentException(
+                        "Short option forms must include a name after '-'.",
+                        nameof(text));
+                }
+                return Short(text.Substring(1));
+            }
+
+            throw new ArgumentException(
+                "Option forms must start with '-' or '--'.",
+                nameof(text));
+        }
     }
-}
\ No newline at end of file
+}
diff --git a/Pixie/Options/OptionParseResult.cs b/Pixie/Options/OptionParseResult.cs
new file mode 100644
index 0000000..b1e079a
--- /dev/null
+++ b/Pixie/Options/OptionParseResult.cs
@@ -0,0 +1,149 @@
+using System.Collections.Generic;
+
+namespace Pixie.Options
+{
+    /// <summary>
+    /// Represents the outcome of parsing a command line.
+    /// </summary>
+    public sealed class OptionParseResult
+    {
+        /// <summary>
+        /// Creates a parse result from parsed options and recorded diagnostics.
+        /// </summary>
+        /// <param name="options">The parsed options.</param>
+        /// <param name="diagnostics">The diagnostics emitted while parsing.</param>
+        /// <param name="wasHandled">
+        /// Tells if parsing already handled a conventional exit path, such as
+        /// printing generated help or version information.
+        /// </param>
+        /// <param name="exitCode">The recommended process exit code.</param>
+        /// <param name="wasHelpRequested">
+        /// Tells if the help option was requested.
+        /// </param>
+        /// <param name="wasVersionRequested">
+        /// Tells if the version option was requested.
+        /// </param>
+        public OptionParseResult(
+            OptionSet options,
+            IReadOnlyList<LogEntry> diagnostics,
+            bool wasHandled,
+            int exitCode,
+            bool wasHelpRequested,
+            bool wasVersionRequested)
+        {
+            this.Options = options;
+            this.Diagnostics = diagnostics;
+            this.WasHandled = wasHandled;
+            this.ExitCode = exitCode;
+            this.WasHelpRequested = wasHelpRequested;
+            this.WasVersionRequested = wasVersionRequested;
+        }
+
+        /// <summary>
+        /// Gets the parsed options.
+        /// </summary>
+        /// <returns>The parsed options.</returns>
+        public OptionSet Options { get; private set; }
+
+        /// <summary>
+        /// Gets the diagnostics emitted while parsing.
+        /// </summary>
+        /// <returns>The diagnostics emitted while parsing.</returns>
+        public IReadOnlyList<LogEntry> Diagnostics { get; private set; }
+
+        /// <summary>
+        /// Tells if parsing already handled a conventional exit path,
+        /// such as printing generated help or version information.
+        /// This is typically <c>true</c> when <see cref="WasHelpRequested"/>
+        /// or <see cref="WasVersionRequested"/> is <c>true</c>.
+        /// It is typically <c>false</c> for ordinary successful parses,
+        /// where the caller should continue running the command, and also
+        /// for parse failures, where <see cref="IsSuccess"/> is <c>false</c>.
+        /// </summary>
+        /// <returns>
+        /// <c>true</c> if parsing printed a built-in terminal response and the
+        /// caller will usually want to return immediately; otherwise, <c>false</c>.
+        /// </returns>
+        public bool WasHandled { get; private set; }
+
+        /// <summary>
+        /// Gets the exit code associated with this parse result.
+        /// </summary>
+        /// <returns>The recommended exit code.</returns>
+        public int ExitCode { get; private set; }
+
+        /// <summary>
+        /// Tells if the help option was requested.
+        /// </summary>
+        /// <returns>
+        /// <c>true</c> if help was requested; otherwise, <c>false</c>.
+        /// </returns>
+        public bool WasHelpRequested { get; private set; }
+
+        /// <summary>
+        /// Tells if the version option was requested.
+        /// </summary>
+        /// <returns>
+        /// <c>true</c> if version information was requested; otherwise, <c>false</c>.
+        /// </returns>
+        public bool WasVersionRequested { get; private set; }
+
+        /// <summary>
+        /// Tells if parsing succeeded without errors.
+        /// </summary>
+        /// <returns>
+        /// <c>true</c> if no errors were emitted while parsing;
+        /// otherwise, <c>false</c>.
+        /// </returns>
+        public bool IsSuccess => !Contains(Severity.Error);
+
+        /// <summary>
+        /// Tests if parsing emitted at least one diagnostic of a particular severity.
+        /// </summary>
+        /// <param name="severity">The severity to look for.</param>
+        /// <returns>
+        /// <c>true</c> if parsing emitted a diagnostic of the requested severity;
+        /// otherwise, <c>false</c>.
+        /// </returns>
+        public bool Contains(Severity severity)
+        {
+            int count = Diagnostics.Count;
+            for (int i = 0; i < count; i++)
+            {
+                if (Diagnostics[i].Severity == severity)
+                {
+                    return true;
+                }
+            }
+            return false;
+        }
+
+        /// <summary>
+        /// Looks for the value that has been parsed for a particular option.
+        /// If there is no such value, then the option's default value is produced.
+        /// </summary>
+        /// <param name="opt">An option to find a parsed value for.</param>
+        /// <param name="result">The resulting value.</param>
+        /// <typeparam name="T">The option's value type.</typeparam>
+        /// <returns>
+        /// <c>true</c> if a form of the option has been parsed;
+        /// otherwise, <c>false</c>.
+        /// </returns>
+        public bool TryGetValue<T>(Option opt, out T result)
+        {
+            return Options.TryGetValue<T>(opt, out result);
+        }
+
+        /// <summary>
+        /// Gets the value that has been parsed for a particular option.
+        /// If there is no such value, then the option's default value is returned.
+        /// </summary>
+        /// <param name="opt">An option to find a parsed value for.</param>
+        /// <typeparam name="T">The option's value type.</typeparam>
+        /// <returns>The parsed value or the option's default value.</returns>
+        public T GetValue<T>(Option opt)
+        {
+            return Options.GetValue<T>(opt);
+        }
+    }
+}
diff --git a/Pixie/Options/SequenceOption.cs b/Pixie/Options/SequenceOption.cs
index bd3e6c8..967e897 100644
--- a/Pixie/Options/SequenceOption.cs
+++ b/Pixie/Options/SequenceOption.cs
@@ -130,6 +130,29 @@ public SequenceOption<T> WithParameters(params OptionParameter[] parameters)
             return WithParameters((IReadOnlyList<OptionParameter>)parameters);
         }
 
+        /// <summary>
+        /// Creates a copy of this option that has a single symbolic parameter.
+        /// </summary>
+        /// <param name="name">The parameter's display name.</param>
+        /// <returns>An option.</returns>
+        public SequenceOption<T> WithParameter(string name)
+        {
+            return WithParameters(new SymbolicOptionParameter(name, true));
+        }
+
+        /// <summary>
+        /// Creates a copy of this option that has a single symbolic parameter.
+        /// </summary>
+        /// <param name="name">The parameter's display name.</param>
+        /// <param name="isVarargs">
+        /// Tells if the parameter can take more than one argument.
+        /// </param>
+        /// <returns>An option.</returns>
+        public SequenceOption<T> WithParameter(string name, bool isVarargs)
+        {
+            return WithParameters(new SymbolicOptionParameter(name, isVarargs));
+        }
+
         /// <inheritdoc/>
         public override IReadOnlyList<OptionForm> Forms => forms;
 
@@ -166,6 +189,34 @@ public override ParsedOption MergeValues(
     /// </summary>
     public static class SequenceOption
     {
+        /// <summary>
+        /// Creates a typed sequence option that takes a single form.
+        /// </summary>
+        /// <typeparam name="T">The parsed element type.</typeparam>
+        /// <param name="form">The option's form.</param>
+        /// <param name="parseArgument">A function that parses each argument.</param>
+        /// <returns>A typed sequence option.</returns>
+        public static SequenceOption<T> CreateOption<T>(
+            OptionForm form,
+            Func<OptionForm, string, ILog, T> parseArgument)
+        {
+            return new SequenceOption<T>(form, parseArgument);
+        }
+
+        /// <summary>
+        /// Creates a typed sequence option that takes a list of forms.
+        /// </summary>
+        /// <typeparam name="T">The parsed element type.</typeparam>
+        /// <param name="forms">The option's forms.</param>
+        /// <param name="parseArgument">A function that parses each argument.</param>
+        /// <returns>A typed sequence option.</returns>
+        public static SequenceOption<T> CreateOption<T>(
+            IReadOnlyList<OptionForm> forms,
+            Func<OptionForm, string, ILog, T> parseArgument)
+        {
+            return new SequenceOption<T>(forms, parseArgument);
+        }
+
         /// <summary>
         /// Creates a string-sequence option that takes a single form.
         /// </summary>
diff --git a/Pixie/Options/ValueOption.cs b/Pixie/Options/ValueOption.cs
index b2cdc95..ef9dc3b 100644
--- a/Pixie/Options/ValueOption.cs
+++ b/Pixie/Options/ValueOption.cs
@@ -130,6 +130,16 @@ public ValueOption<T> WithParameter(OptionParameter parameter)
             return result;
         }
 
+        /// <summary>
+        /// Creates a copy of this option that has a symbolic parameter.
+        /// </summary>
+        /// <param name="name">The parameter's display name.</param>
+        /// <returns>An option.</returns>
+        public ValueOption<T> WithParameter(string name)
+        {
+            return WithParameter(new SymbolicOptionParameter(name));
+        }
+
         /// <inheritdoc/>
         public override IReadOnlyList<OptionForm> Forms => forms;
 
@@ -162,6 +172,38 @@ public override ParsedOption MergeValues(ParsedOption first, ParsedOption second
     /// </summary>
     public static class ValueOption
     {
+        /// <summary>
+        /// Creates a typed option that takes a single form.
+        /// </summary>
+        /// <typeparam name="T">The parsed value type.</typeparam>
+        /// <param name="form">The option's form.</param>
+        /// <param name="parseArgument">A function that parses the option's argument.</param>
+        /// <param name="defaultValue">The default value for the option.</param>
+        /// <returns>A typed option.</returns>
+        public static ValueOption<T> CreateOption<T>(
+            OptionForm form,
+            Func<OptionForm, string, ILog, T> parseArgument,
+            T defaultValue)
+        {
+            return new ValueOption<T>(form, parseArgument, defaultValue);
+        }
+
+        /// <summary>
+        /// Creates a typed option that takes a list of forms.
+        /// </summary>
+        /// <typeparam name="T">The parsed value type.</typeparam>
+        /// <param name="forms">The option's forms.</param>
+        /// <param name="parseArgument">A function that parses the option's argument.</param>
+        /// <param name="defaultValue">The default value for the option.</param>
+        /// <returns>A typed option.</returns>
+        public static ValueOption<T> CreateOption<T>(
+            IReadOnlyList<OptionForm> forms,
+            Func<OptionForm, string, ILog, T> parseArgument,
+            T defaultValue)
+        {
+            return new ValueOption<T>(forms, parseArgument, defaultValue);
+        }
+
         /// <summary>
         /// Creates a string option that takes a single form.
         /// </summary>
diff --git a/Tests/GnuOptionSetParserTests.cs b/Tests/GnuOptionSetParserTests.cs
index 070275f..d27ad96 100644
--- a/Tests/GnuOptionSetParserTests.cs
+++ b/Tests/GnuOptionSetParserTests.cs
@@ -198,6 +198,192 @@ public void TryGetValueReturnsDefaultWhenOptionIsMissing()
             Assert.IsFalse(parsedOpts.ContainsOption(Color));
         }
 
+        [Test]
+        public void ParseOptionFormFromCommandLineSpelling()
+        {
+            Assert.AreEqual(OptionForm.Short("h"), OptionForm.Parse("-h"));
+            Assert.AreEqual(OptionForm.Long("help"), OptionForm.Parse("--help"));
+        }
+
+        [Test]
+        public void HighLevelFlagBuilderCreatesAliasForms()
+        {
+            var help = Option.Flag("-h", "--help");
+            var parser = new GnuOptionSetParser(new Option[] { help });
+
+            var parsedOpts = parser.Parse(new[] { "--help" }, TestEnvironment.GlobalLog);
+
+            Assert.IsTrue(parsedOpts.GetValue<bool>(help));
+        }
+
+        [Test]
+        public void HighLevelValueBuilderParsesTypedValue()
+        {
+            var optimization = Option
+                .Int32WithDefault(0, "-O", "--optimize")
+                .WithDescription("Pick an optimization level.")
+                .WithParameter("level");
+
+            var parser = new GnuOptionSetParser(new Option[] { optimization });
+            var parsedOpts = parser.Parse(new[] { "--optimize=3" }, TestEnvironment.GlobalLog);
+
+            Assert.AreEqual(3, parsedOpts.GetValue<int>(optimization));
+            StringAssert.Contains("level", Render(new OptionHelp(optimization, GnuOptionPrinter.Instance)));
+        }
+
+        [Test]
+        public void HighLevelSequenceBuilderUsesSymbolicParameterHelper()
+        {
+            var files = Option
+                .StringSequence("--file")
+                .WithDescription("Consume files as input.")
+                .WithParameter("path");
+
+            var parser = new GnuOptionSetParser(new Option[] { files });
+            var parsedOpts = parser.Parse(new[] { "--file", "a.txt", "b.txt" }, TestEnvironment.GlobalLog);
+
+            CollectionAssert.AreEqual(
+                new[] { "a.txt", "b.txt" },
+                parsedOpts.GetValue<IReadOnlyList<string>>(files));
+            StringAssert.Contains("path", Render(new OptionHelp(files, GnuOptionPrinter.Instance)));
+        }
+
+        [Test]
+        public void ConvenienceStringBuilderUsesEmptyStringDefault()
+        {
+            var color = Option.String("--color");
+            var parser = new GnuOptionSetParser(new Option[] { color });
+            var parsedOpts = parser.Parse(new string[] { }, TestEnvironment.GlobalLog);
+
+            Assert.AreEqual("", parsedOpts.GetValue<string>(color));
+        }
+
+        [Test]
+        public void GenericValueBuilderParsesCustomType()
+        {
+            var mode = Option
+                .Value(
+                    (OptionForm form, string argument, ILog log) =>
+                        argument == null ? 0 : argument.Length,
+                    0,
+                    "--mode")
+                .WithParameter("name");
+
+            var parser = new GnuOptionSetParser(new Option[] { mode });
+            var parsedOpts = parser.Parse(new[] { "--mode=fast" }, TestEnvironment.GlobalLog);
+
+            Assert.AreEqual(4, parsedOpts.GetValue<int>(mode));
+        }
+
+        [Test]
+        public void GenericSequenceBuilderParsesCustomType()
+        {
+            var lengths = Option.Sequence(
+                (OptionForm form, string argument, ILog log) => argument.Length,
+                "--name-length");
+
+            var parser = new GnuOptionSetParser(new Option[] { lengths });
+            var parsedOpts = parser.Parse(
+                new[] { "--name-length", "Ada", "Grace" },
+                TestEnvironment.GlobalLog);
+
+            CollectionAssert.AreEqual(
+                new[] { 3, 5 },
+                parsedOpts.GetValue<IReadOnlyList<int>>(lengths));
+        }
+
+        [Test]
+        public void CommandLineFacadeParsesOptionsAndPositionals()
+        {
+            var help = Option.Flag("-h", "--help");
+            var files = Option.StringSequence("--files")
+                .WithParameter("file");
+            var commandLine = new CommandLine(
+                new Option[] { help, files },
+                files);
+
+            var result = commandLine.Parse(new[] { "a.txt", "-h", "b.txt" });
+
+            Assert.IsTrue(result.IsSuccess);
+            Assert.IsTrue(result.GetValue<bool>(help));
+            CollectionAssert.AreEqual(
+                new[] { "a.txt", "b.txt" },
+                result.GetValue<IReadOnlyList<string>>(files));
+        }
+
+        [Test]
+        public void CommandLineFacadeCapturesErrors()
+        {
+            var help = Option.Flag("--help");
+            var commandLine = new CommandLine(help);
+
+            var result = commandLine.Parse(new[] { "--unknown" });
+
+            Assert.IsFalse(result.IsSuccess);
+            Assert.IsTrue(result.Contains(Severity.Error));
+            Assert.AreEqual(1, result.Diagnostics.Count);
+        }
+
+        [Test]
+        public void CommandLineFacadeForwardsDiagnosticsToProvidedLog()
+        {
+            var help = Option.Flag("--help");
+            var forwardingLog = new RecordingLog();
+            var commandLine = new CommandLine(help);
+
+            var result = commandLine.Parse(new[] { "--unknown" }, forwardingLog);
+
+            Assert.IsFalse(result.IsSuccess);
+            Assert.AreEqual(1, forwardingLog.RecordedEntries.Count);
+            Assert.AreEqual(1, result.Diagnostics.Count);
+        }
+
+        [Test]
+        public void CommandLineCanPrintGeneratedHelpAndRecommendExit()
+        {
+            var files = Option.StringSequence("--files").WithParameter("file");
+            var commandLine = new CommandLine(files)
+                .WithHelp("Example program.", "example [files-or-options]");
+            var log = new RecordingLog();
+
+            var result = commandLine.Parse(new[] { "--help" }, log);
+
+            Assert.IsTrue(result.IsSuccess);
+            Assert.IsTrue(result.WasHandled);
+            Assert.AreEqual(0, result.ExitCode);
+            Assert.IsTrue(result.WasHelpRequested);
+            StringAssert.Contains("Description", Render(log.RecordedEntries[0].Contents));
+            StringAssert.Contains("example [files-or-options]", Render(log.RecordedEntries[0].Contents));
+        }
+
+        [Test]
+        public void CommandLineCanPrintVersionAndRecommendExit()
+        {
+            var commandLine = new CommandLine()
+                .WithVersion("example 1.2.3");
+            var log = new RecordingLog();
+
+            var result = commandLine.Parse(new[] { "--version" }, log);
+
+            Assert.IsTrue(result.IsSuccess);
+            Assert.IsTrue(result.WasHandled);
+            Assert.AreEqual(0, result.ExitCode);
+            Assert.IsTrue(result.WasVersionRequested);
+            StringAssert.Contains("example 1.2.3", Render(log.RecordedEntries[0].Contents));
+        }
+
+        [Test]
+        public void ParseErrorsRecommendNonZeroExitCode()
+        {
+            var commandLine = new CommandLine();
+
+            var result = commandLine.Parse(new[] { "--unknown" });
+
+            Assert.IsFalse(result.IsSuccess);
+            Assert.IsFalse(result.WasHandled);
+            Assert.AreEqual(1, result.ExitCode);
+        }
+
         private static string Render(MarkupNode node)
         {
             return RenderTests.Render(node).Trim();

From c5c2ad75f218804846e2fba8ee6cf49822c3402c Mon Sep 17 00:00:00 2001
From: jonathanvdc <jonathan.vdc@outlook.com>
Date: Fri, 27 Mar 2026 00:04:47 -0400
Subject: [PATCH 2/3] Add logging helpers and refresh examples

---
 Examples/CaretDiagnostics/Program.cs   |  13 +--
 Examples/FormattedList/Program.cs      |  35 +++---
 Examples/LoycInterop/Program.cs        |   9 +-
 Examples/ParseOptions/Program.cs       | 149 +++++++++++++------------
 Examples/PrintHelp/Program.cs          |  56 +++++-----
 Examples/SimpleErrorMessage/Program.cs |  18 ++-
 Pixie/LogExtensions.cs                 |  94 ++++++++++++++++
 Pixie/Transforms/LogExtensions.cs      |  28 ++++-
 README.md                              |  52 ++++++---
 Tests/LogBehaviorTests.cs              |  27 +++++
 10 files changed, 319 insertions(+), 162 deletions(-)
 create mode 100644 Pixie/LogExtensions.cs

diff --git a/Examples/CaretDiagnostics/Program.cs b/Examples/CaretDiagnostics/Program.cs
index 69b74d5..9c5848d 100644
--- a/Examples/CaretDiagnostics/Program.cs
+++ b/Examples/CaretDiagnostics/Program.cs
@@ -47,15 +47,10 @@ public static void Main(string[] args)
 
             // Write an entry to the log that contains the things
             // we would like to print.
-            log.Log(
-                new LogEntry(
-                    Severity.Error,
-                    "hello world",
-                    new MarkupNode[]
-                    {
-                        new Text("look at this beautiful error message!"),
-                        new HighlightedSource(highlightRegion, focusRegion)
-                    }));
+            log.Error(
+                "hello world",
+                new Text("look at this beautiful error message!"),
+                new HighlightedSource(highlightRegion, focusRegion));
         }
         private const string SourceCode = @"public static class Program
 {
diff --git a/Examples/FormattedList/Program.cs b/Examples/FormattedList/Program.cs
index 1e0dd82..61e8a15 100644
--- a/Examples/FormattedList/Program.cs
+++ b/Examples/FormattedList/Program.cs
@@ -54,27 +54,22 @@ public static void Main(string[] args)
 
             // Write an entry to the log that contains the things
             // we would like to print.
-            log.Log(
-                new LogEntry(
-                    Severity.Info,
-                    new MarkupNode[]
-                    {
-                        // Create a title, underline it and make it green because why not.
-                        new Title(
-                            DecorationSpan.MakeUnderlined(
-                                new ColorSpan("Hello world", Colors.Green))),
+            log.Info(
+                // Create a title, underline it and make it green because why not.
+                new Title(
+                    DecorationSpan.MakeUnderlined(
+                        new ColorSpan("Hello world", Colors.Green))),
 
-                        // Create a word-wrapped bulleted list with a uniform margin of four.
-                        new WrapBox(
-                            new BulletedList(
-                                LoremIpsum
-                                    .Split(new char[] { '\n' }, StringSplitOptions.RemoveEmptyEntries)
-                                    .Select<string, MarkupNode>(QuoteString)
-                                    .ToArray<MarkupNode>(),
-                                true),
-                            WrappingStrategy.Word,
-                            4)
-                    }));
+                // Create a word-wrapped bulleted list with a uniform margin of four.
+                new WrapBox(
+                    new BulletedList(
+                        LoremIpsum
+                            .Split(new char[] { '\n' }, StringSplitOptions.RemoveEmptyEntries)
+                            .Select<string, MarkupNode>(QuoteString)
+                            .ToArray<MarkupNode>(),
+                        true),
+                    WrappingStrategy.Word,
+                    4));
         }
 
         private static MarkupNode QuoteString(string text)
diff --git a/Examples/LoycInterop/Program.cs b/Examples/LoycInterop/Program.cs
index ba3bea0..3d7ff92 100644
--- a/Examples/LoycInterop/Program.cs
+++ b/Examples/LoycInterop/Program.cs
@@ -20,12 +20,9 @@ public static void Main(string[] args)
 
             // First, acquire a terminal log. We'll configure it to
             // turn everything it sees into a diagnostic.
-            var log = new TransformLog(
-                TerminalLog.Acquire(),
-                new Func<LogEntry, LogEntry>[]
-                {
-                    MakeDiagnostic
-                });
+            var log = TerminalLog
+                .Acquire()
+                .WithTransform(MakeDiagnostic);
 
             // Create a message sink that redirects messages to the log.
             var messageSink = new PixieMessageSink(log);
diff --git a/Examples/ParseOptions/Program.cs b/Examples/ParseOptions/Program.cs
index 3eb6f0e..dbf5fd1 100644
--- a/Examples/ParseOptions/Program.cs
+++ b/Examples/ParseOptions/Program.cs
@@ -1,4 +1,5 @@
 using System;
+using System.Collections;
 using System.Collections.Generic;
 using System.Linq;
 using System.Text;
@@ -16,7 +17,7 @@ public static class Program
 
         // This option is a simple flag. It takes no arguments.
         private static readonly FlagOption optimizeFastFlag =
-            new FlagOption(OptionForm.Short("Ofast"))
+            Option.Flag("-Ofast")
             .WithCategory("Optimization options")
             .WithDescription("Enable aggressive optimizations.");
 
@@ -24,54 +25,40 @@ public static class Program
         // different forms:
         //     -h and --help.
         private static readonly FlagOption helpFlag =
-            FlagOption.CreateFlagOption(
-                new OptionForm[]
-                {
-                    OptionForm.Short("h"),
-                    OptionForm.Long("help")
-                })
+            Option.Flag("-h", "--help")
             .WithDescription(
                 "Print a description of the options understood.");
 
         // This option has both a positive and a negative form:
         //     -fsyntax-only and -fno-syntax-only.
         private static readonly FlagOption syntaxOnlyFlag =
-            new FlagOption(
-                OptionForm.Short("fsyntax-only"),
-                OptionForm.Short("fno-syntax-only"),
-                false)
+            Option.Toggle(
+                "-fsyntax-only",
+                "-fno-syntax-only")
             .WithDescription("Check the code for syntax errors only.");
 
         // This option takes zero or more strings as arguments.
         private static readonly SequenceOption<string> filesOption =
-            SequenceOption.CreateStringOption(
-                OptionForm.Long("files"))
+            Option.StringSequence("--files")
             .WithDescription("Consume files as input.")
-            .WithParameters(
-                new OptionParameter[]
-                {
-                    new SymbolicOptionParameter("file", true)
-                });
+            .WithParameter("file");
 
         // This option takes a 32-bit signed integer as argument.
         private static readonly ValueOption<int> optimizeOption =
-            ValueOption.CreateInt32Option(
-                OptionForm.Short("O"),
-                0)
+            Option.Int32WithDefault(
+                0,
+                "-O")
             .WithCategory("Optimization options")
             .WithDescription("Pick an optimization level.")
-            .WithParameter(new SymbolicOptionParameter("n"));
+            .WithParameter("n");
 
         // This option takes a 32-bit signed integer as argument.
         // It also happens to have two forms.
         private static readonly ValueOption<int> maxErrorsOption =
-            ValueOption.CreateInt32Option(
-                new OptionForm[]
-                {
-                    OptionForm.Short("fmax-errors"),
-                    OptionForm.Short("ferror-limit")
-                },
-                0)
+            Option.Int32WithDefault(
+                0,
+                "-fmax-errors",
+                "-ferror-limit")
             .WithDescription(
                 new Sequence(
                     new MarkupNode[]
@@ -80,22 +67,15 @@ public static class Program
                         new SymbolicOptionParameter("n").Representation,
                         "."
                     }))
-            .WithParameter(new SymbolicOptionParameter("n"));
-
-        private static OptionSet parsedOptions;
-
+            .WithParameter("n");
         public static void Main(string[] args)
         {
             // First, acquire a terminal log. You should acquire
             // a log once and then re-use it in your application.
-            ILog log = TerminalLog.Acquire();
-
-            log = new TransformLog(
-                log,
-                new Func<LogEntry, LogEntry>[]
-                {
-                    MakeDiagnostic
-                });
+            ILog log = TerminalLog
+                .Acquire()
+                .WithDiagnostics("program")
+                .WithWordWrap();
 
             var allOptions = new Option[]
             {
@@ -107,64 +87,87 @@ public static void Main(string[] args)
                 maxErrorsOption
             };
 
-            var parser = new GnuOptionSetParser(
+            // `filesOption` plays two roles in this example:
+            // it can be spelled explicitly as `--files`,
+            // and it is also the option that should consume bare
+            // positional arguments such as `a.txt`.
+            //
+            // The third constructor argument picks the form Pixie should
+            // mention when it needs to describe that positional behavior
+            // in help or diagnostics.
+            var commandLine = new CommandLine(
                 allOptions, filesOption, filesOption.Forms[0]);
 
-            parsedOptions = parser.Parse(args, log);
+            var parsedOptions = commandLine.Parse(args, log);
+
+            if (!parsedOptions.IsSuccess || parsedOptions.WasHandled)
+            {
+                return;
+            }
 
             if (!parsedOptions.GetValue<bool>(syntaxOnlyFlag))
             {
-                log.Log(
-                    new LogEntry(
-                        Severity.Info,
-                        new BulletedList(
-                            allOptions
-                                .Select<Option, MarkupNode>(TypesetParsedOption)
-                                .ToArray<MarkupNode>(),
-                            true)));
+                log.Info(RenderParsedOptions(allOptions, parsedOptions));
             }
         }
 
-        private static MarkupNode TypesetParsedOption(Option opt)
+        private static MarkupNode RenderParsedOptions(
+            IReadOnlyList<Option> options,
+            OptionParseResult parsedOptions)
+        {
+            return new BulletedList(
+                options
+                    .Select(opt => RenderParsedOption(opt, parsedOptions))
+                    .ToArray(),
+                true);
+        }
+
+        private static MarkupNode RenderParsedOption(
+            Option opt,
+            OptionParseResult parsedOptions)
         {
+            // Pixie can accept many forms for the same option, such as
+            // `-h` and `--help`.
+            //
+            // For this little report, we print the option's first form as
+            // its canonical display name. That keeps the output stable and
+            // makes it obvious which spelling the example treats as the
+            // primary one, even though the parser still accepts the others.
             return new Sequence(
-                new MarkupNode[]
-                {
-                    new DecorationSpan(new Text(opt.Forms[0].ToString()), TextDecoration.Bold),
-                    new Text(": "),
-                    new Text(ValueToString(parsedOptions.GetValue<object>(opt)))
-                });
+                DecorationSpan.MakeBold(opt.Forms[0].ToString()),
+                ": ",
+                ValueToMarkup(parsedOptions.GetValue<object>(opt)));
         }
 
-        private static string ValueToString(object value)
+        private static MarkupNode ValueToMarkup(object value)
         {
-            if (value is IReadOnlyList<object>)
+            // Sequence options come back as enumerable values, so format them
+            // as `{ a, b, c }` to make it clear that multiple arguments were
+            // gathered into one parsed option value.
+            if (value is IEnumerable sequence && !(value is string))
             {
                 var sb = new StringBuilder();
                 sb.Append("{ ");
-                var arr = (IReadOnlyList<object>)value;
-                for (int i = 0; i < arr.Count; i++)
+                bool first = true;
+                foreach (var element in sequence)
                 {
-                    if (i > 0)
+                    if (!first)
                     {
                         sb.Append(", ");
                     }
-                    sb.Append(ValueToString(arr[i]));
+                    sb.Append(ValueToText(element));
+                    first = false;
                 }
                 sb.Append(" }");
-                return sb.ToString();
-            }
-            else
-            {
-                return value.ToString();
+                return new Text(sb.ToString());
             }
+
+            return new Text(ValueToText(value));
         }
 
-        private static LogEntry MakeDiagnostic(LogEntry entry)
+        private static string ValueToText(object value)
         {
-            return DiagnosticExtractor
-                .Transform(entry, new Text("program"))
-                .Map(WrapBox.WordWrap);
+            return value == null ? "" : value.ToString();
         }
     }
 }
diff --git a/Examples/PrintHelp/Program.cs b/Examples/PrintHelp/Program.cs
index cbd766d..e8116a4 100644
--- a/Examples/PrintHelp/Program.cs
+++ b/Examples/PrintHelp/Program.cs
@@ -38,19 +38,32 @@ public static void Main(string[] args)
             // First, acquire a terminal log. You should acquire
             // a log once and then re-use it in your application.
             var log = TerminalLog.Acquire();
+            var commandLine = new CommandLine(
+                filesOption,
+                syntaxOnlyFlag,
+                optimizeOption,
+                optimizeFastFlag)
+                .WithHelp(
+                    "PrintHelp is an example program that showcases " +
+                    "how easy it is to create pretty help messages using Pixie.",
+                    "PrintHelp [files-or-options]");
 
-            // Wrap the help message into a log entry and send it to the log.
-            log.Log(
-                new LogEntry(
-                    Severity.Info,
-                    ComposeHelpMessage()));
+            var parseArgs = args.Length == 0
+                ? new[] { "--help" }
+                : args;
+
+            var result = commandLine.Parse(parseArgs, log);
+            if (!result.IsSuccess || result.WasHandled)
+            {
+                return;
+            }
         }
 
         // A number of option definitions.
 
         // This option is a simple flag. It takes no arguments.
         private static readonly FlagOption optimizeFastFlag =
-            new FlagOption(OptionForm.Short("Ofast"))
+            Option.Flag("-Ofast")
                 .WithCategory("Optimization options")
                 .WithDescription("Enable aggressive optimizations.");
 
@@ -58,42 +71,31 @@ public static void Main(string[] args)
         // different forms:
         //     -h and --help.
         private static readonly FlagOption helpFlag =
-            FlagOption.CreateFlagOption(
-                new OptionForm[]
-                {
-                    OptionForm.Short("h"),
-                    OptionForm.Long("help")
-                })
+            Option.Flag("-h", "--help")
                 .WithDescription(
                     "Print a description of the options understood.");
 
         // This option has both a positive and a negative form:
         //     -fsyntax-only and -fno-syntax-only.
         private static readonly FlagOption syntaxOnlyFlag =
-            new FlagOption(
-                OptionForm.Short("fsyntax-only"),
-                OptionForm.Short("fno-syntax-only"),
-                false)
+            Option.Toggle(
+                "-fsyntax-only",
+                "-fno-syntax-only")
                 .WithDescription("Check the code for syntax errors only.");
 
         // This option takes zero or more strings as arguments.
         private static readonly SequenceOption<string> filesOption =
-            SequenceOption.CreateStringOption(
-                OptionForm.Long("files"))
+            Option.StringSequence("--files")
                 .WithDescription("Consume files as input.")
-                .WithParameters(
-                    new OptionParameter[]
-                    {
-                        new SymbolicOptionParameter("file", true)
-                    });
+                .WithParameter("file");
 
         // This option takes a 32-bit signed integer as argument.
         private static readonly ValueOption<int> optimizeOption =
-            ValueOption.CreateInt32Option(
-                OptionForm.Short("O"),
-                0)
+            Option.Int32WithDefault(
+                0,
+                "-O")
                 .WithCategory("Optimization options")
                 .WithDescription("Pick an optimization level.")
-                .WithParameter(new SymbolicOptionParameter("n"));
+                .WithParameter("n");
     }
 }
diff --git a/Examples/SimpleErrorMessage/Program.cs b/Examples/SimpleErrorMessage/Program.cs
index 24dc268..da4332a 100644
--- a/Examples/SimpleErrorMessage/Program.cs
+++ b/Examples/SimpleErrorMessage/Program.cs
@@ -33,16 +33,14 @@ public static void Main(string[] args)
                 });
 
             // Log an error diagnostic.
-            log.Log(
-                new LogEntry(
-                    Severity.Error,
-                    WrapBox.WordWrap(
-                        new Diagnostic(
-                            "mcs",
-                            "error",
-                            Colors.Red,
-                            "CS5001",
-                            message))));
+            log.Error(
+                WrapBox.WordWrap(
+                    new Diagnostic(
+                        "mcs",
+                        "error",
+                        Colors.Red,
+                        "CS5001",
+                        message)));
         }
     }
 }
diff --git a/Pixie/LogExtensions.cs b/Pixie/LogExtensions.cs
new file mode 100644
index 0000000..e58972c
--- /dev/null
+++ b/Pixie/LogExtensions.cs
@@ -0,0 +1,94 @@
+using Pixie.Markup;
+
+namespace Pixie
+{
+    /// <summary>
+    /// Convenience helpers for creating and logging entries with a specific severity.
+    /// </summary>
+    public static class LogExtensions
+    {
+        /// <summary>
+        /// Logs an informational entry.
+        /// </summary>
+        /// <param name="log">The log to write to.</param>
+        /// <param name="contents">The entry contents.</param>
+        public static void Info(this ILog log, params MarkupNode[] contents)
+        {
+            log.Log(new LogEntry(Severity.Info, contents));
+        }
+
+        /// <summary>
+        /// Logs an informational entry with a title.
+        /// </summary>
+        /// <param name="log">The log to write to.</param>
+        /// <param name="title">The entry title.</param>
+        /// <param name="contents">The entry contents.</param>
+        public static void Info(this ILog log, string title, params MarkupNode[] contents)
+        {
+            log.Log(new LogEntry(Severity.Info, title, contents));
+        }
+
+        /// <summary>
+        /// Logs a plain message entry.
+        /// </summary>
+        /// <param name="log">The log to write to.</param>
+        /// <param name="contents">The entry contents.</param>
+        public static void Message(this ILog log, params MarkupNode[] contents)
+        {
+            log.Log(new LogEntry(Severity.Message, contents));
+        }
+
+        /// <summary>
+        /// Logs a plain message entry with a title.
+        /// </summary>
+        /// <param name="log">The log to write to.</param>
+        /// <param name="title">The entry title.</param>
+        /// <param name="contents">The entry contents.</param>
+        public static void Message(this ILog log, string title, params MarkupNode[] contents)
+        {
+            log.Log(new LogEntry(Severity.Message, title, contents));
+        }
+
+        /// <summary>
+        /// Logs a warning entry.
+        /// </summary>
+        /// <param name="log">The log to write to.</param>
+        /// <param name="contents">The entry contents.</param>
+        public static void Warning(this ILog log, params MarkupNode[] contents)
+        {
+            log.Log(new LogEntry(Severity.Warning, contents));
+        }
+
+        /// <summary>
+        /// Logs a warning entry with a title.
+        /// </summary>
+        /// <param name="log">The log to write to.</param>
+        /// <param name="title">The entry title.</param>
+        /// <param name="contents">The entry contents.</param>
+        public static void Warning(this ILog log, string title, params MarkupNode[] contents)
+        {
+            log.Log(new LogEntry(Severity.Warning, title, contents));
+        }
+
+        /// <summary>
+        /// Logs an error entry.
+        /// </summary>
+        /// <param name="log">The log to write to.</param>
+        /// <param name="contents">The entry contents.</param>
+        public static void Error(this ILog log, params MarkupNode[] contents)
+        {
+            log.Log(new LogEntry(Severity.Error, contents));
+        }
+
+        /// <summary>
+        /// Logs an error entry with a title.
+        /// </summary>
+        /// <param name="log">The log to write to.</param>
+        /// <param name="title">The entry title.</param>
+        /// <param name="contents">The entry contents.</param>
+        public static void Error(this ILog log, string title, params MarkupNode[] contents)
+        {
+            log.Log(new LogEntry(Severity.Error, title, contents));
+        }
+    }
+}
diff --git a/Pixie/Transforms/LogExtensions.cs b/Pixie/Transforms/LogExtensions.cs
index 4fbdf79..4bbdb77 100644
--- a/Pixie/Transforms/LogExtensions.cs
+++ b/Pixie/Transforms/LogExtensions.cs
@@ -7,6 +7,31 @@ namespace Pixie.Transforms
     /// </summary>
     public static class LogExtensions
     {
+        /// <summary>
+        /// Wraps a log so that every entry is first transformed before
+        /// being forwarded to the underlying log.
+        /// </summary>
+        /// <param name="log">The log to wrap.</param>
+        /// <param name="transform">The transform to apply to each entry.</param>
+        /// <returns>A log that applies the requested transform.</returns>
+        public static ILog WithTransform(
+            this ILog log,
+            System.Func<LogEntry, LogEntry> transform)
+        {
+            return new TransformLog(log, transform);
+        }
+
+        /// <summary>
+        /// Wraps a log so that every entry's contents are passed through
+        /// <see cref="WrapBox.WordWrap(MarkupNode)"/> before rendering.
+        /// </summary>
+        /// <param name="log">The log to wrap.</param>
+        /// <returns>A log that word-wraps each entry.</returns>
+        public static ILog WithWordWrap(this ILog log)
+        {
+            return log.WithTransform(entry => entry.Map(WrapBox.WordWrap));
+        }
+
         /// <summary>
         /// Wraps a log so that every entry is first converted to a
         /// compiler-style diagnostic.
@@ -28,8 +53,7 @@ public static class LogExtensions
         /// <returns>A log that emits diagnostic-formatted entries.</returns>
         public static ILog WithDiagnostics(this ILog log, MarkupNode defaultOrigin)
         {
-            return new TransformLog(
-                log,
+            return log.WithTransform(
                 entry => DiagnosticExtractor.Transform(entry, defaultOrigin));
         }
 
diff --git a/README.md b/README.md
index 4d66f65..3e0fa13 100644
--- a/README.md
+++ b/README.md
@@ -28,9 +28,7 @@ using Pixie.Terminal;
 
 var log = TerminalLog.Acquire();
 
-log.Log(new LogEntry(
-    Severity.Info,
-    "Hello from Pixie."));
+log.Info("Hello from Pixie.");
 ```
 
 `TerminalLog.Acquire()` is the usual entry point for diagnostics and other CLI feedback. It writes to standard error by default, which is often what you want for warnings, errors, and help output.
@@ -160,9 +158,7 @@ using Pixie.Terminal;
 
 var log = TerminalLog.Acquire();
 
-log.Log(new LogEntry(
-    Severity.Error,
-    "Something went wrong."));
+log.Error("Something went wrong.");
 ```
 
 If you want explicit markup nodes, use types from `Pixie.Markup`, such as `Text`, `Sequence`, `BulletedList`, or `HighlightedSource`.
@@ -178,24 +174,50 @@ using Pixie.Terminal;
 
 var log = TerminalLog.Acquire();
 
-var helpFlag = FlagOption.CreateFlagOption(
-    OptionForm.Short("h"),
-    OptionForm.Long("help"));
+var helpFlag = Option.Flag("-h", "--help");
+var filesOption = Option.StringSequence("--files")
+    .WithParameter("file");
 
-var filesOption = SequenceOption.CreateStringOption(
-    OptionForm.Long("files"));
-
-var parser = new GnuOptionSetParser(
+var commandLine = new CommandLine(
     new Option[] { helpFlag },
     filesOption);
 
-var parsedArgs = parser.Parse(new[] { "input.cs", "-h" }, log);
+var parsedArgs = commandLine.Parse(new[] { "input.cs", "-h" }, log);
 
 bool showHelp = parsedArgs.GetValue<bool>(helpFlag);
 string[] files = parsedArgs.GetValue<string[]>(filesOption);
+
+if (!parsedArgs.IsSuccess)
+{
+    return;
+}
+```
+
+If you want the common `--help` and `--version` flow handled for you:
+
+```cs
+var commandLine = new CommandLine(filesOption)
+    .WithHelp("Example program.", "example [files-or-options]")
+    .WithVersion("example 1.0.0");
+
+var result = commandLine.Parse(args, log);
+if (result.WasHandled)
+{
+    return;
+}
+```
+
+For custom typed parsing, use the generic builders:
+
+```cs
+var portOption = Option.Value(
+    (OptionForm form, string argument, ILog log) => int.Parse(argument),
+    8080,
+    "--port")
+    .WithParameter("n");
 ```
 
-When parsing fails, Pixie can report errors to the log instead of leaving formatting and recovery entirely up to the application.
+When parsing fails, Pixie can report errors to the log and also capture them in the returned `OptionParseResult`. The same result can also tell you whether built-in help or version handling already printed output via `WasHandled`. In other words, `WasHandled` is for parser-managed early exits like help/version, not for parse failures.
 
 By design, `Parse(...)` still returns an `OptionSet`, so applications can decide how to recover. A common pattern is to capture log entries and then bail out if any errors were reported:
 
diff --git a/Tests/LogBehaviorTests.cs b/Tests/LogBehaviorTests.cs
index 15e0959..7538d8b 100644
--- a/Tests/LogBehaviorTests.cs
+++ b/Tests/LogBehaviorTests.cs
@@ -1,4 +1,5 @@
 using NUnit.Framework;
+using Pixie.Markup;
 using Pixie.Transforms;
 
 namespace Pixie.Tests
@@ -44,5 +45,31 @@ public void WithDiagnosticsWrapsEntriesInDiagnosticTransform()
             var rendered = RenderTests.Render(sink.RecordedEntries[0].Contents);
             StringAssert.Contains("program: error: oops", rendered);
         }
+
+        [Test]
+        public void WithTransformAppliesSingleEntryTransform()
+        {
+            var sink = new RecordingLog();
+            var log = sink.WithTransform(
+                entry => new LogEntry(entry.Severity, "changed"));
+
+            log.Log(new LogEntry(Severity.Message, "ignored"));
+
+            StringAssert.Contains("changed", RenderTests.Render(sink.RecordedEntries[0].Contents));
+        }
+
+        [Test]
+        public void WithWordWrapMapsEntryContents()
+        {
+            var sink = new RecordingLog();
+            var log = sink.WithWordWrap();
+
+            log.Log(new LogEntry(
+                Severity.Message,
+                WrapBox.WordWrap("very long line")));
+
+            var rendered = RenderTests.Render(sink.RecordedEntries[0].Contents);
+            StringAssert.Contains(System.Environment.NewLine, rendered);
+        }
     }
 }

From ca60c8611fa8715acc3ef51727209efe81ad57af Mon Sep 17 00:00:00 2001
From: jonathanvdc <jonathan.vdc@outlook.com>
Date: Fri, 27 Mar 2026 00:05:02 -0400
Subject: [PATCH 3/3] Fix terminal separator and diagnostic spacing

---
 Pixie.Terminal/Devices/LayoutTerminal.cs      | 35 ++++++++++++--
 Pixie.Terminal/Devices/OutputTerminalBase.cs  | 48 ++++++++++++++++---
 Pixie.Terminal/Devices/TextWriterTerminal.cs  |  2 +
 Pixie.Terminal/Render/DiagnosticRenderer.cs   | 28 +++++++++--
 .../Render/HighlightedSourceRenderer.cs       | 11 ++++-
 Pixie.Terminal/Render/ParagraphRenderer.cs    | 28 +++++++++--
 Pixie.Terminal/Render/PrefixBoxRenderer.cs    | 10 +++-
 .../Render/RenderThemeProperties.cs           | 16 +++++++
 Pixie.Terminal/Render/SequenceRenderer.cs     | 22 ++++++++-
 Pixie.Terminal/Render/WrapBoxRenderer.cs      | 10 +++-
 Pixie.Terminal/TerminalBase.cs                | 14 +++++-
 Pixie.Terminal/TerminalLog.cs                 |  1 +
 Tests/RenderTests.cs                          | 13 +++++
 Tests/TerminalDeviceTests.cs                  |  2 +-
 14 files changed, 215 insertions(+), 25 deletions(-)
 create mode 100644 Pixie.Terminal/Render/RenderThemeProperties.cs

diff --git a/Pixie.Terminal/Devices/LayoutTerminal.cs b/Pixie.Terminal/Devices/LayoutTerminal.cs
index c910d91..827099b 100644
--- a/Pixie.Terminal/Devices/LayoutTerminal.cs
+++ b/Pixie.Terminal/Devices/LayoutTerminal.cs
@@ -90,6 +90,11 @@ public LayoutTerminal(
         /// <inheritdoc/>
         public override int Width => width;
 
+        /// <inheritdoc/>
+        public override bool HasWrittenContent =>
+            lineLength > 0
+            || UnalignedTerminal.HasWrittenContent;
+
         private List<Action<TerminalBase>> commandBuffer;
 
         private int lineLength;
@@ -149,7 +154,10 @@ private void Write(StringInfo text)
         public override void WriteLine()
         {
             Flush();
-            UnalignedTerminal.WriteLine();
+            if (HasWrittenContent)
+            {
+                UnalignedTerminal.WriteLine();
+            }
         }
 
         /// <inheritdoc/>
@@ -159,9 +167,20 @@ public override void WriteSeparator(int lineCount)
             {
                 Flush();
             }
+            if (!HasWrittenContent)
+            {
+                return;
+            }
             UnalignedTerminal.WriteSeparator(lineCount);
         }
 
+        /// <inheritdoc/>
+        public override void FinishOutput()
+        {
+            Flush();
+            UnalignedTerminal.FinishOutput();
+        }
+
         /// <summary>
         /// Starts a layout box. Flushes any buffered output
         /// in the render state to the output terminal, creates
@@ -171,14 +190,22 @@ public override void WriteSeparator(int lineCount)
         /// <param name="state">
         /// The old render state to create a new box in.
         /// </param>
+        /// <param name="writeLeadingSeparator">
+        /// Tells if the layout box should insert its usual leading separator.
+        /// </param>
         /// <returns>A new render state for a layout box.</returns>
-        public RenderState StartLayoutBox(RenderState state)
+        public RenderState StartLayoutBox(
+            RenderState state,
+            bool writeLeadingSeparator = true)
         {
             if (state.Terminal is LayoutTerminal)
             {
                 ((LayoutTerminal)state.Terminal).Flush();
             }
-            WriteSeparator(1);
+            if (writeLeadingSeparator)
+            {
+                WriteSeparator(1);
+            }
             return state.WithTerminal(this);
         }
 
@@ -599,4 +626,4 @@ public void Run(TerminalBase terminal)
             terminal.Style.PushDecoration(Decoration, UpdateDecoration);
         }
     }
-}
\ No newline at end of file
+}
diff --git a/Pixie.Terminal/Devices/OutputTerminalBase.cs b/Pixie.Terminal/Devices/OutputTerminalBase.cs
index 19480ac..d3595a4 100644
--- a/Pixie.Terminal/Devices/OutputTerminalBase.cs
+++ b/Pixie.Terminal/Devices/OutputTerminalBase.cs
@@ -9,27 +9,52 @@ namespace Pixie.Terminal
     public abstract class OutputTerminalBase : TerminalBase
     {
         private int sepLineCounter;
+        private bool hasWrittenContent;
 
         /// <summary>
         /// Writes a raw newline to the output.
         /// </summary>
         protected abstract void WriteLineImpl();
 
+        /// <summary>
+        /// Marks that visible output content has been written.
+        /// </summary>
+        protected void NoteWrittenContent()
+        {
+            hasWrittenContent = true;
+        }
+
+        /// <inheritdoc/>
+        public override bool HasWrittenContent => hasWrittenContent;
+
+        private void FlushSeparator()
+        {
+            for (int i = 0; i < sepLineCounter; i++)
+            {
+                WriteLineImpl();
+            }
+            sepLineCounter = 0;
+        }
+
         /// <inheritdoc/>
         public sealed override void WriteLine()
         {
-            WriteSeparator(1);
+            if (HasWrittenContent)
+            {
+                WriteSeparator(1);
+                FlushSeparator();
+            }
         }
 
         /// <inheritdoc/>
         public override void WriteSeparator(int lineCount)
         {
-            int oldSepLineCounter = sepLineCounter;
-            sepLineCounter = Math.Max(lineCount, sepLineCounter);
-            for (int i = oldSepLineCounter; i < sepLineCounter; i++)
+            if (!hasWrittenContent)
             {
-                WriteLineImpl();
+                return;
             }
+
+            sepLineCounter = Math.Max(lineCount, sepLineCounter);
         }
 
         /// <summary>
@@ -37,7 +62,16 @@ public override void WriteSeparator(int lineCount)
         /// </summary>
         protected void EndSeparator()
         {
-            sepLineCounter = 0;
+            FlushSeparator();
+        }
+
+        /// <inheritdoc/>
+        public override void FinishOutput()
+        {
+            if (HasWrittenContent)
+            {
+                FlushSeparator();
+            }
         }
     }
-}
\ No newline at end of file
+}
diff --git a/Pixie.Terminal/Devices/TextWriterTerminal.cs b/Pixie.Terminal/Devices/TextWriterTerminal.cs
index 2273eb0..3e5e7c1 100644
--- a/Pixie.Terminal/Devices/TextWriterTerminal.cs
+++ b/Pixie.Terminal/Devices/TextWriterTerminal.cs
@@ -106,6 +106,7 @@ public TextWriterTerminal(
         public override void Write(string text)
         {
             EndSeparator();
+            NoteWrittenContent();
             Writer.Write(text);
         }
 
@@ -119,6 +120,7 @@ protected override void WriteLineImpl()
         public override void Write(char character)
         {
             EndSeparator();
+            NoteWrittenContent();
             Writer.Write(character);
         }
 
diff --git a/Pixie.Terminal/Render/DiagnosticRenderer.cs b/Pixie.Terminal/Render/DiagnosticRenderer.cs
index 7ba4f74..fba124b 100644
--- a/Pixie.Terminal/Render/DiagnosticRenderer.cs
+++ b/Pixie.Terminal/Render/DiagnosticRenderer.cs
@@ -24,11 +24,33 @@ public override bool CanRender(MarkupNode node)
         public override void Render(MarkupNode node, RenderState state)
         {
             var diag = (Diagnostic)node;
-            state
+            var titlePart = Text.IsEmpty(diag.Title)
+                ? diag.Title
+                : new Sequence(diag.Title, new Text(": "));
+
+            var header =
+                new Sequence(
+                    diag.Origin,
+                    new Text(": "),
+                    new ColorSpan(
+                        new Text(diag.Kind + ": "),
+                        diag.ThemeColor),
+                    titlePart);
+
+            var bodyState = state
                 .WithThemeProperty(
                     HighlightedSourceRenderer.HighlightColorProperty,
                     diag.ThemeColor)
-                .Render(diag.Fallback);
+                .WithThemeProperty(
+                    RenderThemeProperties.SuppressLeadingSeparatorProperty,
+                    true);
+
+            bodyState.Render(new DecorationSpan(header, TextDecoration.Bold));
+            if (!Text.IsEmpty(diag.Message))
+            {
+                bodyState.Terminal.WriteLine();
+            }
+            bodyState.Render(diag.Message);
         }
     }
-}
\ No newline at end of file
+}
diff --git a/Pixie.Terminal/Render/HighlightedSourceRenderer.cs b/Pixie.Terminal/Render/HighlightedSourceRenderer.cs
index 3971c84..3bec5c9 100644
--- a/Pixie.Terminal/Render/HighlightedSourceRenderer.cs
+++ b/Pixie.Terminal/Render/HighlightedSourceRenderer.cs
@@ -145,6 +145,12 @@ protected Color GetHighlightColor(RenderState state)
         public override void Render(MarkupNode node, RenderState state)
         {
             var src = (HighlightedSource)node;
+            object suppressVal;
+            bool suppressLeading =
+                state.ThemeProperties.TryGetValue(
+                    RenderThemeProperties.SuppressLeadingSeparatorProperty,
+                    out suppressVal)
+                && (bool)suppressVal;
 
             var highlightRegion = src.HighlightRegion;
             var focusRegion = src.FocusRegion;
@@ -173,7 +179,10 @@ public override void Render(MarkupNode node, RenderState state)
             var maxLineWidth = GetLineWidth(
                 firstLineNumber + compressedLines.Count, state);
 
-            state.Terminal.WriteSeparator(2);
+            if (!suppressLeading)
+            {
+                state.Terminal.WriteSeparator(2);
+            }
 
             for (int i = 0; i < compressedLines.Count; i++)
             {
diff --git a/Pixie.Terminal/Render/ParagraphRenderer.cs b/Pixie.Terminal/Render/ParagraphRenderer.cs
index 1133d65..6b3c3e6 100644
--- a/Pixie.Terminal/Render/ParagraphRenderer.cs
+++ b/Pixie.Terminal/Render/ParagraphRenderer.cs
@@ -25,7 +25,18 @@ public override bool CanRender(MarkupNode node)
         public override void Render(MarkupNode node, RenderState state)
         {
             var para = (Paragraph)node;
-            state.Terminal.WriteSeparator(2);
+            object suppressVal;
+            bool suppressLeading =
+                state.ThemeProperties.TryGetValue(
+                    RenderThemeProperties.SuppressLeadingSeparatorProperty,
+                    out suppressVal)
+                && (bool)suppressVal;
+
+            if (!suppressLeading)
+            {
+                state.Terminal.WriteSeparator(2);
+            }
+
             state.Render(para.Contents);
             state.Terminal.WriteSeparator(2);
         }
@@ -53,9 +64,20 @@ public override bool CanRender(MarkupNode node)
         public override void Render(MarkupNode node, RenderState state)
         {
             var para = (Box)node;
-            state.Terminal.WriteSeparator(1);
+            object suppressVal;
+            bool suppressLeading =
+                state.ThemeProperties.TryGetValue(
+                    RenderThemeProperties.SuppressLeadingSeparatorProperty,
+                    out suppressVal)
+                && (bool)suppressVal;
+
+            if (!suppressLeading)
+            {
+                state.Terminal.WriteSeparator(1);
+            }
+
             state.Render(para.Contents);
             state.Terminal.WriteSeparator(1);
         }
     }
-}
\ No newline at end of file
+}
diff --git a/Pixie.Terminal/Render/PrefixBoxRenderer.cs b/Pixie.Terminal/Render/PrefixBoxRenderer.cs
index 844f101..2a019aa 100644
--- a/Pixie.Terminal/Render/PrefixBoxRenderer.cs
+++ b/Pixie.Terminal/Render/PrefixBoxRenderer.cs
@@ -26,10 +26,16 @@ public override void Render(MarkupNode node, RenderState state)
         {
             var boxNode = (PrefixBox)node;
             var newState = state;
+            object suppressVal;
+            bool suppressLeading =
+                state.ThemeProperties.TryGetValue(
+                    RenderThemeProperties.SuppressLeadingSeparatorProperty,
+                    out suppressVal)
+                && (bool)suppressVal;
             var newTerm = LayoutTerminal.Align(
                 state.Terminal, Alignment.Left);
 
-            newState = newTerm.StartLayoutBox(state);
+            newState = newTerm.StartLayoutBox(state, !suppressLeading);
             newState.Render(boxNode.Prefix);
             int lineLength = newTerm.BufferedLineLength;
             newTerm.Flush();
@@ -46,4 +52,4 @@ public override void Render(MarkupNode node, RenderState state)
             newTerm.EndLayoutBox();
         }
     }
-}
\ No newline at end of file
+}
diff --git a/Pixie.Terminal/Render/RenderThemeProperties.cs b/Pixie.Terminal/Render/RenderThemeProperties.cs
new file mode 100644
index 0000000..21cd136
--- /dev/null
+++ b/Pixie.Terminal/Render/RenderThemeProperties.cs
@@ -0,0 +1,16 @@
+namespace Pixie.Terminal.Render
+{
+    /// <summary>
+    /// Common theme property names used by terminal renderers.
+    /// </summary>
+    public static class RenderThemeProperties
+    {
+        /// <summary>
+        /// When set to <c>true</c>, the first paragraph-like renderer in a
+        /// subtree suppresses its leading separator and then clears the flag
+        /// for its children.
+        /// </summary>
+        public const string SuppressLeadingSeparatorProperty =
+            "suppress-leading-separator";
+    }
+}
diff --git a/Pixie.Terminal/Render/SequenceRenderer.cs b/Pixie.Terminal/Render/SequenceRenderer.cs
index 7a71361..e695fac 100644
--- a/Pixie.Terminal/Render/SequenceRenderer.cs
+++ b/Pixie.Terminal/Render/SequenceRenderer.cs
@@ -25,10 +25,30 @@ public override void Render(MarkupNode node, RenderState state)
         {
             var children = ((Sequence)node).Contents;
             int count = children.Count;
+            object suppressVal;
+            bool suppressLeading =
+                state.ThemeProperties.TryGetValue(
+                    RenderThemeProperties.SuppressLeadingSeparatorProperty,
+                    out suppressVal)
+                && (bool)suppressVal;
+
+            if (suppressLeading && count > 0)
+            {
+                state.Render(children[0]);
+                state = state.WithThemeProperty(
+                    RenderThemeProperties.SuppressLeadingSeparatorProperty,
+                    false);
+                for (int i = 1; i < count; i++)
+                {
+                    state.Render(children[i]);
+                }
+                return;
+            }
+
             for (int i = 0; i < count; i++)
             {
                 state.Render(children[i]);
             }
         }
     }
-}
\ No newline at end of file
+}
diff --git a/Pixie.Terminal/Render/WrapBoxRenderer.cs b/Pixie.Terminal/Render/WrapBoxRenderer.cs
index 4ddf0b4..2f54a90 100644
--- a/Pixie.Terminal/Render/WrapBoxRenderer.cs
+++ b/Pixie.Terminal/Render/WrapBoxRenderer.cs
@@ -26,6 +26,12 @@ public override void Render(MarkupNode node, RenderState state)
         {
             var boxNode = (WrapBox)node;
             var newState = state;
+            object suppressVal;
+            bool suppressLeading =
+                state.ThemeProperties.TryGetValue(
+                    RenderThemeProperties.SuppressLeadingSeparatorProperty,
+                    out suppressVal)
+                && (bool)suppressVal;
             var newTerm = LayoutTerminal.Wrap(
                 LayoutTerminal.AddHorizontalMargin(
                     state.Terminal,
@@ -33,9 +39,9 @@ public override void Render(MarkupNode node, RenderState state)
                     boxNode.RightMargin),
                 boxNode.Wrapping);
 
-            newState = newTerm.StartLayoutBox(state);
+            newState = newTerm.StartLayoutBox(state, !suppressLeading);
             newState.Render(boxNode.Contents);
             newTerm.EndLayoutBox();
         }
     }
-}
\ No newline at end of file
+}
diff --git a/Pixie.Terminal/TerminalBase.cs b/Pixie.Terminal/TerminalBase.cs
index d90a901..8a54990 100644
--- a/Pixie.Terminal/TerminalBase.cs
+++ b/Pixie.Terminal/TerminalBase.cs
@@ -55,6 +55,18 @@ public virtual void Write(char character)
             Write(character.ToString());
         }
 
+        /// <summary>
+        /// Tells if this terminal has already emitted visible output content.
+        /// </summary>
+        public virtual bool HasWrittenContent => true;
+
+        /// <summary>
+        /// Flushes any pending layout or separator state to the output.
+        /// Call this after finishing a logical output entry.
+        /// </summary>
+        public virtual void FinishOutput()
+        { }
+
         /// <summary>
         /// Gets the first renderable string in a sequence of strings.
         /// If the sequence is empty or no string is renderable, <c>null</c>
@@ -78,4 +90,4 @@ public string GetFirstRenderableString(params string[] options)
             return null;
         }
     }
-}
\ No newline at end of file
+}
diff --git a/Pixie.Terminal/TerminalLog.cs b/Pixie.Terminal/TerminalLog.cs
index a0138a2..5062695 100644
--- a/Pixie.Terminal/TerminalLog.cs
+++ b/Pixie.Terminal/TerminalLog.cs
@@ -70,6 +70,7 @@ public void Log(MarkupNode node)
             lock (renderLock)
             {
                 BaseRenderState.Render(new Box(node));
+                BaseRenderState.Terminal.FinishOutput();
             }
         }
 
diff --git a/Tests/RenderTests.cs b/Tests/RenderTests.cs
index 82eaf45..09f4991 100644
--- a/Tests/RenderTests.cs
+++ b/Tests/RenderTests.cs
@@ -49,6 +49,19 @@ public static void AssertRendersAs(
                 PrepareForComparison(Render(node, extraRenderers)));
         }
 
+        [Test]
+        public void TerminalLogDoesNotPrefixFirstEntryWithBlankLine()
+        {
+            var writer = new StringWriter();
+            var terminal = new TextWriterTerminal(writer, 80, Encoding.ASCII);
+            var log = new TerminalLog(terminal);
+
+            log.Info("Hello from Pixie.");
+
+            Assert.IsFalse(writer.ToString().StartsWith("\n", StringComparison.Ordinal));
+            StringAssert.Contains("Hello from Pixie.", writer.ToString());
+        }
+
         [Test]
         public void TextBeforeBox()
         {
diff --git a/Tests/TerminalDeviceTests.cs b/Tests/TerminalDeviceTests.cs
index 1198de0..784b57d 100644
--- a/Tests/TerminalDeviceTests.cs
+++ b/Tests/TerminalDeviceTests.cs
@@ -73,7 +73,7 @@ public void OutputTerminalSeparatorsDoNotDuplicateNewlines()
             terminal.Write("x");
             terminal.WriteLine();
 
-            Assert.AreEqual("\nx\n", writer.ToString());
+            Assert.AreEqual("x\n", writer.ToString());
         }
 
         [Test]