CQLParser -- A Python library for parsing CQL.

Author:  Rob Sanderson (azaroth@liv.ac.uk)
Licence:  GPL
Version: 1.4

Quick Usage:
Running CQLParser.py will read a CQL query from stdin and spit out the
XCQL equivalent on stdout.

As part of a larger program (for example an SRW server), you should
import CQLParser and then use:
  query = CQLParser.parse(CQLQuery)

To print the XCQL:
  print query.toXCQL()
Or to convert the query back into CQL:
  print query.toCQL()

SRWDiagnostics
--------------
This file is included in CQLParser and defines the SRW diagnostics.
Each diagnostic has its own object. The base class defines everything:

SRWDiagnostic
  A representation of an SRW Diagnostic record.
  Properties:
    .code        [integer]
    .description [string]
    .details     [string] 

Individual diagnostics may be created by DiagnosticNUM() where NUM is
the code of the diagnostic.  eg diag = Diagnostic10()

CQLParser
---------

Configuration:
There are four configuration options at the top of CQLParser.py

errorOnEmptyTerm:   If the parser encounters an empty term, raise the
                    appropriate diagnostic
errorOnQuotedIdentifier:  If the parser encounters an identifier in
                          quotes, raise a diagnostic
errorOnDuplicatePrefix:   If the parser tries to add an identical
                          prefix to an object, raise a diagnostic.
fullResultSetNameCheck:   Check for mutant present cases like:
                            srw.rsn=foo and srw.rsn=foo


CQLtester.py, sampleQueries.txt:
  CQLtester.py is a recursion checker against the sample queries file.
  This is useful for checking that the parser generates valid XCQL.

shlex.py:
  Python 1.5 comes with a non compatible version of shlex.  Use the
  one included if you're stuck in the stone age, otherwise delete it :)

CQLParser API:

There are three main functions defined:
  .parse(CQLstring)  [Parse the string and return an object]
  .xmlparse(XMLstring) [Parse the XML string and return an object]
  .xcqlparse(DOMnode)  [Transform parsed XCQL into an object]


CQLParser defines the following classes to represent CQL:

PrefixableObject:
  Properties:
    .prefixes    [Hash of prefix to URI]
    .parent      [Object one step above in query tree]
    .config      [Out of CQL configuration object to resolve prefixes]

  Functions:
    .addPrefix(name, uri) [Add a prefix to the object]
    .resolvePrefix(name)  [Resolve the short name to the URI]

PrefixedObject:
  Properties:
    .prefix      [String given as prefix. eg 'cql']
    .prefixURI   [String URI prefix resolved to. DO NOT USE DIRECTLY.]
    .value       [String name of the non prefix section. eg 'title']
    .parent      [SearchClause containing self]

  Functions:
    .resolvePrefix()  [Return the URI form or raise diagnostic if unknown]


Triple:
  (Child of Prefixable)
  The triple class represents an X Boolean Y triple. (<triple> in XCQL)
  Properties:
    .boolean  [A Boolean object]
    .leftOperand     [A Triple or SearchClause object]
    .rightOperand    [A Triple or SearchClause object]

  Functions:
    .getResultSetName()  [Return resultset name if all rsns are identical]

SearchClause:
  (Child of Prefixable)
  This class represents an index/relation/term. (<searchClause> in XCQL)
  Properties:
    .index    [An Index object]
    .relation [A Relation object]
    .term     [A Term object]

  Functions:
    .getResultSetName() [Return rsn if this is a resultset pointer]

Index:
  (Child of Prefixed)
  This class represents an index. (<index> in XCQL)

Relation:
  (Child of Prefixed)
  This class represents a relation. (<relation> in XCQL)
  Properties:
    .modifiers [list of RelationModifier]

RelationModifier:
  (Child of Prefixed)
  This class represents a relation modifier (relation/modifiers/modifier)
  
Term:
  This class represents a term (<term> in XCQL)
  Properties:
    .value [anything]

Boolean:
  This class represents a boolean. (<boolean> in XCQL)
  Properties:
    .value      [string]
    .modifiers  [list of strings]


All objects define the toXCQL() and toCQL() functions to convert
their subtree into XCQL or back to CQL respectively.


There are also a number of helper objects defined:

CQLParser:
  A class to hold the parsing rules for CQL
  Properties:
    .parser        [A CQLShlex Object]
    .currentToken  [string]
    .nextToken     [string]

  Functions:
    .is_boolean()  [Is current token a CQL Boolean]
    .fetch_token() [Get the next token from the lexer]
    .prefixes()    [Return a dictionary of any prefixes at currentToken]
    .query()       [Handles Booleans and Triples]
    .subQuery()    [Handles parentheses and clauses]
    .clause()      [Return a SearchClause]
    .boolean()     [Return a Boolean]
    .relation()    [Return a Relation]

XCQLParser:
  A class to hold the DOM parsing rules for XCQL


CQLshlex:
  A class to add in needed base lexing rules to shlex.
  Functions:
    read_token()  [Return a properly lexed token ala shlex]


CQLUtils
--------

This file contains several subclasses of the main CQL Objects.  It is an example of how you can easily add your own custom functions to objects.
It is imported into the CQLParser, and the objects used in place of the basic ones.  See the end of the CQLParser file.