Metadata-Version: 2.3
Name: kv3parser
Version: 1.0
Summary: A parser for KV3 file format
Project-URL: Homepage, https://github.com/Zehmosu/kv3parser
Project-URL: Bug Tracker, https://github.com/Zehmosu/kv3parser/issues
Author-email: Zehm <mrtentacleshasallthetalent@gmail.com>
License-File: LICENSE
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.6
Description-Content-Type: text/markdown

# kv3parser

A Python parser for converting KV3 (KeyValues3) data format to JSON, built for data analysis in the game Deadlock.

## Overview

This project provides a robust parser that can read KV3 formatted data from .vdata files and convert it to JSON. KV3 is a data format used in some Valve games and tools, including Deadlock. By converting KV3 to JSON, this parser facilitates easier analysis and manipulation of game data using standard JSON tools and libraries.

## Features

- Parses KV3 formatted data from .vdata files and converts it to JSON
- Handles complex KV3 structures including nested objects and arrays
- Supports various data types: strings, numbers, booleans, null values
- Recognizes and preserves KV3-specific flags (resource, resourcename, panorama, soundevent, subclass)
- Provides detailed error messages with line and column information for parsing errors
- Supports multi-line strings
- Handles comments (both single-line and multi-line)
- Allows for flexible syntax, such as omitting commas between key-value pairs

## Usage

```python
import json
from kv3parser import KV3Parser

# Path to your .vdata file
vdata_file_path = 'path/to/your/file.vdata'

# Read the content of the .vdata file
with open(vdata_file_path, 'r', encoding='utf-8') as file:
    vdata_content = file.read()

# Parse the KV3 content
parser = KV3Parser(vdata_content)
try:
    parsed_data = parser.parse()
    
    # Convert to JSON
    json_output = json.dumps(parsed_data, indent=2)
    
    # Print or save the JSON output
    print(json_output)
    
    # Optionally, save to a file
    # with open('output.json', 'w', encoding='utf-8') as json_file:
    #     json_file.write(json_output)

except Exception as e:
    print(f"Error parsing KV3: {e}")
```

## Error Handling

The parser provides detailed error messages when it encounters issues in the KV3 content. The `KV3ParseError` class is used to generate these messages, which include:

- The type of error
- The line and column where the error occurred
- A snippet of the content around the error location
- A pointer to the exact position of the error

## Implementation Details

The parser is implemented as a `KV3Parser` class with the following key methods:

- `parse()`: The main parsing method
- `parse_value()`: Parses different types of values (objects, arrays, strings, numbers, keywords)
- `parse_object()`: Handles parsing of KV3 objects
- `parse_array()`: Handles parsing of arrays
- `parse_string()`: Parses both single-line and multi-line strings
- `parse_number()`: Handles integer and float parsing
- `parse_keyword_or_resource()`: Handles keywords (true, false, null) and resource strings

The parser also includes methods for skipping whitespace and comments, and for parsing keys with potential flags.

## Dependencies

This project requires Python 3.6 or later. It uses only built-in Python libraries (`re` and `json`) and has no external dependencies.

## Contributing

Contributions to improve the parser or extend its functionality are welcome. Please feel free to submit issues or pull requests on the GitHub repository.

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

## Acknowledgments

This parser was created to facilitate data analysis for the game Deadlock. Special thanks to the Deadlock community for their support and feedback.