VB6Parse / Documentation

Overview

The FormFile parser is one of the most complex components in vb6parse due to the unique structure of VB6 Form files (.frm). These files combine:

• Structured header data (VERSION, Object references)
• Hierarchical control definitions (BEGIN...END blocks with properties)
• Metadata attributes (Attribute statements)
• VB6 source code (Event handlers, procedures, functions)

The parser must handle all four sections efficiently while providing both full parsing capability and fast-path extraction when only UI information is needed.

VB6 Form File Structure

A typical .frm file follows this layout:

VERSION 5.00
Object = "{831FDD16-0C5C-11D2-A9FC-0000F8754DA1}#2.0#0"; "mscomctl.ocx"
Begin VB.Form Form1
   Caption         =   "My Form"
   ClientHeight    =   3195
   ClientWidth     =   4680
   BeginProperty Font 
      Name            =   "Verdana"
      Size            =   8.25
      Charset         =   0
   EndProperty
   Begin VB.CommandButton Command1 
      Caption         =   "Click Me"
      Height          =   495
      Left            =   120
   End
End
Attribute VB_Name = "Form1"
Attribute VB_GlobalNameSpace = False

Private Sub Command1_Click()
    MsgBox "Hello!"
End Sub

Challenges

• Mixed content types: Both structured data and free-form code
• Nested hierarchy: Controls can contain child controls (PictureBox, Frame)
• Property groups: BeginProperty...EndProperty blocks with GUIDs
• Large files: Forms can have dozens of controls and thousands of lines of code
• Performance: Tools often only need UI structure, not code analysis

Parsing Architecture

Multi-Layer Pipeline

Design Philosophy & Trade-offs

Core Principles

1. Correctness over speed (but optimize where possible)
2. Preserve all information (CST includes whitespace/comments)
3. Memory efficiency (rowan's red-green tree, shared nodes)
4. Partial success model (return what was parsed + collect errors)
5. Type safety (strong Rust enums for properties and controls)

The Hybrid Approach Decision

The FormFile parser evolved through several iterations:

// Build complete CST, then extract everything from it
let cst = parse(token_stream);
let version = extract_version(&cst);
let objects = extract_objects(&cst);
let control = extract_control(&cst);
let attributes = extract_attributes(&cst);

// Skip CST, extract directly from tokens
let result = FormFile::parse_control_only(token_stream);
let (version, control, remaining_tokens) = result.unpack();

// Direct extraction for structured sections
let version = parser.parse_version_direct();
let objects = parser.parse_objects_direct();
let control = parser.parse_properties_block_to_control();
let attributes = parser.parse_attributes_direct();

// Build CST only for code section
let remaining_tokens = parser.into_tokens();
let cst = parse(TokenStream::from_tokens(remaining_tokens));

The Hybrid Parsing Strategy

Direct Extraction Methods

The Parser struct provides special methods for direct extraction:

1. new_direct_extraction(tokens, pos)

Creates a parser in "direct extraction mode" where tokens are consumed without building CST nodes.

let mut parser = Parser::new_direct_extraction(tokens, 0);

2. parse_version_direct()

Extracts VERSION without CST:

// Parses: VERSION 5.00 [CLASS]
let (version_opt, failures) = parser.parse_version_direct().unpack();

Returns: FileFormatVersion { major, minor }

3. parse_objects_direct()

Extracts Object references without CST:

// Parses: Object = "{UUID}#version#flags"; "filename"
let objects = parser.parse_objects_direct();

Handles two formats:

• Standard: Object = "{...}#2.0#0"; "file.ocx"
• Embedded: Object = *\G{...}#2.0#0; "file.ocx"

4. parse_properties_block_to_control()

This is the most complex direct extraction method. It recursively parses BEGIN...END blocks:

let (control_opt, failures) = parser.parse_properties_block_to_control().unpack();

Parses:

• Control type (e.g., VB.Form, VB.CommandButton)
• Control name
• Properties (Key = Value)
• Property groups (BeginProperty...EndProperty)
• Nested child controls (recursive)
• Menu controls (special handling)

Returns: Fully constructed Control struct with name, tag, index, and typed properties

5. parse_attributes_direct()

Extracts Attribute statements:

// Parses: Attribute VB_Name = "Form1"
let attributes = parser.parse_attributes_direct();

Implementation Details

Control Type Mapping

The parser maps VB6 control type strings to Rust enum variants:

match control_type.as_str() {
    "VB.Form" => ControlKind::Form {
        properties: properties.into(),
        controls: child_controls,
        menus,
    },
    "VB.CommandButton" => ControlKind::CommandButton {
        properties: properties.into(),
    },
    "VB.TextBox" => ControlKind::TextBox {
        properties: properties.into(),
    },
    // ... 30+ built-in controls
    _ => ControlKind::Custom {
        properties: properties.into(),
        property_groups,
    },
}

Property Parsing

Properties are stored in a Properties struct (thin wrapper around HashMap):

pub struct Properties {
    key_value_store: HashMap<String, String>,
}

Type conversion happens at access time:

let width = properties.get_i32("ClientWidth", 600);  // Default: 600
let visible = properties.get_bool("Visible", true);
let color = properties.get_color("BackColor", VB_WINDOW_BACKGROUND);

Property Groups

Property groups handle nested structures like Font properties:

BeginProperty Font {GUID}
   Name            =   "Verdana"
   Size            =   8.25
   Charset         =   0
EndProperty

Structure:

pub struct PropertyGroup {
    pub name: String,
    pub guid: Option<Uuid>,
    pub properties: HashMap<String, Either<String, PropertyGroup>>,
}

Uses Either<String, PropertyGroup> to support nesting:

• Left(String): Simple property value
• Right(PropertyGroup): Nested group (e.g., ListImage1, ListImage2)

Error Handling

The parser uses a partial success model:

pub struct ParseResult<'a, T, E> {
    pub result: Option<T>,
    pub failures: Vec<ErrorDetails<'a, E>>,
}

