i3config #

A Dart library for parsing and processing i3/Sway configuration files. Includes a state machine processor with pluggable handlers, scoped contexts, variable expansion, file imports, string interpolation, block references, dotted command heads, hex color value support, inline comments, and a virtual filesystem for testing.

Table of Contents #

• Installation
• Quick Start
• Key Features
• Language Features
• Built-in Handlers
• Custom Handlers
• Assignments and Arrays
• Error Handling
• Examples
• Documentation
• License

Installation #

dependencies:
  i3config: ^2.0.0

dart pub get

Quick Start #

import 'package:i3config/i3config.dart';

Future<void> main() async {
  final processor = ConfigProcessor();

  await processor.processString('''
set \$mod Mod4
bindsym \$mod+Return exec i3-sensible-terminal
''');

  print(processor.context.getVariable('mod')); // Mod4
}

Config.parse builds the AST. ConfigProcessor.process / processString run the state machine and execute registered handlers.

For simple AST access without the state machine:

import 'package:i3config/i3config.dart';

void main() {
  final config = Config.parse('''
    set \$mod Mod4
    bar {
        status_command i3status
    }
  ''');

  for (final stmt in config.statements) {
    print('${stmt.runtimeType}: $stmt');
  }
}

Key Features #

• State Machine — advanced processing pipeline with configurable states
• Handler System — extensible command and block handlers
• Scoped Commands — commands that only work within specific blocks
• Variable Expansion — dynamic variable resolution with scoping
• String Interpolation — double-quoted strings support $variable references
• Block References — reference block properties via dotted paths like bar.main.position
• Dotted Command Heads — commands with dotted names (client.focused, client.background) parse as a single head
• Hex Color Values — #-prefixed hex colors parsed as bare arguments
• File Imports — include with variable expansion, nesting, and circular detection
• Pluggable Filesystem — PhysicalFileSystem for production, VirtualFileSystem for tests
• Error Reporting — configurable warnings for unresolved references with source spans
• Async Support — handlers can be sync or async; the processor awaits them
• Array Handling — built-in support for array operations via +=
• Context Management — hierarchical variable and option scoping

Language Features #

i3conf parses and processes the full i3/Sway config syntax, with several extensions for dynamic configuration.

String Interpolation #

Double-quoted strings resolve $variable references. Single-quoted strings are literal.

set $theme   dark
set $status  "i3status -c $theme"
set $launcher "rofi -font 'Noto Sans $font_size'"

Block References #

Reference properties from other blocks using dotted paths.

bar "main" {
    status_command i3status
    position top
}

set $bar_pos  bar.main.position
set $bar_cmd  bar.main.status_command

Omitting the identifier matches the first block of that type:

set $first_cmd  bar.status_command

Dotted Command Heads #

Commands with dotted names parse as a single head:

client.focused   #tabbed   #4c7899
client.unfocused #tabbed   #285577
client.urgent    #tabbed   #900000

Hex Color Values #

#-prefixed hex colors are parsed as bare argument values:

set $bg       #2e3440
set $fg       #d8dee9
client.focused #tabbed #4c7899

Inline Comments #

Trailing # comments after commands and assignments are preserved:

bindsym $mod+Return exec alacritty  # launch terminal
set $mod Mod4                        # set mod key

Assignments and Arrays #

= assigns a scalar, += appends to an array:

order = "wireless wlan0"
order += "battery 0"
order += "clock"

File Imports with Variable Expansion #

Include external config files during processing:

include "modules/bar.conf"
include "$config_dir/colors.conf"
include "~/.config/i3/workspaces.conf"

Built-in Handlers #

ConfigProcessor auto-registers these handlers:

Unhandled commands pass through for default property processing.

Custom Handlers #

Custom Command Handler #

class BindsymHandler extends BaseCommandHandler<void> {
  @override
  String get commandName => 'bindsym';

  @override
  void handle(Command command, Context context) {
    final key = command.getArgAsString(0, context);
    final action = command.getArgAsString(1, context);
    context.setVariable('binding_$key', action);
  }
}

Future<void> main() async {
  final processor = ConfigProcessor()
    ..registerCommandHandler(BindsymHandler());

  await processor.processString('bindsym \$mod+Return exec alacritty');
}

Block-Scoped Handlers #

Block handlers register commands that only work inside a specific block:

class BarBlockHandler extends BaseBlockHandler {
  @override
  String get blockType => 'bar';

  @override
  void handle(Block block, Context context) {
    print('Bar: ${getBlockIdentifier(block, context)}');
  }

  @override
  void registerScopedCommands(BlockHandlerRegistry registry) {
    registry.registerCommand('status_command', StatusHandler());
    registry.registerCommand('position', PositionHandler());
  }
}

class StatusHandler extends BaseCommandHandler<void> {
  @override
  String get commandName => 'status_command';

  @override
  void handle(Command command, Context context) {
    context.setVariable('bar_status', command.getArgAsString(0, context));
  }
}

Future<void> main() async {
  final processor = ConfigProcessor()
    ..registerBlockHandler(BarBlockHandler());

  await processor.processString('''
bar "top" {
    status_command i3status
    position top
}
''');
}

Inside a bar block, status_command and position resolve through bar-scoped handlers. Outside, those handlers are inactive.

Assignments and Arrays #

= and += produce Assignment nodes. Direct assignment produces a scalar; append assignment builds an array.

await processor.processString('''
order = "wireless wlan0"
order += "battery 0"
order += "clock"
''');

print(processor.context.getVariable('order'));
// [wireless wlan0, battery 0, clock]

Use Config.parse to inspect the AST without processing:

final config = Config.parse('order += "wireless"');
for (final a in config.statements.whereType<Assignment>()) {
  print('${a.variable} ${a.operator} ${a.values}');
}

Error Handling #

Parse errors throw from Config.parse. Processing errors flow through the error handler.

class Logger implements ErrorHandler {
  @override
  void handleError(String message, Context context, {SourceSpan? span}) {
    print('Error at ${span?.start.line ?? '?'}:${span?.start.column ?? '?'}: $message');
  }
}

final processor = ConfigProcessor()..setErrorHandler(Logger());
await processor.processString('include "missing.conf"');

Enable warnings for unresolved references:

processor.context.reportUnresolvedVariables = true;
processor.context.reportUnresolvedBlockReferences = true;

Examples #

Full runnable examples are in the example/ directory:

• interpolation_and_block_ref_example.dart — string interpolation and block references
• dotted_heads_colors_example.dart — dotted command heads and hex colors
• i3conf_example.dart — basic state machine usage
• file_imports_example.dart — file imports with virtual filesystem
• formatter_example.dart — formatting config AST back to text
• block_scoped_handlers_example.dart — block-scoped command handlers
• command_value_extraction_example.dart — extracting values from commands

Documentation #

• Language Guide — i3 config syntax and library usage
• Block Handlers — processing block types and scoped commands
• Command Handlers — processing individual commands, file imports
• Context and Scoping — variable management and inheritance
• Configuration Examples — real-world config to handler mapping
• Simple AST Iteration — using the parser without the state machine

License #

MIT — see LICENSE.

Additional Resources #

• i3 User Guide
• Package Documentation