|
| 1 | +# Bindings Directory |
| 2 | + |
| 3 | +C++ API bindings for cross-language integration with the PyClaudeCli variable system. |
| 4 | + |
| 5 | +## Files |
| 6 | + |
| 7 | +- `variable_api.cpp` - **C++ interface for variable system access** |
| 8 | +- `CMakeLists.txt` - **CMake build configuration for C++ API** |
| 9 | + |
| 10 | +## C++ Variable API (`variable_api.cpp`) |
| 11 | + |
| 12 | +### Purpose |
| 13 | +Provides a C++ interface to the Python-based variable system, enabling cross-language integration and allowing C++ applications to: |
| 14 | +- Set and retrieve persistent variables |
| 15 | +- Access the same variable storage as the Python CLI |
| 16 | +- Integrate with existing C++ codebases |
| 17 | + |
| 18 | +### Features |
| 19 | + |
| 20 | +#### Core Classes |
| 21 | +```cpp |
| 22 | +class VariableManager { |
| 23 | +public: |
| 24 | + VariableManager(const std::string& config_dir = ""); |
| 25 | + std::string GetVariable(const std::string& name) const; |
| 26 | + bool SetVariable(const std::string& name, const std::string& value) const; |
| 27 | + std::string ListVariables() const; |
| 28 | +}; |
| 29 | +``` |
| 30 | +
|
| 31 | +#### C Interface |
| 32 | +```cpp |
| 33 | +extern "C" { |
| 34 | + VariableManager* create_variable_manager(const char* config_dir); |
| 35 | + void destroy_variable_manager(VariableManager* vm); |
| 36 | + const char* get_variable(VariableManager* vm, const char* name); |
| 37 | + int set_variable(VariableManager* vm, const char* name, const char* value); |
| 38 | + const char* list_variables(VariableManager* vm); |
| 39 | +} |
| 40 | +``` |
| 41 | + |
| 42 | +#### Implementation Details |
| 43 | +- **Python Integration**: Executes Python commands to access the variable system |
| 44 | +- **Error Handling**: Graceful handling of Python execution errors |
| 45 | +- **Memory Management**: Proper cleanup and resource management |
| 46 | +- **Cross-Platform**: Works on Linux, macOS, and Windows |
| 47 | + |
| 48 | +### Usage Examples |
| 49 | + |
| 50 | +#### C++ Class Interface |
| 51 | +```cpp |
| 52 | +#include "variable_api.cpp" |
| 53 | + |
| 54 | +VariableManager vm; |
| 55 | + |
| 56 | +// Set variables |
| 57 | +vm.SetVariable("name", "Alice"); |
| 58 | +vm.SetVariable("age", "25"); |
| 59 | + |
| 60 | +// Get variables |
| 61 | +std::string name = vm.GetVariable("name"); |
| 62 | +std::string age = vm.GetVariable("age"); |
| 63 | + |
| 64 | +// List all variables |
| 65 | +std::string all_vars = vm.ListVariables(); |
| 66 | +``` |
| 67 | + |
| 68 | +#### C Interface |
| 69 | +```cpp |
| 70 | +VariableManager* vm = create_variable_manager(nullptr); |
| 71 | + |
| 72 | +set_variable(vm, "user", "Bob"); |
| 73 | +const char* user = get_variable(vm, "user"); |
| 74 | +const char* vars = list_variables(vm); |
| 75 | + |
| 76 | +destroy_variable_manager(vm); |
| 77 | +``` |
| 78 | +
|
| 79 | +### Build System (`CMakeLists.txt`) |
| 80 | +
|
| 81 | +#### Features |
| 82 | +- **C++23 Standard**: Modern C++ with latest features |
| 83 | +- **Multiple Targets**: |
| 84 | + - `variable_api` - Static library for integration |
| 85 | + - `variable_api_test` - Example/test executable |
| 86 | +- **Conditional Compilation**: Prevents main() conflicts in tests |
| 87 | +- **Doxygen Integration**: Documentation generation support |
| 88 | +
|
| 89 | +#### Build Commands |
| 90 | +```bash |
| 91 | +mkdir build && cd build |
| 92 | +cmake .. -DCMAKE_CXX_COMPILER=clang++ |
| 93 | +make variable_api # Build library |
| 94 | +make variable_api_test # Build example |
| 95 | +``` |
| 96 | + |
| 97 | +### Integration with Python |
| 98 | + |
| 99 | +The C++ API seamlessly integrates with the Python variable system: |
| 100 | +1. **Shared Storage**: Uses same `~/.config/claude/variables.json` file |
| 101 | +2. **Consistent Behavior**: Same variable access patterns as Python |
| 102 | +3. **Live Updates**: Changes in C++ are immediately visible in Python and vice versa |
| 103 | +4. **Type Preservation**: JSON types maintained across language boundaries |
| 104 | + |
| 105 | +### Testing |
| 106 | + |
| 107 | +Comprehensive testing ensures reliability: |
| 108 | +- **Unit Tests**: Basic operations and edge cases |
| 109 | +- **Integration Tests**: Python/C++ interoperability |
| 110 | +- **Error Handling**: Graceful failure modes |
| 111 | +- **Memory Safety**: No leaks or corruption |
| 112 | + |
| 113 | +### Performance |
| 114 | + |
| 115 | +- **Efficient**: Direct file system access when possible |
| 116 | +- **Cached**: Variables cached in memory during session |
| 117 | +- **Minimal Overhead**: Low-cost Python integration |
| 118 | +- **Scalable**: Handles large variable sets efficiently |
| 119 | + |
| 120 | +## Use Cases |
| 121 | + |
| 122 | +- **Native Applications**: Integrate PyClaudeCli variables into C++ apps |
| 123 | +- **Performance Critical**: Fast variable access from compiled code |
| 124 | +- **Legacy Integration**: Connect existing C++ systems to PyClaudeCli |
| 125 | +- **Cross-Language**: Share data between Python and C++ components |
| 126 | +- **Embedded Systems**: Lightweight variable access for resource-constrained environments |
0 commit comments