Example Usage:

let (form_file_opt, failures) = FormFile::parse(&source_file).unpack();

if let Some(form) = form_file_opt {
    // Use parsed data
    println!("Form: {}", form.form.name);
}

if !failures.is_empty() {
    // Report warnings
    for error in failures {
        eprintln!("Warning: {:?}", error);
    }
}

Control Hierarchy & Properties

Type-Safe Control System

Each control type has a dedicated properties struct:

pub enum ControlKind {
    Form {
        properties: FormProperties,
        controls: Vec<Control>,
        menus: Vec<MenuControl>,
    },
    CommandButton {
        properties: CommandButtonProperties,
    },
    TextBox {
        properties: TextBoxProperties,
    },
    // ... 30+ variants
    Custom {
        properties: CustomControlProperties,
        property_groups: Vec<PropertyGroup>,
    },
}

Property structs use strong types:

pub struct FormProperties {
    pub caption: String,
    pub back_color: Color,
    pub border_style: FormBorderStyle,
    pub client_height: i32,
    pub client_width: i32,
    pub max_button: MaxButton,
    pub min_button: MinButton,
    // ... 50+ fields
}

Enums for discrete values:

#[derive(TryFromPrimitive)]
#[repr(i32)]
pub enum FormBorderStyle {
    None = 0,
    FixedSingle = 1,
    Sizable = 2,
    FixedDialog = 3,
    FixedToolWindow = 4,
    SizableToolWindow = 5,
}

Future Considerations

Potential Improvements

Performance Metrics

Based on benchmarks with real-world VB6 projects:

Summary

The FormFile parser represents a pragmatic balance between:

1. Completeness: Full CST for code, typed properties for controls
2. Performance: Direct extraction for structured sections
3. Flexibility: Both full parse and fast-path APIs
4. Correctness: Windows-1252 encoding, partial success model
5. Maintainability: Rowan abstracted, single source of truth

This architecture successfully handles the diverse requirements of VB6 form parsing while maintaining reasonable performance and memory characteristics for real-world projects.