SiKuLa

Simple Query Language - [ˈziːˈkuːˈlaː]

Rationale

Another query language, are you serious?

Actually it isn't that new. But naming it "Query language similar to GitHub's search syntax" (QLSTGHSS) wasn't a real option.

Think of it more as an implementation of a familiar syntax.

What's the difference then?

They are subtle. But I don't want to spoil the surprise. Or maybe I am just too lazy documenting it. 🤷

Example

Assuming you have an enum defined for searching e-mails:

use sikula::prelude::*;

#[derive(Search, Clone, Debug, PartialEq, Eq)]
enum DeriveResource<'a> {
    /// Standard qualifier: `author:someone`
    #[search(sort, scope)]
    Author(&'a str),
    /// Default primary: `warranty`
    #[search(default)]
    Subject(Primary<'a>),
    /// Non-default primary: `warranty in:message`, to search in both: `warranty in:message in:subject`
    #[search(scope)]
    Message(Primary<'a>),

    /// Predicate: `is:read`
    Read,

    /// Numeric qualifier example:
    /// * `size:100` (equals)
    /// * `size:>=100` (size greater than or equals 100)
    /// * `size:100..200` (size between 100 inclusive and 200 exclusive)
    /// * `size:*..200` (size up to 200 exclusive)
    #[search(sort)]
    Size(Ordered<usize>),

    #[search(sort)]
    Sent(Ordered<time::OffsetDateTime>),

    Label(Qualified<'a, &'a str>),
}

The Query derive provides the trait implementation. The #[query(scope)] attribute flags the variant Subject as Body scopes for the primary search terms, marking Subject as the default if none was selected.

In general, there are three types of terms: Primary, Qualifiers, Predicates. Predicates are simple "is this condition true" style of filters. If an enum variant doesn't have any value, it is a predicate.

Qualifiers are additional matching criteria, which depend on the type of the value.

With the #[query(sort)] flag, a field can be used for sorting the result.

Now, you can do the following queries:

For testing more examples with the resource above, you can run the cli example:

cargo run --example cli --features time -- -is:read AND foo

Which will give you a structured output of the parsed query:

Input: '-is:read AND foo'
Query {
    terms: And(
        [
            Not(
                Match(
                    Read,
                ),
            ),
            Match(
                Subject(
                    Partial(
                        "foo",
                    ),
                ),
            ),
        ],
    ),
    sorting: [],
}