CodeParser Module

The codeparser module provides a comprehensive indexing and analysis system for V codebases. It walks directory trees, parses all V files, and allows efficient searching, filtering, and analysis of code structures.

Features

• Directory Scanning: Automatically walks directory trees and finds all V files
• Batch Parsing: Parses multiple files efficiently
• Indexing: Indexes code by module, structs, functions, interfaces, constants
• Search: Find specific items by name
• Filtering: Use predicates to filter code items
• Statistics: Get module statistics (file count, struct count, etc.)
• Export: Export complete codebase structure as JSON
• Error Handling: Gracefully handles parse errors

Basic Usage

import incubaid.herolib.core.codeparser

// Create a parser for a directory
mut parser := codeparser.new('/path/to/herolib')!

// List all modules
modules := parser.list_modules()
for mod in modules {
    println('Module: ${mod}')
}

// Find a specific struct
struct_ := parser.find_struct('User', 'mymodule')!
println('Struct: ${struct_.name}')

// List all public functions
pub_fns := parser.filter_public_functions()

// Get methods on a struct
methods := parser.list_methods_on_struct('User')

// Export to JSON
json_str := parser.to_json()!

API Reference

Factory

• new(root_dir: string) !CodeParser - Create parser for a directory

Listers

• list_modules() []string - All modules
• list_files() []string - All files
• list_files_in_module(module: string) []string - Files in module
• list_structs(module: string = '') []Struct - All structs
• list_functions(module: string = '') []Function - All functions
• list_interfaces(module: string = '') []Interface - All interfaces
• list_methods_on_struct(struct: string, module: string = '') []Function - Methods
• list_imports(module: string = '') []Import - All imports
• list_constants(module: string = '') []Const - All constants

Finders

• find_struct(name: string, module: string = '') !Struct
• find_function(name: string, module: string = '') !Function
• find_interface(name: string, module: string = '') !Interface
• find_method(struct: string, method: string, module: string = '') !Function
• find_module(name: string) !ParsedModule
• find_file(path: string) !ParsedFile
• find_structs_with_method(method: string, module: string = '') []string
• find_callers(function: string, module: string = '') []Function

Filters

• filter_structs(predicate: fn(Struct) bool, module: string = '') []Struct
• filter_functions(predicate: fn(Function) bool, module: string = '') []Function
• filter_public_structs(module: string = '') []Struct
• filter_public_functions(module: string = '') []Function
• filter_functions_with_receiver(module: string = '') []Function
• filter_functions_returning_error(module: string = '') []Function
• filter_structs_with_field(type: string, module: string = '') []Struct
• filter_structs_by_name(pattern: string, module: string = '') []Struct
• filter_functions_by_name(pattern: string, module: string = '') []Function

Export

• to_json(module: string = '') !string - Export to JSON
• to_json_pretty(module: string = '') !string - Pretty-printed JSON

Error Handling

• has_errors() bool - Check if parsing errors occurred
• error_count() int - Get number of errors
• print_errors() - Print all errors

Example: Analyzing a Module

import incubaid.herolib.core.codeparser

mut parser := codeparser.new(os.home_dir() + '/code/github/incubaid/herolib/lib/core')!

// Get all public functions in the 'pathlib' module
pub_fns := parser.filter_public_functions('incubaid.herolib.core.pathlib')

for fn in pub_fns {
    println('${fn.name}() -> ${fn.result.typ.symbol()}')
}

// Find all structs with a specific method
structs := parser.find_structs_with_method('read')

// Export pathlib module to JSON
json_str := parser.to_json('incubaid.herolib.core.pathlib')!
println(json_str)

Implementation Notes

1. Lazy Parsing: Files are parsed only when needed
2. Error Recovery: Parsing errors don't stop the indexing process
3. Memory Efficient: Maintains index in memory but doesn't duplicate code
4. Module Agnostic: Works with any V module structure
5. Cross-Module Search: Can search across entire codebase or single module

fn new(args ParserOptions) !CodeParser

new creates a CodeParser and scans the given root directory

struct CodeParser {
pub mut:
	root_dir     string
	options      ParserOptions
	parsed_files map[string]ParsedFile
	modules      map[string][]string
	parse_errors []ParseError
}

fn (p CodeParser) all_consts() []code.Const

all_consts returns all constants from all parsed files

fn (p CodeParser) all_enums() []code.Enum

all_enums returns all enums from all parsed files

fn (p CodeParser) all_functions() []code.Function

all_functions returns all functions from all parsed files

fn (p CodeParser) all_imports() map[string]bool

all_imports returns a map of all unique imports

fn (p CodeParser) all_structs() []code.Struct

all_structs returns all structs from all parsed files

fn (parser CodeParser) error_count() int

error_count returns the number of parsing errors

fn (parser CodeParser) filter_methods(module_name string) []code.Function

filter_methods returns all functions with receivers (methods)

fn (parser CodeParser) filter_public_functions(module_name string) []code.Function

filter_public_functions returns all public functions

fn (parser CodeParser) filter_public_structs(module_name string) []code.Struct

filter_public_structs returns all public structs

