valaq/man/valaq.1

.\" valaq.1 - VAPI File Query Tool man page
.\"
.\" Copyright (C) 2023 Valaq Project
.\" License: GPLv3
.\"
.TH VALAQ 1 "2023-12-10" "valaq 1.0.0" "User Commands"
.SH NAME
valaq \- VAPI File Query Tool for exploring Vala API files
.SH SYNOPSIS
.B valaq
[\fIOPTIONS\fR] [\fIVAPI_FILE\fR] [\fISYMBOL_PATH\fR...]
.SH DESCRIPTION
.B 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.

When run without arguments,
.B valaq
lists all available VAPI files in the standard search paths. When a VAPI file is
specified, it displays the symbols contained in that file. Symbol paths can be used
to navigate to specific symbols within the hierarchy.

.SH OPTIONS
.TP
.B \-h, \-\-help
Show this help message and exit.
.TP
.B \-v, \-\-version
Show version information and exit.
.TP
.B \-j, \-\-json
Output in JSON format instead of human-readable text.

.SH ARGUMENTS
.TP
.B VAPI_FILE
Path to a VAPI file to analyze. Can be:
.RS
.IP \(bu 2
Full path: \fI/usr/share/vala/vapi/gtk+-3.0.vapi\fR
.IP \(bu 2
Basename with extension: \fIgtk+-3.0.vapi\fR
.IP \(bu 2
Basename without extension: \fIgtk+-3.0\fR
.RE

.TP
.B SYMBOL_PATH...
Hierarchical path to a symbol. Supports both space-separated and dot-separated paths.

.SH SYMBOL PATH FORMATS
Symbol paths can be specified using spaces or dots as separators:

.TP
Space-separated:
.EX
valaq gtk+-3.0 Gtk Window show
.EE
# Navigates to Gtk -> Window -> show

.TP
Dot-separated:
.EX
valaq gtk+-3.0 Gtk.Window.show
.EE
# Same navigation using dot notation

.TP
Mixed separators:
.EX
valaq gtk+-3.0 Gtk.Window show
.EE
# Combines both formats

.SH SUPPORTED SYMBOL TYPES
.B valaq
supports all major Vala language constructs:

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

.SH VAPI FILE DISCOVERY
.B valaq
automatically searches for VAPI files in standard directories:

.RS
.IP \(bu 2
Primary: \fI/usr/share/vala-0.56/vapi\fR
.IP \(bu 2
Secondary: \fI/usr/share/vala/vapi\fR
.IP \(bu 2
Fallbacks: \fI/usr/share/vala-0.54/vapi\fR, \fI/usr/share/vala/vapi\fR
.RE

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

.SH OUTPUT FORMATS
.SS Text Output
Human-readable output with hierarchical symbol listing:

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

.SS JSON Output
Structured JSON output for programmatic use:

.EX
{
  "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-..."
  }
}
.EE

.SH EXAMPLES
.TP
List all available VAPI files
.EX
valaq
.EE

.TP
List VAPI files in JSON format
.EX
valaq --json
.EE

.TP
List top-level symbols (using basename without extension)
.EX
valaq gtk+-3.0
.EE

.TP
List top-level symbols (using basename with extension)
.EX
valaq gtk+-3.0.vapi
.EE

.TP
List top-level symbols (using full path)
.EX
valaq /usr/share/vala/vapi/gtk+-3.0.vapi
.EE

.TP
Navigate to a class
.EX
valaq gtk+-3.0 Gtk.Window
.EE

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

.TP
Navigate to a method (space-separated)
.EX
valaq gtk+-3.0 Gtk Window show
.EE

.TP
Navigate to nested symbols with dots in names
.EX
valaq package-name Namespace.Class
.EE

.TP
Get JSON output for symbol details
.EX
valaq json-glib-1.0 Json.Object --json
.EE

.TP
Explore namespace contents
.EX
valaq gio-2.0 GLib
.EE

.TP
View method details with parameters
.EX
valaq glib-2.0 GLib.Timeout.add
.EE

.TP
Examine enum values
.EX
valaq glib-2.0 GLib.FileType
.EE

.SH EXIT STATUS
.TP
.B 0
Success
.TP
.B 1
General error (invalid arguments, file not found, etc.)
.TP
.B 2
Parse error (invalid VAPI file syntax)

.SH TROUBLESHOOTING
.SS VAPI Files Not Found
If VAPI files are not found:
.RS
.IP \(bu 2
Run 'valaq' with no arguments to see available files
.IP \(bu 2
Use full path: \fIvalaq /path/to/your/file.vapi\fR
.IP \(bu 2
Check if vala development packages are installed
.RE

.SS Symbol Navigation Issues
If symbols are not found:
.RS
.IP \(bu 2
Check symbol name case (case-sensitive)
.IP \(bu 2
List top-level symbols first: \fIvalaq <vapi-file>\fR
.IP \(bu 2
Verify symbol path hierarchy
.RE

.SH SEE ALSO
.BR valac (1),
.BR vala (1)

.SH BUGS
Report bugs to the Valaq project issue tracker at:
https://github.com/valaq/valaq/issues

.SH AUTHOR
.B valaq
was written by the Valaq Project.

This manual page was written for the Valaq Project.

.SH COPYRIGHT
Copyright (C) 2023 Valaq Project
License: GPLv3
This is free software; see the source for copying conditions.