NAME

Query::Tags - Raku-inspired query language for attributes

SYNOPSIS

use Query::Tags;

# Select all @books for which the 'title' field matches the regex /Perl/.
my $q = Query::Tags->new(q[:title/Perl/]);
my @shelf = $q->select(@books);

VERSION

This document describes v0.0.3 of Query::Tags.

DESCRIPTION

Query::Tags implements a simple query language for stringy object attributes. Its main features are:

• Attribute syntax

  :key(value) designates that an object should have a field or method named key whose value should match value. If value is missing (is undef), the key or field should exist.

• Regular expressions

  Perl regular expressions are fully supported.

• Junctions

  Simple logic operations on queries is supported in the form of junctions (as in Raku). For example, :title!</Dummies/ /in \d+ days/> matches all books whose title field matches neither /Dummies/ nor makes an /in \d+ days/.

• Pegex grammar

  The language is specified using a Pegex grammar which means that it can be easily changed and extended. You can also supply your own Pegex::Receiver to the Pegex parser engine, for instance to compile a Query::Tags query to SQL.

This feature set allows for reasonably flexible filtering of tagged, unstructured data (think of email headers). They also allow for a straightforward query syntax and quick parsing (discussed in detail below).

It does not support:

• Nested data structures

  There is no way to match values inside a list, for example.

• Types

  There is no type information. All matching is string-based. There are no operators for comparing numbers, dates or ranges (but they could be added without too much work).

• Complex logic

  Junctions provide only a limited means for using logical connectives with query assertions. You can specify "all books whose title is X or Y" but you cannot specify "all books whose title is X or whose author is Y".

Methods

new

my $q = Query::Tags->new($query_string, \%opts);

Parses the query string and creates a new query object. The query is internally represented by a syntax tree.

The optional argument \%opts is a hashref containing options. Only one option is supported at the moment:

• default_key

  Controls the matching of assertions in the query for pairs with an empty key part. If the given value is a CODEREF, it is invoked with each tested object together with the value part of an assertion (and the \%opts hashref unaltered). It should return a truthy or falsy value depending on match. If the default_key value is not a CODEREF it is assumed to be a string and is used instead of any missing key in an assertion.

tree

my $root = $q->tree;

Get the root of the underlying syntax tree representation. It is an object of class Query::Tags::To::AST::Query.

test

$q->test($obj) ? 'PASS' : 'FAIL'

Check if the given object passes all query assertions in $q.

select

my @pass = $q->select(@objs);

Return all objects which pass all query assertions in $q.

Exports

parse_query

my $q = parse_query($query_string);

Optional export which provides a more procedural interface to the constructor of this package.

Query syntax

The query language is specified in a Pegex grammar called query-tags which is included in the distribution's share directory. See that file for detailed technical information. What follows is an overview of the language.

• Query

  A query is represented by a Query::Tags::To::AST::Query object. It contains a list of assertions in the form of pairs.

• Pair

  A pair consists of a key and a value. Keys are alphanumeric strings (beginning with an alphabetic character) also permitting the punctuation characters ., - and _. The value can be a quoted string, a regex or a junction. A pair starts with a colon : and the value is written directly after the key. E.g., :key'value' (for a string value), :key/value/ (for a regex value) or :key&<value1 value2> (for a junction value). The value is optional.

  If instead of a value, the question mark character ? appears, the key field must exist and its value must be truthy.

• Quoted string

  A quoted string is a string delimited by single quotes '. E.g., 'Perl' but not Perl or "Perl" or «Perl».

• Regex

  A regex is a standard Perl regex, as usual between a pair of slahes / but not allowing modifiers. E.g., /Perl/ or /(?i)Perl/ but not /Perl/i.

• Junction

  A junction is a superposition of several values together with a mode. The mode can be & (meaning the object should match all of the given values), | (the object should match at least one of the given values) and ! (the object should match none of the given values). The list of values is given in angular backets < ... > and is whitespace-separated. It can contain (and freely mix) quoted strings, regexes, junctions and barewords. A junction can also be negated by prefixing its mode with a tilde ~. E.g., &</Perl/ /Master/> (both match) or |</Perl/ /Raku/> (at least one matches) or ~&</AI/ /.*coin/ /as a service/> (not all match).

• Bareword

  All of the above constructs start with a non-alphabetical character: : for pairs, ' for quoted strings, / for regexes and &, |, ! or ~ for junctions. Hence, single word strings do not actually have to be written in quotes as they can be distinguished from non-strings. A bareword is a string of \w characters, \d numbers or the punctuation characters ., - or _. It is internally converted to a string. Barewords can appear in junctions as well as the top-level query. At the top level, they are converted to pairs with no key and with the bareword as a string value. It is up to the application to decide what to do with them.

EXAMPLES

Searching a small database

Get all books (co-)authored by /foy/:

use Modern::Perl;
use Query::Tags qw(parse_query);

my @books = (
    { title => 'Programming Perl', authors => 'Tom Christiansen, brian d foy, Larry Wall, Jon Orwant' },
    { title => 'Learning Perl', authors => 'Randal L. Schwartz, Tom Phoenix, brian d foy' },
    { title => 'Intermediate Perl', authors => 'Randal L. Schwartz and brian d foy, with Tom Phoenix' },
    { title => 'Mastering Perl', authors => 'brian d foy' },
    { title => 'Perl Best Practices', authors => 'Damian Conway' },
    { title => 'Higher-Order Perl', authors => 'Mark-Jason Dominus' },
    { title => 'Object Oriented Perl', authors => 'Damian Conway' },
    { title => 'Modern Perl', authors => 'chromatic' }
);

say $_->{title} for parse_query(q[:authors/foy/])->select(@books);

Email headers

Find all work emails from a mailing list that mention /seminar/ or /talk/:

use v5.16;
use Mail::Header;
use Path::Tiny;
use Query::Tags qw(parse_query);

my @mail = map { Mail::Header->new([$_->lines]) } path('~/Mail/work/cur')->children;
my @headers = map { my $mh = $_; +{ map { fc $_ => $mh->get($_) } $mh->tags } } @mail;
say $_->{subject} for
    parse_query(q[:list-id :subject|</(?i)seminar/ /(?i)talk/>])->select(@headers);

AUTHOR

Tobias Boege tobs@taboege.de

COPYRIGHT AND LICENSE

This software is copyright (C) 2025 by Tobias Boege.

This is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.