QEQuery.h

/*
 * Copyright (c) 2006 Apple Computer, Inc. All rights reserved.
 *
 * @APPLE_LICENSE_HEADER_START@
 * 
 * This file contains Original Code and/or Modifications of Original Code
 * as defined in and that are subject to the Apple Public Source License
 * Version 2.0 (the 'License'). You may not use this file except in
 * compliance with the License. Please obtain a copy of the License at
 * http://www.opensource.apple.com/apsl/ and read it before using this
 * file.
 * 
 * The Original Code and all software distributed under the License are
 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
 * Please see the License for the specific language governing rights and
 * limitations under the License.
 * 
 * @APPLE_LICENSE_HEADER_END@
 */
#ifndef _QEQUERY_H_
#define _QEQUERY_H_

#include <CoreFoundation/CoreFoundation.h>

typedef struct __QEQuery * QEQueryRef;

/*******************************************************************************
* Flexible Query Engine
*
* This engine builds complex logical expression evaluators with predicates you
* define via callbacks. The engine directly supports AND, OR, NOT operators,
* as well as grouping. The engine is currently designed to build queries by
* serially adding elements, and figures out the grouping by itself. Operator
* precedence is explicit groups, then NOT, then AND, then OR.
*
* Query elements are dictionaries with three basic attributes:
*
* - Predicate: the 'verb' to evaluate
* - Arguments: data for use by the predicate
* - Negated:   whether the evaluated result must be negated (this is handled
*              by the engine, and your callbacks needn't worry about it)
*
* Your callbacks can stuff arbitrary key/value pairs into the dictionary in
* lieu of using the arguments array. Note that the engine reserves keys of the
* form '__QE...__', so don't use those.
*
********************************************************************************
* Using a Query
*
* You start by calling QEQueryCreate(), which takes a user data pointer for
* context info. Then you set parse and evaluation callbacks for the predicates
* you want to handle, add elements to your query using one of the two methods
* just below, and then use QEQueryEvaluate() on the objects you want to check.
*
* QEQueryEvaluate() returns true if the query matches the object you provide,
* and false if it doesn't or if an evaluation error occurs. If it does return
* false, you should call QEQueryLastError() and possibly cancel further queries
* using that query engine instance if an error did occur.
*
**********
* Building a Query from Strings
*
* If you set parse callbacks, you need only call QEQueryAppendElementFromArgs()
* repeatedly until it returns false. After doing that you should check whether
* there were any errors using QEQueryLastError().
*
* By default, the parse engine automatically  handles the tokens '-and', '-or',
* '-not', '(', and ')', but does not give them any priority over your parse
* callbacks. That is, if your callback eats up an '-and' as an argument for a
* predicate, the query engine will just keep rolling along (and you might see a
* syntax error later).
*
* Your parse calllback will have as arguments:
*
* - The element being built, with its predicate already set to the token
*   that triggered the callback.
* - A pointer to a list of strings following that token,  which you can
*   proceed to parse.
* - An in/out 'num used' parameter giving how many tokens have been parsed
*   by the query engine as a whole; you should update this by the number of
*   tokens you consume in parsing, if successful--if parsing fails, do not
*   adjust it. This number is *not* to be used as an index into the list
*   of argument strings; that starts at zero.
* - A pointer to the query user data.
* - A pointer to the query's error code, which you should set to
*   kQEQueryErrorInvalidOrMissingArgument or kQEQueryErrorParseCallbackFailed
*   if something goes wrong.
*
* Your callback should update the element by changing its predicate if necessary
* (so you can have a single keyword routed to different evaluation calbacks,
* or multiple keywords routed into a single evaluation callback), and reading
* as many arguments as needed from the list of strings and adding them to the
* elements arguments array. You can also set arbitrary properties on the element
* as noted above. It should update the num_used parameter as it successfully
* handles arguments. Upon successfully parsing all potential arguments, it
* should  return true; otherwise, it should set the error code as appopriate
* and return false.
*
* Functions that you may find useful in a parse callback are:
*
* - QEQueryElementGetPredicate()
* - QEQueryElementSetPredicate()
* - QEQueryElementAppendArgument()
* - QEQueryElementSetArgumentsArray()
* - QEQueryElementSetArguments()
*
* NOTE: If you get a reference to query element's predicate, and then set the
* predicate, your original predicate will change! Always 're-fetch' the
* predicate if you need to check it after setting it. (I think this is a CF
* bug, but I haven't investigated it thoroughly).
*
**********
* Building a Query by Hand
*
* You can forgo using parse callbacks if you want to build query elements
* directly, using:
*
* - QEQueryCreateElement() - creates an element with a user-define predicate
* - QEQueryAppendElement()
* - QEQueryAppendAndOperator() and QEQueryAppendOrOperator()
* - QEQueryStartGroup() and QEQueryEndGroup()
*
* Just call them in sequence and the engine will produce the correct evaluation
* structure. These functions return true on success, and false if they would
* result in an incorrectly-structures query (for example, with two OR operators
* in a row). You can call QEQueryLastError() to find out the specific problem.
*
********************************************************************************
* Evaluating a Query
*
* Your evaluation callback will have as arguments:
*
* - The query element being evaluated.
* - A pointer to the object being checked.
* - A pointer to the query use data.
* - A pointer to the query's error code, which you should set to
*   kQEQueryErrorEvaluationCallbackFailed if something goes wrong.
*
* Your callback should call QEQueryElementGetPredicate(),
* QEQueryElementGetArguments(), and QEQueryElementGetArgumentAtIndex()
* as necessary to apply its logic to the object and return a true or false
* value. It can also get arbitrary keys from the dictionary, as noted above.
* Your callback does not need to handle whether the query element is negated;
* the query engine does that.
*
* If your callback suffers a failure, it should set the error and return false.
*
* Note that evaluation callbacks can perform operations on or with the object
* as well as just checking them against a query predicate. For example, you
* could define a '-print' predicate that just prints data from the object
* and returns true.
********************************************************************************
* TO DO:
* XXX: Add functions that take CF strings?
* XXX: Allow for inspection/traversal of query, and insertion?
* XXX: Make QEQueryPrint() output friendlier (always record raw input tokens?)
* XXX: Add internal parse item counter and formatted error messages listing
* XXX:     problem item and its number?
*******************************************************************************/
typedef enum {
    kQEQueryErrorNone = 0,
    kQEQueryErrorUnspecified,
    kQEQueryErrorNoMemory,
    kQEQueryErrorGroupNesting,  // doesn't distinguish lib error from user....
    kQEQueryErrorEmptyGroup,
    kQEQueryErrorSyntax,
    kQEQueryErrorNoParseCallback,
    kQEQueryErrorNoEvaluationCallback,
    kQEQueryErrorInvalidOrMissingArgument,   // set by user parse callback
    kQEQueryErrorParseCallbackFailed,        // set by user parse callback
    kQEQueryErrorEvaluationCallbackFailed,   // set by user eval callback
} QEQueryError;

