valaq

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:

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:

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

Building from Source

# 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

# List all available VAPI files in text format
valaq

# List VAPI files in JSON format
valaq --json

Explore VAPI Files

# 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

# 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:

valaq gtk+-3.0 Gtk Window show
# Navigates to Gtk -> Window -> show

Dot-separated:

valaq gtk+-3.0 Gtk.Window.show
# Same navigation using dot notation

Mixed separators:

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/vapi

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

Examples

Basic Exploration

# 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

# 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

# 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:

{
  "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:

# 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:

# 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

# 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 for accurate VAPI parsing
• Uses GLib for core functionality
• JSON output powered by JSON-GLib