filemap Module

Parse directories or formatted strings into file maps with automatic ignore pattern support.

Features

• 📂 Walk directories recursively and build file maps
• 🚫 Respect .gitignore and .heroignore ignore patterns with directory scoping
• 📝 Parse custom ===FILE:name=== format into file maps
• 📦 Export/write file maps to disk
• 🛡️ Robust, defensive parsing (handles spaces, variable = length, case-insensitive)

Quick Start

From Directory Path

import incubaid.herolib.lib.ai.filemap

mut cw := filemap.new()
mut fm := cw.filemap_get(path: '/path/to/project')!

// Iterate files
for path, content in fm.content {
    println('${path}: ${content.len} bytes')
}

From Formatted String

content_str := '
===FILE:main.v===
fn main() {
    println("Hello!")
}
===FILE:utils/helper.v===
pub fn help() {}
===END===
'

mut cw := filemap.new()
mut fm := cw.parse(content_str)!

println(fm.get('main.v')!)

FileMap Operations

// Get file content
content := fm.get('path/to/file.txt')!

// Set/modify file
fm.set('new/file.txt', 'content here')

// Find files by prefix
files := fm.find('src/')

// Export to directory
fm.export('/output/dir')!

// Write updates to directory
fm.write('/project/dir')!

// Convert back to formatted string
text := fm.content()

File Format

Full Files

===FILE:path/to/file.txt===
File content here
Can span multiple lines
===END===

Partial Content (for future morphing)

===FILECHANGE:src/models.v===
struct User {
    id int
}
===END===

Both Together

===FILE:main.v===
fn main() {}
===FILECHANGE:utils.v===
fn helper() {}
===END===

Parsing Robustness

Parser handles variations:

===FILE:name.txt===     // Standard
== FILE : name.txt ==   
===file:name.txt===     // Lowercase
==FILE:name.txt==       // Different = count

Error Handling

Errors are collected in FileMap.errors:

mut fm := cw.filemap_get(content: str)!

if fm.errors.len > 0 {
    for err in fm.errors {
        println('Line ${err.linenr}: ${err.message}')
    }
}

Ignore Patterns

• Respects .gitignore and .heroignore in any parent directory
• Default patterns include .git/, node_modules/, *.pyc, etc.
• Use / suffix for directory patterns: dist/
• Use * for wildcards: *.log
• Lines starting with # are comments

Example .heroignore:

build/
*.tmp
.env
__pycache__/

fn filemap(args FileMapArgs) !FileMap

filemap_get creates FileMap from path or content string

fn find_ignore_patterns(start_path string) ![]string

find_ignore_patterns collects all .gitignore patterns from current directory up to repository root

Walks up the directory tree using parent_find_advanced to locate all .gitignore files, stopping when it encounters the .git directory (repository root). Patterns are collected from:1. Default ignore patterns (built-in)2. All .gitignore files found from current directory to repository root3. Filter out comments (lines starting with '#') and empty lines

Parameters:- start_path: Optional starting directory path (defaults to current working directory if empty)

Returns:- Combined, sorted, unique ignore patterns from all sources

• Error if path operations fail (file not found, permission denied, etc.)

Examples: // Use current working directory patterns := find_ignore_patterns()!

// Use specific project directory patterns := find_ignore_patterns('/home/user/myproject')!

enum BlockKind {
	file
	filechange
	end
}

BlockKind defines the type of block in parsed content

struct FMError {
pub:
	message  string
	linenr   int
	category string
	filename string
}

struct FileMap {
pub mut:
	source         string            // Source path or origin
	content        map[string]string // Full file content by path
	content_change map[string]string // Partial/change content by path
	errors         []FMError         // Parse errors encountered
}

FileMap represents parsed file structure with content and changes

fn (mut fm FileMap) content() string

content generates formatted string representation

fn (mut fm FileMap) export(path string) !

export writes all FILE content to destination directory

fn (mut fm FileMap) write(path string) !

write updates files in destination directory (creates or overwrites)

fn (fm FileMap) get(relpath string) !string

get retrieves file content by path

fn (mut fm FileMap) set(relpath string, content string)

set stores file content by path

fn (mut fm FileMap) delete(relpath string)

delete removes file from content map

fn (fm FileMap) find(path string) []string

find returns all paths matching prefix

struct FileMapArgs {
pub mut:
	path         string
	content      string
	content_read bool = true // If false, file content not read from disk
	// Include if matches any wildcard pattern (* = any sequence)
	filter []string
	// Exclude if matches any wildcard pattern
	filter_ignore []string
}

struct WriteParams {
	path        string
	v_test      bool = true
	v_format    bool = true
	python_test bool
}