# Valaq - VAPI File Query Tool

Valaq is a powerful command-line tool for querying and exploring VAPI (Vala API) files. It provides hierarchical navigation of symbols within VAPI files with support for both human-readable and JSON output formats. Built with libvala for accurate VAPI parsing and symbol extraction.

## Features

- **VAPI File Discovery**: Automatically discovers VAPI files in standard system directories
- **Symbol Navigation**: Hierarchical exploration of namespaces, classes, methods, and more
- **Flexible Output**: Both human-readable text and structured JSON output formats
- **Smart File Resolution**: Supports full paths, basenames with/without extensions
- **Comprehensive Symbol Support**: Handles all major Vala language constructs
- **Path-based Navigation**: Intuitive symbol traversal using space or dot-separated paths

## Installation

### Prerequisites

Valaq requires the following dependencies:

- Vala compiler (valac) 0.56 or later
- libvala-0.56 development package
- GLib 2.0 development libraries
- JSON-GLib 1.0 development libraries
- libgee 0.8 development libraries
- Meson build system
- Ninja build system

On Ubuntu/Debian systems:

```bash
sudo apt-get install valac libvala-0.56-dev libglib2.0-dev libjson-glib-dev libgee-0.8-dev meson ninja-build
```

On Fedora/RHEL systems:

```bash
sudo dnf install vala libvala-devel glib2-devel json-glib-devel libgee-devel meson ninja
```

### Building from Source

```bash
# Clone the repository
git clone https://github.com/your-repo/valaq.git
cd valaq

# Setup build directory
meson setup builddir

# Compile
meson compile -C builddir

# Run tests (optional)
meson test -C builddir

# Install
sudo meson install -C builddir
```

## Usage

### Basic Commands

#### List Available VAPI Files

```bash
# List all available VAPI files in text format
valaq

# List VAPI files in JSON format
valaq --json
```

#### Explore VAPI Files

```bash
# List top-level symbols using basename without extension
valaq gtk+-3.0

# List top-level symbols using basename with extension
valaq gtk+-3.0.vapi

# List top-level symbols using full path
valaq /usr/share/vala/vapi/gtk+-3.0.vapi
```

#### Navigate to Specific Symbols

```bash
# Navigate to a class (space-separated)
valaq gtk+-3.0 Gtk Window

# Navigate to a method (dot-separated)
valaq gtk+-3.0 Gtk.Window.show

# Navigate using mixed separators
valaq gtk+-3.0 Gtk.Window show

# Get JSON output for symbol details
valaq json-glib-1.0 Json.Object --json
```

### Command-Line Options

- `-h, --help`: Show help message and exit
- `-v, --version`: Show version information and exit
- `-j, --json`: Output in JSON format instead of human-readable text

### Symbol Path Formats

Symbol paths can be specified using spaces or dots as separators:

**Space-separated:**
```bash
valaq gtk+-3.0 Gtk Window show
# Navigates to Gtk -> Window -> show
```

**Dot-separated:**
```bash
valaq gtk+-3.0 Gtk.Window.show
# Same navigation using dot notation
```

**Mixed separators:**
```bash
valaq gtk+-3.0 Gtk.Window show
# Combines both formats
```

### Supported Symbol Types

Valaq supports all major Vala language constructs:

- **Namespaces**: Containers for related symbols
- **Classes**: Object-oriented class definitions
- **Interfaces**: Abstract interfaces for classes
- **Structs**: Value type structures
- **Enums**: Enumeration types with named values
- **Delegates**: Function pointer types
- **Methods**: Member functions with parameters
- **Properties**: Object properties with getters/setters
- **Fields**: Member variables
- **Constants**: Compile-time constant values

### VAPI File Discovery

Valaq automatically searches for VAPI files in standard directories:

- Primary: `/usr/share/vala-0.56/vapi`
- Secondary: `/usr/share/vala/vapi`
- Fallbacks: `/usr/share/vala-0.54/vapi`, `/usr/share/vala-0.52/vapi`, `/usr/local/share/vala/vapi`

Run `valaq` with no arguments to see all available VAPI files.

## Examples

### Basic Exploration

