i3config library

A library for parsing and manipulating i3 window manager configuration files.

This library provides a robust parser and data model for working with i3 configuration files. It handles all major i3 configuration elements including sections, properties, arrays, commands, and comments while preserving their structure and order.

Version Information

This package provides two parser implementations:

  • Default (V2): Modern PetitParser implementation with enhanced features
  • V1: Stable, hand-written parser for compatibility

To use the legacy V1 implementation:

import 'package:i3config/i3config_v1.dart';

Key Features

  • Full support for i3/Sway configuration syntax
  • Preserves comments and formatting
  • Handles nested sections and blocks
  • Supports line continuations
  • Enhanced error reporting
  • Built-in JSON serialization
  • Preserves order of configuration elements

Basic Usage

Parse an i3 configuration file:

import 'package:i3config/i3config.dart';

void main() {
  final config = Config.parse('''
  # Set mod key
  set \$mod Mod4

  # Start terminal
  bindsym \$mod+Return exec i3-sensible-terminal
  ''');

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

Legacy V1 Support

For compatibility with older code, use the V1 implementation:

import 'package:i3config/i3config_v1.dart';

final parser = I3ConfigParser(configContent);
final config = parser.parse();
print('Parsed ${config.elements.length} elements');

Error Handling

The parser provides detailed error information:

try {
  final config = Config.parse(malformedContent);
} catch (e) {
  print('Parse error: $e');
}

Migration Guide

  • Existing code: Import package:i3config/i3config_v1.dart explicitly to maintain compatibility
  • New projects: Use default import for enhanced V2 features
  • Gradual migration: Default import now uses V2 with enhanced capabilities

Core Classes

V2 (Default):

  • Config: Enhanced root container with source position tracking
  • Statement: Base class for all statements with sealed class hierarchy
  • Command: Generic commands with enhanced type safety
  • Value: Sealed hierarchy for values (Quoted, VariableRef, BareArg)
  • I3ConfigParser: Advanced parsing engine with detailed error reporting

V1 (Legacy):

  • I3Config: The original root configuration container
  • ConfigElement: Base class for all configuration elements

Additional Information

For more details on i3 configuration syntax and options, see the i3 User Guide.

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