fn (parser CodeParser) find_callers(args FinderOptions) []code.Function

find_callers finds all functions that call a specific function (basic text matching)

fn (parser CodeParser) find_file(path string) !ParsedFile

find_file retrieves parsed file information

fn (parser CodeParser) find_function(args FinderOptions) !code.Function

find_function searches for a function by name

fn (parser CodeParser) find_interface(args FinderOptions) !code.Interface

find_interface searches for an interface by name

fn (parser CodeParser) find_method(args FinderOptions) !code.Function

find_method searches for a method on a struct

fn (parser CodeParser) find_module(module_name string) !ParsedModule

find_module searches for a module by name

fn (parser CodeParser) find_struct(args FinderOptions) !code.Struct

find_struct searches for a struct by name

fn (parser CodeParser) find_structs_with_method(args FinderOptions) []string

find_structs_with_method finds all structs that have a specific method

fn (parser CodeParser) functions(options FilterOptions) []code.Function

functions returns a filtered list of all functions found in the parsed files

fn (parser CodeParser) get_module_stats(module_name string) ModuleStats

get_module_stats calculates statistics for a module

fn (parser CodeParser) get_parsed_file(file_path string) ?ParsedFile

get_parsed_file returns the parsed file for a given path

fn (parser CodeParser) has_errors() bool

has_errors returns true if any parsing errors occurred

fn (parser CodeParser) list_constants(module_name string) []code.Const

list_constants returns all constants in the codebase (optionally filtered by module)

fn (parser CodeParser) list_files() []string

fn (parser CodeParser) list_files_in_module(module_name string) []string

list_files_in_module returns all file paths in a specific module

fn (parser CodeParser) list_functions(module_name string) []code.Function

list_functions returns all functions in the codebase (optionally filtered by module)

fn (parser CodeParser) list_imports(module_name string) []code.Import

list_imports returns all unique imports used in the codebase (optionally filtered by module)

fn (parser CodeParser) list_interfaces(module_name string) []code.Interface

list_interfaces returns all interfaces in the codebase (optionally filtered by module)

fn (parser CodeParser) list_methods_on_struct(struct_name string, module_name string) []code.Function

list_methods_on_struct returns all methods (receiver functions) for a struct

fn (parser CodeParser) list_modules() []string

list_modules returns a list of all parsed module names

fn (parser CodeParser) list_structs(module_name string) []code.Struct

list_structs returns all structs in the codebase (optionally filtered by module)

fn (mut parser CodeParser) parse() !

parse processes all V files that were scanned and parses them

fn (mut parser CodeParser) parse_file(file_path string) !

parse_file parses a single V file and adds it to the index

fn (parser CodeParser) structs(options FilterOptions) []code.Struct

structs returns a filtered list of all structs found in the parsed files

fn (parser CodeParser) to_json(module_name string) !string

to_json exports the complete code structure to JSON

Args: module_name - optional module filter (if empty, exports all modules) Returns: JSON string representation

struct CodeParserJSON {
pub mut:
	root_dir string
	modules  map[string]ModuleJSON
	summary  SummaryJSON
}

JSON export structures

struct ConstJSON {
pub:
	name  string
	value string
}

struct EnumJSON {
pub:
	name        string
	is_pub      bool
	value_count int
	description string
}

struct FileJSON {
pub:
	path        string
	module_name string
	items_count int
	structs     []StructJSON
	functions   []FunctionJSON
	interfaces  []InterfaceJSON
	enums       []EnumJSON
	constants   []ConstJSON
}

struct FilterOptions {
pub:
	module_name  string
	name_filter  string // just partial match
	is_public    bool
	has_receiver bool
}

struct FinderOptions {
pub:
	name        string @[required]
	struct_name string // only useful for methods on structs
	module_name string
}

struct FunctionJSON {
pub:
	name       string
	is_pub     bool
	has_return bool
	params     int
	receiver   string
}

struct InterfaceJSON {
pub:
	name        string
	is_pub      bool
	description string
}

struct ModuleJSON {
pub mut:
	name    string
	files   map[string]FileJSON
	stats   ModuleStats
	imports []string
}

struct ModuleStats {
pub mut:
	file_count      int
	struct_count    int
	function_count  int
	interface_count int
	const_count     int
}

struct ParseError {
pub:
	file_path string
	error     string
}

ParseError represents an error that occurred while parsing a file

struct ParsedFile {
pub:
	path        string
	module_name string
	vfile       code.VFile
}

ParsedFile represents a successfully parsed V file

struct ParsedModule {
pub:
	name       string
	file_paths []string
	stats      ModuleStats
}

struct ParserOptions {
pub:
	path             string @[required]
	recursive        bool = true
	exclude_patterns []string
	include_patterns []string = ['*.v']
}

import incubaid.herolib.core.pathlib import incubaid.herolib.core.code

struct StructJSON {
pub:
	name        string
	is_pub      bool
	field_count int
	description string
}

struct SummaryJSON {
pub mut:
	total_files      int
	total_modules    int
	total_structs    int
	total_functions  int
	total_interfaces int
	total_enums      int
}