Home

QQL — Quran Query Language

A small, portable Rust library that parses compact textual references to Islamic texts and resolves them against local JSON data.

Q:2:1-5,255;Q:1;

Surah 2 ayat 1–5 plus ayah 255, then all of Surah 1.

Usable as a Rust crate, or through a C ABI from any language that speaks one — Dart FFI, Python, Go, C/C++ — on Linux, Windows, macOS, Android NDK and iOS. Not coupled to Flutter.

Start here

git clone https://github.com/mazhar266/QQ-Lang
cd QQ-Lang
cargo build --release
./target/release/qql 'Q:2:255'

{
  "ok": true,
  "query": "Q:2:255",
  "results": [
    {
      "source": "Q",
      "collection": "Quran",
      "surah": 2,
      "surah_name_ar": "البقرة",
      "surah_name_en": "Al-Baqarah",
      "ayah": 255,
      "ar": "ٱللَّهُ لَآ إِلَٰهَ إِلَّا هُوَ ٱلْحَىُّ ٱلْقَيُّومُ …",
      "en": "Allah - there is no deity except Him, the Ever-Living …"
    }
  ]
}

The manual

Page	What it covers
Query Language	The complete language, with examples. Start here.
Sources	The collections, their codes and numbering
Search	The three search engines and when to use each
CLI	qql and qql-index
Rust API	Using QQL as a crate
C API	The FFI surface and its memory rules
Dart Binding	dart:ffi, Flutter bundling
Custom Sources	Add a collection with JSON, no Rust
Errors	Every error code and what causes it
Building	Features, data, indexes
Architecture	How it fits together, for contributors

In one minute

Q:1                    a whole Surah
Q:2:255                one ayah
Q:2:1-5,255            ranges and singles
Q:1;B:1:1-3            two collections in one query
1,2:255                no code means the Quran
q:1:2,3,2:3,4-6        two chapters in one reference
B::100                 book-wide hadith numbering
q:2:"prayer"           exact search
q:1:?"mercy"           ranked full text  (optional feature)
q:*"worship"~3          vector similarity (optional feature)

Every result is JSON, including errors — the library never returns a malformed response, and Arabic passes through byte-for-byte.

Status

Complete for v1: parser, source registry, Quran / hadith / Hisnul Muslim resolvers, user-defined sources, CLI, C ABI, Dart binding, and two optional search engines. 18 built-in sources — the Quran, 16 hadith collections and Hisnul Muslim. 113 Rust tests, 137 with both features, plus 13 Dart tests.

GPL-3.0-or-later. See CONTRIBUTING.