query_expr.h

Go to the documentation of this file.

// ============================================================= //
//                                                               //
//   File      : query_expr.h                                    //
//   Purpose   : gui independent query functionality             //
//                                                               //
//   Coded by Ralf Westram (coder@reallysoft.de) in April 2017   //
//   http://www.arb-home.de/                                     //
//                                                               //
// ============================================================= //

#ifndef QUERY_EXPR_H
#define QUERY_EXPR_H

#ifndef SMARTPTR_H
#include <smartptr.h>
#endif
#ifndef ARB_MATCH_H
#include <arb_match.h>
#endif
#ifndef ARBDBT_H
#include <arbdbt.h>
#endif
#ifndef GB_ACI_H
#include <gb_aci.h>
#endif
#ifndef _GLIBCXX_STRING
#include <string>
#endif

#define qe_assert(cond) arb_assert(cond)

// --------------------------------------------------------------------------------
// Provides query logic as used in ARB species search & query:
//
// - multiple query expressions
//   - combinable via AND and OR (w/o precedence!)
//   - invertible (global "not")
//   - query expression consists of
//     - some key (e.g. name of DB-field)
//     - equal / not-equal operator
//     - a match expression (wildcard, numeric compare, ACI, regexpr,  ...)
//     - combining operator (AND/OR)
// - provides "hit reason" for each positive hit
//
//
// To implement specific queries derive from classes QueryTarget and QueryKey.
// - QueryTarget-derivate shall be used by client to iterate over queried "things"
// - QueryKey-derivate defines how to access the (user-defined) specific key of the target
//   i.e. how to retrieve the data that actually will be queried vs. match expressions.
//
// Create an instance of QueryExpr (e.g. from AWAR defined values),
// loop your QueryTarget-derivate over all targets and
// ask your QueryExpr-instance whether it matches the current target.
//
//
// Example usage:
// ../DB_QUERY/db_query.cxx@TargetItem
// ../DB_QUERY/db_query.cxx@ItemQueryKey
// --------------------------------------------------------------------------------


#define MAX_SHOWN_DATA_SIZE 500

enum query_operator { ILLEGAL, AND, OR };

enum query_type {
    AQT_INVALID,
    AQT_EMPTY,
    AQT_NON_EMPTY,
    AQT_LOWER,
    AQT_GREATER,
    AQT_EXACT_MATCH,
    AQT_OCCURS,
    AQT_STARTS_WITH,
    AQT_ENDS_WITH,
    AQT_WILDCARD,
    AQT_REGEXPR,
    AQT_ACI,
};

enum query_key_type {
    QKEY_EXPLICIT, // query should match one explicit target (e.g. a specific DB-field)
    QKEY_ANY,      // query should match one of many targets - no matter which (e.g. any DB-field)
    QKEY_ALL,      // query should match all targets (e.g. all DB-fields)
    QKEY_ANY_REC,  // like QKEY_ANY (but descend through all sub-containers)
    QKEY_ALL_REC,  // like QKEY_ALL (dito)
};

class QueryTarget : virtual Noncopyable {
    // Points to a specific target (e.g. a species).
    // Can be matched using a QueryKey.

    GBL_env env;

public:
    QueryTarget(GBDATA *gb_main, const char *treename) : env(gb_main, treename) {}
    virtual ~QueryTarget() {}

    GBDATA *get_gb_main() const { return env.get_gb_main(); }
    const GBL_env& get_env() const { return env; }

    // virtual interface:
    virtual GBDATA *get_ACI_item() const = 0; // may NOT return NULp!
    // ----------
};

class QueryKey {
    query_key_type type; // type of search key

public:
    QueryKey(query_key_type type_) :
        type(type_)
    {}
    virtual ~QueryKey() {}

    // virtual interface:
    virtual char *get_target_data(const QueryTarget& target, GB_ERROR& error) const = 0;  // retrieve content of target-key (e.g. species field)

