Skip to content

Modernize CLI ergonomics and terminal spacing #8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jonathanvdc merged 3 commits into from
Mar 27, 2026
Merged

Modernize CLI ergonomics and terminal spacing #8

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
bd06e37
Add ergonomic command-line parsing APIs
jonathanvdc Mar 27, 2026
c5c2ad7
Add logging helpers and refresh examples
jonathanvdc Mar 27, 2026
ca60c86
Fix terminal separator and diagnostic spacing
jonathanvdc Mar 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 4 additions & 9 deletions Examples/CaretDiagnostics/Program.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
{
Expand Down
35 changes: 15 additions & 20 deletions Examples/FormattedList/Program.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
9 changes: 3 additions & 6 deletions Examples/LoycInterop/Program.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down
149 changes: 76 additions & 73 deletions Examples/ParseOptions/Program.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
using System;
using System.Collections;
using System.Collections.Generic;
using System.Linq;
using System.Text;
Expand All @@ -16,62 +17,48 @@ 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.");

// This option is also a simple flag, but it has two
// 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[]
Expand All @@ -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[]
{
Expand All @@ -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();
}
}
}
Loading
Loading