i3config_v2 library

i3config v2 - Modern PetitParser implementation with source position tracking

This is the new, advanced implementation of the i3config parser using the PetitParser framework. It provides enhanced features including:

  • Precise source position tracking for all parsed elements
  • Enhanced error reporting with line/column information
  • Comprehensive AST with sealed class hierarchies
  • Better type safety and exhaustiveness checking
  • Support for complex parsing scenarios

Usage

import 'package:i3config/i3config_v2.dart';

// Parse with automatic position tracking
final config = Config.parse(configContent);

// Access source position information
for (final statement in config.statements) {
  if (statement.span != null) {
    print('Statement at line ${statement.span!.start.line + 1}');
    print('Source: "${statement.span!.text}"');
  }
}

// Or use the parser directly for advanced options
final parser = I3ConfigParser();
final result = parser.parseWithDetails(configContent);

Features

  • Source Position Tracking: Every parsed element includes optional SourceSpan information showing its exact location in source
  • Enhanced Error Reporting: Detailed error messages with suggestions
  • Type-Safe AST: Sealed classes for better pattern matching
  • Visitor Pattern: Built-in visitor support for AST traversal
  • Extensible Handlers: Plugin architecture for custom processing

Migration from V1

The v2 API is largely compatible with v1, but provides additional features:

// v1 style (still works)
final config = Config.parse(configContent);

// v2 enhanced features
final parser = I3ConfigParser();
final result = parser.parseWithDetails(configContent, url: Uri.file('config'));

if (result.isSuccess) {
  final config = result.config;
  // Access position information
  for (final stmt in config.statements) {
    print('Statement span: ${stmt.span}');
  }
} else {
  print('Error: ${result.error}');
  if (result.suggestion != null) {
    print('Suggestion: ${result.suggestion}');
  }
}

Classes

ArrayValue
Array value: ["a", "b", "c"]
Assignment
Assignment statement: variable = value or variable += value
AssignmentProcessingState
State for processing assignments.
BareArg
Bare argument (unquoted value)
BaseBlockHandler
Base class for block handlers with built-in child processing.
BaseCommandHandler<T>
Base class for command handlers with built-in value expansion.
Block
Block statement: { ... } with optional type and identifier
BlockHandler
Handler for specific block types.
BlockHandlerRegistry
Registry interface for registering commands and sub-block handlers within a block handler's registerScopedCommands method.
BlockProcessingState
State for processing blocks.
Command
Generic command statement
CommandHandler
Handler for specific command types.
CommandProcessingState
State for processing commands.
Comment
Comment element
Config
Root configuration container.
ConfigElement
Base class for all configuration elements.
ConfigFormatter
Formats an i3 config AST back to formatted config text.
ConfigProcessor
Main configuration processor that orchestrates the state machine.
ConfigVisitor<T>
Base visitor interface for processing configuration elements.
Context
Context object that holds processing state and configuration.
Criterion
Criterion for criteria blocks: key=value
ErrorHandler
Error handler for processing errors.
FileSystem
Abstract filesystem for reading configuration files.
FormatterOptions
Options for configuring the ConfigFormatter.
I3Config
InitialState
Initial processing state.
KeyPart
Key part for bindings (symbolic or code)
ParseFailure
Failed parse result.
Parser
Main parser class for i3/Sway configuration files.
ParseResult
Result of a parsing operation.
ParseSuccess
Successful parse result.
PhysicalFileSystem
Default FileSystem implementation backed by dart:io.
ProcessorState
Base state for the configuration processor.
Quoted
Quoted string value
SetCommandHandler
Built-in handler for 'set' commands (global variable assignment).
Statement
Base class for all statements.
Value
Base class for all values
VariableRef
Variable reference: $variable
VirtualFileSystem
Virtual filesystem for testing imports.

Enums

AssignmentOperator
Assignment operators for i3 config variables

Mixins

DefaultChildProcessing
Provides default automatic child processing. Mix this in for standard sequential processing (most common case).
ValueExpander
Mixin that provides value expansion utility for handlers.

Extensions

CommandValueExtraction on Command
Extension on Command for ergonomic value extraction.
ManualProcessing on ConfigProcessor
Extension to provide manual element processing for custom block handlers.

Properties

vfs → VirtualFileSystem
Global test virtual filesystem instance.
final

Functions

buildBlockHierarchy(Config config) → void
Build block hierarchy by establishing parent-child relationships.

Exceptions / Errors

ParseError
Parse error with location information