    virtual const char *get_name() const = 0; // name of target (e.g. for reports)
    virtual bool iterate() const         = 0; // iterate key to next entry (not for QKEY_EXPLICIT)
    virtual void reset() const           = 0; // reset iteration
    // ----------

    bool next() const {
        if (type == QKEY_EXPLICIT) return false; // explicit keys cannot iterate
        return iterate();
    }

    query_key_type get_type() const { return type; }
    void negate() {
        switch (type) {
            case QKEY_EXPLICIT: break;
            case QKEY_ALL:     type = QKEY_ANY;     break; // not match all keys <=> mismatch any key
            case QKEY_ALL_REC: type = QKEY_ANY_REC; break;
            case QKEY_ANY:     type = QKEY_ALL;     break; // not match any key  <=> mismatch all keys
            case QKEY_ANY_REC: type = QKEY_ALL_REC; break;
        }
    }
};
typedef SmartPtr<QueryKey> QueryKeyPtr;

struct ExplicitQueryKey: public QueryKey {
    ExplicitQueryKey() :
        QueryKey(QKEY_EXPLICIT)
    {}
    ~ExplicitQueryKey() OVERRIDE {}

    // virtual interface:
    char *get_target_data(const QueryTarget& target, GB_ERROR& error) const OVERRIDE = 0; // retrieve content of target-key (e.g. species field)
    const char *get_name() const                                            OVERRIDE = 0; // name of target (e.g. for reports)

    // implement part of QueryKey interface:
    bool iterate() const { return false; } // iterate key to next entry (not for QKEY_EXPLICIT)
    void reset() const {} // reset iteration
};

class QueryExpr : virtual Noncopyable {
    query_operator op;   // operator (AND or OR)
    QueryKeyPtr    qkey; // what to search (specialized by caller)

    bool  Not;  // true means "don't match"
    char *expr; // search expression

    query_type type;                      // type of 'query'
    struct XQuery : virtual Noncopyable { // used for some values of 'type'
        std::string  str;
        GBS_regex   *regexp;
        float        number;
        XQuery() : regexp(NULp) {}
        ~XQuery() { GBS_free_regexpr(regexp); }
    } xquery;

    mutable char *error;         // either set by matches() or manually via setError(); once set all future matches fail
    mutable char *lastACIresult; // result of last ACI query

    QueryExpr *next;

    // --------------------

    void       detect_query_type();
    QueryExpr *remove_tail();

    bool first_matches(const QueryTarget& target, char*& matched_data) const;
    bool shallMatch() const { return !Not; }

    const char *get_last_ACI_result() const { return type == AQT_ACI ? lastACIresult : NULp; }

public:

    QueryExpr(query_operator aqo, QueryKeyPtr key, bool not_equal, const char *expression);
    ~QueryExpr() {
        free(expr);
        free(lastACIresult);
        free(error);
        delete next;
    }

    void append(QueryExpr*& tail);

    query_key_type get_key_type() const { return qkey->get_type(); }

    QueryKey& get_key() { return *qkey; }
    const QueryKey& get_key() const { return *qkey; }

    void negate(); // expr -> !expr

    bool matches(const QueryTarget& target, std::string& hit_reason) const;

    GB_ERROR getError(int count = 0) const;
    void setError(GB_ERROR error_) const {
        qe_assert(!error); // refuse to overwrite errors
        error = strdup(error_);
    }

#if defined(DEBUG)
    std::string dump_str() const {
        return std::string(qkey->get_name()) + (Not ? "!=" : "==") + expr;
    }
    void dump(std::string *prev = NULp) const {
        std::string mine = dump_str();
        if (prev) {
            std::string both = *prev+' ';
            switch (op) {
                case AND: both += "&&"; break;
                case OR: both  += "||"; break;
                default: qe_assert(0); break;
            }
            both += ' '+mine;
            mine  = both;

            if (next) mine = '('+mine+')';
        }

        if (next) next->dump(&mine);
        else fputs(mine.c_str(), stdout);
    }
#endif // DEBUG
};

#else
#error query_expr.h included twice
#endif // QUERY_EXPR_H