/* The default set of tokens understood by the engine.
 * You may need to handle these specially while processing
 * options.
 */
#define kQEQueryTokenAnd         "-and"
#define kQEQueryTokenOr          "-or"
#define kQEQueryTokenNot         "-not"
#define kQEQueryTokenGroupStart  "("
#define kQEQueryTokenGroupEnd    ")"

typedef Boolean (*QEQueryParseCallback)(
    CFMutableDictionaryRef element,
    int argc,
    char * const argv[],
    uint32_t * num_used,
    void * user_data,
    QEQueryError * error);

typedef Boolean (*QEQueryEvaluationCallback)(
    CFDictionaryRef element,
    void * object,
    void * user_data,
    QEQueryError * error);

/*******************************************************************************
* Create and set up a query.
*******************************************************************************/
QEQueryRef QEQueryCreate(void * userData);
void QEQueryFree(QEQueryRef query);

/* Replace the builtin logical operators with your own. If you pass NULL
 * for any one, the builtin is used (and for -not, ! is automatically registered
 * as a synonym). If you just want to add synonyms for logical operators, or
 * remove the default alias ! for -not, use QEQuerySetSynonymForPredicate().
 */
void QEQuerySetOperators(QEQueryRef query,
    CFStringRef andPredicate,
    CFStringRef orPredicate,
    CFStringRef notPredicate,
    CFStringRef groupStartPredicate,
    CFStringRef groupEndPredicate);