```bash
# List all available VAPI files
valaq

# Explore GLib namespace
valaq glib-2.0

# View method details with parameters
valaq glib-2.0 GLib.Timeout.add

# Examine enum values
valaq glib-2.0 GLib.FileType
```

### JSON Output

```bash
# Get VAPI file list in JSON
valaq --json

# Get symbol details in JSON format
valaq json-glib-1.0 Json.Object --json

# JSON output for method with full signature
valaq gtk+-3.0 Gtk.Window.show --json
```

### Advanced Navigation

```bash
# Navigate to nested symbols with dots in names
valaq package-name Namespace.Class

# Explore namespace contents
valaq gio-2.0 GLib

# Drill down into specific class methods
valaq gtk+-3.0 Gtk.Button Button_clicked
```

## Output Formats

### Text Output

Human-readable output with hierarchical symbol listing:

```
VAPI file: gtk+-3.0.vapi
Symbols:
  Gtk
    Window
      show() -> void
      hide() -> void
      destroy() -> void
    Button
      clicked() -> void
      set_label(string) -> void
```

### JSON Output

Structured JSON output for programmatic use:

```json
{
  "result_type": "symbol_details",
  "vapi_file": "gtk+-3.0.vapi",
  "query_path": ["Gtk", "Window"],
  "symbol": {
    "name": "Window",
    "type": "class",
    "access": "public",
    "base_types": ["Bin"],
    "methods": [
      {
        "name": "show",
        "return_type": "void",
        "parameters": []
      }
    ],
    "properties": [...],
    "fields": [...]
  },
  "metadata": {
    "vala_version": "0.56",
    "timestamp": "2023-..."
  }
}
```

## Exit Codes

- `0`: Success
- `1`: General error (invalid arguments, file not found, etc.)
- `2`: Parse error (invalid VAPI file syntax)

## Troubleshooting

### VAPI Files Not Found

If VAPI files are not found:

```bash
# Run 'valaq' with no arguments to see available files
valaq

# Use full path to specific file
valaq /path/to/your/file.vapi

# Check if vala development packages are installed
dpkg -l | grep libvala
```

### Symbol Navigation Issues

If symbols are not found:

```bash
# Check symbol name case (case-sensitive)
valaq gtk+-3.0 Gtk.Window

# List top-level symbols first to verify names
valaq gtk+-3.0

# Verify symbol path hierarchy
valaq gtk+-3.0 Gtk
valaq gtk+-3.0 Gtk.Window
valaq gtk+-3.0 Gtk.Window.show
```

### File Resolution

Valaq supports multiple file reference formats:

- **Full path**: `/usr/share/vala/vapi/gtk+-3.0.vapi`
- **Basename with extension**: `gtk+-3.0.vapi`
- **Basename without extension**: `gtk+-3.0`

The tool searches in standard VAPI directories and current working directory.

## Development

### Running Tests

```bash
# Run all tests
meson test -C builddir

# Run specific test
meson test -C builddir test-vapi-parser
```

### Project Structure

```
valaq/
├── src/
│   ├── main.vala              # Application entry point
│   ├── cli/
│   │   ├── argument-parser.vala    # Command-line argument parsing
│   │   └── command-handler.vala   # Command processing logic
│   ├── core/
│   │   ├── vapi-parser.vala        # VAPI file parsing using libvala
│   │   ├── symbol-navigator.vala   # Symbol hierarchy navigation
│   │   └── symbol-model.vala       # Data models for symbols
│   ├── output/
│   │   ├── formatter.vala          # Output formatting interface
│   │   ├── text-formatter.vala     # Human-readable output
│   │   └── json-formatter.vala     # JSON output formatting
│   └── utils/
│       ├── file-utils.vala         # File system operations
│       └── error-handling.vala     # Error handling utilities
├── tests/                     # Unit tests
├── meson.build               # Build configuration
└── README.md
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

## License

This project is licensed under the GPLv3 License. See the LICENSE file for details.

## Acknowledgments

- Built with [libvala](https://wiki.gnome.org/Projects/Vala) for accurate VAPI parsing
- Uses [GLib](https://docs.gtk.org/glib/) for core functionality
- JSON output powered by [JSON-GLib](https://docs.gtk.org/json-glib/)