# cartographer/common/configuration_file_resolver.h

## Overview

`ConfigurationFileResolver` locates and reads Lua configuration files, handling include directives and search paths.

## Class: `cartographer::common::ConfigurationFileResolver`

### Construction

```cpp
explicit ConfigurationFileResolver(
    const std::vector<std::string>& configuration_files_directories);
```

### Methods

```cpp
// Get file content with includes resolved
std::string GetFileContentOrDie(const std::string& filename);

// Get full path to file
std::string GetFullPathOrDie(const std::string& filename);
```

### Include Resolution

When a Lua file contains `include "other.lua"`:
1. Searches `configuration_files_directories` in order
2. Reads included file
3. Recursively resolves its includes
4. Concatenates all content

### Search Paths

Directories searched in order:
1. Current working directory (for relative paths)
2. Directories passed to constructor (in order)
3. Compile-time default (e.g., `/usr/local/share/cartographer/configuration_files`)

## Usage

```cpp
// Configure search paths
std::vector<std::string> config_dirs = {
  "/etc/cartographer",
  "./config",
  "/opt/cartographer/share/configuration_files"
};

auto resolver = std::make_unique<ConfigurationFileResolver>(config_dirs);

// Load main config (resolves all includes)
std::string lua_code = resolver->GetFileContentOrDie("my_robot.lua");

// Parse to LuaParameterDictionary
auto lua_dict = common::MakeLuaParameterDictionary(lua_code);
```

## Include Syntax

```lua
-- In Lua config file
include "base_config.lua"
include "trajectory_builder_2d.lua"
include "pose_graph.lua"

-- Can use relative paths
include "my_robot/sensor_config.lua"
```

## Error Handling

- File not found → `LOG(FATAL)` (crash)
- Include cycles → `LOG(FATAL)`
- Use `GetFullPathOrDie()` to verify path before loading

## See Also

- [LuaParameterDictionary](lua_parameter_dictionary.md) — Parses resolved Lua code
- [MapBuilder](../mapping/map_builder.md) — Uses resolver for config