/* Empty all custom parse information: predicates, synonyms, and callbacks.
 */
void QEQueryEmptyParseDictionaries(QEQueryRef query);

/* You can remove a single callback by passing NULL.
 */
void QEQuerySetParseCallbackForPredicate(
    QEQueryRef query,
    CFStringRef predicate,
    QEQueryParseCallback parseCallback);

void QEQuerySetEvaluationCallbackForPredicate(
    QEQueryRef query,
    CFStringRef predicate,
    QEQueryEvaluationCallback evaluationCallback);

/* Causes 'synonym' to be automatically replaced with 'predicate' during
 * parsing and upon creation of an element dictionary with
 * QEQueryCreateElement(). If 'predicate' is NULL, the synonym is unregistered.
 */
void QEQuerySetSynonymForPredicate(
    QEQueryRef  query,
    CFStringRef synonym,
    CFStringRef predicate);

Boolean QEQueryIsComplete(QEQueryRef query);
QEQueryError QEQueryLastError(QEQueryRef query);

/*******************************************************************************
* Evaluate a query.
*******************************************************************************/
void    QEQuerySetShortCircuits(QEQueryRef query, Boolean flag);
Boolean QEQueryGetShortCircuits(QEQueryRef query);
Boolean QEQueryEvaluate(QEQueryRef query, void * object);

/*******************************************************************************
* Build a query from command-line arguments. See below for hand-building.
*******************************************************************************/
Boolean QEQueryAppendElementFromArgs(
    QEQueryRef query,
    int argc,
    char * const argv[],
    uint32_t * num_used);

/*******************************************************************************
* Functions for manually building a query.
*******************************************************************************/
CFMutableDictionaryRef QEQueryCreateElement(
    QEQueryRef  query,
    CFStringRef predicate,  // will be replaced if a synonym for another
    CFArrayRef  arguments,  // may be NULL
    Boolean     negated);

/* Do not manually build a dictionary element; use QEQueryCreateElement(),
 * which sets internal values needed by the query engine.
 */
Boolean QEQueryAppendElement(
    QEQueryRef query,
    CFMutableDictionaryRef element);

Boolean QEQueryAppendAndOperator(QEQueryRef query);
Boolean QEQueryAppendOrOperator(QEQueryRef query);

Boolean QEQueryStartGroup(QEQueryRef query, Boolean negated);
Boolean QEQueryEndGroup(QEQueryRef query);

/*******************************************************************************
* Functions for use by parse and evaluation callbacks.
*******************************************************************************/
CFStringRef       QEQueryElementGetPredicate(CFDictionaryRef element);
CFMutableArrayRef QEQueryElementGetArguments(CFDictionaryRef element);
CFTypeRef         QEQueryElementGetArgumentAtIndex(
    CFDictionaryRef element,
    CFIndex i);

/*******************************************************************************
* Functions for use by parse callbacks.
*******************************************************************************/
void QEQueryElementSetPredicate(CFMutableDictionaryRef element,
    CFStringRef predicate);
void QEQueryElementAppendArgument(CFMutableDictionaryRef element,
    CFTypeRef argument);
void QEQueryElementSetArgumentsArray(CFMutableDictionaryRef element,
    CFArrayRef arguments);
Boolean QEQueryElementSetArguments(CFMutableDictionaryRef element,
    uint32_t numArgs,
    ...);

/*******************************************************************************
* Print the raw CFPropertyList contents of a query.
*******************************************************************************/
void QEQueryPrint(QEQueryRef query);

#endif /* _QEQUERY_H_ */