namespace ost { namespace mol {
/**

\page query Queries

It is often convenient to highlight or focus certain parts of the structure. 
OpenStructure includes a powerful query system that allows you to perform custom 
selections in a convenient way.

Please refer to the tutorial on the query language for an introduction.

\section query_lang The query language reference

The query consists of one or more predicates combined with boolean 
operators. A predicate takes the form \em prop \em op \em value. Operators are
one of \code =, !=, >, >=, <=` and `< \endcode. A predicate has the following form:
PROPERTY - OPERATOR - ARGUMENT.
The following properties may be used in predicates. The supported type of the
value is given for each property.

\li     \c rname residue name. type: string
\li     \c rnum residue number. currently only numeric part is honored. 
        type: int
\li     \c rtype residue type as given by the DSSP code, i.e. H for helix, E
        for extended. type: string
\li     \c aname atom name. type: string
\li     \c ele element of atom. type: string
\li     \c cname chain name. type: string
\li     \c occ occupancy, between 0 and 1. type: float
\li     \c abfac B (temperature) factor of atom. type: float
\li     \c rbfac average B (temperature) factor of residue. type: float. 
        Note that this does not work for views as expected. When running a 
        second selection statement on a view, all atoms of the residue handle 
        and not the view are considered in the calculation
\li     \c ishetatm whether the atom is a hetorogenous atom. type: bool or int
        (0 for false, 1 for true)
\li     \c peptide whether the residue is peptide linking. type: bool or int
        (0 for false, 1 for true)        
\li     \c x  X coordinate of atom. type: float
\li     \c y  Y coordinate of atom. type: float
\li     \c z  Z coordinate of atom. type: float
\li     \c rindex index of residue in chain. This index is the same for views 
        and handles
\li     \c for \ref gen_prop see below

Distance-based selections within a given atom position are supported by
the within statement. To select atoms within 5 Angstrom of the point
\c {1,\c 2,\c 3}, one would write:
\code
5 <> {1,2,3}
\endcode
Negation of this expression is possible with the not operator, i.e.
\code
not 5 <> {1,2,3}
\endcode
will select atoms that are further than five Angstrom apart from 
\c {1,\c 2,\c 3}

Two abbreviations exist for convenience:

Instead of writing `aname=CA or aname=C or aname=O or aname=N`, one can 
write `aname=CA,N,C,O`. For integral value ranges, one can use the colon
syntax: instead of  rnum>=10 and rnum<=20` one can write \c rnum=10:20`

\section gen_prop GenericProperties

The query language can also be used for numeric generic properties (i.e.
FloatProp and IntProp), but the syntax is slightly
different. To access any generic properties, it needs to be specified that
they are generic and at which level they are defined. Therefore, all generic
properties start with a \c g, followed by an \c a, \c r or \c c for atom,
residue or chain level respectively. 
\code
# set generic properties for atom, residue, chain
atom_handle.SetFloatProp("testpropatom", 5.2)
resid_handle.SetFloatProp("testpropres", 1.1)
chain_handle.SetIntProp("testpropchain", 10)

# query statements
sel_a=e.Select("gatestpropatom<=10.0")
sel_r=e.Select("grtestpropres=1.0")
sel_c=e.Select("gctestpropchain>5")
\endcode
Since generic properties do not need to be defined for all parts of an entity
(e.g. it could be specified for one single atomhandle), the query statement
will throw an error unless you specify a default value in the query statement
which can be done using a ':' character:
\code
# if one or more atoms have no generic properties

sel=e.Select("gatestprop=5")
# this will throw an error

# you can specify a default value:
sel=e.Select("gatestprop:1.0=5")
# this will run through smoothly and use 1.0 as
# the default value for all atoms that do not
# have the generic property 'testprop'
\endcode

Using this method, you will be warned if a generic property is not set for all
atoms, residues or chains unless you specify a default value. So, be careful
when you do.
*/
}}
