Getting Started with Pixie

Pixie is easiest to adopt when you treat it as three layers:

  1. ILog and its convenience helpers for application-facing output.
  2. Markup nodes for structured terminal content.
  3. Optional helpers for diagnostics, option parsing, and help generation.

Pick the right log

For diagnostics and CLI feedback, start with standard error:

using Pixie.Terminal;

var log = TerminalLog.Acquire();

For normal program output, prefer standard output:

using Pixie.Terminal;

var log = TerminalLog.AcquireStandardOutput();

In both cases, acquire a log once and reuse it throughout the application.

Log plain messages first

The smallest useful Pixie program acquires a log and writes a message:

using Pixie;
using Pixie.Terminal;

var log = TerminalLog.Acquire();

log.Info("Hello from Pixie.");

Strings automatically become markup nodes, so you can start simple and add structure later. If you need full control, log.Log(new LogEntry(...)) is still available.

Add structure with markup nodes

When plain strings stop being enough, compose output with types from Pixie.Markup.

Common building blocks:

Type Use it for
Text Explicit text nodes.
Sequence Concatenating multiple markup nodes.
BulletedList Lists with automatic bullets and spacing.
WrapBox Word- or character-wrapped content.
Title Section headings.
ColorSpan and DecorationSpan Styling.
HighlightedSource Source snippets with highlighted regions.

The FormattedList example is a good reference for layout and wrapping.

Log diagnostics

If you want compiler-style output such as file.cs:12:4: error: expected expression, log an explicit diagnostic:

using Pixie;
using Pixie.Code;
using Pixie.Markup;
using Pixie.Terminal;

var log = TerminalLog.Acquire();

var document = new StringDocument("file.cs", source);
var span = new SourceSpan(document, offset, length);
var region = new SourceRegion(span);
var snippet = new HighlightedSource(region, region);

log.ErrorDiagnostic(
    new SourceReference(snippet.HighlightedSpan),
    "expected expression",
    snippet);

HighlightedSource renders the caret snippet. SourceReference tells the diagnostic header where the error came from. Ordinary LogEntry values remain ordinary output, which makes it straightforward to mix diagnostics with help text or status messages in the same command-line application.

See the CaretDiagnostics example for the full pattern.

Parse options and keep docs in sync

Pixie's option parser and help output are designed to share the same definitions:

using Pixie.Options;

var helpFlag = Option.Flag("-h", "--help");
var filesOption = Option.StringSequence("--files")
    .WithParameter("file");

var commandLine = new CommandLine(
    new Option[] { helpFlag },
    filesOption);

Once parsed, read typed values back through OptionParseResult. The option object carries the value type, so you do not need to repeat it at the call site:

using System.Collections.Generic;

var parsedArgs = commandLine.Parse(args, log);

bool showHelp = parsedArgs.GetValue(helpFlag);
IReadOnlyList<string> files = parsedArgs.GetValue(filesOption);

If you want the common --help and --version flow handled automatically, add it once:

var commandLine = new CommandLine(filesOption)
    .WithHelp("Example program.", "example [files-or-options]")
    .WithVersion("example 1.0.0");

The same option definitions can still feed HelpMessage directly when you want to generate help as markup yourself.

See:

Decide how to handle parse failures

CommandLine.Parse(...) logs problems and returns an OptionParseResult. That gives applications room to inspect typed values, see whether parsing succeeded, and decide whether to continue.

For command-line applications, a practical pattern is:

using Pixie.Options;
using Pixie.Terminal;

var log = TerminalLog.Acquire();

var result = commandLine.Parse(args, log);

if (!result.IsSuccess || result.WasHandled)
{
    return result.ExitCode;
}

WasHandled is for parser-managed early exits such as generated help or version output. Parse failures are represented by IsSuccess == false.

For tests or strict tooling, TestLog can throw when selected severities are logged.

Customize rendering only when needed

The default terminal acquisition methods are usually enough. Reach for lower-level terminal APIs when you need to control:

  • output width,
  • encoding,
  • ANSI styling,
  • console styling,
  • degraded rendering for limited terminals.

The FormattedList example shows how to build a custom TextWriterTerminal and pass it into TerminalLog.Acquire(...).

Edit this page