Skip to content

getting-started.md

Latest commit

 

History

History
151 lines (98 loc) · 4.44 KB

getting-started.md

File metadata and controls

151 lines (98 loc) · 4.44 KB

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.

Turn entries into diagnostics

If you want compiler-style output such as file.cs:12:4: error: expected expression, wrap your log once:

using Pixie.Terminal;
using Pixie.Transforms;

var log = TerminalLog.Acquire().WithDiagnostics("program");

After that, ordinary LogEntry values are rendered as diagnostics automatically. When a log entry contains a HighlightedSource, Pixie can use its source span to populate the filename and line/column header.

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:

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

bool showHelp = parsedArgs.GetValue<bool>(helpFlag);
string[] files = parsedArgs.GetValue<string[]>(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(...).